strawberry-graphql 0.235.2__py3-none-any.whl → 0.236.0__py3-none-any.whl

strawberry/{lazy_type.py → types/lazy_type.py}

@@ -25,6 +25,14 @@ Module = TypeVar("Module")
 
 @dataclass(frozen=True)
 class LazyType(Generic[TypeName, Module]):
+    """A class that represents a type that will be resolved at runtime.
+
+    This is useful when you have circular dependencies between types.
+
+    This class is not meant to be used directly, instead use the `strawberry.lazy`
+    function.
+    """
+
     type_name: str
     module: str
     package: Optional[str] = None
@@ -81,6 +89,14 @@ class LazyType(Generic[TypeName, Module]):
 
 
 class StrawberryLazyReference:
+    """A class that represents a lazy reference to a type in another module.
+
+    This is useful when you have circular dependencies between types.
+
+    This class is not meant to be used directly, instead use the `strawberry.lazy`
+    function.
+    """
+
     def __init__(self, module: str) -> None:
         self.module = module
         self.package = None
@@ -105,4 +121,38 @@ class StrawberryLazyReference:
 
 
 def lazy(module_path: str) -> StrawberryLazyReference:
+    """Creates a lazy reference to a type in another module.
+
+    Args:
+        module_path: The path to the module containing the type, supports relative paths
+            starting with `.`
+
+    Returns:
+        A `StrawberryLazyReference` object that can be used to reference a type in another
+        module.
+
+    This is useful when you have circular dependencies between types.
+
+    For example, assuming you have a `Post` type that has a field `author` that
+    references a `User` type (which also has a field `posts` that references a list of
+    `Post`), you can use `strawberry.lazy` to avoid the circular dependency:
+
+    ```python
+    from typing import TYPE_CHECKING, Annotated
+
+    import strawberry
+
+    if TYPE_CHECKING:
+        from .users import User
+
+
+    @strawberry.type
+    class Post:
+        title: str
+        author: Annotated["User", strawberry.lazy(".users")]
+    ```
+    """
     return StrawberryLazyReference(module_path)
+
+
+__all__ = ["LazyType", "StrawberryLazyReference", "lazy"]

strawberry/types/mutation.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import dataclasses
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    Type,
+    Union,
+    overload,
+)
+from typing_extensions import Literal
+
+from strawberry.types.field import (
+    _RESOLVER_TYPE,
+    _RESOLVER_TYPE_ASYNC,
+    _RESOLVER_TYPE_SYNC,
+    StrawberryField,
+    T,
+    field,
+)
+
+if TYPE_CHECKING:
+    from typing_extensions import Literal
+
+    from strawberry.extensions.field_extension import FieldExtension
+    from strawberry.permission import BasePermission
+
+# NOTE: we are separating the sync and async resolvers because using both
+# in the same function will cause mypy to raise an error. Not sure if it is a bug
+
+
+@overload
+def mutation(
+    *,
+    resolver: _RESOLVER_TYPE_ASYNC[T],
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    init: Literal[False] = False,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+) -> T: ...
+
+
+@overload
+def mutation(
+    *,
+    resolver: _RESOLVER_TYPE_SYNC[T],
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    init: Literal[False] = False,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+) -> T: ...
+
+
+@overload
+def mutation(
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    init: Literal[True] = True,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+) -> Any: ...
+
+
+@overload
+def mutation(
+    resolver: _RESOLVER_TYPE_ASYNC[T],
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+) -> StrawberryField: ...
+
+
+@overload
+def mutation(
+    resolver: _RESOLVER_TYPE_SYNC[T],
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+) -> StrawberryField: ...
+
+
+def mutation(
+    resolver: Optional[_RESOLVER_TYPE[Any]] = None,
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+    # This init parameter is used by PyRight to determine whether this field
+    # is added in the constructor or not. It is not used to change
+    # any behavior at the moment.
+    init: Literal[True, False, None] = None,
+) -> Any:
+    """Annotates a method or property as a GraphQL mutation.
+
+    Args:
+        resolver: The resolver for the field. It can be a sync or async function.
+        name: The GraphQL name of the field.
+        description: The GraphQL description of the field.
+        permission_classes: The permission classes required to access the field.
+        deprecation_reason: The deprecation reason for the field.
+        default: The default value for the field.
+        default_factory: The default factory for the field.
+        metadata: The metadata for the field.
+        directives: The directives for the field.
+        extensions: The extensions for the field.
+        graphql_type: The GraphQL type for the field, useful when you want to use a
+            different type in the resolver than the one in the schema.
+        init: This parameter is used by PyRight to determine whether this field is
+            added in the constructor or not. It is not used to change any behavior at
+            the moment.
+
+    Returns:
+        The field object.
+
+    This is normally used inside a type declaration:
+
+    ```python
+    import strawberry
+
+
+    @strawberry.type
+    class Mutation:
+        @strawberry.mutation
+        def create_post(self, title: str, content: str) -> Post: ...
+    ```
+
+    It can be used both as decorator and as a normal function.
+    """
+    return field(
+        resolver=resolver,  # type: ignore
+        name=name,
+        description=description,
+        permission_classes=permission_classes,
+        deprecation_reason=deprecation_reason,
+        default=default,
+        default_factory=default_factory,
+        metadata=metadata,
+        directives=directives,
+        extensions=extensions,
+        graphql_type=graphql_type,
+    )
+
+
+# NOTE: we are separating the sync and async resolvers because using both
+# in the same function will cause mypy to raise an error. Not sure if it is a bug
+
+
+@overload
+def subscription(
+    *,
+    resolver: _RESOLVER_TYPE_ASYNC[T],
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    init: Literal[False] = False,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+) -> T: ...
+
+
+@overload
+def subscription(
+    *,
+    resolver: _RESOLVER_TYPE_SYNC[T],
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    init: Literal[False] = False,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+) -> T: ...
+
+
+@overload
+def subscription(
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    init: Literal[True] = True,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+) -> Any: ...
+
+
+@overload
+def subscription(
+    resolver: _RESOLVER_TYPE_ASYNC[T],
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+) -> StrawberryField: ...
+
+
+@overload
+def subscription(
+    resolver: _RESOLVER_TYPE_SYNC[T],
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+) -> StrawberryField: ...
+
+
+def subscription(
+    resolver: Optional[_RESOLVER_TYPE[Any]] = None,
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    permission_classes: Optional[List[Type[BasePermission]]] = None,
+    deprecation_reason: Optional[str] = None,
+    default: Any = dataclasses.MISSING,
+    default_factory: Union[Callable[..., object], object] = dataclasses.MISSING,
+    metadata: Optional[Mapping[Any, Any]] = None,
+    directives: Optional[Sequence[object]] = (),
+    extensions: Optional[List[FieldExtension]] = None,
+    graphql_type: Optional[Any] = None,
+    init: Literal[True, False, None] = None,
+) -> Any:
+    """Annotates a method or property as a GraphQL subscription.
+
+    Args:
+        resolver: The resolver for the field.
+        name: The GraphQL name of the field.
+        description: The GraphQL description of the field.
+        permission_classes: The permission classes required to access the field.
+        deprecation_reason: The deprecation reason for the field.
+        default: The default value for the field.
+        default_factory: The default factory for the field.
+        metadata: The metadata for the field.
+        directives: The directives for the field.
+        extensions: The extensions for the field.
+        graphql_type: The GraphQL type for the field, useful when you want to use a
+            different type in the resolver than the one in the schema.
+        init: This parameter is used by PyRight to determine whether this field is
+            added in the constructor or not. It is not used to change any behavior at
+            the moment.
+
+    Returns:
+        The field for the subscription.
+
+    This is normally used inside a type declaration:
+
+    ```python
+    import strawberry
+
+
+    @strawberry.type
+    class Subscription:
+        @strawberry.subscription
+        def post_created(self, title: str, content: str) -> Post: ...
+    ```
+
+    it can be used both as decorator and as a normal function.
+    """
+    return field(
+        resolver=resolver,  # type: ignore
+        name=name,
+        description=description,
+        is_subscription=True,
+        permission_classes=permission_classes,
+        deprecation_reason=deprecation_reason,
+        default=default,
+        default_factory=default_factory,
+        metadata=metadata,
+        directives=directives,
+        extensions=extensions,
+        graphql_type=graphql_type,
+    )
+
+
+__all__ = ["mutation", "subscription"]

strawberry/types/nodes.py

@@ -1,5 +1,4 @@
-"""
-Abstraction layer for graphql-core field nodes.
+"""Abstraction layer for graphql-core field nodes.
 
 Call `convert_sections` on a list of GraphQL `FieldNode`s,
 such as in `info.field_nodes`.
@@ -151,3 +150,6 @@ class SelectedField:
                 info, getattr(node.selection_set, "selections", [])
             ),
         )
+
+
+__all__ = ["convert_selections", "FragmentSpread", "InlineFragment", "SelectedField"]

strawberry/{object_type.py → types/object_type.py}

@@ -16,20 +16,19 @@ from typing import (
 )
 from typing_extensions import dataclass_transform
 
-from .exceptions import (
+from strawberry.exceptions import (
     MissingFieldAnnotationError,
     MissingReturnAnnotationError,
     ObjectIsNotClassError,
 )
+from strawberry.types.base import get_object_definition
+from strawberry.utils.dataclasses import add_custom_init_fn
+from strawberry.utils.deprecations import DEPRECATION_MESSAGES, DeprecatedDescriptor
+from strawberry.utils.str_converters import to_camel_case
+
+from .base import StrawberryObjectDefinition
 from .field import StrawberryField, field
-from .type import get_object_definition
-from .types.type_resolver import _get_fields
-from .types.types import (
-    StrawberryObjectDefinition,
-)
-from .utils.dataclasses import add_custom_init_fn
-from .utils.deprecations import DEPRECATION_MESSAGES, DeprecatedDescriptor
-from .utils.str_converters import to_camel_case
+from .type_resolver import _get_fields
 
 T = TypeVar("T", bound=Type)
 
@@ -103,9 +102,7 @@ def _check_field_annotations(cls: Type[Any]) -> None:
 
 
 def _wrap_dataclass(cls: Type[T]) -> Type[T]:
-    """Wrap a strawberry.type class with a dataclass and check for any issues
-    before doing so"""
-
+    """Wrap a strawberry.type class with a dataclass and check for any issues before doing so."""
     # Ensure all Fields have been properly type-annotated
     _check_field_annotations(cls)
 
@@ -232,11 +229,36 @@ def type(
 ) -> Union[T, Callable[[T], T]]:
     """Annotates a class as a GraphQL type.
 
+    Similar to `dataclasses.dataclass`, but with additional functionality for
+    defining GraphQL types.
+
+    Args:
+        cls: The class we want to create a GraphQL type from.
+        name: The name of the GraphQL type.
+        is_input: Whether the class is an input type. Used internally, use `@strawerry.input` instead of passing this flag.
+        is_interface: Whether the class is an interface. Used internally, use `@strawerry.interface` instead of passing this flag.
+        description: The description of the GraphQL type.
+        directives: The directives of the GraphQL type.
+        extend: Whether the class is extending an existing type.
+
+    Returns:
+        The class.
+
     Example usage:
 
-    >>> @strawberry.type
-    >>> class X:
-    >>>     field_abc: str = "ABC"
+    ```python
+    @strawberry.type
+    class User:
+        name: str = "A name"
+    ```
+
+    You can also pass parameters to the decorator:
+
+    ```python
+    @strawberry.type(name="UserType", description="A user type")
+    class MyUser:
+        name: str = "A name"
+    ```
     """
 
     def wrap(cls: T) -> T:
@@ -321,12 +343,35 @@ def input(
     directives: Optional[Sequence[object]] = (),
 ):
     """Annotates a class as a GraphQL Input type.
+
+    Similar to `@strawberry.type`, but for input types.
+
+    Args:
+        cls: The class we want to create a GraphQL input type from.
+        name: The name of the GraphQL input type.
+        description: The description of the GraphQL input type.
+        directives: The directives of the GraphQL input type.
+        one_of: Whether the input type is a `oneOf` type.
+
+    Returns:
+        The class.
+
     Example usage:
-    >>> @strawberry.input
-    >>> class X:
-    >>>     field_abc: str = "ABC"
-    """
 
+    ```python
+    @strawberry.input
+    class UserInput:
+        name: str
+    ```
+
+    You can also pass parameters to the decorator:
+
+    ```python
+    @strawberry.input(name="UserInputType", description="A user input type")
+    class MyUserInput:
+        name: str
+    ```
+    """
     from strawberry.schema_directives import OneOf
 
     if one_of:
@@ -377,12 +422,34 @@ def interface(
     directives: Optional[Sequence[object]] = (),
 ):
     """Annotates a class as a GraphQL Interface.
+
+    Similar to `@strawberry.type`, but for interfaces.
+
+    Args:
+        cls: The class we want to create a GraphQL interface from.
+        name: The name of the GraphQL interface.
+        description: The description of the GraphQL interface.
+        directives: The directives of the GraphQL interface.
+
+    Returns:
+        The class.
+
     Example usage:
-    >>> @strawberry.interface
-    >>> class X:
-    >>>     field_abc: str
-    """
 
+    ```python
+    @strawberry.interface
+    class Node:
+        id: str
+    ```
+
+    You can also pass parameters to the decorator:
+
+    ```python
+    @strawberry.interface(name="NodeType", description="A node type")
+    class MyNode:
+        id: str
+    ```
+    """
     return type(  # type: ignore # not sure why mypy complains here
         cls,
         name=name,
@@ -394,15 +461,27 @@ def interface(
 
 def asdict(obj: Any) -> Dict[str, object]:
     """Convert a strawberry object into a dictionary.
+
     This wraps the dataclasses.asdict function to strawberry.
 
+    Args:
+        obj: The object to convert into a dictionary.
+
+    Returns:
+        A dictionary representation of the object.
+
     Example usage:
-    >>> @strawberry.type
-    >>> class User:
-    >>>     name: str
-    >>>     age: int
-    >>> # should be {"name": "Lorem", "age": 25}
-    >>> user_dict = strawberry.asdict(User(name="Lorem", age=25))
+
+    ```python
+    @strawberry.type
+    class User:
+        name: str
+        age: int
+
+
+    strawberry.asdict(User(name="Lorem", age=25))
+    # {"name": "Lorem", "age": 25}
+    ```
     """
     return dataclasses.asdict(obj)
 

strawberry/{private.py → types/private.py}

@@ -10,17 +10,24 @@ class StrawberryPrivate: ...
 T = TypeVar("T")
 
 Private = Annotated[T, StrawberryPrivate()]
-Private.__doc__ = """Represents a field that won't be exposed in the GraphQL schema
+"""Represents a field that won't be exposed in the GraphQL schema.
 
 Example:
 
->>> import strawberry
->>> @strawberry.type
-... class User:
-...     name: str
-...     age: strawberry.Private[int]
+```python
+import strawberry
+
+
+@strawberry.type
+class User:
+    name: str
+    age: strawberry.Private[int]
+```
 """
 
 
 def is_private(type_: object) -> bool:
     return type_has_annotation(type_, StrawberryPrivate)
+
+
+__all__ = ["Private", "is_private"]