csvdir 0.9.0

Read all csv files in a directory with one iterator.

csvdir

Read every CSV in a directory as one stream of rows. No manual file loops, no header surprises — discovery, encoding, chunking, and optional pandas integration.

Documentation (primary): csvdir.readthedocs.io — getting started, guides, configuration, API reference, and changelog.

At a glance

Without csvdir	With csvdir
Loop glob + open per file	read_dir("/data") yields every row
Header drift breaks pipelines	strict_headers / on_mismatch="skip"
Load huge dirs into memory	chunksize= streams list[dict] batches
Awkward pandas glue code	CsvDirFile works with pandas.read_csv

Includes: row and chunked iterators, .with_names() / .with_paths(), column helpers, recursive discovery, per-file encoding and quote sniffing. Dict iterators compare header names as sets; CsvDirFile (pandas) stitches using header sequence and sorted path order — see docs.

Requirements

Python 3.10+. No runtime dependencies (pandas optional for CsvDirFile).

Install

pip install csvdir

From a clone (contributors):

git clone https://github.com/eddiethedean/csvdir.git
cd csvdir
pip install -e ".[dev]"

Quick start

from csvdir import read_dir

for row in read_dir("/data/csvs"):
    print(row)

for stem, row in read_dir("/data/csvs").with_names():
    print(stem, row["name"])

More patterns (headers, chunks, columns, pandas) are in the guides on Read the Docs.

Documentation map

Start here	Read the Docs
Install & mental model	Getting started
Feature guides	Guides overview
Every read_dir option	Configuration
Autodoc	API reference
Release history	Changelog

Design files remain in docs/ in the repo; the site above is the supported reading path for releases.

Contributing

pip install -e ".[dev,docs]"
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest
ruff check csvdir tests && ruff format --check csvdir tests
mypy
python -m mkdocs build --strict

CI runs the same checks on Python 3.10–3.13. See Development on RTD.

License

MIT — LICENSE.