Metadata-Version: 2.4
Name: fs-schema
Version: 0.4.5
Summary: Strongly typed Python schemas for binding and validating filesystem layouts
Keywords: filesystem,schema,pathlib,typed,layout
Author: HeyEntropyYield
License-Expression: MIT
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.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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: beartype>=0.23.0rc1
Requires-Dist: glom
Requires-Dist: parse
Requires-Dist: typing-extensions>=4.10
Requires-Dist: mashumaro>=3.22 ; extra == 'mashumaro'
Requires-Dist: mashumaro[msgpack]>=3.22 ; extra == 'msgpack'
Requires-Dist: mashumaro[orjson]>=3.22 ; extra == 'orjson'
Requires-Dist: mashumaro[toml]>=3.22 ; extra == 'toml'
Requires-Dist: mashumaro[yaml]>=3.22 ; extra == 'yaml'
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/HeyEntropyYield/fs-schema
Project-URL: Repository, https://github.com/HeyEntropyYield/fs-schema
Project-URL: Issues, https://github.com/HeyEntropyYield/fs-schema/issues
Provides-Extra: mashumaro
Provides-Extra: msgpack
Provides-Extra: orjson
Provides-Extra: toml
Provides-Extra: yaml
Description-Content-Type: text/markdown

# fs-schema

Typed schemas for filesystem layouts. Dataclass-like declarations turn directory
contracts into validated, navigable Python values.

```bash
uv add "fs-schema[mashumaro,orjson]"
```

```python
from dataclasses import dataclass

import fs_schema as fss

@dataclass
class Contents:
    title: str

class DataDownload(fss.Schema):
    schema = {
        "packs": {
            fss.FILES: ["upload.log", "request.log"],
            fss.Dir(alias="days", fmt="{day:%Y-%m-%d}"): {
                "parts": fss.File(fmt="{stem}.{ext}", max=4),
            },
        },
        "contents": fss.File("contents.json", schema=Contents),
    }

download = fss.raise_mismatch(DataDownload.bind("."))
with open(download.packs.upload_log, encoding="utf-8") as stream:
    print(stream.read())
part = download.packs.days[-1].parts[-1]
print(part.kwargs.stem, part.path.stat().st_size)
contents: Contents = fss.raise_exn(download.contents.load())
print(contents.title)
```

Binding validates an existing layout. Templates are collections; indexing selects
a concrete match whose parsed captures are available through `.args` and
`.kwargs`. `relative_to()` plans output paths without claiming they exist.
Format-backed collections plan concrete files or recursively navigable
directories; only the top-level plan binds the whole schema. Dataclass schemas
use Mashumaro for JSON; install the `mashumaro` or faster `orjson` extra.

<details>
<summary>Expanded quickstart</summary>

```python
--8<-- "examples/quickstart.py"
```

</details>

<details>
<summary>Development</summary>

```text
--8<-- "docs/run-help.txt"
```

</details>

[API reference](https://heyentropyyield.github.io/fs-schema/reference/) ·
[Tutorial](https://heyentropyyield.github.io/fs-schema/tutorial/) ·
[Source](https://github.com/HeyEntropyYield/fs-schema) ·
[MIT LICENSE](https://heyentropyyield.github.io/fs-schema/LICENSE)
