Metadata-Version: 2.4
Name: pyivt
Version: 0.0.6
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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 :: Rust
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Dist: pyarrow>=14
License-File: LICENSE
Summary: Read Statistics Canada Beyond 20/20 .ivt tables: metadata and Apache Arrow export
Keywords: arrow,beyond-2020,ivt,pyarrow,statcan,statistics-canada
Author: Nate Babyak
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/natebabyak/pyivt/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/natebabyak/pyivt
Project-URL: Issues, https://github.com/natebabyak/pyivt/issues
Project-URL: Repository, https://github.com/natebabyak/pyivt.git

# pyivt

Read Statistics Canada Beyond 20/20 (`.ivt`) files in Python. Inspect bilingual metadata and export data to Apache Arrow or Parquet.

pyivt is unstable until version 0.1.0. Its public API and output schemas may change between earlier releases.

## Install

```sh
pip install pyivt
```

With uv, run `uv add pyivt`. The package requires Python 3.10 or later.

## Open a file and export it

```python
import pyarrow.parquet as pq
import pyivt

ivt = pyivt.open("data.ivt")
print(ivt.metadata.title.en or ivt.metadata.title.fr)

table, members = ivt.to_arrow()
pq.write_table(table, "data.parquet")
members.to_json("data.members.json")
```

`pyivt.open()` also accepts bytes or a binary file object. For a download, pass the response bytes.

The table has one label column per dimension and a numeric `value` column. Keep the JSON with the export to retain native member codes and attributes.

## Read metadata

```python
meta = ivt.metadata

print(meta.title.en, meta.title.fr)
for dimension in meta.dimensions:
    print(dimension.name.en, dimension.items)
```

Use `.en` or `.fr` for localized fields. Missing translations are `None`. You can inspect metadata without exporting cells.

## Select members

```python
axis = ivt.layout.slugs[0]
subset, subset_members = ivt.to_arrow({axis: [1]})
```

Keys are dimension slugs and values are 1-based member codes. An omitted dimension keeps all its rows and leaves out its column. The export does not aggregate values.

## Documentation

- [Usage guide](docs/usage.md) for metadata, member maps, pandas, and Polars.
- [Development guide](docs/development.md) for tests and benchmarks.

## License

[MIT](LICENSE)

## Acknowledgements

- [canivt](https://github.com/mountainMath/canivt)
- [REA](https://github.com/morluto/rea)

