Datagrunt 4.5.2: Controllable Data Profiling with Custom Sample Sizes

Datagrunt 4.5.2 is a refined patch release that introduces customizable data sampling sizes for all tabular readers, alongside important fixes to ensure our automated documentation and blogging release pipeline triggers correctly and reliably.

Custom Sampling Sizes with the New n_rows Parameter

When evaluating massive datasets, loading the entire file can be exceptionally slow and memory-intensive. Datagrunt provides .get_sample() to retrieve a lightweight preview of the source files.

Prior to version 4.5.2, .get_sample() was fixed to a hardcoded size of 20 rows. While 20 is a sensible default for quick terminal inspections, modern data pipelines often require smaller samples for lightning-fast schema checks, or larger samples (such as 100 or 500 rows) to perform more robust statistical analysis and type inference over messy columns.

In Datagrunt 4.5.2, all three tabular reader classes (CSVReader, ExcelReader, and ParquetReader) now support an optional n_rows parameter on their .get_sample() method.

How It Works

Simply pass n_rows as a positive integer. If omitted, it inherits the engine default (20 rows).

from datagrunt import CSVReader, ExcelReader, ParquetReader

# 1. CSV Sampling (supports Polars, Arrow, and DuckDB engines)
csv_reader = CSVReader("large_transactions.csv")
# Get a custom sample of 100 rows
sample_csv = csv_reader.get_sample(n_rows=100)

# 2. Excel Sampling (select sheets by name/index and customize preview size)
excel_reader = ExcelReader("annual_report.xlsx")
# Read the first 5 rows of sheet 'Sales'
sample_xl = excel_reader.get_sample(sheet="Sales", n_rows=5)

# 3. Parquet Sampling (supports Polars-driven high-performance previews)
parquet_reader = ParquetReader("telemetry.parquet")
# Custom sample of 250 rows
sample_pq = parquet_reader.get_sample(n_rows=250)

Proactive & Uniform Input Validation

To keep API semantics predictable and prevent silent errors or unexpected behavior across varying reader backends, the n_rows parameter is strictly validated before any underlying file reading begins:

• It must be a positive integer ($\ge 1$).
• Unintended types like bool (which behaves like an integer in Python under the hood) are caught early and explicitly rejected.
• Empty/blank files will bypass processing but still trigger this input validation first, ensuring consistent error surfaces independent of a file’s state.

Passing a non-integer or a non-positive value will immediately raise a clean ValueError:

# Raises ValueError: n_rows must be a positive integer, got False.
csv_reader.get_sample(n_rows=False)

# Raises ValueError: n_rows must be a positive integer, got 0.
csv_reader.get_sample(n_rows=0)

Release Pipeline & Automation Enhancements

This release also implements several crucial fixes to our developer CI/CD workflows, addressing several issues with how release-coordination documentation updates are queued and published:

• Triggering Workflows on skip-ci Version Bumps: Previously, our auto-publish workflow failed to run because our automatic version bumper pushes unprefixed tags on bump commits decorated with [skip ci]. GitHub Actions limits triggering pushes by default if push commands suppress CI execution. We resolved this by chaining the documentation auto-publisher directly to the success of the upstream version-bump workflow completion (workflow_run), duplicating the robust workflow setup used by our PyPI deployment.
• Accurate Release Delta Extraction: The documentation coordination agent previously generated release notes using a strict diff against HEAD~1 (the single commit preceding release-time commits). Moving forward, the auto-scheduler dynamically extracts the previous tag (e.g. v4.5.1) and feeds the complete differential delta to our AI agent. This means tomorrow’s blog posts and documentation index edits will capture the entire release delta even when a release spans multiple feature branches and micro-commits.
• Immediate Site Publication: Blog posts are no longer parked in “draft: true” state awaiting manual interventions. Newly produced blogs are built immediately as draft: false and pushed live, saving operational overhead and avoiding the risks of draft buildup.

Technical Upgrade

Upgrade your local environment today for immediate access to customized tabular sampling:

# Upgrade the core package
uv pip install --upgrade datagrunt

# Alternatively, upgrade with optional PDF capabilities
uv pip install --upgrade "datagrunt[pdf]"

Enjoy the new custom profiling control, and happy data engineering!