fastpycsv 5.2.0__cp313-cp313-win_amd64.whl

fastpycsv/__init__.py

@@ -0,0 +1,71 @@
+import importlib.machinery as _machinery
+import importlib.util as _util
+import os as _os
+import sys as _sys
+
+__path__ = [_os.path.dirname(__file__)]
+
+
+def _load_native_module():
+    module_name = __name__ + ".fastpycsv"
+    existing = _sys.modules.get(module_name)
+    if existing is not None:
+        return existing
+
+    for suffix in _machinery.EXTENSION_SUFFIXES:
+        path = _os.path.join(__path__[0], "fastpycsv" + suffix)
+        if not _os.path.exists(path):
+            continue
+
+        spec = _util.spec_from_file_location(module_name, path)
+        if spec is None or spec.loader is None:
+            continue
+
+        module = _util.module_from_spec(spec)
+        _sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+        return module
+
+    raise ImportError("cannot find the fastpycsv native extension next to the Python package")
+
+
+_native = _load_native_module()
+
+CSVFileInfo = _native.CSVFileInfo
+DataType = _native.DataType
+Field = _native.Field
+Reader = _native.Reader
+Row = _native.Row
+csv_data_types = _native.csv_data_types
+all_of = _native.all_of
+equal = _native.equal
+greater = _native.greater
+greater_equal = _native.greater_equal
+get_file_info = _native.get_file_info
+less = _native.less
+less_equal = _native.less_equal
+parse_no_header = _native.parse_no_header
+from ._numpy import read_numpy, read_numpy_batches
+from ._reader import reader
+from ._writer import write_csv
+
+__all__ = [
+    "CSVFileInfo",
+    "DataType",
+    "Field",
+    "Reader",
+    "Row",
+    "all_of",
+    "csv_data_types",
+    "equal",
+    "greater",
+    "greater_equal",
+    "get_file_info",
+    "less",
+    "less_equal",
+    "parse_no_header",
+    "read_numpy",
+    "read_numpy_batches",
+    "reader",
+    "write_csv",
+]

fastpycsv/_format.py

@@ -0,0 +1,40 @@
+"""CSVFormat construction helpers for the public Python facade."""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+from .fastpycsv import Format as _NativeFormat
+from .fastpycsv import VariableColumnPolicy as _NativeVariableColumnPolicy
+
+
+def _make_format(
+    delimiter: str = ",",
+    quotechar: Optional[str] = '"',
+    doublequote: bool = True,
+    skipinitialspace: bool = False,
+    strict: bool = False,
+    fieldnames: Optional[Sequence[str]] = None,
+    no_header: bool = True,
+) -> _NativeFormat:
+    if len(delimiter) != 1:
+        raise TypeError("delimiter must be a one-character string")
+    if quotechar is not None and len(quotechar) != 1:
+        raise TypeError("quotechar must be a one-character string or None")
+    if not doublequote:
+        raise NotImplementedError("fastpycsv.reader does not support doublequote=False")
+
+    fmt = _NativeFormat().delimiter(delimiter)
+    if no_header:
+        fmt.no_header()
+    if quotechar is None:
+        fmt.quote(False)
+    else:
+        fmt.quote(quotechar)
+    if skipinitialspace:
+        fmt.trim([" "])
+    if strict:
+        fmt.variable_columns(_NativeVariableColumnPolicy.THROW)
+    if fieldnames is not None:
+        fmt.column_names(list(fieldnames))
+    return fmt

fastpycsv/_numpy.py

@@ -0,0 +1,115 @@
+"""NumPy export facade sharing reader() CSV format handling."""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+from ._format import _make_format
+from ._reader import _CSVSource
+from .fastpycsv import _read_numpy as _native_read_numpy
+from .fastpycsv import _read_numpy_batches as _native_read_numpy_batches
+
+
+def _numpy_format(
+    delimiter: str,
+    quotechar: Optional[str],
+    doublequote: bool,
+    skipinitialspace: bool,
+    strict: bool,
+    consume_header: bool,
+    fieldnames: Optional[Sequence[str]],
+):
+    return _make_format(
+        delimiter,
+        quotechar,
+        doublequote,
+        skipinitialspace,
+        strict,
+        fieldnames=fieldnames,
+        no_header=(not consume_header) or fieldnames is not None,
+    )
+
+
+def read_numpy(
+    csvfile,
+    columns=None,
+    *,
+    cast: bool = True,
+    predicate=None,
+    delimiter: str = ",",
+    quotechar: Optional[str] = '"',
+    doublequote: bool = True,
+    skipinitialspace: bool = False,
+    strict: bool = False,
+    consume_header: bool = True,
+    fieldnames: Optional[Sequence[str]] = None,
+):
+    fmt = _numpy_format(
+        delimiter,
+        quotechar,
+        doublequote,
+        skipinitialspace,
+        strict,
+        consume_header,
+        fieldnames,
+    )
+    source = _CSVSource(csvfile)
+    try:
+        return _native_read_numpy(source.name, fmt, columns, cast, predicate)
+    finally:
+        source.cleanup()
+
+
+def read_numpy_batches(
+    csvfile,
+    columns=None,
+    *,
+    predicate=None,
+    cast: bool = True,
+    batch_size: int = 50000,
+    schema: str = "sample",
+    delimiter: str = ",",
+    quotechar: Optional[str] = '"',
+    doublequote: bool = True,
+    skipinitialspace: bool = False,
+    strict: bool = False,
+    consume_header: bool = True,
+    fieldnames: Optional[Sequence[str]] = None,
+):
+    fmt = _numpy_format(
+        delimiter,
+        quotechar,
+        doublequote,
+        skipinitialspace,
+        strict,
+        consume_header,
+        fieldnames,
+    )
+    source = _CSVSource(csvfile)
+    try:
+        reader = _native_read_numpy_batches(source.name, fmt, columns, predicate, cast, batch_size, schema)
+    except Exception:
+        source.cleanup()
+        raise
+    return _NumpyBatchIterator(reader, source)
+
+
+class _NumpyBatchIterator:
+    def __init__(self, reader, source: _CSVSource):
+        self._reader = reader
+        self._source = source
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        try:
+            return next(self._reader)
+        except StopIteration:
+            self._source.cleanup()
+            raise
+
+    def __del__(self):
+        source = getattr(self, "_source", None)
+        if source is not None:
+            source.cleanup()

fastpycsv/_reader.py

@@ -0,0 +1,185 @@
+"""Lazy stdlib-adjacent reader facade over the native fastpycsv extension."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from typing import Iterable, Optional, Sequence
+
+from ._format import _make_format
+from .fastpycsv import _RowsReader
+
+
+def _is_path(value: object) -> bool:
+    return isinstance(value, (str, bytes, os.PathLike))
+
+
+def _at_start(value: object) -> bool:
+    try:
+        return value.tell() == 0
+    except (AttributeError, OSError):
+        return False
+
+
+class _TempCSV:
+    def __init__(self, rows: Iterable[str]):
+        handle = tempfile.NamedTemporaryFile("w", encoding="utf-8", newline="", delete=False)
+        self.name = handle.name
+        with handle:
+            for row in rows:
+                handle.write(row)
+
+    def cleanup(self) -> None:
+        try:
+            os.unlink(self.name)
+        except FileNotFoundError:
+            pass
+
+
+class _CSVSource:
+    def __init__(self, csvfile):
+        self._temp = None
+        self.name = self._filename(csvfile)
+
+    def cleanup(self) -> None:
+        if self._temp is not None:
+            self._temp.cleanup()
+
+    def _filename(self, csvfile) -> str:
+        if _is_path(csvfile):
+            return os.fspath(csvfile)
+        if (
+            hasattr(csvfile, "name")
+            and _is_path(csvfile.name)
+            and not getattr(csvfile, "closed", False)
+            and _at_start(csvfile)
+        ):
+            return os.fspath(csvfile.name)
+
+        self._temp = _TempCSV(csvfile)
+        return self._temp.name
+
+
+class _MaterializedRows:
+    def __init__(self, parent: "_BaseReader", iterator):
+        self._parent = parent
+        self._iterator = iterator
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        try:
+            return next(self._iterator)
+        except StopIteration:
+            self._parent._source.cleanup()
+            raise
+
+    def all(self):
+        try:
+            return self._iterator.all()
+        finally:
+            self._parent._source.cleanup()
+
+    def chunks(self, size: int):
+        if size <= 0:
+            raise ValueError("chunk size must be greater than zero")
+
+        def chunk_iterator():
+            while True:
+                batch = self._iterator.read_chunk(size)
+                if not batch:
+                    self._parent._source.cleanup()
+                    return
+                yield batch
+
+        return chunk_iterator()
+
+
+class _BaseReader:
+    def _init_reader(self, csvfile, fmt, cast: bool, batch_size: int) -> None:
+        self._source = _CSVSource(csvfile)
+        self._iterator = iter(_RowsReader(self._source.name, fmt, cast, batch_size))
+
+    @property
+    def fieldnames(self):
+        return list(self._iterator.fieldnames)
+
+    def get_col_names(self):
+        return self.fieldnames
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        try:
+            row = next(self._iterator)
+        except StopIteration:
+            self._source.cleanup()
+            raise
+        return row
+
+    def filter(self, predicate, *, append: bool = True):
+        if predicate is None:
+            raise TypeError("reader.filter() expects a fastpycsv predicate; create a fresh reader for an unfiltered pass")
+        self._iterator.filter(predicate, append)
+        return self
+
+    def lists(self, columns=None):
+        return _MaterializedRows(self, self._iterator.lists(columns))
+
+    def tuples(self, columns=None):
+        return _MaterializedRows(self, self._iterator.tuples(columns))
+
+    def dicts(self, columns=None):
+        return _MaterializedRows(self, self._iterator.dicts(columns))
+
+    def to_lists(self, columns=None):
+        return self.lists(columns).all()
+
+    def to_tuples(self, columns=None):
+        return self.tuples(columns).all()
+
+    def to_dicts(self, columns=None):
+        return self.dicts(columns).all()
+
+    def __del__(self):
+        source = getattr(self, "_source", None)
+        if source is not None:
+            source.cleanup()
+
+
+class _Reader(_BaseReader):
+    def __init__(
+        self,
+        csvfile,
+        *,
+        delimiter: str = ",",
+        quotechar: Optional[str] = '"',
+        doublequote: bool = True,
+        skipinitialspace: bool = False,
+        strict: bool = False,
+        cast: bool = False,
+        typed: Optional[bool] = None,
+        consume_header: bool = True,
+        fieldnames: Optional[Sequence[str]] = None,
+        batch_size: int = 8192,
+    ):
+        if typed is not None:
+            cast = typed
+        fmt = _make_format(
+            delimiter,
+            quotechar,
+            doublequote,
+            skipinitialspace,
+            strict,
+            fieldnames=fieldnames,
+            no_header=(not consume_header) or fieldnames is not None,
+        )
+        self._init_reader(csvfile, fmt, cast, batch_size)
+
+
+def reader(csvfile, dialect="excel", **fmtparams) -> _Reader:
+    if dialect != "excel":
+        raise NotImplementedError("fastpycsv.reader currently supports only the default excel dialect")
+    return _Reader(csvfile, **fmtparams)

fastpycsv/_writer.py

@@ -0,0 +1,38 @@
+"""CSV writer facade over the native fastpycsv extension."""
+
+from __future__ import annotations
+
+import os
+from typing import Iterable, Optional, Sequence
+
+from . import fastpycsv as _native
+
+
+def write_csv(
+    csvfile,
+    rows: Iterable[object],
+    *,
+    fieldnames: Optional[Sequence[object]] = None,
+    write_header: bool = True,
+    quote_minimal: bool = True,
+) -> None:
+    """Write rows to a CSV file.
+
+    `rows` may contain lazy fastpycsv rows, dictionaries, or ordinary Python
+    iterables. Fields are stringified before writing; `None` becomes an empty
+    CSV field.
+    """
+
+    if hasattr(csvfile, "write"):
+        write = getattr(_native, "_write_csv_filelike", None)
+        if write is None:
+            raise AttributeError("fastpycsv native extension has not been rebuilt with file-like write_csv support")
+
+        write(csvfile, rows, fieldnames, write_header, quote_minimal)
+        return
+
+    write = getattr(_native, "_write_csv", None)
+    if write is None:
+        raise AttributeError("fastpycsv native extension has not been rebuilt with write_csv support")
+
+    write(os.fspath(csvfile), rows, fieldnames, write_header, quote_minimal)

fastpycsv/compat.py

@@ -0,0 +1,5 @@
+"""Compatibility imports for the split fastpycsv Python facade."""
+
+from ._reader import reader
+
+__all__ = ["reader"]

fastpycsv-5.2.0.dist-info/METADATA

@@ -0,0 +1,336 @@
+Metadata-Version: 2.2
+Name: fastpycsv
+Version: 5.2.0
+Summary: Fast ETL-focused CSV parsing for Python, backed by Vince's CSV Parser
+Keywords: csv,parser,etl,dataframe,numpy
+Author: Vincent La
+Maintainer: Vincent La
+License: MIT License
+         
+         Copyright (c) 2017-2026 Vincent La
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+         
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Project-URL: Homepage, https://github.com/vincentlaucsb/csv-parser
+Project-URL: Documentation, https://vincentlaucsb.github.io/csv-parser/python/
+Project-URL: Source, https://github.com/vincentlaucsb/csv-parser
+Project-URL: Issues, https://github.com/vincentlaucsb/csv-parser/issues
+Requires-Python: >=3.9
+Provides-Extra: numpy
+Requires-Dist: numpy>=2; extra == "numpy"
+Provides-Extra: pandas
+Requires-Dist: numpy>=2; extra == "pandas"
+Requires-Dist: pandas; extra == "pandas"
+Description-Content-Type: text/markdown
+
+# fastpycsv
+
+<p align="center">
+  <img src="assets/fastpycsv-logo.png" alt="fastpycsv logo" width="240">
+</p>
+
+`fastpycsv` is a fast Python CSV toolkit backed by Vince's CSV Parser. It is built
+for ETL-style workflows where users need to scan large CSV files, filter rows,
+extract selected columns, materialize NumPy arrays, or write cleaned CSV output
+without routing every job through pandas or pyarrow.
+
+The package is named `fastpycsv`; it does not replace or shadow Python's stdlib
+`csv` module.
+
+Long-form Python documentation lives in `python/docs/` and is written in
+Sphinx/MyST-flavored Markdown so it can be published with Read the Docs later.
+
+Main API:
+
+- `fastpycsv.reader()` yields lazy, list-like row objects over the native parser.
+- `fastpycsv.read_numpy()` exports selected columns as eager NumPy arrays.
+- `fastpycsv.read_numpy_batches()` streams selected columns as bounded-memory NumPy
+  batches.
+- `fastpycsv.write_csv()` streams lazy rows or Python iterables through the native
+  CSV writer.
+
+## Building
+
+Install the local package directly from the repository root:
+
+```powershell
+python -m pip install -e E:\GitHub\csv-parser
+```
+
+For a regular non-editable local install:
+
+```powershell
+python -m pip install E:\GitHub\csv-parser
+```
+
+The package build uses CMake through `scikit-build-core` and builds the native
+`fastpycsv` extension for the Python interpreter running `pip`.
+
+Build the extension with `BUILD_PYTHON=ON`:
+
+```powershell
+cmake -S . -B build/fastpycsv -DBUILD_PYTHON=ON -DCMAKE_BUILD_TYPE=Release
+cmake --build build/fastpycsv --target fastpycsv --config Release
+```
+
+For an existing top-level build configured without `BUILD_PYTHON=ON`, build the
+`fastpycsv` target directly. It bootstraps a separate `build/fastpycsv` tree with
+`BUILD_PYTHON=ON`, so the main build does not need to be reconfigured:
+
+```powershell
+cmake --build build/x64-Release --target fastpycsv --config Release
+```
+
+To force a specific interpreter, configure the main build with:
+
+```powershell
+cmake -S . -B build/x64-Release -DFASTPYCSV_BOOTSTRAP_PYTHON_EXECUTABLE=C:/Python314/python.exe
+```
+
+The `fastpycsv` build fetches nanobind with CMake `FetchContent` only when the
+Python binding is requested. A normal C++ library/test build does not require
+the nanobind checkout.
+
+## Reader API
+
+Use `fastpycsv.reader()` for lazy row objects. By default, it consumes the first row
+as column names:
+
+```python
+import fastpycsv
+
+with open("data.csv", newline="", encoding="utf-8") as handle:
+    for row in fastpycsv.reader(handle):
+        assert isinstance(row["name"], str)
+        values = row.as_list()  # Materialize explicitly when needed.
+```
+
+Pass `consume_header=False` when the first input row should be emitted as data:
+
+```python
+with open("headerless.csv", newline="", encoding="utf-8") as handle:
+    for row in fastpycsv.reader(handle, consume_header=False):
+        print(row[0])
+```
+
+Call `row.as_dict()` only when you explicitly want to materialize a row as a
+plain Python dictionary.
+
+When plain Python row objects are the desired output, use the materialized row
+iterators instead of converting each lazy row manually:
+
+```python
+predicate = fastpycsv.all_of(
+    fastpycsv.equal("region", "el paso", case_sensitive=False),
+    fastpycsv.less("price", "15000"),
+)
+reader = fastpycsv.reader("data.csv").filter(predicate)
+
+for row in reader.lists(["id", "price"]):
+    ...
+
+for batch in fastpycsv.reader("data.csv").dicts(["id", "price"]).chunks(50_000):
+    ...
+
+rows = fastpycsv.reader("data.csv").tuples(["id", "price"]).all()
+```
+
+The `.lists()`, `.tuples()`, and `.dicts()` iterators stream one row at a time.
+Their `.chunks(size)` methods keep memory bounded while amortizing native
+conversion overhead, and `.all()` is the eager bulk-export path. Native
+`reader.filter(predicate)` uses the same `fastpycsv.equal()`, `less()`, `greater()`,
+and `all_of()` predicate objects as the NumPy APIs, and validates predicate
+column names before rows are consumed.
+
+Most users can ignore `reader(batch_size=...)`. It does not make ordinary
+iteration return batches:
+
+```python
+for row in fastpycsv.reader("data.csv"):
+    ...  # one row at a time
+```
+
+Use `.chunks(size)` when you want Python lists of rows. `batch_size` only tunes
+how many rows fastpycsv asks the native parser to process at once while doing
+filtered or projected materialization, such as `.filter(...).dicts(...).all()`.
+The default is a good starting point; change it only after benchmarking a large
+filtered export.
+
+Use `fastpycsv.write_csv()` to stream lazy rows or ordinary Python iterables back
+out through csv-parser's native writer:
+
+```python
+reader = fastpycsv.reader("vehicles.csv")
+
+fastpycsv.write_csv(
+    "cheap_el_paso_fords.csv",
+    (row for row in reader if row["region"] == "el paso" and row["manufacturer"] == "ford"),
+    fieldnames=["id", "price", "year", "region"],
+)
+```
+
+Dictionary rows infer their header from the first row when `fieldnames` is not
+provided. `None` is written as an empty field; all other Python field values are
+stringified.
+
+Pass `cast=True` only when you want csv-parser's scalar classification exposed
+as Python values. Empty fields become `None`, boolean fields become `bool`,
+integral fields become `int`, floating point fields become `float`, timestamp
+fields become `datetime.datetime`, and all other fields remain `str`.
+
+```python
+reader = fastpycsv.reader(["id,amount,active\n", "1,2.5,true\n"], cast=True)
+rows = list(reader)
+assert reader.fieldnames == ["id", "amount", "active"]
+assert rows[0].as_list() == [1, 2.5, True]
+```
+
+Use `fastpycsv.read_numpy(path, columns=None, *, cast=True, predicate=None)` when
+you want eager column arrays suitable for pandas:
+
+```python
+import pandas as pd
+
+frame = pd.DataFrame(fastpycsv.read_numpy("data.csv"))
+```
+
+`read_numpy()` returns a `dict` keyed by column name. String columns use NumPy
+2.x `StringDType`, nullable numeric and boolean columns widen to `float64` with
+`NaN`, and non-null integer, float, and boolean columns use dense NumPy arrays.
+It does not produce object arrays. The C++ export path batches rows through
+`DataFrame` column views and `DataFrameExecutor`; remaining fixed costs are
+mostly NumPy `StringDType` construction for string-heavy data and pandas'
+DataFrame materialization after the arrays have been built.
+
+Use `fastpycsv.read_numpy_batches(path, columns=None, *, predicate=None, cast=True,
+batch_size=50000, schema="sample")` when you want streaming dictionaries of
+NumPy arrays instead of one eager full-file result. `schema="sample"` infers
+dtypes from the first bounded batch and then streams once, `schema="global"`
+does a full pre-scan for stable dtypes matching `read_numpy()`, and
+`schema="batch"` infers each emitted batch independently for true one-pass
+bounded-memory streaming. With `cast=False`, batches are string-only and skip
+schema inference. Explicit `dtypes={column: dtype}` overrides are not implemented
+yet and are tracked as a follow-up.
+
+For simple row filters, create native predicates and pass them to
+`read_numpy()` or `read_numpy_batches()`:
+
+```python
+predicate = fastpycsv.equal("region", "el paso", case_sensitive=False)
+arrays = fastpycsv.read_numpy("vehicles.csv", columns=["price", "year"], predicate=predicate)
+```
+
+The facade supports the common `delimiter`, `quotechar`, `doublequote=True`,
+`skipinitialspace`, `strict`, `consume_header`, and `fieldnames` options.
+Unsupported dialect features intentionally fail fast instead of silently
+diverging from stdlib behavior.
+
+Lower-level extension objects remain available where they have a clear Python
+use, but `fastpycsv` intentionally keeps C++ configuration machinery out of the
+stable Python facade.
+
+## Benchmarks
+
+To compare reader throughput locally:
+
+```powershell
+python python/benchmarks/compare_readers.py path/to/input.csv
+```
+
+To compare the streaming EDA script against pandas using the pyarrow CSV engine:
+
+```powershell
+python python/benchmarks/compare_eda.py path/to/input.csv
+```
+
+To compare a streaming `fastpycsv` filter against pyarrow on the Used Cars-style
+`region == "el paso"` workload:
+
+```powershell
+python python/benchmarks/compare_filter.py path/to/vehicles.csv
+```
+
+To compare selected-column CSV-to-NumPy materialization against pyarrow:
+
+```powershell
+python python/benchmarks/compare_numpy_materialization.py path/to/vehicles.csv
+```
+
+To compare ordinary Python object materialization against pyarrow and Polars:
+
+```powershell
+python python/benchmarks/compare_python_materialization.py path/to/vehicles.csv
+```
+
+This compares full CSV and first+last-column subset materialization for
+row-oriented `list[dict]` outputs and column-oriented `dict[str, list]` outputs.
+
+The NumPy benchmark includes pyarrow's direct CSV reader, Dataset/Scanner path,
+streaming CSV reader, and Polars lazy scanning. The Dataset row is pyarrow's
+closest API for parallel predicate/projection work, but it can require explicit
+column types: otherwise pyarrow may infer a narrow integer type from early rows
+and later fail on wider values. The benchmark pins obvious numeric columns such
+as `price`, `year`, and `odometer` so the comparison measures throughput instead
+of schema-inference failure handling.
+
+This runs each workload in a fresh Python process and reports wall time,
+throughput, and peak resident/working-set memory.
+
+The benchmark helper searches `build/` and `out/` for a compatible built
+`fastpycsv` extension and errors clearly if it is missing. Use the same Python
+version that built `fastpycsv`; a `cp310` extension, for example, will not import
+under Python 3.14.
+
+The benchmark matrix compares stdlib `csv.reader`, lazy `fastpycsv.reader` rows with
+strings, lazy `fastpycsv.reader` rows with `cast=True`, stdlib `csv.DictReader`, raw
+`fastpycsv.read_numpy()` array export, and `pandas.DataFrame(fastpycsv.read_numpy(...))`.
+It reports file path, size, rows, columns, elapsed seconds, MiB/s, and rows/s.
+
+## Exploratory Summary
+
+For a small dependency-free EDA pass over a CSV:
+
+```powershell
+python python/examples/eda_summary.py path/to/input.csv
+```
+
+The script streams lazy `fastpycsv` rows once and reports per-column mean, sample
+standard deviation, null count, and top observed values. Histograms use a
+bounded approximate heavy-hitter sketch by default to keep memory usage stable
+on high-cardinality columns. Use `--top-n N` to change the report size,
+`--top-capacity N` to change the per-column sketch size, `--exact-values` for
+exact value counts, or `--no-header` for headerless files.

fastpycsv-5.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+fastpycsv/__init__.py,sha256=KXGyFcQFPW28TzYWcPXq43n9sFrIwOtkwLzFq-zcuUo,1819
+fastpycsv/_format.py,sha256=iGb0F-dj29GiGjmY3NDBrsCUwxxgJ7EnLHGnWC1mIq8,1311
+fastpycsv/_numpy.py,sha256=Y0M4pxvJtdY5n8zT7f-_gjnQ28FdAI5eH9jGZIXIEFc,2874
+fastpycsv/_reader.py,sha256=bdg_fgWY4j_NykD384tNWemwv7DPPOfttDi_QBfpOtA,5264
+fastpycsv/_writer.py,sha256=1bQ6-cvJe-NcL31W87J56vVh2rGX25EMEpHUQMumdpc,1211
+fastpycsv/compat.py,sha256=a2kGFJzFiNScOKwXFZrV5iwbY-7dviYEuMBhAQY1nCM,123
+fastpycsv/fastpycsv.cp313-win_amd64.pyd,sha256=PSBAfePOpO5YshSvxayy_TtNfjpS5ygejLEYRKsrUMQ,619008
+fastpycsv-5.2.0.dist-info/METADATA,sha256=pfyAoo-2KiwE_X4VSmKHYSWBKrM4L1EdjVJFekzdqTU,13452
+fastpycsv-5.2.0.dist-info/WHEEL,sha256=UZrbbE4r80xj7Ncfa6JoeTVe-77bdXLkKUA63V8pKWQ,106
+fastpycsv-5.2.0.dist-info/licenses/LICENSE,sha256=SxqZ9a3mGockrO5T6dlEi7rehS2hmC5C6Afd3jhdMLE,1093
+fastpycsv-5.2.0.dist-info/RECORD,,

fastpycsv-5.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 0.12.2
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_amd64
+

fastpycsv-5.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2026 Vincent La
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.