graphty 0.1.0__tar.gz → 0.2.0__tar.gz

graphty-0.2.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.3
+Name: graphty
+Version: 0.2.0
+Summary: Add your description here
+Author: Lukas Plank
+Author-email: Lukas Plank <lupl@tuta.io>
+Requires-Dist: polars>=1.39.3
+Requires-Dist: pydantic>=2.12.5
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+<img src="graphty.svg" width="50%" height="50%" />
+
+# 
+![tests](https://github.com/lu-pl/graphty/actions/workflows/tests.yaml/badge.svg)
+[![coverage](https://coveralls.io/repos/github/lu-pl/graphty/badge.svg?branch=lupl/actions)](https://coveralls.io/github/lu-pl/graphty?branch=lupl/actions)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+
+
+Typed object graph materializer over relational binding sets.
+
+> WARNING: This project is in an early stage of development and should be used with caution.
+
+## Introduction
+
+[Intro]
+
+## Installation
+
+[Installation]

graphty-0.2.0/README.md

@@ -0,0 +1,20 @@
+<img src="graphty.svg" width="50%" height="50%" />
+
+# 
+![tests](https://github.com/lu-pl/graphty/actions/workflows/tests.yaml/badge.svg)
+[![coverage](https://coveralls.io/repos/github/lu-pl/graphty/badge.svg?branch=lupl/actions)](https://coveralls.io/github/lu-pl/graphty?branch=lupl/actions)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+
+
+Typed object graph materializer over relational binding sets.
+
+> WARNING: This project is in an early stage of development and should be used with caution.
+
+## Introduction
+
+[Intro]
+
+## Installation
+
+[Installation]

graphty-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "graphty"
+version = "0.2.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Lukas Plank", email = "lupl@tuta.io" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "polars>=1.39.3",
+    "pydantic>=2.12.5",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.30,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "pytest-randomly>=4.1.0",
+    "ruff>=0.15.17",
+]
+
+[tool.pytest.ini_options]
+addopts = [
+    "--import-mode=importlib",
+]

graphty-0.2.0/src/graphty/.ruff_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by ruff.
+*

graphty-0.2.0/src/graphty/.ruff_cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

graphty-0.2.0/src/graphty/planner.py

@@ -0,0 +1,323 @@
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass
+from functools import cached_property, reduce
+from itertools import chain
+from types import UnionType
+from typing import Annotated, cast, get_args, get_origin
+
+import polars as pl
+from pydantic import BaseModel, Discriminator, Tag
+from pydantic import ConfigDict as PydanticConfigDict
+from pydantic.fields import FieldInfo
+from typing_extensions import TypeForm, get_annotations
+
+from graphty.utils.type_utils import (
+    de_annotate,
+    is_parametrized_list_static_type,
+    is_pydantic_model_static_type,
+    is_pydantic_model_union_static_type,
+    is_structured_field_static_type,
+)
+
+
+def get_model_projection(model: type[BaseModel]) -> set[str]:
+    return {
+        field_name
+        for field_name, field_info in model.model_fields.items()
+        if not is_structured_field_static_type(field_info.annotation)
+    }
+
+
+class ConfigDict(PydanticConfigDict):
+    group_by: str
+
+
+@dataclass
+class Agg:
+    """Configuration class for aggregation fields.
+
+    The class allows to configure aggregation behavior for
+    model fields with aggretation targets:
+
+    E.g. `field: typing.Annotated[list[int], Agg(unique=False)]`
+    will aggregate non-unique values of a given partition into `field`.
+
+    Note: This is a draft and likely subject of breaking API changes.
+    """
+
+    unique: bool = True
+    drop_nulls: bool = True
+
+    def __iter__(self) -> Iterator[Callable[[pl.Expr], pl.Expr]]:
+        if self.unique:
+            yield lambda expr: expr.unique()
+        if self.drop_nulls:
+            yield lambda expr: expr.drop_nulls()
+
+    def apply_to(self, expr: pl.Expr) -> pl.Expr:
+        return reduce(lambda x, y: y(x), self, expr)
+
+
+class ModelUnionDispatch:
+    def __init__(
+        self,
+        type_form: TypeForm,
+        base_cols: set[str],
+        discriminator: str | Callable | None,
+    ) -> None:
+        self.type_form = type_form
+        self.base_cols = base_cols
+        self.discriminator = discriminator
+
+        self.model_members: list[type[BaseModel]] = [
+            member
+            for member in get_args(de_annotate(self.type_form))
+            if is_pydantic_model_static_type(member)
+        ]
+        self.model_union_members: list[UnionType] = [
+            member
+            for member in get_args(de_annotate(self.type_form))
+            if is_pydantic_model_union_static_type(member)
+        ]
+
+    def compute_model_expr(self) -> pl.Expr:
+        match self.model_members, self.model_union_members:
+            case [model], []:
+                # TODO: this duplicates Exprs._struct_expr and should be abstracted
+                model_projection: set[str] = get_model_projection(model=model)
+                return pl.struct(model_projection).struct.with_fields(
+                    *Exprs(model=model, base_cols=self.base_cols),
+                )
+
+        whens = self._compute_whens()
+        when, *rest_whens = whens
+
+        return reduce(
+            lambda x, y: y.otherwise(x),
+            rest_whens,
+            when.otherwise(None),
+        )
+
+    def _compute_whens(self) -> list["pl.When"]:
+        return [
+            *self._compute_model_whens(),
+            *self._compute_model_union_whens(),
+        ]
+
+    def _compute_model_whens(self) -> list["pl.When"]:
+        if not self.model_members:
+            return []
+
+        union_projection: set[str] = reduce(
+            set.union,
+            [get_model_projection(member) for member in self.model_members],
+        )
+
+        discriminator: Discriminator = self._resolve_discriminator()
+        discriminator_value: str | Callable = discriminator.discriminator
+
+        match discriminator_value:
+            case str():
+                discriminator_mapping: dict[tuple[str, ...], type[BaseModel]] = {
+                    get_args(model.model_fields[discriminator_value].annotation): model
+                    for model in self.model_members
+                }
+
+                return [
+                    pl.when(pl.col(discriminator_value).is_in(list(k))).then(
+                        pl.struct(union_projection).struct.with_fields(
+                            *Exprs(model=v, base_cols=self.base_cols),
+                        )
+                    )
+                    for k, v in discriminator_mapping.items()
+                ]
+
+            case Callable():
+                tag_mapping: dict[str, type[BaseModel]] = self._get_tag_mapping()
+
+                discriminator_expression = pl.struct(union_projection).map_elements(
+                    function=discriminator_value,
+                    return_dtype=pl.String,
+                )
+
+                return [
+                    pl.when(discriminator_expression == k).then(
+                        pl.struct(union_projection).struct.with_fields(
+                            *Exprs(model=v, base_cols=self.base_cols),
+                        )
+                    )
+                    for k, v in tag_mapping.items()
+                ]
+
+            case _:
+                assert False, "Expected discriminator to be of type str | Callable."
+
+    def _compute_model_union_whens(self) -> list["pl.When"]:
+        return list(
+            chain.from_iterable(
+                ModelUnionDispatch(
+                    type_form=cast(TypeForm, type_form),
+                    base_cols=self.base_cols,
+                    discriminator=None,
+                )._compute_whens()
+                for type_form in self.model_union_members
+            )
+        )
+
+    def _resolve_discriminator(self) -> Discriminator:
+        if self.discriminator is not None:
+            return Discriminator(discriminator=self.discriminator)
+
+        args = (
+            get_args(self.type_form) if get_origin(self.type_form) is Annotated else []
+        )
+
+        for arg in args:
+            match arg:
+                case FieldInfo(discriminator=discriminator):
+                    assert discriminator is not None, (
+                        "Expected discriminator to be non-None."
+                    )
+                    return (
+                        discriminator
+                        if isinstance(discriminator, Discriminator)
+                        else Discriminator(discriminator=discriminator)
+                    )
+
+                case Discriminator():
+                    return arg
+
+        msg = (
+            "Multi-Model unions must be discriminated unions. "
+            f"Unable to extract discriminator for type form '{self.type_form}'."
+        )
+        raise ValueError(msg)
+
+    # TODO: this needs to be more defensive and raise a clear exception in case Tags cannot be retrieved
+    def _get_tag_mapping(self):
+        """Prototype; this needs proper abstraction."""
+
+        def _generate():
+            for type_form in get_args(de_annotate(self.type_form)):
+                model, *rest = get_args(type_form)
+                tag = next(member for member in rest if isinstance(member, Tag))
+
+                yield tag.tag, model
+
+        return dict(_generate())
+
+
+class Exprs(Iterable[pl.Expr]):
+    def __init__(
+        self, model: type[BaseModel], base_cols: set[str], group_context: bool = False
+    ) -> None:
+        self.model = model
+        self.base_cols = base_cols
+        self.group_context = group_context
+
+    def __iter__(self) -> Iterator[pl.Expr]:
+        for field_name, field_info in self.model.model_fields.items():
+            annotation = cast(TypeForm, field_info.annotation)
+
+            if is_pydantic_model_static_type(annotation):
+                expr: pl.Expr = self._struct_expr(model=annotation).alias(field_name)
+                yield (expr.first() if self.group_context else expr)
+
+            elif is_pydantic_model_union_static_type(annotation):
+                expr: pl.Expr = (
+                    ModelUnionDispatch(
+                        type_form=get_annotations(self.model)[
+                            field_name
+                        ],  # pass full TypeForm for discriminator resolution
+                        base_cols=self.base_cols,
+                        discriminator=field_info.discriminator,
+                    )
+                    .compute_model_expr()
+                    .alias(field_name)
+                )
+                yield (expr.first() if self.group_context else expr)
+
+            elif is_parametrized_list_static_type(annotation):
+                (item_annotation,) = get_args(annotation)
+
+                partition_value: str = self._get_partition_value(model=self.model)
+                agg: Agg = self._get_agg(field_info)
+
+                if is_pydantic_model_static_type(item_annotation):
+                    inner: pl.Expr = self._struct_expr(model=item_annotation).alias(
+                        field_name
+                    )
+                elif is_pydantic_model_union_static_type(item_annotation):
+                    inner = (
+                        ModelUnionDispatch(
+                            type_form=item_annotation,  # pyright: ignore
+                            base_cols=self.base_cols,
+                            discriminator=field_info.discriminator,
+                        )
+                        .compute_model_expr()
+                        .alias(field_name)
+                    )
+                else:
+                    inner: pl.Expr = pl.col(field_name)
+
+                expr: pl.Expr = agg.apply_to(inner)
+                yield (
+                    expr
+                    if self.group_context
+                    else expr.implode().over(partition_by=partition_value)
+                )
+
+    def _struct_expr(self, model: type[BaseModel]) -> pl.Expr:
+        model_projection: set[str] = get_model_projection(model=model)
+        exprs: chain[pl.Expr] = chain(
+            [pl.col(member) for member in model_projection],
+            Exprs(model=model, base_cols=self.base_cols),
+        )
+        return pl.struct(*exprs)
+
+    @staticmethod
+    def _get_partition_value(model: type[BaseModel]) -> str:
+        try:
+            partition_value = model.model_config["group_by"]  # type: ignore
+        except KeyError:
+            raise Exception(
+                f"Model '{model.__name__}' with aggregation target "
+                "does not specify ConfigDict.group_by."
+            )
+        else:
+            return partition_value
+
+    @staticmethod
+    def _get_agg(field_info: FieldInfo) -> Agg:
+        agg: Agg | None = next(
+            (entry for entry in field_info.metadata if isinstance(entry, Agg)), None
+        )
+        return agg or Agg()
+
+
+class LazyFramePlanner:
+    def __init__(
+        self, model: type[BaseModel], data: pl._typing.FrameInitTypes | pl.LazyFrame
+    ) -> None:
+        self.model = model
+        self.lazy_frame: pl.LazyFrame = (
+            data if isinstance(data, pl.LazyFrame) else pl.LazyFrame(data=data)
+        )
+
+    def run(self) -> pl.LazyFrame:
+        group_by: str | None = self.model.model_config.get("group_by")
+        model_projection: set[str] = get_model_projection(self.model)
+
+        if group_by is None:
+            return self.lazy_frame.with_columns(
+                *Exprs(model=self.model, base_cols=self._base_cols)
+            ).drop(self._base_cols.difference(model_projection))
+
+        return self.lazy_frame.group_by(group_by, maintain_order=True).agg(
+            *[pl.col(col).first() for col in model_projection.difference({group_by})],
+            *Exprs(model=self.model, base_cols=self._base_cols, group_context=True),
+        )
+
+    @cached_property
+    def _base_cols(self) -> set[str]:
+        return set(self.lazy_frame.collect_schema().names())

graphty-0.2.0/src/graphty/utils/.ruff_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by ruff.
+*

graphty-0.2.0/src/graphty/utils/.ruff_cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

graphty-0.2.0/src/graphty/utils/alias_map.py

@@ -0,0 +1,135 @@
+from collections import UserDict
+from collections.abc import Callable, Iterator
+from types import resolve_bases
+
+from pydantic import AliasChoices, BaseModel
+from pydantic.fields import FieldInfo
+
+
+class AliasMap(UserDict):
+    """Custom mapping for resolving Pydantic field validation aliases.
+
+    E.g. for a given model
+
+    class Point(BaseModel):
+        a: int = Field(alias="x")
+        y: int
+
+    the mapping would compute to {"a": "x", "y": y}.
+
+    Alias choices, alias generators and alias priority are supported;
+    alias choices are resolved against a projection.
+
+    Note that AliasPath is currently not supported.
+    """
+
+    def __init__(self, model: type[BaseModel], projection: set[str]) -> None:
+        self.model = model
+        self.projection = projection
+
+        self.data = dict(self._generate_alias_map())
+
+    def _generate_alias_map(self) -> Iterator[tuple[str, str]]:
+        """Generate an alias mapping.
+
+        For every field in a given model, the generator resolves aliases
+        and yields 2-tuples representing key/value pairs.
+        """
+
+        alias_resolver: Callable[[str, FieldInfo], list[str]] = (
+            self._get_alias_resolver()
+        )
+
+        for k, v in self.model.model_fields.items():
+            aliases: list[str] = alias_resolver(k, v)
+
+            match aliases:
+                case []:
+                    yield k, k
+                case [alias]:
+                    yield (k, alias)
+                case [_alias, *_aliases] as aliases:
+                    alias: str | None = next(
+                        (i for i in aliases if i in self.projection), None
+                    )
+
+                    if alias is None:
+                        msg = (
+                            f"Unable to resolve AliasChoice for field '{k}' of model '{self.model.__name__}'.\n"
+                            f"None of computed aliases '{aliases}' in projection '{self.projection}'."
+                        )
+                        raise ValueError(msg)
+
+                    yield (k, alias)
+                case _:  # pragma: no cover; unreachable
+                    assert False, "This should never happen."
+
+    def _get_alias_resolver(self) -> Callable[[str, FieldInfo], list[str]]:
+        """Helper for acquiring an alias resolver.
+
+        An alias resolver computes alias candidates given a field name and
+        FieldInfo object and according to validate_by_name/validate_by_alias flags.
+
+        Note that the deprecated populate_by_name flag is not supported.
+        """
+
+        model_config = self.model.model_config
+
+        if model_config.get("populate_by_name") is not None:
+            msg = (
+                "Config option 'populate_by_name' is not supported. "
+                "Use Pydantic >=2.11 flags 'validate_by_name'/'validate_by_alias' instead."
+            )
+            raise ValueError(msg)
+
+        validate_by_name, validate_by_alias = (
+            model_config.get("validate_by_name", False),
+            model_config.get("validate_by_alias", True),
+        )
+
+        match validate_by_name, validate_by_alias:
+            case True, False:  # TODO: trigger in tests
+                return lambda field_name, _: [field_name]
+            case False, True:
+                return lambda _, field_info: self._compute_alias_candidates(
+                    field_info=field_info
+                )
+            case True, True:  # TODO: trigger in tests
+                return lambda field_name, field_info: [
+                    field_name,
+                    *self._compute_alias_candidates(field_info=field_info),
+                ]
+            case (
+                False,
+                False,
+            ):  # pragma: no cover; False, False raises error in Pydantic
+                msg = "Invalid config: validate_by_name=False, validate_by_alias=False."
+                raise ValueError(msg)
+            case _:  # pragma: no cover
+                assert False, "This should never happen."
+
+    def _compute_alias_candidates(self, field_info: FieldInfo) -> list[str]:
+        if (validation_alias := field_info.validation_alias):
+            return self._resolve_alias(validation_alias)
+        return []
+        
+    @staticmethod
+    def _resolve_alias(alias: str | AliasChoices) -> list[str]:
+        """Helper for resolving alias/validation_alias values in FieldInfo objects.
+
+        Note that pydantic.AliasPath is not meaningful in the context of flat relational binding mappings;
+        the method therefore raises an Exception for AliasPath and AliasChoices/AliasPath objects.
+        """
+        match alias:
+            case str():
+                return [alias]
+            case AliasChoices(choices=choices) if all(
+                isinstance(choice, str) for choice in choices
+            ):
+                return choices
+            case _:
+                msg = (
+                    "Unable to resolve alias. "
+                    f"Expected str or AliasChoices of str, got '{alias}'."
+                )
+                raise ValueError(msg)

graphty-0.2.0/src/graphty/utils/type_utils.py

@@ -0,0 +1,64 @@
+import types
+import typing
+from typing import Annotated, TypeGuard, get_args, get_origin
+
+from pydantic import BaseModel
+from typing_extensions import TypeForm
+
+
+def de_annotate(type_form: TypeForm) -> TypeForm:
+    """Unwrap potentially nested Annotated wrappers."""
+
+    if get_origin(type_form) is Annotated:
+        type_form, *_ = get_args(type_form)
+        return de_annotate(type_form)
+    return type_form
+
+
+def is_pydantic_model_static_type(type_form: TypeForm) -> TypeGuard[type[BaseModel]]:
+    """Check if type_form denotes a Pydantic model type."""
+    type_form = de_annotate(type_form)
+
+    return (
+        isinstance(type_form, type)
+        and issubclass(type_form, BaseModel)
+        and (type_form is not BaseModel)
+    )
+
+
+def is_parametrized_list_static_type(type_form: TypeForm) -> TypeGuard[type[list]]:
+    """Check if type_form denotes a parametrized list type."""
+    type_form = de_annotate(type_form)
+    return get_origin(type_form) is list
+
+
+def is_pydantic_model_union_static_type(
+    type_form: TypeForm,
+) -> TypeGuard[types.UnionType]:
+    """Check if type_form denotes a union type of a Pydantic model."""
+
+    type_form = de_annotate(type_form)
+
+    is_union_type: bool = get_origin(type_form) in (types.UnionType, typing.Union)
+    has_any_model: bool = any(
+        is_pydantic_model_static_type(obj) or is_pydantic_model_union_static_type(obj)
+        for obj in get_args(type_form)
+    )
+
+    return is_union_type and has_any_model
+
+
+def is_structured_field_static_type(type_form: TypeForm) -> bool:
+    """Check if type_form denotes a structured field type.
+
+    A structured field type is a type that triggers a recursion
+    and/or aggregation code path in the GraphTy planner.
+    """
+    return any(
+        predicate(type_form)
+        for predicate in [
+            is_pydantic_model_static_type,
+            is_pydantic_model_union_static_type,
+            is_parametrized_list_static_type,
+        ]
+    )

graphty-0.1.0/.gitignore

@@ -1,10 +0,0 @@
-# Python-generated files
-__pycache__/
-*.py[oc]
-build/
-dist/
-wheels/
-*.egg-info
-
-# Virtual environments
-.venv

graphty-0.1.0/.python-version

@@ -1 +0,0 @@
-3.13

graphty-0.1.0/PKG-INFO

@@ -1,11 +0,0 @@
-Metadata-Version: 2.4
-Name: graphty
-Version: 0.1.0
-Summary: Add your description here
-Author-email: Lukas Plank <lupl@tuta.io>
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-
-# GraphTy
-
-Typed Views over RDF Graph data.

graphty-0.1.0/README.md

@@ -1,3 +0,0 @@
-# GraphTy
-
-Typed Views over RDF Graph data.

graphty-0.1.0/pyproject.toml

@@ -1,14 +0,0 @@
-[project]
-name = "graphty"
-version = "0.1.0"
-description = "Add your description here"
-readme = "README.md"
-authors = [
-    { name = "Lukas Plank", email = "lupl@tuta.io" }
-]
-requires-python = ">=3.13"
-dependencies = []
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"

graphty-0.1.0/src/graphty/__init__.py

@@ -1,2 +0,0 @@
-def hello() -> str:
-    return "Hello from graphty!"