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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strawberry-orm
-Version: 0.2.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>
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: strawberry-graphql>=0.311.0
+Requires-Dist: greenlet>=3.3.2 ; extra == 'dev'
 Requires-Dist: pytest>=8.0 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
 Requires-Dist: pytest-django>=4.8 ; extra == 'dev'
@@ -54,9 +55,9 @@ Backend-agnostic schema generation for [Strawberry GraphQL](https://strawberry.r
 uv add strawberry-orm
 
 # With a backend
-uv add strawberry-orm[django]
-uv add strawberry-orm[sqlalchemy]
-uv add strawberry-orm[tortoise]
+uv add "strawberry-orm[django]"
+uv add "strawberry-orm[sqlalchemy]"
+uv add "strawberry-orm[tortoise]"
 ```
 
 You can do the same with `pip`:
@@ -65,6 +66,8 @@ You can do the same with `pip`:
 pip install "strawberry-orm[sqlalchemy]"
 ```
 
+If you are using `zsh`, keep the quotes around extras such as `"strawberry-orm[sqlalchemy]"`. Unquoted square brackets are treated as shell glob syntax before `uv` or `pip` sees the package name.
+
 Requirements:
 
 - Python `>=3.12`
@@ -422,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:
@@ -640,6 +741,143 @@ In practice:
 
 ---
 
+### Recursive Node Mutations
+
+`orm.mutations.create_node(...)` and `orm.mutations.update_node(...)` generate catch-all Relay `Node` mutations with recursive nested inputs.
+
+If you want to implement the resolver logic yourself, you can generate the root input types directly with `orm.mutations.create_node_input(...)` and `orm.mutations.update_node_input(...)`:
+
+```python
+import strawberry
+from strawberry import relay
+
+
+@orm.type(User)
+class UserNode(relay.Node):
+    id: relay.NodeID[int]
+    name: auto
+    email: auto
+
+
+@orm.type(Post)
+class PostNode(relay.Node):
+    id: relay.NodeID[int]
+    title: auto
+    body: auto
+
+
+CreateNodeInput = orm.mutations.create_node_input()
+UpdateNodeInput = orm.mutations.update_node_input()
+
+
+@strawberry.type
+class Mutation:
+    create_node = orm.mutations.create_node()
+    update_node = orm.mutations.update_node()
+
+    @strawberry.field
+    def custom_create_node(self, input: CreateNodeInput) -> str:
+        return "implement your own create logic here"
+
+    @strawberry.field
+    def custom_update_node(self, input: UpdateNodeInput) -> str:
+        return "implement your own update logic here"
+```
+
+List relations use `items`, while singular relations use explicit `create` / `update` branches:
+
+```graphql
+mutation {
+  createNode(input: {
+    post: {
+      title: "Hello"
+      body: "World"
+      author: {
+        create: {
+          name: "Alice"
+          email: "alice@example.com"
+        }
+      }
+      tags: {
+        items: [{ create: { name: "python" } }]
+        mode: REPLACE
+        onRemove: DELETE
+      }
+    }
+  }) {
+    __typename
+  }
+}
+```
+
+#### Projection And Policy Config
+
+Pass `project={...}` to restrict recursion depth and configure relation semantics in one dict:
+
+```python
+project = {
+    "post": {
+        "author": {
+            "_meta": {"onReplace": ["DISCONNECT", "DELETE"]},
+        },
+        "comments": {
+            "_meta": {
+                "mode": ["PATCH", "REPLACE"],
+                "onRemove": ["DISCONNECT", "DELETE"],
+            },
+            "author": {
+                "_meta": {"onReplace": ["DISCONNECT", "DELETE"]},
+            },
+        },
+        "tags": {
+            "_meta": {
+                "mode": "REPLACE",
+                "onRemove": "DELETE",
+            },
+        },
+    },
+    "comment": {
+        "author": {
+            "_meta": {"onReplace": ["DISCONNECT", "DELETE"]},
+        },
+    },
+}
+
+
+@strawberry.type
+class Mutation:
+    create_node = orm.mutations.create_node(project=project)
+    update_node = orm.mutations.update_node(project=project)
+```
+
+Rules for the config object:
+
+- Root keys are model names (`post`, `comment`, `user`, ...).
+- Nested keys are relation names available on that model.
+- `_meta` is optional and configures behavior for that relation subtree.
+- Omitted relations still exist as shallow nested inputs, but recursion stops after one more level.
+
+`_meta` supports:
+
+- `mode`: list relation merge strategy (`PATCH` or `REPLACE`)
+- `onRemove`: what to do with removed items from a list relation (`DISCONNECT` or `DELETE`)
+- `onReplace`: what to do with the previous object when replacing a singular relation (`DISCONNECT` or `DELETE`)
+
+The `_meta` values can be either:
+
+- an array of enum strings, which means the GraphQL input exposes that field and the caller may choose from those options
+- a single enum string, which fixes that behavior for the relation and omits the corresponding GraphQL field
+
+Default behavior when a field is exposed but omitted in the mutation input:
+
+- `mode` defaults to `PATCH` when allowed
+- `onRemove` defaults to `DISCONNECT` when allowed
+- `onReplace` defaults to `DISCONNECT` when allowed
+
+If the preferred default is not included in the allowed array, the first configured value is used.
+
+---
+
 ## Query Optimization
 
 Add the optimizer extension to your schema:

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

@@ -20,9 +20,9 @@ Backend-agnostic schema generation for [Strawberry GraphQL](https://strawberry.r
 uv add strawberry-orm
 
 # With a backend
-uv add strawberry-orm[django]
-uv add strawberry-orm[sqlalchemy]
-uv add strawberry-orm[tortoise]
+uv add "strawberry-orm[django]"
+uv add "strawberry-orm[sqlalchemy]"
+uv add "strawberry-orm[tortoise]"
 ```
 
 You can do the same with `pip`:
@@ -31,6 +31,8 @@ You can do the same with `pip`:
 pip install "strawberry-orm[sqlalchemy]"
 ```
 
+If you are using `zsh`, keep the quotes around extras such as `"strawberry-orm[sqlalchemy]"`. Unquoted square brackets are treated as shell glob syntax before `uv` or `pip` sees the package name.
+
 Requirements:
 
 - Python `>=3.12`
@@ -388,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:
@@ -606,6 +706,143 @@ In practice:
 
 ---
 
+### Recursive Node Mutations
+
+`orm.mutations.create_node(...)` and `orm.mutations.update_node(...)` generate catch-all Relay `Node` mutations with recursive nested inputs.
+
+If you want to implement the resolver logic yourself, you can generate the root input types directly with `orm.mutations.create_node_input(...)` and `orm.mutations.update_node_input(...)`:
+
+```python
+import strawberry
+from strawberry import relay
+
+
+@orm.type(User)
+class UserNode(relay.Node):
+    id: relay.NodeID[int]
+    name: auto
+    email: auto
+
+
+@orm.type(Post)
+class PostNode(relay.Node):
+    id: relay.NodeID[int]
+    title: auto
+    body: auto
+
+
+CreateNodeInput = orm.mutations.create_node_input()
+UpdateNodeInput = orm.mutations.update_node_input()
+
+
+@strawberry.type
+class Mutation:
+    create_node = orm.mutations.create_node()
+    update_node = orm.mutations.update_node()
+
+    @strawberry.field
+    def custom_create_node(self, input: CreateNodeInput) -> str:
+        return "implement your own create logic here"
+
+    @strawberry.field
+    def custom_update_node(self, input: UpdateNodeInput) -> str:
+        return "implement your own update logic here"
+```
+
+List relations use `items`, while singular relations use explicit `create` / `update` branches:
+
+```graphql
+mutation {
+  createNode(input: {
+    post: {
+      title: "Hello"
+      body: "World"
+      author: {
+        create: {
+          name: "Alice"
+          email: "alice@example.com"
+        }
+      }
+      tags: {
+        items: [{ create: { name: "python" } }]
+        mode: REPLACE
+        onRemove: DELETE
+      }
+    }
+  }) {
+    __typename
+  }
+}
+```
+
+#### Projection And Policy Config
+
+Pass `project={...}` to restrict recursion depth and configure relation semantics in one dict:
+
+```python
+project = {
+    "post": {
+        "author": {
+            "_meta": {"onReplace": ["DISCONNECT", "DELETE"]},
+        },
+        "comments": {
+            "_meta": {
+                "mode": ["PATCH", "REPLACE"],
+                "onRemove": ["DISCONNECT", "DELETE"],
+            },
+            "author": {
+                "_meta": {"onReplace": ["DISCONNECT", "DELETE"]},
+            },
+        },
+        "tags": {
+            "_meta": {
+                "mode": "REPLACE",
+                "onRemove": "DELETE",
+            },
+        },
+    },
+    "comment": {
+        "author": {
+            "_meta": {"onReplace": ["DISCONNECT", "DELETE"]},
+        },
+    },
+}
+
+
+@strawberry.type
+class Mutation:
+    create_node = orm.mutations.create_node(project=project)
+    update_node = orm.mutations.update_node(project=project)
+```
+
+Rules for the config object:
+
+- Root keys are model names (`post`, `comment`, `user`, ...).
+- Nested keys are relation names available on that model.
+- `_meta` is optional and configures behavior for that relation subtree.
+- Omitted relations still exist as shallow nested inputs, but recursion stops after one more level.
+
+`_meta` supports:
+
+- `mode`: list relation merge strategy (`PATCH` or `REPLACE`)
+- `onRemove`: what to do with removed items from a list relation (`DISCONNECT` or `DELETE`)
+- `onReplace`: what to do with the previous object when replacing a singular relation (`DISCONNECT` or `DELETE`)
+
+The `_meta` values can be either:
+
+- an array of enum strings, which means the GraphQL input exposes that field and the caller may choose from those options
+- a single enum string, which fixes that behavior for the relation and omits the corresponding GraphQL field
+
+Default behavior when a field is exposed but omitted in the mutation input:
+
+- `mode` defaults to `PATCH` when allowed
+- `onRemove` defaults to `DISCONNECT` when allowed
+- `onReplace` defaults to `DISCONNECT` when allowed
+
+If the preferred default is not included in the allowed array, the first configured value is used.
+
+---
+
 ## Query Optimization
 
 Add the optimizer extension to your schema:

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

@@ -1,6 +1,6 @@
 [project]
 name = "strawberry-orm"
-version = "0.2.0"
+version = "0.4.0"
 description = "Unified, backend-agnostic ORM abstraction for Strawberry GraphQL"
 readme = "README.md"
 license = "MIT"
@@ -33,6 +33,7 @@ django = ["django>=4.2"]
 sqlalchemy = ["sqlalchemy>=2.0"]
 tortoise = ["tortoise-orm>=0.25.0"]
 dev = [
+    "greenlet>=3.3.2",
     "pytest>=8.0",
     "pytest-asyncio>=0.24",
     "pytest-django>=4.8",
@@ -46,6 +47,7 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "pytest-cov>=7.0.0",
     "starlette>=0.52.1",
     "typer>=0.24.1",
     "uvicorn>=0.41.0",