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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strawberry-orm
-Version: 0.1.1
+Version: 0.3.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>
@@ -9,11 +9,12 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-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: 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'
@@ -22,7 +23,7 @@ Requires-Dist: uvicorn>=0.30 ; extra == 'dev'
 Requires-Dist: django>=4.2 ; extra == 'django'
 Requires-Dist: sqlalchemy>=2.0 ; extra == 'sqlalchemy'
 Requires-Dist: tortoise-orm>=0.25.0 ; extra == 'tortoise'
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Project-URL: Homepage, https://github.com/strawberry-graphql/strawberry-orm
 Project-URL: Repository, https://github.com/strawberry-graphql/strawberry-orm
 Project-URL: Issues, https://github.com/strawberry-graphql/strawberry-orm/issues
@@ -36,8 +37,8 @@ Description-Content-Type: text/markdown
 
 Backend-agnostic schema generation for [Strawberry GraphQL](https://strawberry.rocks/) on top of Django ORM, SQLAlchemy, and Tortoise ORM.
 
-> **WARNING**
-> `strawberry-orm` is still in **alpha**. Expect breaking changes, incomplete APIs, and release-to-release churn while the package stabilizes.
+> ## WARNING
+> 🟧🟨 `strawberry-orm` is still in **alpha**. Expect breaking changes, incomplete APIs, and release-to-release churn while the package stabilizes. 🟨🟧
 
 `strawberry-orm` helps you keep one Strawberry schema style across multiple ORMs. It focuses on:
 
@@ -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,9 +66,11 @@ 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.10`
+- Python `>=3.12`
 - `strawberry-graphql>=0.311.0`
 
 ## Quick Start
@@ -121,11 +124,24 @@ That single `users` field will:
 
 ## Backends
 
+`strawberry-orm` follows Strawberry's mixed execution model:
+
+- sync and async schema execution are both supported
+- a resolver can return plain values, backend query objects, or awaitables
+- the optimizer extension handles both sync and async execution paths
+- direct helper APIs such as `apply_ref_list(...)` may be sync or awaitable depending on the backend/session in use
+
+As a rule of thumb:
+
+- Django works in both sync and async Strawberry execution, but custom async resolvers still need `sync_to_async(...)` around direct Django ORM access
+- SQLAlchemy supports both sync `Session` and `AsyncSession`
+- Tortoise is async-first; use async Strawberry execution there
+
 | Backend | Constructor | Notes |
 | --- | --- | --- |
-| Django | `StrawberryORM("django")` | Uses Django querysets directly. |
-| SQLAlchemy | `StrawberryORM("sqlalchemy", dialect="postgresql", session_getter=...)` | Requires a SQLAlchemy session at resolve time. |
-| Tortoise | `StrawberryORM("tortoise")` | Async ORM; use Strawberry in async mode. |
+| Django | `StrawberryORM("django")` | Uses Django querysets directly; async execution is supported via Strawberry's mixed sync/async model. |
+| SQLAlchemy | `StrawberryORM("sqlalchemy", dialect="postgresql", session_getter=...)` | Requires a SQLAlchemy `Session` or `AsyncSession` at resolve time. |
+| Tortoise | `StrawberryORM("tortoise")` | Async ORM; use Strawberry's async execution path. |
 
 ### Django
 
@@ -133,6 +149,8 @@ That single `users` field will:
 orm = StrawberryORM("django")
 ```
 
+When executing the schema asynchronously, custom resolvers that touch Django models directly should still wrap those ORM calls with `sync_to_async(...)`, following the same guidance as `strawberry-django`.
+
 ### SQLAlchemy
 
 ```python
@@ -152,12 +170,48 @@ SQLAlchemy needs a session when a query is executed. `strawberry-orm` can obtain
 
 If your context stores a callable session factory, pass a `session_getter` instead of putting the callable directly on `info.context`.
 
+Both sync and async sessions are supported:
+
+```python
+# Sync session
+orm = StrawberryORM(
+    "sqlalchemy",
+    dialect="postgresql",
+    session_getter=lambda info: info.context["session"],
+)
+
+# Async session
+orm = StrawberryORM(
+    "sqlalchemy",
+    dialect="postgresql",
+    session_getter=lambda info: info.context["session"],
+)
+
+@strawberry.type
+class Query:
+    @strawberry.field
+    def users(self) -> list[UserType]:
+        return select(User)
+
+# context["session"] can be either Session or AsyncSession
+```
+
 ### Tortoise
 
 ```python
 orm = StrawberryORM("tortoise")
 ```
 
+Tortoise resolvers, mutations, and related-list helpers should be used from async Strawberry execution:
+
+```python
+@strawberry.type
+class Query:
+    @strawberry.field
+    async def users(self) -> list[UserType]:
+        return await User.all()
+```
+
 ### Backend Options
 
 Shared options:
@@ -453,6 +507,17 @@ class Query:
 
 This works with the optimizer extension and with type-level `get_queryset` hooks.
 
+If you execute your schema asynchronously, the same pattern works with async resolvers too:
+
+```python
+@strawberry.type
+class Query:
+    @strawberry.field
+    async def active_users(self, info: strawberry.types.Info) -> list[UserType]:
+        return await User.filter(is_active=True)  # Tortoise
+        # return await sync_to_async(list)(User.objects.filter(is_active=True))  # Django
+```
+
 ---
 
 ## Mutations
@@ -483,6 +548,24 @@ class Mutation:
         ...
 ```
 
+Async mutations work too. Use async ORM calls in the resolver body, and await backend helpers when the active backend/session requires it:
+
+```python
+@strawberry.type
+class Mutation:
+    @strawberry.mutation
+    async def create_post(
+        self,
+        info: strawberry.types.Info,
+        input: CreatePostInput,
+    ) -> PostType:
+        return await Post.create(
+            title=input.title,
+            body=input.body,
+            author_id=input.author_id,
+        )
+```
+
 ### Related List Inputs (`orm.ref`)
 
 `orm.ref(...)` generates a `@oneOf` input for managing related lists:
@@ -517,6 +600,24 @@ def set_post_tags(self, info: strawberry.types.Info, post_id: int, tags: list[Ta
     return post
 ```
 
+Async backends can use the same helper from async mutations:
+
+```python
+@strawberry.mutation
+async def set_post_tags(
+    self,
+    info: strawberry.types.Info,
+    post_id: int,
+    tags: list[TagRef],
+) -> PostType | None:
+    post = await Post.get_or_none(pk=post_id)
+    if post is None:
+        return None
+
+    await orm.apply_ref_list(post, "tags", tags, info)
+    return post
+```
+
 ```graphql
 mutation {
   setPostTags(postId: 1, tags: [
@@ -533,6 +634,150 @@ mutation {
 
 `apply_ref_list` supports `mode="replace"` (default, replaces the entire list) and `mode="patch"` (only touches mentioned items). An optional `authorize` callback receives `(action, model, obj_id, info)` and returns `bool`.
 
+In practice:
+
+- use it directly in sync Django / sync SQLAlchemy mutations
+- `await` it for Tortoise
+- `await` it for SQLAlchemy when your request context carries an `AsyncSession`
+- in custom async Django resolvers, prefer the same async-safe pattern you already use for direct ORM calls
+
+---
+
+### 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

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

@@ -2,8 +2,8 @@
 
 Backend-agnostic schema generation for [Strawberry GraphQL](https://strawberry.rocks/) on top of Django ORM, SQLAlchemy, and Tortoise ORM.
 
-> **WARNING**
-> `strawberry-orm` is still in **alpha**. Expect breaking changes, incomplete APIs, and release-to-release churn while the package stabilizes.
+> ## WARNING
+> 🟧🟨 `strawberry-orm` is still in **alpha**. Expect breaking changes, incomplete APIs, and release-to-release churn while the package stabilizes. 🟨🟧
 
 `strawberry-orm` helps you keep one Strawberry schema style across multiple ORMs. It focuses on:
 
@@ -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,9 +31,11 @@ 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.10`
+- Python `>=3.12`
 - `strawberry-graphql>=0.311.0`
 
 ## Quick Start
@@ -87,11 +89,24 @@ That single `users` field will:
 
 ## Backends
 
+`strawberry-orm` follows Strawberry's mixed execution model:
+
+- sync and async schema execution are both supported
+- a resolver can return plain values, backend query objects, or awaitables
+- the optimizer extension handles both sync and async execution paths
+- direct helper APIs such as `apply_ref_list(...)` may be sync or awaitable depending on the backend/session in use
+
+As a rule of thumb:
+
+- Django works in both sync and async Strawberry execution, but custom async resolvers still need `sync_to_async(...)` around direct Django ORM access
+- SQLAlchemy supports both sync `Session` and `AsyncSession`
+- Tortoise is async-first; use async Strawberry execution there
+
 | Backend | Constructor | Notes |
 | --- | --- | --- |
-| Django | `StrawberryORM("django")` | Uses Django querysets directly. |
-| SQLAlchemy | `StrawberryORM("sqlalchemy", dialect="postgresql", session_getter=...)` | Requires a SQLAlchemy session at resolve time. |
-| Tortoise | `StrawberryORM("tortoise")` | Async ORM; use Strawberry in async mode. |
+| Django | `StrawberryORM("django")` | Uses Django querysets directly; async execution is supported via Strawberry's mixed sync/async model. |
+| SQLAlchemy | `StrawberryORM("sqlalchemy", dialect="postgresql", session_getter=...)` | Requires a SQLAlchemy `Session` or `AsyncSession` at resolve time. |
+| Tortoise | `StrawberryORM("tortoise")` | Async ORM; use Strawberry's async execution path. |
 
 ### Django
 
@@ -99,6 +114,8 @@ That single `users` field will:
 orm = StrawberryORM("django")
 ```
 
+When executing the schema asynchronously, custom resolvers that touch Django models directly should still wrap those ORM calls with `sync_to_async(...)`, following the same guidance as `strawberry-django`.
+
 ### SQLAlchemy
 
 ```python
@@ -118,12 +135,48 @@ SQLAlchemy needs a session when a query is executed. `strawberry-orm` can obtain
 
 If your context stores a callable session factory, pass a `session_getter` instead of putting the callable directly on `info.context`.
 
+Both sync and async sessions are supported:
+
+```python
+# Sync session
+orm = StrawberryORM(
+    "sqlalchemy",
+    dialect="postgresql",
+    session_getter=lambda info: info.context["session"],
+)
+
+# Async session
+orm = StrawberryORM(
+    "sqlalchemy",
+    dialect="postgresql",
+    session_getter=lambda info: info.context["session"],
+)
+
+@strawberry.type
+class Query:
+    @strawberry.field
+    def users(self) -> list[UserType]:
+        return select(User)
+
+# context["session"] can be either Session or AsyncSession
+```
+
 ### Tortoise
 
 ```python
 orm = StrawberryORM("tortoise")
 ```
 
+Tortoise resolvers, mutations, and related-list helpers should be used from async Strawberry execution:
+
+```python
+@strawberry.type
+class Query:
+    @strawberry.field
+    async def users(self) -> list[UserType]:
+        return await User.all()
+```
+
 ### Backend Options
 
 Shared options:
@@ -419,6 +472,17 @@ class Query:
 
 This works with the optimizer extension and with type-level `get_queryset` hooks.
 
+If you execute your schema asynchronously, the same pattern works with async resolvers too:
+
+```python
+@strawberry.type
+class Query:
+    @strawberry.field
+    async def active_users(self, info: strawberry.types.Info) -> list[UserType]:
+        return await User.filter(is_active=True)  # Tortoise
+        # return await sync_to_async(list)(User.objects.filter(is_active=True))  # Django
+```
+
 ---
 
 ## Mutations
@@ -449,6 +513,24 @@ class Mutation:
         ...
 ```
 
+Async mutations work too. Use async ORM calls in the resolver body, and await backend helpers when the active backend/session requires it:
+
+```python
+@strawberry.type
+class Mutation:
+    @strawberry.mutation
+    async def create_post(
+        self,
+        info: strawberry.types.Info,
+        input: CreatePostInput,
+    ) -> PostType:
+        return await Post.create(
+            title=input.title,
+            body=input.body,
+            author_id=input.author_id,
+        )
+```
+
 ### Related List Inputs (`orm.ref`)
 
 `orm.ref(...)` generates a `@oneOf` input for managing related lists:
@@ -483,6 +565,24 @@ def set_post_tags(self, info: strawberry.types.Info, post_id: int, tags: list[Ta
     return post
 ```
 
+Async backends can use the same helper from async mutations:
+
+```python
+@strawberry.mutation
+async def set_post_tags(
+    self,
+    info: strawberry.types.Info,
+    post_id: int,
+    tags: list[TagRef],
+) -> PostType | None:
+    post = await Post.get_or_none(pk=post_id)
+    if post is None:
+        return None
+
+    await orm.apply_ref_list(post, "tags", tags, info)
+    return post
+```
+
 ```graphql
 mutation {
   setPostTags(postId: 1, tags: [
@@ -499,6 +599,150 @@ mutation {
 
 `apply_ref_list` supports `mode="replace"` (default, replaces the entire list) and `mode="patch"` (only touches mentioned items). An optional `authorize` callback receives `(action, model, obj_id, info)` and returns `bool`.
 
+In practice:
+
+- use it directly in sync Django / sync SQLAlchemy mutations
+- `await` it for Tortoise
+- `await` it for SQLAlchemy when your request context carries an `AsyncSession`
+- in custom async Django resolvers, prefer the same async-safe pattern you already use for direct ORM calls
+
+---
+
+### 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