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

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

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