Metadata-Version: 2.4
Name: framespec
Version: 0.0.3
Summary: Declarative DataFrame specifications for PySpark.
Author: RyPy
License-Expression: MIT
Requires-Dist: pyspark>=4.0.0
Requires-Dist: packaging>=24.0
Requires-Dist: typing-extensions>=4.10.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# framespec

Declarative specifications for PySpark DataFrames.

Define frame-level metadata and column contracts in one place, then bind them
into a Spark schema and typed column references.

## Installation

```bash
pip install framespec
```

## Example

```py
from typing import final

from framespec import FrameSpec, framespec, spec
from framespec import colspecs as C


@spec
class TableSpec(FrameSpec):
    name: str


@final
@framespec
class Customer:
    spec = TableSpec(name="customers")

    customer_id = C.Integer(nullable=False)
    name = C.String(min_length=1)


# Frame contract
Customer.spec.schema

# Column surfaces
Customer.name == "name"
Customer.name.spec.min_length
Customer.name.col.isNull()
df.select(Customer.name)
```

## Mental model

| Access | Meaning |
|---|---|
| `@spec` | Define a frozen contract type |
| `@framespec` | Bind a frame spec and its columns |
| `Customer.spec` | Frame-level contract |
| `Customer.name` | Column name (`str`-like) |
| `Customer.name.spec` | Column contract |
| `Customer.name.col` | Spark `Column` (`F.col(...)`) |

Extend built-in column types (`C.String`, `C.Integer`, …) with `@spec` for
domain-specific constraints. The name `spec` is reserved on declaration
classes for the frame spec.

## License

MIT
