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

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

@@ -16,25 +16,28 @@ from typing import (
 from typing_extensions import Annotated, get_args, get_origin
 
 from strawberry.annotation import StrawberryAnnotation
-from strawberry.enum import EnumDefinition
-from strawberry.lazy_type import LazyType, StrawberryLazyReference
-from strawberry.type import StrawberryList, StrawberryOptional, has_object_definition
-
-from .exceptions import MultipleStrawberryArgumentsError, UnsupportedTypeError
-from .scalars import is_scalar
-from .unset import UNSET as _deprecated_UNSET
-from .unset import _deprecated_is_unset  # noqa # type: ignore
+from strawberry.exceptions import MultipleStrawberryArgumentsError, UnsupportedTypeError
+from strawberry.scalars import is_scalar
+from strawberry.types.base import (
+    StrawberryList,
+    StrawberryOptional,
+    has_object_definition,
+)
+from strawberry.types.enum import EnumDefinition
+from strawberry.types.lazy_type import LazyType, StrawberryLazyReference
+from strawberry.types.unset import UNSET as _deprecated_UNSET
+from strawberry.types.unset import _deprecated_is_unset  # noqa # type: ignore
 
 if TYPE_CHECKING:
-    from strawberry.custom_scalar import ScalarDefinition, ScalarWrapper
     from strawberry.schema.config import StrawberryConfig
-    from strawberry.type import StrawberryType
+    from strawberry.types.base import StrawberryType
+    from strawberry.types.scalar import ScalarDefinition, ScalarWrapper
 
 
 DEPRECATED_NAMES: Dict[str, str] = {
     "UNSET": (
         "importing `UNSET` from `strawberry.arguments` is deprecated, "
-        "import instead from `strawberry` or from `strawberry.unset`"
+        "import instead from `strawberry` or from `strawberry.types.unset`"
     ),
     "is_unset": "`is_unset` is deprecated use `value is UNSET` instead",
 }
@@ -202,8 +205,8 @@ def convert_arguments(
     """Converts a nested dictionary to a dictionary of actual types.
 
     It deals with conversion of input types to proper dataclasses and
-    also uses a sentinel value for unset values."""
-
+    also uses a sentinel value for unset values.
+    """
     if not arguments:
         return {}
 
@@ -234,6 +237,34 @@ def argument(
     directives: Iterable[object] = (),
     metadata: Optional[Mapping[Any, Any]] = None,
 ) -> StrawberryArgumentAnnotation:
+    """Function to add metadata to an argument, like a description or deprecation reason.
+
+    Args:
+        description: The GraphQL description of the argument
+        name: The GraphQL name of the argument
+        deprecation_reason: The reason why this argument is deprecated,
+            setting this will mark the argument as deprecated
+        directives: The directives to attach to the argument
+        metadata: Metadata to attach to the argument, this can be used
+            to store custom data that can be used by custom logic or plugins
+
+    Returns:
+        A StrawberryArgumentAnnotation object that can be used to customise an argument
+
+    Example:
+    ```python
+    import strawberry
+
+
+    @strawberry.type
+    class Query:
+        @strawberry.field
+        def example(
+            self, info, value: int = strawberry.argument(description="The value")
+        ) -> int:
+            return value
+    ```
+    """
     return StrawberryArgumentAnnotation(
         description=description,
         name=name,

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

@@ -3,9 +3,8 @@ from __future__ import annotations
 from typing import Any, Optional, Union, cast
 from typing_extensions import Annotated, get_args, get_origin
 
-from strawberry.type import StrawberryType
-
-from .annotation import StrawberryAnnotation
+from strawberry.annotation import StrawberryAnnotation
+from strawberry.types.base import StrawberryType
 
 
 class StrawberryAutoMeta(type):
@@ -77,3 +76,22 @@ class StrawberryAuto(metaclass=StrawberryAutoMeta):
 
 
 auto = Annotated[Any, StrawberryAuto()]
+"""Special marker for automatic annotation.
+
+A special value that can be used to automatically infer the type of a field
+when using integrations like Strawberry Django or Strawberry Pydantic.
+
+Example:
+```python
+import strawberry
+
+from my_user_app import models
+
+
+@strawberry.django.type(models.User)
+class User:
+    name: strawberry.auto
+```
+"""
+
+__all__ = ["auto"]

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

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 import dataclasses
+from abc import ABC, abstractmethod
 from typing import (
     TYPE_CHECKING,
     Any,
     Callable,
+    ClassVar,
     Dict,
     List,
     Mapping,
@@ -13,29 +15,237 @@ from typing import (
     Type,
     TypeVar,
     Union,
+    overload,
 )
-from typing_extensions import Self, deprecated
+from typing_extensions import Literal, Protocol, Self, deprecated
 
-from strawberry.type import (
-    StrawberryList,
-    StrawberryType,
-    StrawberryTypeVar,
-    WithStrawberryObjectDefinition,
-)
 from strawberry.utils.deprecations import DEPRECATION_MESSAGES, DeprecatedDescriptor
 from strawberry.utils.inspect import get_specialized_type_var_map
+from strawberry.utils.typing import is_concrete_generic
 from strawberry.utils.typing import is_generic as is_type_generic
 
 if TYPE_CHECKING:
+    from typing_extensions import TypeGuard
+
     from graphql import GraphQLAbstractType, GraphQLResolveInfo
 
-    from strawberry.field import StrawberryField
+    from strawberry.types.field import StrawberryField
+
+
+class StrawberryType(ABC):
+    """The base class for all types that Strawberry uses.
+
+    Every type that is decorated by strawberry should have a dunder
+    `__strawberry_definition__` with an instance of a StrawberryType that contains
+    the parsed information that strawberry created.
+
+    NOTE: ATM this is only true for @type @interface @input follow
+    https://github.com/strawberry-graphql/strawberry/issues/2841 to see progress.
+    """
+
+    @property
+    def type_params(self) -> List[TypeVar]:
+        return []
+
+    @property
+    def is_one_of(self) -> bool:
+        return False
+
+    @abstractmethod
+    def copy_with(
+        self,
+        type_var_map: Mapping[
+            str, Union[StrawberryType, Type[WithStrawberryObjectDefinition]]
+        ],
+    ) -> Union[StrawberryType, Type[WithStrawberryObjectDefinition]]:
+        raise NotImplementedError()
+
+    @property
+    @abstractmethod
+    def is_graphql_generic(self) -> bool:
+        raise NotImplementedError()
+
+    def has_generic(self, type_var: TypeVar) -> bool:
+        return False
+
+    def __eq__(self, other: object) -> bool:
+        from strawberry.annotation import StrawberryAnnotation
+
+        if isinstance(other, StrawberryType):
+            return self is other
+
+        elif isinstance(other, StrawberryAnnotation):
+            return self == other.resolve()
+
+        else:
+            # This could be simplified if StrawberryAnnotation.resolve() always returned
+            # a StrawberryType
+            resolved = StrawberryAnnotation(other).resolve()
+            if isinstance(resolved, StrawberryType):
+                return self == resolved
+            else:
+                return NotImplemented
+
+    def __hash__(self) -> int:
+        # TODO: Is this a bad idea? __eq__ objects are supposed to have the same hash
+        return id(self)
+
+
+class StrawberryContainer(StrawberryType):
+    def __init__(
+        self, of_type: Union[StrawberryType, Type[WithStrawberryObjectDefinition], type]
+    ) -> None:
+        self.of_type = of_type
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, self.of_type))
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, StrawberryType):
+            if isinstance(other, StrawberryContainer):
+                return self.of_type == other.of_type
+            else:
+                return False
+
+        return super().__eq__(other)
+
+    @property
+    def type_params(self) -> List[TypeVar]:
+        if has_object_definition(self.of_type):
+            parameters = getattr(self.of_type, "__parameters__", None)
+
+            return list(parameters) if parameters else []
+
+        elif isinstance(self.of_type, StrawberryType):
+            return self.of_type.type_params
+
+        else:
+            return []
+
+    def copy_with(
+        self,
+        type_var_map: Mapping[
+            str, Union[StrawberryType, Type[WithStrawberryObjectDefinition]]
+        ],
+    ) -> Self:
+        of_type_copy = self.of_type
+
+        if has_object_definition(self.of_type):
+            type_definition = self.of_type.__strawberry_definition__
+
+            if type_definition.is_graphql_generic:
+                of_type_copy = type_definition.copy_with(type_var_map)
+
+        elif (
+            isinstance(self.of_type, StrawberryType) and self.of_type.is_graphql_generic
+        ):
+            of_type_copy = self.of_type.copy_with(type_var_map)
+
+        return type(self)(of_type_copy)
+
+    @property
+    def is_graphql_generic(self) -> bool:
+        from strawberry.schema.compat import is_graphql_generic
+
+        type_ = self.of_type
+
+        return is_graphql_generic(type_)
+
+    def has_generic(self, type_var: TypeVar) -> bool:
+        if isinstance(self.of_type, StrawberryType):
+            return self.of_type.has_generic(type_var)
+        return False
+
+
+class StrawberryList(StrawberryContainer): ...
+
+
+class StrawberryOptional(StrawberryContainer): ...
+
+
+class StrawberryTypeVar(StrawberryType):
+    def __init__(self, type_var: TypeVar) -> None:
+        self.type_var = type_var
+
+    def copy_with(
+        self, type_var_map: Mapping[str, Union[StrawberryType, type]]
+    ) -> Union[StrawberryType, type]:
+        return type_var_map[self.type_var.__name__]
+
+    @property
+    def is_graphql_generic(self) -> bool:
+        return True
+
+    def has_generic(self, type_var: TypeVar) -> bool:
+        return self.type_var == type_var
+
+    @property
+    def type_params(self) -> List[TypeVar]:
+        return [self.type_var]
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, StrawberryTypeVar):
+            return self.type_var == other.type_var
+        if isinstance(other, TypeVar):
+            return self.type_var == other
+
+        return super().__eq__(other)
+
+    def __hash__(self) -> int:
+        return hash(self.type_var)
+
+
+class WithStrawberryObjectDefinition(Protocol):
+    __strawberry_definition__: ClassVar[StrawberryObjectDefinition]
+
+
+def has_object_definition(
+    obj: Any,
+) -> TypeGuard[Type[WithStrawberryObjectDefinition]]:
+    if hasattr(obj, "__strawberry_definition__"):
+        return True
+    # TODO: Generics remove dunder members here, so we inject it here.
+    #  Would be better to avoid it somehow.
+    # https://github.com/python/cpython/blob/3a314f7c3df0dd7c37da7d12b827f169ee60e1ea/Lib/typing.py#L1152
+    if is_concrete_generic(obj):
+        concrete = obj.__origin__
+        if hasattr(concrete, "__strawberry_definition__"):
+            obj.__strawberry_definition__ = concrete.__strawberry_definition__
+            return True
+    return False
+
+
+@overload
+def get_object_definition(
+    obj: Any,
+    *,
+    strict: Literal[True],
+) -> StrawberryObjectDefinition: ...
+
+
+@overload
+def get_object_definition(
+    obj: Any,
+    *,
+    strict: bool = False,
+) -> Optional[StrawberryObjectDefinition]: ...
+
+
+def get_object_definition(
+    obj: Any,
+    *,
+    strict: bool = False,
+) -> Optional[StrawberryObjectDefinition]:
+    definition = obj.__strawberry_definition__ if has_object_definition(obj) else None
+    if strict and definition is None:
+        raise TypeError(f"{obj!r} does not have a StrawberryObjectDefinition")
+
+    return definition
 
 
 @dataclasses.dataclass(eq=False)
 class StrawberryObjectDefinition(StrawberryType):
-    """
-    Encapsulates definitions for Input / Object / interface GraphQL Types.
+    """Encapsulates definitions for Input / Object / interface GraphQL Types.
 
     In order get the definition from a decorated object you can use
     `has_object_definition` or `get_object_definition` as a shortcut.
@@ -247,3 +457,17 @@ if TYPE_CHECKING:
 
 else:
     TypeDefinition = StrawberryObjectDefinition
+
+
+__all__ = [
+    "StrawberryContainer",
+    "StrawberryList",
+    "StrawberryObjectDefinition",
+    "StrawberryOptional",
+    "StrawberryType",
+    "StrawberryTypeVar",
+    "TypeDefinition",
+    "WithStrawberryObjectDefinition",
+    "get_object_definition",
+    "has_object_definition",
+]

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

@@ -12,9 +12,8 @@ from typing import (
     overload,
 )
 
-from strawberry.type import StrawberryType
-
-from .exceptions import ObjectIsNotAnEnumError
+from strawberry.exceptions import ObjectIsNotAnEnumError
+from strawberry.types.base import StrawberryType
 
 
 @dataclasses.dataclass
@@ -67,6 +66,30 @@ def enum_value(
     directives: Iterable[object] = (),
     description: Optional[str] = None,
 ) -> EnumValueDefinition:
+    """Function to customise an enum value, for example to add a description or deprecation reason.
+
+    Args:
+        value: The value of the enum member.
+        deprecation_reason: The deprecation reason of the enum member,
+            setting this will mark the enum member as deprecated.
+        directives: The directives to attach to the enum member.
+        description: The GraphQL description of the enum member.
+
+    Returns:
+        An EnumValueDefinition object that can be used to customise an enum member.
+
+    Example:
+    ```python
+    from enum import Enum
+    import strawberry
+
+
+    @strawberry.enum
+    class MyEnum(Enum):
+        FIRST_VALUE = strawberry.enum_value(description="The first value")
+        SECOND_VALUE = strawberry.enum_value(description="The second value")
+    ```
+    """
     return EnumValueDefinition(
         value=value,
         deprecation_reason=deprecation_reason,
@@ -131,7 +154,7 @@ def _process_enum(
 
 @overload
 def enum(
-    _cls: EnumType,
+    cls: EnumType,
     *,
     name: Optional[str] = None,
     description: Optional[str] = None,
@@ -141,7 +164,7 @@ def enum(
 
 @overload
 def enum(
-    _cls: None = None,
+    cls: None = None,
     *,
     name: Optional[str] = None,
     description: Optional[str] = None,
@@ -150,13 +173,47 @@ def enum(
 
 
 def enum(
-    _cls: Optional[EnumType] = None,
+    cls: Optional[EnumType] = None,
     *,
     name: Optional[str] = None,
     description: Optional[str] = None,
     directives: Iterable[object] = (),
 ) -> Union[EnumType, Callable[[EnumType], EnumType]]:
-    """Registers the enum in the GraphQL type system.
+    """Annotates an Enum class a GraphQL enum.
+
+    GraphQL enums only have names, while Python enums have names and values,
+    Strawberry will use the names of the Python enum as the names of the
+    GraphQL enum values.
+
+    Args:
+        cls: The Enum class to be annotated.
+        name: The name of the GraphQL enum.
+        description: The description of the GraphQL enum.
+        directives: The directives to attach to the GraphQL enum.
+
+    Returns:
+        The decorated Enum class.
+
+    Example:
+    ```python
+    from enum import Enum
+    import strawberry
+
+
+    @strawberry.enum
+    class MyEnum(Enum):
+        FIRST_VALUE = "first_value"
+        SECOND_VALUE = "second_value"
+    ```
+
+    The above code will generate the following GraphQL schema:
+
+    ```graphql
+    enum MyEnum {
+        FIRST_VALUE
+        SECOND_VALUE
+    }
+    ```
 
     If name is passed, the name of the GraphQL type will be
     the value passed of name instead of the Enum class name.
@@ -165,7 +222,10 @@ def enum(
     def wrap(cls: EnumType) -> EnumType:
         return _process_enum(cls, name, description, directives=directives)
 
-    if not _cls:
+    if not cls:
         return wrap
 
-    return wrap(_cls)
+    return wrap(cls)
+
+
+__all__ = ["EnumValue", "EnumDefinition", "EnumValueDefinition", "enum", "enum_value"]

strawberry/types/execution.py

@@ -94,3 +94,6 @@ class ExecutionResult:
 
 class ParseOptions(TypedDict):
     max_tokens: NotRequired[int]
+
+
+__all__ = ["ExecutionContext", "ExecutionResult", "ParseOptions"]

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

@@ -24,25 +24,24 @@ from typing import (
 
 from strawberry.annotation import StrawberryAnnotation
 from strawberry.exceptions import InvalidArgumentTypeError, InvalidDefaultFactoryError
-from strawberry.type import (
+from strawberry.types.base import (
     StrawberryType,
     WithStrawberryObjectDefinition,
     has_object_definition,
 )
-from strawberry.union import StrawberryUnion
+from strawberry.types.union import StrawberryUnion
 
-from .types.fields.resolver import StrawberryResolver
+from .fields.resolver import StrawberryResolver
 
 if TYPE_CHECKING:
     import builtins
     from typing_extensions import Literal, Self
 
-    from strawberry.arguments import StrawberryArgument
     from strawberry.extensions.field_extension import FieldExtension
+    from strawberry.permission import BasePermission
+    from strawberry.types.arguments import StrawberryArgument
+    from strawberry.types.base import StrawberryObjectDefinition
     from strawberry.types.info import Info
-    from strawberry.types.types import StrawberryObjectDefinition
-
-    from .permission import BasePermission
 
 T = TypeVar("T")
 
@@ -64,7 +63,7 @@ UNRESOLVED = object()
 
 
 def _is_generic(resolver_type: Union[StrawberryType, type]) -> bool:
-    """Returns True if `resolver_type` is generic else False"""
+    """Returns True if `resolver_type` is generic else False."""
     if isinstance(resolver_type, StrawberryType):
         return resolver_type.is_graphql_generic
 
@@ -149,7 +148,7 @@ class StrawberryField(dataclasses.Field):
 
         # Automatically add the permissions extension
         if len(self.permission_classes):
-            from .permission import PermissionExtension
+            from strawberry.permission import PermissionExtension
 
             if not self.extensions:
                 self.extensions = []
@@ -189,8 +188,7 @@ class StrawberryField(dataclasses.Field):
         return new_field
 
     def __call__(self, resolver: _RESOLVER_TYPE) -> Self:
-        """Add a resolver to the field"""
-
+        """Add a resolver to the field."""
         # Allow for StrawberryResolvers or bare functions to be provided
         if not isinstance(resolver, StrawberryResolver):
             resolver = StrawberryResolver(resolver)
@@ -217,12 +215,11 @@ class StrawberryField(dataclasses.Field):
     def get_result(
         self, source: Any, info: Optional[Info], args: List[Any], kwargs: Any
     ) -> Union[Awaitable[Any], Any]:
-        """
-        Calls the resolver defined for the StrawberryField.
+        """Calls the resolver defined for the StrawberryField.
+
         If the field doesn't have a resolver defined we default
         to using the default resolver specified in StrawberryConfig.
         """
-
         if self.base_resolver:
             return self.base_resolver(*args, **kwargs)
 
@@ -230,8 +227,9 @@ class StrawberryField(dataclasses.Field):
 
     @property
     def is_basic_field(self) -> bool:
-        """
-        Flag indicating if this is a "basic" field that has no resolver or
+        """Returns a boolean indicating if the field is a basic field.
+
+        A "basic" field us a field that has no resolver or
         permission classes, i.e. it just returns the relevant attribute from
         the source object. If it is a basic field we can avoid constructing
         an `Info` object and running any permission checks in the resolver
@@ -538,19 +536,44 @@ def field(
 ) -> Any:
     """Annotates a method or property as a GraphQL field.
 
+    Args:
+        resolver: The resolver for the field. This can be a function or a `StrawberryResolver`.
+        name: The GraphQL name of the field.
+        is_subscription: Whether the field is a subscription 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.
+
     This is normally used inside a type declaration:
 
-    >>> @strawberry.type
-    >>> class X:
-    >>>     field_abc: str = strawberry.field(description="ABC")
+    ```python
+    import strawberry
+
 
-    >>>     @strawberry.field(description="ABC")
-    >>>     def field_with_resolver(self) -> str:
-    >>>         return "abc"
+    @strawberry.type
+    class X:
+        field_abc: str = strawberry.field(description="ABC")
+
+        @strawberry.field(description="ABC")
+        def field_with_resolver(self) -> str:
+            return "abc"
+    ```
 
     it can be used both as decorator and as a normal function.
     """
-
     type_annotation = StrawberryAnnotation.from_annotation(graphql_type)
 
     field_ = StrawberryField(

strawberry/types/fields/resolver.py

@@ -23,13 +23,13 @@ from typing import (
 from typing_extensions import Annotated, Protocol, get_origin
 
 from strawberry.annotation import StrawberryAnnotation
-from strawberry.arguments import StrawberryArgument
 from strawberry.exceptions import (
     ConflictingArgumentsError,
     MissingArgumentsAnnotationsError,
 )
 from strawberry.parent import StrawberryParent
-from strawberry.type import StrawberryType, has_object_definition
+from strawberry.types.arguments import StrawberryArgument
+from strawberry.types.base import StrawberryType, has_object_definition
 from strawberry.types.info import Info
 from strawberry.utils.typing import type_has_annotation
 

strawberry/types/graphql.py

@@ -25,3 +25,6 @@ class OperationType(enum.Enum):
             }
 
         raise ValueError(f"Unsupported HTTP method: {method}")  # pragma: no cover
+
+
+__all__ = ["OperationType"]