Metadata-Version: 2.4
Name: flat-adapter
Version: 0.1.0
Summary: Flatten nested hierarchical data into flat records for database imports.
Project-URL: Homepage, https://github.com/groshevpavel/flat_adapter
Project-URL: Repository, https://github.com/groshevpavel/flat_adapter
Project-URL: Issues, https://github.com/groshevpavel/flat_adapter/issues
Author-email: "Pavel.Groshev" <pavel.groshev@oro.moscow>
License: MIT License
        
        Copyright (c) 2026 Pavel Groshev
        
        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.
License-File: LICENSE
Keywords: adapter,database,etl,flatten,nested-data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: python-dateutil>=2.9.0.post0
Description-Content-Type: text/markdown

# flat-adapter

`flat-adapter` converts nested mappings into deterministic flat rows suitable
for database imports and ETL pipelines.

## Quick start

```python
from flat_adapter import FlatAdapter


class ItemAdapter(FlatAdapter):
    item_id: int
    quantity: int


class OrderAdapter(FlatAdapter):
    order_id: int
    items: list[ItemAdapter]


rows = OrderAdapter.adapt(
    {
        "order_id": "1001",
        "items": [
            {"item_id": "10", "quantity": "2"},
            {"item_id": "20", "quantity": "1"},
        ],
    }
)

assert rows == [
    {"order_id": 1001, "item_id": 10, "quantity": 2},
    {"order_id": 1001, "item_id": 20, "quantity": 1},
]
```

The first release supports `Mapping[str, object]` input, nested mappings,
typed scalar conversion, optional fields, aliases, custom `Field` paths, and
deterministic Cartesian expansion of nested lists. It always returns
`list[dict[str, object]]`.

## Field configuration

Use `typing.Annotated` to attach extraction metadata without a runtime
assignment or a `cast`:

```python
from typing import Annotated

from flat_adapter import Field, FlatAdapter


class CustomerAdapter(FlatAdapter):
    customer_id: Annotated[int, Field(source="payload.customer_id")]
    display_name: Annotated[str, Field(source="payload.name", default="Unknown")]
```

The legacy `name: int = Field(...)` form remains supported at runtime, but
`Annotated` is the preferred form for `mypy --strict` projects.

## Performance and row limits

Depth of seven to ten nested adapters is normally safe; the main cost comes
from Cartesian expansion. For list lengths `L1`, `L2`, ..., the result count
can grow as `product(max(1, len(Li)))`, and the returned rows are materialized
in memory.

Use `max_rows` to fail fast before an expansion becomes too large:

```python
rows = OrderAdapter.adapt(payload, max_rows=10_000)
```

Run the local benchmark scenarios with:

```bash
uv run python benchmarks/flatten_benchmark.py
```

## Development

The project uses [uv](https://docs.astral.sh/uv/) for environments,
dependencies, and lockfile management.

```bash
uv sync
uv run pre-commit install
uv run pre-commit run --all-files
uv run pytest --cov=flat_adapter --cov-report=term-missing
uv run ruff check src tests
uv run mypy --strict src tests
uv build
uv run twine check dist/*
```

## Package layout

```text
src/flat_adapter/  Library package
tests/unit/        Pure behavior tests
docs/              English/Russian guides and promotion notes
benchmarks/        Manual performance scenarios
```

See [CONTEXT.md](CONTEXT.md) for architecture boundaries and
[TECHDEBT.md](TECHDEBT.md) for known risks.

Русская версия руководства: [docs/README.ru.md](docs/README.ru.md).
English guide: [docs/README.en.md](docs/README.en.md).

## Versioning

Releases follow Semantic Versioning. While the package is below `1.0.0`, a
minor release may include a documented contract change; patch releases remain
backward-compatible fixes. `CHANGELOG.md` records user-visible changes.
