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.
Metadata
Release files for csvdir 0.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| csvdir-0.9.0.tar.gz | 21.5 kB | Without provenance | Details for csvdir-0.9.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| csvdir-0.9.0-py3-none-any.whl | Python 3 | none | any | Details for csvdir-0.9.0-py3-none-any.whl |
Total release size: 42.4 kB
Release files / csvdir-0.9.0.tar.gz
| Download URL | csvdir-0.9.0.tar.gz |
|---|---|
| Size | 21.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
af1fa64f6737566c18b13759d1d125b85accc15b407f840a8398a2bed3780289
|
|
BLAKE2b-256 checksum How to use checksums |
cf84d39f16ac2ab80205bfe6032361c7b0b8e22182f83b14df00aed185bdebcf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / csvdir-0.9.0-py3-none-any.whl
| Download URL | csvdir-0.9.0-py3-none-any.whl |
|---|---|
| Size | 20.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5a650f1faf5b835ffc5cd559b2d44718ccc80df27e81be62cb5fcdf56c2502aa
|
|
BLAKE2b-256 checksum How to use checksums |
ebd3accae36db53de0ee811b03ca1e266c5314068f4547eb1b0cf59a8aa5ed7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for csvdir 0.9.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.