zspec 0.1.0__py3-none-any.whl

zspec/__init__.py

@@ -0,0 +1,14 @@
+"""ZSpec — a specification pattern library for Python."""
+
+from zspec.specification import (
+    AndSpecification as AndSpecification,
+)
+from zspec.specification import (
+    NotSpecification as NotSpecification,
+)
+from zspec.specification import (
+    OrSpecification as OrSpecification,
+)
+from zspec.specification import (
+    Specification as Specification,
+)

zspec/specification.py

@@ -0,0 +1,111 @@
+"""Specification pattern — composable business rule objects."""
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from functools import reduce
+from operator import and_, or_
+from typing import override
+
+
+class Specification[T](ABC):
+    """Abstract specification that can be combined with ``&``, ``|``, ``~``."""
+
+    __slots__: tuple[str, ...] = ()
+
+    @abstractmethod
+    def is_satisfied_by(self, candidate: T) -> bool:
+        """Check whether *candidate* satisfies this specification."""
+        raise NotImplementedError
+
+    def __and__(self, other: Specification[T]) -> AndSpecification[T]:
+        """Combine with *other* via logical AND."""
+        return AndSpecification(left=self, right=other)
+
+    def __or__(self, other: Specification[T]) -> OrSpecification[T]:
+        """Combine with *other* via logical OR."""
+        return OrSpecification(self, other)
+
+    def __invert__(self) -> NotSpecification[T]:
+        """Negate this specification."""
+        return NotSpecification(self)
+
+    def __call__(self, candidate: T) -> bool:
+        """Evaluate the specification against *candidate*."""
+        return self.is_satisfied_by(candidate)
+
+    @classmethod
+    def all_of(
+        cls, specs: Iterable[Specification[T]],
+    ) -> Specification[T] | None:
+        """Return a specification that is satisfied when **all** of *specs* are.
+
+        Returns ``None`` when *specs* is empty.
+        """
+        items = list(specs)
+        if not items:
+            return None
+        return reduce(and_, items)
+
+    @classmethod
+    def any_of(
+        cls, specs: Iterable[Specification[T]],
+    ) -> Specification[T] | None:
+        """Return a specification that is satisfied when **any** of *specs* is.
+
+        Returns ``None`` when *specs* is empty.
+        """
+        items = list(specs)
+        if not items:
+            return None
+        return reduce(or_, items)
+
+
+class AndSpecification[T](Specification[T]):
+    """Conjunction of two specifications (produced by ``&``)."""
+
+    __slots__ = ("left", "right")
+
+    def __init__(self, left: Specification[T], right: Specification[T]) -> None:
+        """Initialize with *left* and *right* specifications."""
+        self.left = left
+        self.right = right
+
+    @override
+    def is_satisfied_by(self, candidate: T) -> bool:
+        """Check whether *candidate* satisfies both specifications."""
+        return self.left.is_satisfied_by(
+            candidate,
+        ) and self.right.is_satisfied_by(candidate)
+
+
+class OrSpecification[T](Specification[T]):
+    """Disjunction of two specifications (produced by ``|``)."""
+
+    __slots__ = ("left", "right")
+
+    def __init__(self, left: Specification[T], right: Specification[T]) -> None:
+        """Initialize with *left* and *right* specifications."""
+        self.left = left
+        self.right = right
+
+    @override
+    def is_satisfied_by(self, candidate: T) -> bool:
+        """Check whether *candidate* satisfies at least one specification."""
+        return self.left.is_satisfied_by(
+            candidate,
+        ) or self.right.is_satisfied_by(candidate)
+
+
+class NotSpecification[T](Specification[T]):
+    """Negation of a specification (produced by ``~``)."""
+
+    __slots__ = ("spec",)
+
+    def __init__(self, spec: Specification[T]) -> None:
+        """Initialize with *spec* to negate."""
+        self.spec = spec
+
+    @override
+    def is_satisfied_by(self, candidate: T) -> bool:
+        """Check whether *candidate* does **not** satisfy the specification."""
+        return not self.spec.is_satisfied_by(candidate)

zspec-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.3
+Name: zspec
+Version: 0.1.0
+Summary: Composable specification pattern for Python
+Author: Alexandr
+Author-email: Alexandr <alexandr.panteleev2000@gmail.com>
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# ZSpec
+
+Composable specification pattern for Python 3.14+.
+
+## Installation
+
+```bash
+pip install zspec
+```
+
+## Quick start
+
+```python
+from dataclasses import dataclass
+from zspec import Specification
+
+
+@dataclass
+class Product:
+    name: str
+    price: int
+    in_stock: bool
+
+
+# Define specifications as simple subclasses
+class InStock(Specification[Product]):
+    def is_satisfied_by(self, p: Product) -> bool:
+        return p.in_stock
+
+
+class Affordable(Specification[Product]):
+    def __init__(self, max_price: int) -> None:
+        self.max_price = max_price
+
+    def is_satisfied_by(self, p: Product) -> bool:
+        return p.price <= self.max_price
+
+
+# Compose with &, |, ~
+in_stock = InStock()
+reasonable = Affordable(max_price=1000)
+eligible = in_stock & reasonable
+
+product = Product(name="Laptop", price=800, in_stock=True)
+assert eligible(product)  # True -- callable directly
+assert eligible.is_satisfied_by(product)  # same thing
+```
+
+## Features
+
+- **Composable** --- combine specs with `&` (and), `|` (or), `~` (not)
+- **Type-safe** --- generic `Specification[T]` preserves the candidate type
+- **Bulk combinators** --- `Specification.all_of(...)` and `Specification.any_of(...)`
+- **Zero dependencies** --- standard library only
+- **Python 3.14+** --- leverages modern generics (`class Foo[T]`)
+
+## API overview
+
+| Method | Description |
+|---|---|
+| `spec & other` | Both must be satisfied (AND) |
+| `spec \| other` | At least one must be satisfied (OR) |
+| `~spec` | Negation (NOT) |
+| `spec(candidate)` | Shorthand for `is_satisfied_by` |
+| `Specification.all_of(specs)` | Reduce with AND, returns `None` for empty input |
+| `Specification.any_of(specs)` | Reduce with OR, returns `None` for empty input |
+
+## License
+
+MIT

zspec-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+zspec/__init__.py,sha256=0VSucegkSPaM3H0OWBMhbT0w9J-7Mry0x-afvz9DuhE,365
+zspec/specification.py,sha256=LzgVVpgv1EzLK7BcmS3sJb5mtVEX23ZaltIYl9tl53k,3592
+zspec-0.1.0.dist-info/WHEEL,sha256=iCTolw4aw2dP3yfM-EQCGTDsFCXL_ymmbYnBRVH7plA,81
+zspec-0.1.0.dist-info/METADATA,sha256=TC_J72-rDeJ3FBRC85X4TMqTy8p6vaI2-jy12YMel4Q,1988
+zspec-0.1.0.dist-info/RECORD,,

zspec-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.11
+Root-Is-Purelib: true
+Tag: py3-none-any