Metadata-Version: 2.4
Name: pyrecords
Version: 0.1.0
Summary: Read records from Excel or JSON, then order, filter (JSON rules) and group them.
Keywords: records,excel,json,filter,order-by,group-by
Author: aaltatan
Author-email: aaltatan <a.altatan@gmail.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pyordering>=0.1.3
Requires-Dist: pyspecification>=4.0.0
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/aaltatan/pyrecords
Project-URL: Repository, https://github.com/aaltatan/pyrecords
Project-URL: Issues, https://github.com/aaltatan/pyrecords/issues
Description-Content-Type: text/markdown

# pyrecords

Read records (`list[dict]`) from Excel or JSON, then order, filter and group them. Extracted
from [templify](https://github.com/aaltatan/templify) so other CLIs can share it.

```bash
uv add pyrecords
```

```python
from pathlib import Path
from pyrecords import OrderByKey, filter_data, get_compiler, group_by_data, order_by_data, readers

data = readers["xlsx"](Path("people.xlsx"))  # first row = column names

data = order_by_data(data, [OrderByKey("city"), OrderByKey("-age")])  # "-" = descending

data = filter_data(data, get_compiler(), {"name": "int__gt", "args": ["age", "30"]})

groups = group_by_data(data, ["city"])  # [{"city": "Homs", "items": [...]}, ...]
```

| Module | What it does |
| --- | --- |
| `readers` | `readers` (`xlsx`, `json` → list of records) and `object_readers` (`json` → one record), picked by extension |
| `transformers` | `order_by_data` (via [pyordering](https://github.com/aaltatan/pyordering); empty values last), `filter_data`, `group_by_data` |
| `filter_rules` | `rules`: a [pyspecification](https://github.com/aaltatan/pyspecification) registry of `int__gt`, `string__icontains`, `date__ge`, ... and `get_compiler()` for `all` / `any` filter schemas |

Add a reader for another extension:

```python
@readers.reader("csv")
def read_csv(filepath: Path) -> Data: ...
```
