framespec 0.0.1__tar.gz → 0.0.3__tar.gz

framespec-0.0.3/PKG-INFO

@@ -0,0 +1,76 @@
+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

framespec-0.0.3/README.md

@@ -0,0 +1,64 @@
+# 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

framespec-0.0.3/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "framespec"
+version = "0.0.3"
+description = "Declarative DataFrame specifications for PySpark."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+dependencies = [
+    "pyspark >= 4.0.0",
+    "packaging >= 24.0",
+    "typing-extensions >= 4.10.0",
+]
+
+[[project.authors]]
+name = "RyPy"
+
+[dependency-groups]
+dev = [
+    "basedpyright >= 1.29.0",
+    "pytest >= 8.0",
+    "pytest-cov >= 5.0",
+    "mypy >= 1.10",
+    "ruff >= 0.5.0",
+]
+
+[build-system]
+requires = ["uv-build"]
+build-backend = "uv_build"
+
+[tool.basedpyright]
+reportUnannotatedClassAttribute = "none"

framespec-0.0.3/pyproject.toml.orig

@@ -0,0 +1,30 @@
+[project]
+name = "framespec"
+version = "0.0.3"
+description = "Declarative DataFrame specifications for PySpark."
+readme = "README.md"
+authors = [{ name = "RyPy" }]
+requires-python = ">=3.12"
+license = "MIT"
+
+dependencies = [
+    "pyspark >= 4.0.0",
+    "packaging >= 24.0",
+    "typing-extensions >= 4.10.0",
+]
+
+[dependency-groups]
+dev = [
+    "basedpyright >= 1.29.0",
+    "pytest >= 8.0",
+    "pytest-cov >= 5.0",
+    "mypy >= 1.10",
+    "ruff >= 0.5.0",
+]
+
+[build-system]
+requires = ["uv-build"]
+build-backend = "uv_build"
+
+[tool.basedpyright]
+reportUnannotatedClassAttribute = "none"

framespec-0.0.3/src/framespec/__init__.py

@@ -0,0 +1,12 @@
+from . import colspecs
+from .decorator import framespec
+from .spec import ColRef, ColSpec, FrameSpec, spec
+
+__all__ = [
+    "ColRef",
+    "ColSpec",
+    "FrameSpec",
+    "colspecs",
+    "framespec",
+    "spec",
+]

framespec-0.0.3/src/framespec/colspecs.py

@@ -0,0 +1,451 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import field
+from typing import override
+
+from pyspark.sql import types as T
+
+from .spec import ColRef, ColSpec, spec
+
+type NestedDType = ColSpec | ColRef[ColSpec] | T.DataType
+
+
+def _resolve_dtype(element: NestedDType) -> T.DataType:
+    if isinstance(element, ColSpec):
+        return element.dtype
+    if isinstance(element, ColRef):
+        return element.spec.dtype
+    return element
+
+
+def _validate_non_negative(name: str, value: int | None) -> None:
+    if value is not None and value < 0:
+        raise ValueError(f"{name} cannot be negative")
+
+
+def _validate_integral_bounds(
+    *,
+    min_value: int | None,
+    max_value: int | None,
+    exclusive_min: int | None,
+    exclusive_max: int | None,
+) -> None:
+    if min_value is not None and max_value is not None and min_value > max_value:
+        raise ValueError("min_value cannot be greater than max_value")
+
+    if (
+        exclusive_min is not None
+        and exclusive_max is not None
+        and exclusive_min >= exclusive_max
+    ):
+        raise ValueError("exclusive_min must be less than exclusive_max")
+
+
+def _validate_fractional_bounds(
+    *,
+    min_value: float | None,
+    max_value: float | None,
+    exclusive_min: float | None,
+    exclusive_max: float | None,
+) -> None:
+    if min_value is not None and max_value is not None and min_value > max_value:
+        raise ValueError("min_value cannot be greater than max_value")
+
+    if (
+        exclusive_min is not None
+        and exclusive_max is not None
+        and exclusive_min >= exclusive_max
+    ):
+        raise ValueError("exclusive_min must be less than exclusive_max")
+
+
+# --- String ------------------------------------------------------------------
+
+
+@spec
+class String(ColSpec):
+    min_length: int | None = None
+    max_length: int | None = None
+    allowed_values: tuple[str, ...] | None = None
+    pattern: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.allowed_values is not None:
+            object.__setattr__(self, "allowed_values", tuple(self.allowed_values))
+
+        _validate_non_negative("min_length", self.min_length)
+        _validate_non_negative("max_length", self.max_length)
+
+        if (
+            self.min_length is not None
+            and self.max_length is not None
+            and self.min_length > self.max_length
+        ):
+            raise ValueError("min_length cannot be greater than max_length")
+
+        super().__post_init__()
+
+    @property
+    @override
+    def dtype(self) -> T.StringType:
+        return T.StringType()
+
+
+@spec
+class Char(ColSpec):
+    length: int = 1
+
+    def __post_init__(self) -> None:
+        if self.length < 1:
+            raise ValueError("length must be at least 1")
+
+        super().__post_init__()
+
+    @property
+    @override
+    def dtype(self) -> T.CharType:
+        return T.CharType(self.length)
+
+
+@spec
+class Varchar(ColSpec):
+    length: int = 1
+
+    def __post_init__(self) -> None:
+        if self.length < 1:
+            raise ValueError("length must be at least 1")
+
+        super().__post_init__()
+
+    @property
+    @override
+    def dtype(self) -> T.VarcharType:
+        return T.VarcharType(self.length)
+
+
+# --- Boolean -----------------------------------------------------------------
+
+
+@spec
+class Boolean(ColSpec):
+    @property
+    @override
+    def dtype(self) -> T.BooleanType:
+        return T.BooleanType()
+
+
+# --- Binary ------------------------------------------------------------------
+
+
+@spec
+class Binary(ColSpec):
+    min_length: int | None = None
+    max_length: int | None = None
+    content_encoding: str | None = None
+    content_media_type: str | None = None
+
+    def __post_init__(self) -> None:
+        _validate_non_negative("min_length", self.min_length)
+        _validate_non_negative("max_length", self.max_length)
+
+        if (
+            self.min_length is not None
+            and self.max_length is not None
+            and self.min_length > self.max_length
+        ):
+            raise ValueError("min_length cannot be greater than max_length")
+
+        super().__post_init__()
+
+    @property
+    @override
+    def dtype(self) -> T.BinaryType:
+        return T.BinaryType()
+
+
+# --- Numeric -----------------------------------------------------------------
+
+
+@spec
+class _IntegralColSpec(ColSpec, ABC):
+    min_value: int | None = None
+    max_value: int | None = None
+    exclusive_min: int | None = None
+    exclusive_max: int | None = None
+    multiple_of: int | None = None
+
+    def __post_init__(self) -> None:
+        _validate_integral_bounds(
+            min_value=self.min_value,
+            max_value=self.max_value,
+            exclusive_min=self.exclusive_min,
+            exclusive_max=self.exclusive_max,
+        )
+
+        if self.multiple_of is not None and self.multiple_of <= 0:
+            raise ValueError("multiple_of must be positive")
+
+        super().__post_init__()
+
+    @property
+    @abstractmethod
+    @override
+    def dtype(self) -> T.DataType: ...
+
+
+@spec
+class Byte(_IntegralColSpec):
+    @property
+    @override
+    def dtype(self) -> T.ByteType:
+        return T.ByteType()
+
+
+@spec
+class Short(_IntegralColSpec):
+    @property
+    @override
+    def dtype(self) -> T.ShortType:
+        return T.ShortType()
+
+
+@spec
+class Integer(_IntegralColSpec):
+    @property
+    @override
+    def dtype(self) -> T.IntegerType:
+        return T.IntegerType()
+
+
+@spec
+class Long(_IntegralColSpec):
+    @property
+    @override
+    def dtype(self) -> T.LongType:
+        return T.LongType()
+
+
+@spec
+class _FractionalColSpec(ColSpec, ABC):
+    min_value: float | None = None
+    max_value: float | None = None
+    exclusive_min: float | None = None
+    exclusive_max: float | None = None
+    multiple_of: float | None = None
+
+    def __post_init__(self) -> None:
+        _validate_fractional_bounds(
+            min_value=self.min_value,
+            max_value=self.max_value,
+            exclusive_min=self.exclusive_min,
+            exclusive_max=self.exclusive_max,
+        )
+
+        if self.multiple_of is not None and self.multiple_of <= 0:
+            raise ValueError("multiple_of must be positive")
+
+        super().__post_init__()
+
+    @property
+    @abstractmethod
+    @override
+    def dtype(self) -> T.DataType: ...
+
+
+@spec
+class Float(_FractionalColSpec):
+    @property
+    @override
+    def dtype(self) -> T.FloatType:
+        return T.FloatType()
+
+
+@spec
+class Double(_FractionalColSpec):
+    @property
+    @override
+    def dtype(self) -> T.DoubleType:
+        return T.DoubleType()
+
+
+@spec
+class Decimal(ColSpec):
+    precision: int = 10
+    scale: int = 0
+    min_value: float | None = None
+    max_value: float | None = None
+    exclusive_min: float | None = None
+    exclusive_max: float | None = None
+    multiple_of: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.precision < 1:
+            raise ValueError("precision must be at least 1")
+
+        if self.scale < 0:
+            raise ValueError("scale cannot be negative")
+
+        if self.scale > self.precision:
+            raise ValueError("scale cannot be greater than precision")
+
+        _validate_fractional_bounds(
+            min_value=self.min_value,
+            max_value=self.max_value,
+            exclusive_min=self.exclusive_min,
+            exclusive_max=self.exclusive_max,
+        )
+
+        if self.multiple_of is not None and self.multiple_of <= 0:
+            raise ValueError("multiple_of must be positive")
+
+        super().__post_init__()
+
+    @property
+    @override
+    def dtype(self) -> T.DecimalType:
+        return T.DecimalType(self.precision, self.scale)
+
+
+# --- Temporal ----------------------------------------------------------------
+
+
+@spec
+class _TemporalColSpec(ColSpec, ABC):
+    minimum: str | None = None
+    maximum: str | None = None
+    format: str | None = None
+
+    @property
+    @abstractmethod
+    @override
+    def dtype(self) -> T.DataType: ...
+
+
+@spec
+class Date(_TemporalColSpec):
+    @property
+    @override
+    def dtype(self) -> T.DateType:
+        return T.DateType()
+
+
+@spec
+class Timestamp(_TemporalColSpec):
+    @property
+    @override
+    def dtype(self) -> T.TimestampType:
+        return T.TimestampType()
+
+
+@spec
+class TimestampNTZ(_TemporalColSpec):
+    @property
+    @override
+    def dtype(self) -> T.TimestampNTZType:
+        return T.TimestampNTZType()
+
+
+# --- Collection --------------------------------------------------------------
+
+
+@spec
+class Array(ColSpec):
+    element: NestedDType = field(kw_only=True)  # pyright: ignore[reportAny]
+    contains_null: bool = True
+    min_items: int | None = None
+    max_items: int | None = None
+    unique_items: bool | None = None
+
+    def __post_init__(self) -> None:
+        _validate_non_negative("min_items", self.min_items)
+        _validate_non_negative("max_items", self.max_items)
+
+        if (
+            self.min_items is not None
+            and self.max_items is not None
+            and self.min_items > self.max_items
+        ):
+            raise ValueError("min_items cannot be greater than max_items")
+
+        super().__post_init__()
+
+    @property
+    @override
+    def dtype(self) -> T.ArrayType:
+        return T.ArrayType(_resolve_dtype(self.element), self.contains_null)
+
+
+@spec
+class Map(ColSpec):
+    key: NestedDType = field(kw_only=True)  # pyright: ignore[reportAny]
+    value: NestedDType = field(kw_only=True)  # pyright: ignore[reportAny]
+    value_contains_null: bool = True
+    min_properties: int | None = None
+    max_properties: int | None = None
+
+    def __post_init__(self) -> None:
+        _validate_non_negative("min_properties", self.min_properties)
+        _validate_non_negative("max_properties", self.max_properties)
+
+        if (
+            self.min_properties is not None
+            and self.max_properties is not None
+            and self.min_properties > self.max_properties
+        ):
+            raise ValueError("min_properties cannot be greater than max_properties")
+
+        super().__post_init__()
+
+    @property
+    @override
+    def dtype(self) -> T.MapType:
+        return T.MapType(
+            _resolve_dtype(self.key),
+            _resolve_dtype(self.value),
+            self.value_contains_null,
+        )
+
+
+# --- Interval ----------------------------------------------------------------
+
+
+@spec
+class DayTimeInterval(ColSpec):
+    start_field: int | None = None
+    end_field: int | None = None
+
+    @property
+    @override
+    def dtype(self) -> T.DayTimeIntervalType:
+        return T.DayTimeIntervalType(self.start_field, self.end_field)
+
+
+@spec
+class YearMonthInterval(ColSpec):
+    start_field: int | None = None
+    end_field: int | None = None
+
+    @property
+    @override
+    def dtype(self) -> T.YearMonthIntervalType:
+        return T.YearMonthIntervalType(self.start_field, self.end_field)
+
+
+# --- Other -------------------------------------------------------------------
+
+
+@spec
+class Null(ColSpec):
+    @property
+    @override
+    def dtype(self) -> T.NullType:
+        return T.NullType()
+
+
+@spec
+class Variant(ColSpec):
+    @property
+    @override
+    def dtype(self) -> T.VariantType:
+        return T.VariantType()

framespec-0.0.3/src/framespec/decorator.py

@@ -0,0 +1,21 @@
+from collections.abc import Mapping
+from typing import cast
+
+from .spec import ColSpec, FrameSpec
+
+
+def discover_colspecs(cls: type[object]) -> tuple[ColSpec, ...]:
+    attributes = cast(Mapping[str, object], cls.__dict__)
+    return tuple(value for value in attributes.values() if isinstance(value, ColSpec))
+
+
+def framespec[T](cls: type[T]) -> type[T]:
+    spec = cls.__dict__.get("spec")
+
+    if not isinstance(spec, FrameSpec):
+        raise TypeError(
+            f"{cls.__name__} must define a 'spec' attribute as a FrameSpec instance."
+        )
+
+    object.__setattr__(spec, "_colspecs", discover_colspecs(cls))
+    return cls

framespec-0.0.3/src/framespec/spec.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Self, cast, dataclass_transform
+
+from pyspark.sql import Column
+from pyspark.sql import functions as F
+from pyspark.sql import types as T
+
+type Metadata = Mapping[str, object]
+
+
+@dataclass_transform(frozen_default=True)
+def spec[T](cls: type[T]) -> type[T]:
+    return dataclass(frozen=True, kw_only=True)(cls)
+
+
+class ColRef[T: ColSpec](str):
+    """String-like column name with contract and Spark column accessors."""
+
+    __slots__ = ("_spec",)
+
+    def __new__(cls, name: str, column_spec: T, /) -> Self:
+        instance = str.__new__(cls, name)
+        object.__setattr__(instance, "_spec", column_spec)
+        return instance
+
+    @property
+    def spec(self) -> T:
+        return self._spec
+
+    @property
+    def col(self) -> Column:
+        return F.col(str(self))
+
+
+@spec
+class ColSpec(ABC):
+    nullable: bool = True
+    description: str | None = None
+    metadata: Metadata | None = None
+    name: str | None = field(default=None, init=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if self.metadata is not None:
+            object.__setattr__(
+                self,
+                "metadata",
+                MappingProxyType(dict(self.metadata)),
+            )
+
+    def __set_name__(self, owner: type[object], name: str) -> None:
+        if name == "spec":
+            raise TypeError(
+                f"{owner.__name__} cannot declare a column named 'spec'; that name is reserved for the frame spec."
+            )
+
+        object.__setattr__(self, "name", name)
+
+    def __get__(
+        self,
+        obj: object | None,
+        owner: type[object] | None = None,
+    ) -> ColRef[Self]:
+        if owner is None:
+            raise RuntimeError(
+                f"{type(self).__name__} must be accessed from a declaring class."
+            )
+
+        if self.name is None:
+            raise RuntimeError(
+                f"{type(self).__name__} is not bound to a class attribute."
+            )
+
+        return ColRef(self.name, self)
+
+    @property
+    @abstractmethod
+    def dtype(self) -> T.DataType: ...
+
+    @property
+    def field(self) -> T.StructField:
+        if self.name is None:
+            raise RuntimeError(
+                "ColSpec must be declared as a class attribute before field is accessed."
+            )
+
+        return T.StructField(
+            self.name,
+            self.dtype,
+            self.nullable,
+            dict(self.metadata) if self.metadata else {},
+        )
+
+
+@spec
+class FrameSpec:
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "_colspecs", ())
+
+    @property
+    def colspecs(self) -> tuple[ColSpec, ...]:
+        return cast(
+            tuple[ColSpec, ...],
+            object.__getattribute__(self, "_colspecs"),
+        )
+
+    @property
+    def schema(self) -> T.StructType:
+        return T.StructType([column.field for column in self.colspecs])

framespec-0.0.1/PKG-INFO

@@ -1,38 +0,0 @@
-Metadata-Version: 2.3
-Name: framespec
-Version: 0.0.1
-Summary: Declarative DataFrame specifications for PySpark.
-Author: Ryan
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-
-> 🛠️ Currently under construction...
-
-# framespec
-
-Declarative specifications for PySpark DataFrames.
-
-`framespec` lets you define column types and attach reusable expressions
-that capture validation rules, invariants, and metrics. Specs can be applied
-to any DataFrame—intermediate, transformed, or table-backed.
-
-## Installation
-
-```bash
-pip install framespec
-```
-
-## Example
-
-```py
-from framespec import framespec, Int, Timestamp, greater_than
-
-@framespec
-class Events:
-    start: Timestamp
-    end: Timestamp(expressions=[greater_than(start)])
-```
-
-## License
-
-MIT

framespec-0.0.1/README.md

@@ -1,30 +0,0 @@
-> 🛠️ Currently under construction...
-
-# framespec
-
-Declarative specifications for PySpark DataFrames.
-
-`framespec` lets you define column types and attach reusable expressions
-that capture validation rules, invariants, and metrics. Specs can be applied
-to any DataFrame—intermediate, transformed, or table-backed.
-
-## Installation
-
-```bash
-pip install framespec
-```
-
-## Example
-
-```py
-from framespec import framespec, Int, Timestamp, greater_than
-
-@framespec
-class Events:
-    start: Timestamp
-    end: Timestamp(expressions=[greater_than(start)])
-```
-
-## License
-
-MIT

framespec-0.0.1/pyproject.toml

@@ -1,14 +0,0 @@
-[project]
-name = "framespec"
-version = "0.0.1"
-description = "Declarative DataFrame specifications for PySpark."
-readme = "README.md"
-requires-python = ">=3.12"
-dependencies = []
-
-[[project.authors]]
-name = "Ryan"
-
-[build-system]
-requires = ["uv_build>=0.12.5,<0.13.0"]
-build-backend = "uv_build"

framespec-0.0.1/pyproject.toml.orig

@@ -1,12 +0,0 @@
-[project]
-name = "framespec"
-version = "0.0.1"
-description = "Declarative DataFrame specifications for PySpark."
-readme = "README.md"
-authors = [{ name = "Ryan" }]
-requires-python = ">=3.12"
-dependencies = []
-
-[build-system]
-requires = ["uv_build>=0.12.5,<0.13.0"]
-build-backend = "uv_build"

framespec-0.0.1/src/framespec/__init__.py

@@ -1,2 +0,0 @@
-def main() -> None:
-    print("Hello from framespec!")