loom-kernel 2.8.0__tar.gz → 2.9.0__tar.gz

{loom_kernel-2.8.0 → loom_kernel-2.9.0}/PKG-INFO

@@ -1,8 +1,14 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.8.0
+Version: 2.9.0
 Summary: Loom Python project
 License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: aiocache<1.0,>=0.12
@@ -62,14 +68,14 @@ Requires-Dist: opentelemetry-sdk<2.0,>=1.27; extra == 'etl-polars'
 Requires-Dist: polars<2.0,>=1.24; extra == 'etl-polars'
 Requires-Dist: pyarrow>=14.0; extra == 'etl-polars'
 Provides-Extra: etl-spark
-Requires-Dist: delta-spark<4.0,>=3.2; extra == 'etl-spark'
+Requires-Dist: delta-spark<4.0,>=3.2; (python_version < '3.13') and extra == 'etl-spark'
 Requires-Dist: findspark<3.0,>=2.0; extra == 'etl-spark'
 Requires-Dist: fsspec>=2024.2.0; extra == 'etl-spark'
 Requires-Dist: opentelemetry-api<2.0,>=1.27; extra == 'etl-spark'
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.27; extra == 'etl-spark'
 Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.27; extra == 'etl-spark'
 Requires-Dist: opentelemetry-sdk<2.0,>=1.27; extra == 'etl-spark'
-Requires-Dist: pyspark<4.0,>=3.5; extra == 'etl-spark'
+Requires-Dist: pyspark<4.0,>=3.5; (python_version < '3.13') and extra == 'etl-spark'
 Provides-Extra: jwt
 Requires-Dist: pyjwt[crypto]<3,>=2.8; extra == 'jwt'
 Provides-Extra: logfire
@@ -88,7 +94,7 @@ Requires-Dist: pyyaml>=6.0; extra == 'prefect'
 Provides-Extra: prometheus
 Requires-Dist: prometheus-client>=0.20; extra == 'prometheus'
 Provides-Extra: pyspark
-Requires-Dist: pyspark<4.0,>=3.5; extra == 'pyspark'
+Requires-Dist: pyspark<4.0,>=3.5; (python_version < '3.13') and extra == 'pyspark'
 Provides-Extra: rest
 Requires-Dist: fastapi<1.0,>=0.115; extra == 'rest'
 Requires-Dist: httptools<1.0,>=0.6; extra == 'rest'
@@ -118,14 +124,14 @@ Description-Content-Type: text/markdown
 
 # loom-kernel
 
-[![CI](https://img.shields.io/github/actions/workflow/status/the-reacher-data/loom-py/ci-main.yml?branch=master&label=ci)](https://github.com/the-reacher-data/loom-py/actions/workflows/ci-main.yml)
-[![Docs](https://img.shields.io/github/actions/workflow/status/the-reacher-data/loom-py/docs.yml?branch=master&label=docs)](https://github.com/the-reacher-data/loom-py/actions/workflows/docs.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/MassiveDataScope/loom-py/ci-main.yml?branch=master&label=ci)](https://github.com/MassiveDataScope/loom-py/actions/workflows/ci-main.yml)
+[![Docs](https://img.shields.io/github/actions/workflow/status/MassiveDataScope/loom-py/docs.yml?branch=master&label=docs)](https://github.com/MassiveDataScope/loom-py/actions/workflows/docs.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=the-reacher-data_loom-py&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=the-reacher-data_loom-py)
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=the-reacher-data_loom-py&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=the-reacher-data_loom-py)
 [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=the-reacher-data_loom-py&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=the-reacher-data_loom-py)
-[![Coverage](https://codecov.io/gh/the-reacher-data/loom-py/branch/master/graph/badge.svg)](https://app.codecov.io/gh/the-reacher-data/loom-py/tree/master)
+[![Coverage](https://codecov.io/gh/MassiveDataScope/loom-py/branch/master/graph/badge.svg)](https://app.codecov.io/gh/MassiveDataScope/loom-py/tree/master)
 [![PyPI](https://img.shields.io/pypi/v/loom-kernel)](https://pypi.org/project/loom-kernel/)
-[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/the-reacher-data/loom-py/blob/master/pyproject.toml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/MassiveDataScope/loom-py/blob/master/pyproject.toml)
 
 Framework-agnostic Python toolkit to build backend applications with:
 
@@ -137,6 +143,13 @@ Framework-agnostic Python toolkit to build backend applications with:
 - **declarative ETL** — compile-time-validated pipelines for Polars and Spark
 - testing utilities for business workflows and ETL steps
 
+## Python versions
+
+`loom-kernel` supports Python 3.11, 3.12, 3.13 and 3.14. Two extras are limited
+to Python < 3.13 until their upstream packages publish wheels for later versions:
+`streaming` (Bytewax) and `etl-spark`/`pyspark` (PySpark 3.5). On Python 3.13 or
+later those extras install without that dependency.
+
 ## Purpose
 
 `loom-kernel` helps you ship production APIs faster without sacrificing clean
@@ -532,6 +545,11 @@ pip install "loom-kernel[etl-polars]"
 pip install "loom-kernel[etl-spark]"
 ```
 
+The `etl-spark` and `pyspark` extras install PySpark and delta-spark only on
+Python < 3.13, because PySpark 3.5 supports Python up to 3.12. The Spark runtime
+that runs the job (EMR, Glue, Databricks) fixes the PySpark version, and with it
+the Python version; on Python 3.13 or later these extras resolve without Spark.
+
 Declare a pipeline — sources, targets, and transformation logic are explicit and compile-time validated:
 
 ```python

{loom_kernel-2.8.0 → loom_kernel-2.9.0}/README.md

@@ -4,14 +4,14 @@
 
 # loom-kernel
 
-[![CI](https://img.shields.io/github/actions/workflow/status/the-reacher-data/loom-py/ci-main.yml?branch=master&label=ci)](https://github.com/the-reacher-data/loom-py/actions/workflows/ci-main.yml)
-[![Docs](https://img.shields.io/github/actions/workflow/status/the-reacher-data/loom-py/docs.yml?branch=master&label=docs)](https://github.com/the-reacher-data/loom-py/actions/workflows/docs.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/MassiveDataScope/loom-py/ci-main.yml?branch=master&label=ci)](https://github.com/MassiveDataScope/loom-py/actions/workflows/ci-main.yml)
+[![Docs](https://img.shields.io/github/actions/workflow/status/MassiveDataScope/loom-py/docs.yml?branch=master&label=docs)](https://github.com/MassiveDataScope/loom-py/actions/workflows/docs.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=the-reacher-data_loom-py&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=the-reacher-data_loom-py)
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=the-reacher-data_loom-py&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=the-reacher-data_loom-py)
 [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=the-reacher-data_loom-py&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=the-reacher-data_loom-py)
-[![Coverage](https://codecov.io/gh/the-reacher-data/loom-py/branch/master/graph/badge.svg)](https://app.codecov.io/gh/the-reacher-data/loom-py/tree/master)
+[![Coverage](https://codecov.io/gh/MassiveDataScope/loom-py/branch/master/graph/badge.svg)](https://app.codecov.io/gh/MassiveDataScope/loom-py/tree/master)
 [![PyPI](https://img.shields.io/pypi/v/loom-kernel)](https://pypi.org/project/loom-kernel/)
-[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/the-reacher-data/loom-py/blob/master/pyproject.toml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/MassiveDataScope/loom-py/blob/master/pyproject.toml)
 
 Framework-agnostic Python toolkit to build backend applications with:
 
@@ -23,6 +23,13 @@ Framework-agnostic Python toolkit to build backend applications with:
 - **declarative ETL** — compile-time-validated pipelines for Polars and Spark
 - testing utilities for business workflows and ETL steps
 
+## Python versions
+
+`loom-kernel` supports Python 3.11, 3.12, 3.13 and 3.14. Two extras are limited
+to Python < 3.13 until their upstream packages publish wheels for later versions:
+`streaming` (Bytewax) and `etl-spark`/`pyspark` (PySpark 3.5). On Python 3.13 or
+later those extras install without that dependency.
+
 ## Purpose
 
 `loom-kernel` helps you ship production APIs faster without sacrificing clean
@@ -418,6 +425,11 @@ pip install "loom-kernel[etl-polars]"
 pip install "loom-kernel[etl-spark]"
 ```
 
+The `etl-spark` and `pyspark` extras install PySpark and delta-spark only on
+Python < 3.13, because PySpark 3.5 supports Python up to 3.12. The Spark runtime
+that runs the job (EMR, Glue, Databricks) fixes the PySpark version, and with it
+the Python version; on Python 3.13 or later these extras resolve without Spark.
+
 Declare a pipeline — sources, targets, and transformation logic are explicit and compile-time validated:
 
 ```python

{loom_kernel-2.8.0 → loom_kernel-2.9.0}/pyproject.toml

@@ -5,6 +5,12 @@ description = "Loom Python project"
 readme = "README.md"
 requires-python = ">=3.11"
 classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Typing :: Typed",
 ]
 dependencies = [
@@ -70,9 +76,12 @@ etl-polars = [
     "opentelemetry-exporter-otlp-proto-http>=1.27,<2.0",
     "opentelemetry-exporter-otlp-proto-grpc>=1.27,<2.0",
 ]
+# PySpark 3.5 supports Python up to 3.12; the Spark runtime that runs the job
+# (EMR, Glue, Databricks) fixes the version, not loom. On 3.13+ the extra
+# resolves without Spark.
 etl-spark = [
-    "pyspark>=3.5,<4.0",
-    "delta-spark>=3.2,<4.0",
+    "pyspark>=3.5,<4.0; python_version < '3.13'",
+    "delta-spark>=3.2,<4.0; python_version < '3.13'",
     "findspark>=2.0,<3.0",
     "fsspec>=2024.2.0",
     "opentelemetry-api>=1.27,<2.0",
@@ -95,7 +104,7 @@ prefect = [
     "docker>=7.0",
 ]
 pyspark = [
-    "pyspark>=3.5,<4.0",
+    "pyspark>=3.5,<4.0; python_version < '3.13'",
 ]
 prometheus = [
     "prometheus-client>=0.20",
@@ -243,7 +252,7 @@ dev = [
     "httptools>=0.6,<1.0",
     "uvloop>=0.21,<1.0; sys_platform != 'win32'",
     "prometheus-client>=0.20",
-    "delta-spark>=3.2,<4.0",
+    "delta-spark>=3.2,<4.0; python_version < '3.13'",
     "chispa>=0.10,<1.0",
     "pytest-cov>=7.1.0",
     "findspark>=2.0.1",
@@ -279,6 +288,15 @@ include = [
     "src/loom/ai/declarative/schemas/*.json",
 ]
 
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "pyproject.toml",
+]
+
 [tool.ruff]
 line-length = 100
 target-version = "py311"

loom_kernel-2.9.0/src/loom/core/authz/__init__.py

@@ -0,0 +1,43 @@
+"""Role-based authorization primitives, free of any product vocabulary.
+
+A product declares its permissions and roles in code, stores grants (who
+holds which role on which scope) wherever it likes, and asks the pure
+functions here for decisions.  Scopes are paths whose meaning the product
+chooses; a grant on a scope reaches everything below it.
+"""
+
+from loom.core.authz._decide import (
+    Decision,
+    GrantCheck,
+    can_grant,
+    can_revoke,
+    evaluate,
+    scopes_with,
+)
+from loom.core.authz._grants import Grant, GrantSource, InMemoryGrantSource
+from loom.core.authz._roles import (
+    Permission,
+    Role,
+    RoleCatalog,
+    UnknownPermission,
+    UnknownRole,
+)
+from loom.core.authz._scope import Scope
+
+__all__ = [
+    "Decision",
+    "Grant",
+    "GrantCheck",
+    "GrantSource",
+    "InMemoryGrantSource",
+    "Permission",
+    "Role",
+    "RoleCatalog",
+    "Scope",
+    "UnknownPermission",
+    "UnknownRole",
+    "can_grant",
+    "can_revoke",
+    "evaluate",
+    "scopes_with",
+]

loom_kernel-2.9.0/src/loom/core/authz/_decide.py

@@ -0,0 +1,197 @@
+"""Pure decisions over a subject's grants: access, listing and delegation."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from loom.core.authz._grants import Grant
+from loom.core.authz._roles import Permission, RoleCatalog
+from loom.core.authz._scope import Scope
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    """Outcome of an access check, truthy when allowed.
+
+    Attributes:
+        allowed: Whether the permission is held on the scope.
+        grant: The grant that allowed it; ``None`` when denied.
+    """
+
+    allowed: bool
+    grant: Grant | None
+
+    def __post_init__(self) -> None:
+        """Reject a decision whose grant disagrees with :attr:`allowed`."""
+        if self.allowed != (self.grant is not None):
+            raise ValueError("A decision names a grant exactly when it allows.")
+
+    def __bool__(self) -> bool:
+        """Return :attr:`allowed`."""
+        return self.allowed
+
+
+@dataclass(frozen=True, slots=True)
+class GrantCheck:
+    """Outcome of a delegation check, truthy when allowed.
+
+    Attributes:
+        allowed: Whether the granter may hand out or remove the role there.
+        missing: Permissions the granter lacks on that scope.
+    """
+
+    allowed: bool
+    missing: frozenset[Permission]
+
+    def __post_init__(self) -> None:
+        """Reject a check whose :attr:`allowed` disagrees with :attr:`missing`."""
+        if self.allowed == bool(self.missing):
+            raise ValueError("A grant check allows exactly when nothing is missing.")
+
+    def __bool__(self) -> bool:
+        """Return :attr:`allowed`."""
+        return self.allowed
+
+
+def _specificity(grant: Grant) -> tuple[int, str, str]:
+    return (-len(grant.scope.path), grant.role, grant.subject)
+
+
+def evaluate(
+    catalog: RoleCatalog,
+    grants: Iterable[Grant],
+    permission: Permission,
+    scope: Scope,
+) -> Decision:
+    """Decide whether a subject holds *permission* on *scope*.
+
+    Denies unless one of *grants* names a role that includes *permission* on a
+    scope covering *scope*.  A grant whose role the catalog does not declare
+    allows nothing.  When several grants allow, the decision names the one on
+    the deepest scope, then the first by role name and subject, regardless of
+    the order of *grants*.
+
+    Args:
+        catalog: The product's roles.
+        grants: The grants of one subject.
+        permission: The capability being exercised.
+        scope: Where it is exercised.
+
+    Returns:
+        The decision, carrying the grant that allowed it.
+
+    Raises:
+        UnknownPermission: When *permission* is not declared in the catalog.
+    """
+    roles = catalog.roles_with(permission)
+    covering = {scope.path[:depth] for depth in range(len(scope.path) + 1)}
+    winner: Grant | None = None
+    for grant in grants:
+        if (
+            grant.role in roles
+            and grant.scope.path in covering
+            and (winner is None or _specificity(grant) < _specificity(winner))
+        ):
+            winner = grant
+    return Decision(winner is not None, winner)
+
+
+def scopes_with(
+    catalog: RoleCatalog,
+    grants: Iterable[Grant],
+    permission: Permission,
+) -> frozenset[Scope]:
+    """Return the outermost scopes on which a subject holds *permission*.
+
+    A scope covered by another returned scope is left out, so a listing can
+    be filtered with one :meth:`Scope.covers` test per returned scope.
+
+    Args:
+        catalog: The product's roles.
+        grants: The grants of one subject.
+        permission: The capability being listed.
+
+    Returns:
+        The minimal set of scopes covering everything the subject may reach.
+
+    Raises:
+        UnknownPermission: When *permission* is not declared in the catalog.
+    """
+    roles = catalog.roles_with(permission)
+    held = {grant.scope for grant in grants if grant.role in roles}
+    return frozenset(
+        scope for scope in held if not any(other != scope and other.covers(scope) for other in held)
+    )
+
+
+def _delegation_check(
+    catalog: RoleCatalog,
+    granter_grants: Iterable[Grant],
+    needed: Iterable[Permission],
+    scope: Scope,
+) -> GrantCheck:
+    held = tuple(granter_grants)
+    missing = frozenset(
+        permission for permission in needed if not evaluate(catalog, held, permission, scope)
+    )
+    return GrantCheck(not missing, missing)
+
+
+def can_grant(
+    catalog: RoleCatalog,
+    granter_grants: Iterable[Grant],
+    role: str,
+    scope: Scope,
+    *,
+    delegate: Permission,
+) -> GrantCheck:
+    """Decide whether a granter may assign *role* on *scope*.
+
+    The granter needs *delegate* and every permission of *role*, each held on
+    a scope covering *scope*.
+
+    Args:
+        catalog: The product's roles.
+        granter_grants: The granter's grants.
+        role: Name of the role to assign.
+        scope: Where it would apply.
+        delegate: The permission that allows assigning roles at all.
+
+    Returns:
+        The check, listing the permissions the granter lacks there.
+
+    Raises:
+        UnknownRole: When *role* is not declared in the catalog.
+        UnknownPermission: When *delegate* is not declared in the catalog.
+    """
+    needed = {delegate, *catalog.role(role).permissions}
+    return _delegation_check(catalog, granter_grants, needed, scope)
+
+
+def can_revoke(
+    catalog: RoleCatalog,
+    granter_grants: Iterable[Grant],
+    grant: Grant,
+    *,
+    delegate: Permission,
+) -> GrantCheck:
+    """Decide whether a granter may remove *grant*.
+
+    Revoking needs what granting it would.  A grant whose role the code does
+    not declare allows nothing, so removing it needs *delegate* only.
+
+    Args:
+        catalog: The product's roles.
+        granter_grants: The granter's grants.
+        grant: The assignment to remove.
+        delegate: The permission that allows assigning roles at all.
+
+    Returns:
+        The check, listing the permissions the granter lacks there.
+
+    Raises:
+        UnknownPermission: When *delegate* is not declared in the catalog.
+    """
+    needed = {delegate, *(catalog.permissions_of(grant.role) or frozenset())}
+    return _delegation_check(catalog, granter_grants, needed, grant.scope)

loom_kernel-2.9.0/src/loom/core/authz/_grants.py

@@ -0,0 +1,79 @@
+"""Who holds which role where, and where those assignments come from."""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Iterable
+from dataclasses import dataclass
+from typing import Protocol
+
+from loom.core.authz._roles import require_name
+from loom.core.authz._scope import Scope
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class Grant:
+    """An assignment of a role to a subject on a scope.
+
+    Attributes:
+        subject: Opaque identifier of the holder, such as an identity subject
+            or a service account id.
+        role: Name of the role; its permissions are looked up in the catalog
+            at decision time.
+        scope: Where the role applies, including everything below it.
+    """
+
+    subject: str
+    role: str
+    scope: Scope
+
+    def __post_init__(self) -> None:
+        """Reject a grant that names no holder, an unusable role name or no scope."""
+        if not self.subject:
+            raise ValueError("A grant needs a subject.")
+        require_name("role", self.role)
+        if not isinstance(self.scope, Scope):
+            raise TypeError(f"A grant scope must be a Scope, not {type(self.scope).__name__}.")
+
+
+class GrantSource(Protocol):
+    """Where the grants of a subject are loaded from.
+
+    Any class with this method satisfies the protocol structurally, with no
+    inheritance required.
+    """
+
+    async def grants_for(self, subject: str) -> Collection[Grant]:
+        """Return every grant held by *subject*.
+
+        Args:
+            subject: Identifier of the holder.
+
+        Returns:
+            The subject's grants; empty when it holds none.
+        """
+        ...
+
+
+class InMemoryGrantSource:
+    """A :class:`GrantSource` over a fixed list, for tests and examples."""
+
+    __slots__ = ("_grants",)
+
+    def __init__(self, grants: Iterable[Grant]) -> None:
+        """Hold *grants*, deduplicated in their original order.
+
+        Args:
+            grants: Grants of any number of subjects.
+        """
+        self._grants = tuple(dict.fromkeys(grants))
+
+    async def grants_for(self, subject: str) -> Collection[Grant]:
+        """Return the grants of *subject*, in the order they were given.
+
+        Args:
+            subject: Identifier of the holder.
+
+        Returns:
+            The subject's grants.
+        """
+        return tuple(grant for grant in self._grants if grant.subject == subject)