strawberry-graphql 0.235.1.dev1719337273__py3-none-any.whl → 0.236.0__py3-none-any.whl

strawberry/types/info.py

@@ -23,10 +23,13 @@ if TYPE_CHECKING:
     from graphql.language import FieldNode
     from graphql.pyutils.path import Path
 
-    from strawberry.arguments import StrawberryArgument
-    from strawberry.field import StrawberryField
     from strawberry.schema import Schema
-    from strawberry.type import StrawberryType, WithStrawberryObjectDefinition
+    from strawberry.types.arguments import StrawberryArgument
+    from strawberry.types.base import (
+        StrawberryType,
+        WithStrawberryObjectDefinition,
+    )
+    from strawberry.types.field import StrawberryField
 
     from .nodes import Selection
 
@@ -36,6 +39,36 @@ RootValueType = TypeVar("RootValueType", default=Any)
 
 @dataclasses.dataclass
 class Info(Generic[ContextType, RootValueType]):
+    """Class containing information about the current execution.
+
+    This class is passed to resolvers when there's an argument with type `Info`.
+
+    Example:
+    ```python
+    import strawberry
+
+
+    @strawberry.type
+    class Query:
+        @strawberry.field
+        def hello(self, info: strawberry.Info) -> str:
+            return f"Hello, {info.context['name']}!"
+    ```
+
+    It also supports passing the type of the context and root types:
+
+    ```python
+    import strawberry
+
+
+    @strawberry.type
+    class Query:
+        @strawberry.field
+        def hello(self, info: strawberry.Info[str, str]) -> str:
+            return f"Hello, {info.context}!"
+    ```
+    """
+
     _raw_info: GraphQLResolveInfo
     _field: StrawberryField
 
@@ -48,7 +81,6 @@ class Info(Generic[ContextType, RootValueType]):
         See:
         https://discuss.python.org/t/passing-only-one-typevar-of-two-when-using-defaults/49134
         """
-
         if not isinstance(types, tuple):
             types = (types, Any)  # type: ignore
 
@@ -56,10 +88,12 @@ class Info(Generic[ContextType, RootValueType]):
 
     @property
     def field_name(self) -> str:
+        """The name of the current field being resolved."""
         return self._raw_info.field_name
 
     @property
     def schema(self) -> Schema:
+        """The schema of the current execution."""
         return self._raw_info.schema._strawberry_schema  # type: ignore
 
     @property
@@ -74,48 +108,57 @@ class Info(Generic[ContextType, RootValueType]):
 
     @cached_property
     def selected_fields(self) -> List[Selection]:
+        """The fields that were selected on the current field's type."""
         info = self._raw_info
         return convert_selections(info, info.field_nodes)
 
     @property
     def context(self) -> ContextType:
+        """The context passed to the query execution."""
         return self._raw_info.context
 
     @property
     def root_value(self) -> RootValueType:
+        """The root value passed to the query execution."""
         return self._raw_info.root_value
 
     @property
     def variable_values(self) -> Dict[str, Any]:
+        """The variable values passed to the query execution."""
         return self._raw_info.variable_values
 
     @property
     def return_type(
         self,
     ) -> Optional[Union[Type[WithStrawberryObjectDefinition], StrawberryType]]:
+        """The return type of the current field being resolved."""
         return self._field.type
 
     @property
     def python_name(self) -> str:
+        """The name of the current field being resolved in Python format."""
         return self._field.python_name
 
     # TODO: create an abstraction on these fields
     @property
     def operation(self) -> OperationDefinitionNode:
+        """The operation being executed."""
         return self._raw_info.operation
 
     @property
     def path(self) -> Path:
+        """The path of the current field being resolved."""
         return self._raw_info.path
 
     # TODO: parent_type as strawberry types
 
     # Helper functions
     def get_argument_definition(self, name: str) -> Optional[StrawberryArgument]:
-        """
-        Get the StrawberryArgument definition for the current field by name.
-        """
+        """Get the StrawberryArgument definition for the current field by name."""
         try:
             return next(arg for arg in self._field.arguments if arg.python_name == name)
         except StopIteration:
             return None
+
+
+__all__ = ["Info"]

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"]