strawberry-orm 0.3.0__tar.gz → 0.4.0__tar.gz

{strawberry_orm-0.3.0 → strawberry_orm-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strawberry-orm
-Version: 0.3.0
+Version: 0.4.0
 Summary: Unified, backend-agnostic ORM abstraction for Strawberry GraphQL
 Author: James Davidson, Patrick Arminio
 Author-email: James Davidson <jamie.t.davidson@gmail.com>, Patrick Arminio <patrick.arminio@gmail.com>
@@ -425,6 +425,104 @@ Typical string lookups: `exact`, `neq`, `contains`, `iContains`, `startsWith`, `
 
 Regex lookups (`regex`, `iRegex`) are disabled by default. Enable with `enable_regex_filters=True`.
 
+#### Object Traversal
+
+When filters are registered for related models, the generated filter gains an `object` key that lets you filter parent rows based on conditions on their related objects:
+
+```python
+UserFilter = orm.filter(User)
+PostFilter = orm.filter(Post)   # Post has an "author" relation to User
+```
+
+```graphql
+{
+  posts(filter: {
+    object: { author: { field: { name: { exact: "Alice" } } } }
+  }) {
+    title
+  }
+}
+```
+
+Object traversal composes with boolean operators:
+
+```graphql
+{
+  posts(filter: {
+    all: [
+      { field: { isPublished: { exact: true } } }
+      { object: { author: { field: { name: { exact: "Alice" } } } } }
+    ]
+  }) { title }
+}
+```
+
+Multi-level traversal works when the intermediate models also have registered filters:
+
+```python
+UserFilter = orm.filter(User)
+PostFilter = orm.filter(Post)
+CommentFilter = orm.filter(Comment)  # Comment -> Post -> User
+```
+
+```graphql
+# Find comments on posts written by Alice
+{
+  comments(filter: {
+    object: { post: {
+      object: { author: { field: { name: { exact: "Alice" } } } }
+    } }
+  }) { body }
+}
+```
+
+The `object` type is `@oneOf`, so each filter entry names exactly one relation.
+
+Relations only appear in `object` if their target model already has a registered filter at the time `orm.filter()` is called. Register child model filters before parent model filters.
+
+#### Filter Projection
+
+By default every relation with a registered filter appears in `object`. Pass `project={...}` to `orm.filter()` to control exactly which relations are exposed and how deep traversal can go:
+
+```python
+UserFilter  = orm.filter(User)
+TagFilter   = orm.filter(Tag)
+CommentFilter = orm.filter(Comment)
+
+# Only expose "author" in the object type — tags and comments are excluded
+PostFilter = orm.filter(Post, project={"author": {}})
+```
+
+```graphql
+# This works (author is projected)
+{ posts(filter: { object: { author: { field: { name: { exact: "Alice" } } } } }) { title } }
+
+# This would be a schema error (tags is not projected)
+{ posts(filter: { object: { tags: { field: { name: { exact: "python" } } } } }) { title } }
+```
+
+Sub-project dicts control nested traversal. An empty dict `{}` means "include this relation but don't allow further object traversal from it". A non-empty dict lists which of the related model's relations are reachable:
+
+```python
+# Allow Comment -> post, and from post -> author (but not post -> tags)
+CommentFilter = orm.filter(Comment, project={
+    "post": {
+        "author": {},
+    },
+})
+```
+
+Summary:
+
+| `project` value | Behavior |
+| --- | --- |
+| `None` (default) | Auto-include all relations with registered filters |
+| `{}` | No `object` type at all (scalar lookups only) |
+| `{"rel": {}}` | Include `rel` as a leaf (no further traversal from it) |
+| `{"rel": {"nested": {}}}` | Include `rel` and allow traversal to `nested` from it |
+
+Projected filters are cached internally and do not overwrite the global filter registry, so you can create multiple projected variants of the same model's filter for different schema entry points.
+
 ### Ordering
 
 Generate an order input:

{strawberry_orm-0.3.0 → strawberry_orm-0.4.0}/README.md

@@ -390,6 +390,104 @@ Typical string lookups: `exact`, `neq`, `contains`, `iContains`, `startsWith`, `
 
 Regex lookups (`regex`, `iRegex`) are disabled by default. Enable with `enable_regex_filters=True`.
 
+#### Object Traversal
+
+When filters are registered for related models, the generated filter gains an `object` key that lets you filter parent rows based on conditions on their related objects:
+
+```python
+UserFilter = orm.filter(User)
+PostFilter = orm.filter(Post)   # Post has an "author" relation to User
+```
+
+```graphql
+{
+  posts(filter: {
+    object: { author: { field: { name: { exact: "Alice" } } } }
+  }) {
+    title
+  }
+}
+```
+
+Object traversal composes with boolean operators:
+
+```graphql
+{
+  posts(filter: {
+    all: [
+      { field: { isPublished: { exact: true } } }
+      { object: { author: { field: { name: { exact: "Alice" } } } } }
+    ]
+  }) { title }
+}
+```
+
+Multi-level traversal works when the intermediate models also have registered filters:
+
+```python
+UserFilter = orm.filter(User)
+PostFilter = orm.filter(Post)
+CommentFilter = orm.filter(Comment)  # Comment -> Post -> User
+```
+
+```graphql
+# Find comments on posts written by Alice
+{
+  comments(filter: {
+    object: { post: {
+      object: { author: { field: { name: { exact: "Alice" } } } }
+    } }
+  }) { body }
+}
+```
+
+The `object` type is `@oneOf`, so each filter entry names exactly one relation.
+
+Relations only appear in `object` if their target model already has a registered filter at the time `orm.filter()` is called. Register child model filters before parent model filters.
+
+#### Filter Projection
+
+By default every relation with a registered filter appears in `object`. Pass `project={...}` to `orm.filter()` to control exactly which relations are exposed and how deep traversal can go:
+
+```python
+UserFilter  = orm.filter(User)
+TagFilter   = orm.filter(Tag)
+CommentFilter = orm.filter(Comment)
+
+# Only expose "author" in the object type — tags and comments are excluded
+PostFilter = orm.filter(Post, project={"author": {}})
+```
+
+```graphql
+# This works (author is projected)
+{ posts(filter: { object: { author: { field: { name: { exact: "Alice" } } } } }) { title } }
+
+# This would be a schema error (tags is not projected)
+{ posts(filter: { object: { tags: { field: { name: { exact: "python" } } } } }) { title } }
+```
+
+Sub-project dicts control nested traversal. An empty dict `{}` means "include this relation but don't allow further object traversal from it". A non-empty dict lists which of the related model's relations are reachable:
+
+```python
+# Allow Comment -> post, and from post -> author (but not post -> tags)
+CommentFilter = orm.filter(Comment, project={
+    "post": {
+        "author": {},
+    },
+})
+```
+
+Summary:
+
+| `project` value | Behavior |
+| --- | --- |
+| `None` (default) | Auto-include all relations with registered filters |
+| `{}` | No `object` type at all (scalar lookups only) |
+| `{"rel": {}}` | Include `rel` as a leaf (no further traversal from it) |
+| `{"rel": {"nested": {}}}` | Include `rel` and allow traversal to `nested` from it |
+
+Projected filters are cached internally and do not overwrite the global filter registry, so you can create multiple projected variants of the same model's filter for different schema entry points.
+
 ### Ordering
 
 Generate an order input:

{strawberry_orm-0.3.0 → strawberry_orm-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "strawberry-orm"
-version = "0.3.0"
+version = "0.4.0"
 description = "Unified, backend-agnostic ORM abstraction for Strawberry GraphQL"
 readme = "README.md"
 license = "MIT"

{strawberry_orm-0.3.0 → strawberry_orm-0.4.0}/src/strawberry_orm/backends/_base.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import re
 import typing
 import warnings
@@ -59,6 +60,8 @@ class BaseBackend:
         self._filter_overrides: dict[type, type] = kwargs.get("filter_overrides") or {}
         self._type_registry: dict[str, type] = {}
         self._graphql_type_registry: dict[type, type] = {}
+        self._filter_registry: dict[type, type] = {}
+        self._projected_filter_cache: dict[tuple[type, Any], type] = {}
         self._type_querysets: dict[type, Any] = {}
         self._warn_sensitive: bool = kwargs.get("warn_sensitive", True)
         self._exclude_sensitive_fields: bool = kwargs.get(
@@ -137,15 +140,40 @@ class BaseBackend:
         model = model_or_type
         include = kwargs.get("include")
         exclude = kwargs.get("exclude")
+        project: dict[str, Any] | None = kwargs.get("project")
 
         enable_regex = getattr(self, "_enable_regex_filters", False)
 
         fields_meta = self._introspect_model(model)
 
+        if project is not None:
+            relation_names = {
+                fname for fname, _, is_rel, _ in fields_meta if is_rel
+            }
+            unknown = set(project.keys()) - relation_names
+            if unknown:
+                raise ValueError(
+                    f"Unknown relation(s) in project for {model.__name__}: "
+                    f"{', '.join(sorted(unknown))}"
+                )
+
+        # Check the projected-filter cache for projected (non-default) calls.
+        if project is not None:
+            cache_key = (model, self._filter_project_signature(project))
+            cached = self._projected_filter_cache.get(cache_key)
+            if cached is not None:
+                return cached
+
+        suffix = self._filter_project_suffix(project)
+
         field_annotations: dict[str, Any] = {}
         field_defaults: dict[str, Any] = {}
 
-        for fname, ftype, is_relation, _rel_model in fields_meta:
+        object_annotations: dict[str, Any] = {}
+        object_defaults: dict[str, Any] = {}
+        relation_models: dict[str, type] = {}
+
+        for fname, ftype, is_relation, rel_model in fields_meta:
             if include and fname not in include:
                 continue
             if exclude and fname in exclude:
@@ -153,6 +181,19 @@ class BaseBackend:
             if self._exclude_generated_sensitive_field(fname, include):
                 continue
             if is_relation:
+                if rel_model is None:
+                    continue
+                if project is not None and fname not in project:
+                    continue
+                sub_project = project[fname] if project is not None else None
+                if sub_project is not None:
+                    rel_filter = self._get_projected_filter(rel_model, sub_project)
+                else:
+                    rel_filter = self._filter_registry.get(rel_model)
+                if rel_filter is not None:
+                    object_annotations[fname] = Optional[rel_filter]
+                    object_defaults[fname] = strawberry.UNSET
+                    relation_models[fname] = rel_model
                 continue
             lookup_type = self._filter_overrides.get(ftype) or TYPE_TO_LOOKUP.get(ftype)
             if lookup_type is not None:
@@ -161,15 +202,20 @@ class BaseBackend:
                 field_annotations[fname] = Optional[lookup_type]
                 field_defaults[fname] = strawberry.UNSET
 
-        field_type_name = f"{model.__name__}Field"
-        field_ns: dict[str, Any] = {
-            "__annotations__": field_annotations,
-            **field_defaults,
-        }
-        field_cls = type(field_type_name, (), field_ns)
-        FieldType = strawberry.input(field_cls, one_of=True)
-
-        filter_type_name = f"{model.__name__}Filter"
+        # Reuse the existing FieldType when creating a projected variant.
+        base_filter = self._filter_registry.get(model)
+        if project is not None and base_filter is not None and hasattr(base_filter, "_field_type"):
+            FieldType = base_filter._field_type
+        else:
+            field_type_name = f"{model.__name__}Field{suffix}"
+            field_ns: dict[str, Any] = {
+                "__annotations__": field_annotations,
+                **field_defaults,
+            }
+            field_cls = type(field_type_name, (), field_ns)
+            FieldType = strawberry.input(field_cls, one_of=True)
+
+        filter_type_name = f"{model.__name__}Filter{suffix}"
         filter_ns: dict[str, Any] = {
             "__annotations__": {"field": Optional[FieldType]},
             "field": strawberry.UNSET,
@@ -185,11 +231,77 @@ class BaseBackend:
         FilterCls.not_ = strawberry.field(default=strawberry.UNSET, name="not")
         FilterCls.one_of = strawberry.UNSET
 
+        if object_annotations:
+            obj_type_name = f"{model.__name__}Object{suffix}"
+            obj_ns: dict[str, Any] = {
+                "__annotations__": object_annotations,
+                **object_defaults,
+            }
+            obj_cls = type(obj_type_name, (), obj_ns)
+            ObjectType = strawberry.input(obj_cls, one_of=True)
+            FilterCls.__annotations__["object"] = Optional[ObjectType]
+            FilterCls.object = strawberry.UNSET
+
         FilterType = strawberry.input(FilterCls, one_of=True)
         FilterType._field_type = FieldType  # type: ignore[attr-defined]
         FilterType.__orm_model__ = model  # type: ignore[attr-defined]
+        if object_annotations:
+            FilterType._object_type = ObjectType  # type: ignore[attr-defined]
+            FilterType._relation_models = relation_models  # type: ignore[attr-defined]
+
+        if project is None:
+            self._filter_registry[model] = FilterType
+        else:
+            self._projected_filter_cache[cache_key] = FilterType
         return FilterType
 
+    # -- Filter project helpers ------------------------------------------------
+
+    def _get_projected_filter(self, model: type, sub_project: dict[str, Any]) -> Any:
+        """Return a filter type for *model* constrained by *sub_project*.
+
+        If *sub_project* is empty the returned filter has no ``object`` type
+        (leaf).  Otherwise only the relations listed in *sub_project* are
+        exposed, each recursively constrained by their own sub-project.
+        """
+        sig = self._filter_project_signature(sub_project)
+        cache_key = (model, sig)
+        cached = self._projected_filter_cache.get(cache_key)
+        if cached is not None:
+            return cached
+        if not sub_project:
+            base = self._filter_registry.get(model)
+            if base is not None and not hasattr(base, "_object_type"):
+                self._projected_filter_cache[cache_key] = base
+                return base
+        result = self.filter(model, project=sub_project)
+        return result
+
+    @staticmethod
+    def _filter_project_signature(project: dict[str, Any] | None) -> Any:
+        """Turn a project dict into a hashable, comparable value."""
+        if project is None:
+            return None
+        if not project:
+            return ()
+        return tuple(
+            sorted(
+                (k, BaseBackend._filter_project_signature(v))
+                for k, v in project.items()
+            )
+        )
+
+    @staticmethod
+    def _filter_project_suffix(project: dict[str, Any] | None) -> str:
+        """Short hash suffix for projected type names (empty for default)."""
+        sig = BaseBackend._filter_project_signature(project)
+        if sig is None:
+            return ""
+        if not sig:
+            return "_leaf"
+        digest = hashlib.sha1(repr(sig).encode("utf-8")).hexdigest()[:8]
+        return f"_{digest}"
+
     def order(self, model_or_type: type, **kwargs: Any) -> Any:
         model = model_or_type
         include = kwargs.get("include")

{strawberry_orm-0.3.0 → strawberry_orm-0.4.0}/src/strawberry_orm/backends/django.py

@@ -636,6 +636,7 @@ def _build_django_filter(
     enable_regex: bool = False,
     max_in_list_size: int = 500,
     _depth: int = 0,
+    _prefix: str = "",
 ) -> Any:
     from django.db.models import Q
 
@@ -652,6 +653,7 @@ def _build_django_filter(
         enable_regex=enable_regex,
         max_in_list_size=max_in_list_size,
         _depth=_depth + 1,
+        _prefix=_prefix,
     )
 
     for key in fields:
@@ -662,9 +664,25 @@ def _build_django_filter(
         if key == "field":
             return _build_django_field_clause(
                 val,
+                prefix=_prefix,
                 enable_regex=enable_regex,
                 max_in_list_size=max_in_list_size,
             )
+        elif key == "object":
+            obj_fields = val.__class__.__dataclass_fields__
+            for rel_name in obj_fields:
+                nested_filter = getattr(val, rel_name)
+                if nested_filter is strawberry.UNSET or nested_filter is None:
+                    continue
+                return _build_django_filter(
+                    nested_filter,
+                    max_depth=max_depth,
+                    max_branches=max_branches,
+                    enable_regex=enable_regex,
+                    max_in_list_size=max_in_list_size,
+                    _depth=_depth + 1,
+                    _prefix=f"{_prefix}{rel_name}__",
+                )
         elif key == "all":
             if len(val) > max_branches:
                 raise ValueError(
@@ -708,6 +726,7 @@ def _build_django_filter(
 def _build_django_field_clause(
     field_input: Any,
     *,
+    prefix: str = "",
     enable_regex: bool = False,
     max_in_list_size: int = 500,
 ) -> Any:
@@ -722,7 +741,7 @@ def _build_django_field_clause(
             continue
 
         col_q = _build_django_lookup(
-            col_name,
+            f"{prefix}{col_name}",
             lookup,
             enable_regex=enable_regex,
             max_in_list_size=max_in_list_size,

{strawberry_orm-0.3.0 → strawberry_orm-0.4.0}/src/strawberry_orm/backends/sqlalchemy.py

@@ -880,6 +880,20 @@ def _build_sa_filter(
                 enable_regex=enable_regex,
                 max_in_list_size=max_in_list_size,
             )
+        elif key == "object":
+            obj_fields = val.__class__.__dataclass_fields__
+            for rel_name in obj_fields:
+                nested_filter = getattr(val, rel_name)
+                if nested_filter is strawberry.UNSET or nested_filter is None:
+                    continue
+                relationship_prop = getattr(model, rel_name)
+                rel_model = relationship_prop.property.mapper.class_
+                inner = _build_sa_filter(nested_filter, rel_model, **recurse_kw)
+                if inner is not None:
+                    if relationship_prop.property.uselist:
+                        return relationship_prop.any(inner)
+                    else:
+                        return relationship_prop.has(inner)
         elif key == "all":
             if len(val) > max_branches:
                 raise ValueError(

{strawberry_orm-0.3.0 → strawberry_orm-0.4.0}/src/strawberry_orm/backends/tortoise.py

@@ -803,6 +803,7 @@ def _build_tortoise_filter(
     enable_regex: bool = False,
     max_in_list_size: int = 500,
     _depth: int = 0,
+    _prefix: str = "",
 ) -> Any:
     """Recursively translate a filter input into a Tortoise Q object."""
     from tortoise.queryset import Q
@@ -820,6 +821,7 @@ def _build_tortoise_filter(
         enable_regex=enable_regex,
         max_in_list_size=max_in_list_size,
         _depth=_depth + 1,
+        _prefix=_prefix,
     )
 
     for key in fields:
@@ -830,9 +832,25 @@ def _build_tortoise_filter(
         if key == "field":
             return _build_tortoise_field_clause(
                 val,
+                prefix=_prefix,
                 enable_regex=enable_regex,
                 max_in_list_size=max_in_list_size,
             )
+        elif key == "object":
+            obj_fields = val.__class__.__dataclass_fields__
+            for rel_name in obj_fields:
+                nested_filter = getattr(val, rel_name)
+                if nested_filter is strawberry.UNSET or nested_filter is None:
+                    continue
+                return _build_tortoise_filter(
+                    nested_filter,
+                    max_depth=max_depth,
+                    max_branches=max_branches,
+                    enable_regex=enable_regex,
+                    max_in_list_size=max_in_list_size,
+                    _depth=_depth + 1,
+                    _prefix=f"{_prefix}{rel_name}__",
+                )
         elif key == "all":
             if len(val) > max_branches:
                 raise ValueError(
@@ -882,6 +900,7 @@ def _build_tortoise_filter(
 def _build_tortoise_field_clause(
     field_input: Any,
     *,
+    prefix: str = "",
     enable_regex: bool = False,
     max_in_list_size: int = 500,
 ) -> Any:
@@ -896,7 +915,7 @@ def _build_tortoise_field_clause(
         if lookup is strawberry.UNSET or lookup is None:
             continue
         col_q = _build_tortoise_lookup(
-            col_name,
+            f"{prefix}{col_name}",
             lookup,
             enable_regex=enable_regex,
             max_in_list_size=max_in_list_size,

{strawberry_orm-0.3.0 → strawberry_orm-0.4.0}/src/strawberry_orm/mutations.py

@@ -170,30 +170,39 @@ class MutationNamespace:
         *,
         models: Iterable[type] | None = None,
         project: dict[str, Any] | None = None,
+        name: str | None = None,
     ) -> type:
         selected_models = self._resolve_root_models(models)
         root_projects = self._normalize_root_project(selected_models, project)
-        return self._root_input_type("create", selected_models, root_projects)
+        return self._root_input_type(
+            "create", selected_models, root_projects, name=name
+        )
 
     def update_node_input(
         self,
         *,
         models: Iterable[type] | None = None,
         project: dict[str, Any] | None = None,
+        name: str | None = None,
     ) -> type:
         selected_models = self._resolve_root_models(models)
         root_projects = self._normalize_root_project(selected_models, project)
-        return self._root_input_type("update", selected_models, root_projects)
+        return self._root_input_type(
+            "update", selected_models, root_projects, name=name
+        )
 
     def create_node(
         self,
         *,
         models: Iterable[type] | None = None,
         project: dict[str, Any] | None = None,
+        input_name: str | None = None,
         description: str | None = None,
     ) -> Any:
         factory = self
-        input_type = self.create_node_input(models=models, project=project)
+        input_type = self.create_node_input(
+            models=models, project=project, name=input_name
+        )
 
         if self._backend.__class__.__name__ == "TortoiseBackend":
 
@@ -221,10 +230,13 @@ class MutationNamespace:
         *,
         models: Iterable[type] | None = None,
         project: dict[str, Any] | None = None,
+        input_name: str | None = None,
         description: str | None = None,
     ) -> Any:
         factory = self
-        input_type = self.update_node_input(models=models, project=project)
+        input_type = self.update_node_input(
+            models=models, project=project, name=input_name
+        )
 
         if self._backend.__class__.__name__ == "TortoiseBackend":
 
@@ -409,16 +421,19 @@ class MutationNamespace:
         operation: str,
         models: tuple[type, ...],
         root_projects: dict[str, Any],
+        *,
+        name: str | None = None,
     ) -> type:
         cache = (
             self._root_create_inputs
             if operation == "create"
             else self._root_update_inputs
         )
-        cache_key = tuple(
-            (model, self._project_signature(root_projects[_model_key(model)]))
+        root_signature = tuple(
+            (model.__name__, self._project_signature(root_projects[_model_key(model)]))
             for model in models
         )
+        cache_key = (root_signature, name)
         if cache_key in cache:
             return cache[cache_key]
 
@@ -433,13 +448,12 @@ class MutationNamespace:
             ) | None
             defaults[key] = strawberry.UNSET
 
-        root_signature = tuple(
-            (model.__name__, self._project_signature(root_projects[_model_key(model)]))
-            for model in models
-        )
         root_suffix = self._signature_suffix(root_signature)
+        class_name = name or (
+            f"{'Create' if operation == 'create' else 'Update'}NodeInput{root_suffix}"
+        )
         cls = type(
-            f"{'Create' if operation == 'create' else 'Update'}NodeInput{root_suffix}",
+            class_name,
             (),
             {"__annotations__": annotations, **defaults},
         )