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

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

strawberry/{custom_scalar.py → types/scalar.py}

@@ -16,9 +16,8 @@ from typing import (
 )
 
 from strawberry.exceptions import InvalidUnionTypeError
-from strawberry.type import StrawberryType
-
-from .utils.str_converters import to_camel_case
+from strawberry.types.base import StrawberryType
+from strawberry.utils.str_converters import to_camel_case
 
 if TYPE_CHECKING:
     from graphql import GraphQLScalarType
@@ -166,30 +165,44 @@ def scalar(
 ) -> Any:
     """Annotates a class or type as a GraphQL custom scalar.
 
+    Args:
+        cls: The class or type to annotate.
+        name: The GraphQL name of the scalar.
+        description: The description of the scalar.
+        specified_by_url: The URL of the specification.
+        serialize: The function to serialize the scalar.
+        parse_value: The function to parse the value.
+        parse_literal: The function to parse the literal.
+        directives: The directives to apply to the scalar.
+
+    Returns:
+        The decorated class or type.
+
     Example usages:
 
-    >>> strawberry.scalar(
-    >>>     datetime.date,
-    >>>     serialize=lambda value: value.isoformat(),
-    >>>     parse_value=datetime.parse_date
-    >>> )
-
-    >>> Base64Encoded = strawberry.scalar(
-    >>>     NewType("Base64Encoded", bytes),
-    >>>     serialize=base64.b64encode,
-    >>>     parse_value=base64.b64decode
-    >>> )
-
-    >>> @strawberry.scalar(
-    >>>     serialize=lambda value: ",".join(value.items),
-    >>>     parse_value=lambda value: CustomList(value.split(","))
-    >>> )
-    >>> class CustomList:
-    >>>     def __init__(self, items):
-    >>>         self.items = items
+    ```python
+    strawberry.scalar(
+        datetime.date,
+        serialize=lambda value: value.isoformat(),
+        parse_value=datetime.parse_date,
+    )
 
-    """
+    Base64Encoded = strawberry.scalar(
+        NewType("Base64Encoded", bytes),
+        serialize=base64.b64encode,
+        parse_value=base64.b64decode,
+    )
 
+
+    @strawberry.scalar(
+        serialize=lambda value: ",".join(value.items),
+        parse_value=lambda value: CustomList(value.split(",")),
+    )
+    class CustomList:
+        def __init__(self, items):
+            self.items = items
+    ```
+    """
     if parse_value is None:
         parse_value = cls
 
@@ -209,3 +222,6 @@ def scalar(
         return wrap
 
     return wrap(cls)
+
+
+__all__ = ["ScalarDefinition", "ScalarWrapper", "scalar"]

strawberry/types/type_resolver.py

@@ -10,16 +10,16 @@ from strawberry.exceptions import (
     FieldWithResolverAndDefaultValueError,
     PrivateStrawberryFieldError,
 )
-from strawberry.field import StrawberryField
-from strawberry.private import is_private
-from strawberry.type import has_object_definition
-from strawberry.unset import UNSET
+from strawberry.types.base import has_object_definition
+from strawberry.types.field import StrawberryField
+from strawberry.types.private import is_private
+from strawberry.types.unset import UNSET
 
 
 def _get_fields(
     cls: Type[Any], original_type_annotations: Dict[str, Type[Any]]
 ) -> List[StrawberryField]:
-    """Get all the strawberry fields off a strawberry.type cls
+    """Get all the strawberry fields off a strawberry.type cls.
 
     This function returns a list of StrawberryFields (one for each field item), while
     also paying attention the name and typing of the field.
@@ -27,16 +27,19 @@ def _get_fields(
     StrawberryFields can be defined on a strawberry.type class as either a dataclass-
     style field or using strawberry.field as a decorator.
 
-    >>> import strawberry
-    >>> @strawberry.type
-    ... class Query:
-    ...     type_1a: int = 5
-    ...     type_1b: int = strawberry.field(...)
-    ...     type_1c: int = strawberry.field(resolver=...)
-    ...
-    ...     @strawberry.field
-    ...     def type_2(self) -> int:
-    ...         ...
+    ```python
+    import strawberry
+
+
+    @strawberry.type
+    class Query:
+        type_1a: int = 5
+        type_1b: int = strawberry.field(...)
+        type_1c: int = strawberry.field(resolver=...)
+
+        @strawberry.field
+        def type_2(self) -> int: ...
+    ```
 
     Type #1:
         A pure dataclass-style field. Will not have a StrawberryField; one will need to
@@ -51,7 +54,6 @@ def _get_fields(
     passing a named function (i.e. not an anonymous lambda) to strawberry.field
     (typically as a decorator).
     """
-
     fields: Dict[str, StrawberryField] = {}
 
     # before trying to find any fields, let's first add the fields defined in
@@ -163,3 +165,6 @@ def _get_fields(
         fields[field_name] = field
 
     return list(fields.values())
+
+
+__all__ = ["_get_fields"]

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

@@ -31,12 +31,12 @@ from strawberry.exceptions import (
     WrongReturnTypeForUnion,
 )
 from strawberry.exceptions.handler import should_use_rich_exceptions
-from strawberry.lazy_type import LazyType
-from strawberry.type import (
+from strawberry.types.base import (
     StrawberryOptional,
     StrawberryType,
     has_object_definition,
 )
+from strawberry.types.lazy_type import LazyType
 
 if TYPE_CHECKING:
     from graphql import (
@@ -173,7 +173,7 @@ class StrawberryUnion(StrawberryType):
         ) -> str:
             assert isinstance(type_, GraphQLUnionType)
 
-            from strawberry.types.types import StrawberryObjectDefinition
+            from strawberry.types.base import StrawberryObjectDefinition
 
             # If the type given is not an Object type, try resolving using `is_type_of`
             # defined on the union's inner types
@@ -250,15 +250,27 @@ def union(
 ) -> StrawberryUnion:
     """Creates a new named Union type.
 
+    Args:
+        name: The GraphQL name of the Union type.
+        types: The types that the Union can be.
+            (Deprecated, use `Annotated[U, strawberry.union("Name")]` instead)
+        description: The  GraphQL description of the Union type.
+        directives: The directives to attach to the Union type.
+
     Example usages:
 
-    >>> @strawberry.type
-    ... class A: ...
-    >>> @strawberry.type
-    ... class B: ...
-    >>> Annotated[A | B, strawberry.union("Name")]
-    """
+    ```python
+    import strawberry
+    from typing import Annotated
+
+    @strawberry.type
+    class A: ...
+
+    @strawberry.type
+    class B: ...
 
+    MyUnion = Annotated[A | B, strawberry.union("Name")]
+    """
     if types is None:
         union = StrawberryUnion(
             name=name,
@@ -299,3 +311,6 @@ def union(
         description=description,
         directives=directives,
     )
+
+
+__all__ = ["StrawberryUnion", "union"]

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

@@ -28,6 +28,26 @@ class UnsetType:
 
 
 UNSET: Any = UnsetType()
+"""A special value that can be used to represent an unset value in a field or argument.
+Similar to `undefined` in JavaScript, this value can be used to differentiate between
+a field that was not set and a field that was set to `None` or `null`.
+
+Example:
+
+```python
+import strawberry
+
+
+@strawberry.input
+class UserInput:
+    name: str | None = strawberry.UNSET
+    age: int | None = strawberry.UNSET
+```
+
+In the example above, if `name` or `age` are not provided when creating a `UserInput`
+object, they will be set to `UNSET` instead of `None`. Use `is UNSET` to check
+whether a value is unset.
+"""
 
 
 def _deprecated_is_unset(value: Any) -> bool:

strawberry/utils/aio.py

@@ -67,3 +67,11 @@ async def resolve_awaitable(
 ) -> _R:
     """Resolves an awaitable object and calls a callback with the resolved value."""
     return callback(await awaitable)
+
+
+__all__ = [
+    "aenumerate",
+    "aislice",
+    "asyncgen_to_list",
+    "resolve_awaitable",
+]

strawberry/utils/await_maybe.py

@@ -12,3 +12,6 @@ async def await_maybe(value: AwaitableOrValue[T]) -> T:
         return await value
 
     return cast(T, value)
+
+
+__all__ = ["await_maybe", "AwaitableOrValue", "AsyncIteratorOrIterator"]

strawberry/utils/dataclasses.py

@@ -32,3 +32,6 @@ def add_custom_init_fn(cls: Any) -> None:
             globals_=globals_,
         ),
     )
+
+
+__all__ = ["add_custom_init_fn"]

strawberry/utils/debug.py

@@ -14,8 +14,8 @@ def pretty_print_graphql_operation(
 ) -> None:
     """Pretty print a GraphQL operation using pygments.
 
-    Won't print introspection operation to prevent noise in the output."""
-
+    Won't print introspection operation to prevent noise in the output.
+    """
     try:
         from pygments import highlight, lexers
         from pygments.formatters import Terminal256Formatter
@@ -41,3 +41,6 @@ def pretty_print_graphql_operation(
         print(  # noqa: T201
             highlight(variables_json, lexers.JsonLexer(), Terminal256Formatter())
         )
+
+
+__all__ = ["pretty_print_graphql_operation"]

strawberry/utils/deprecations.py

@@ -25,3 +25,6 @@ class DeprecatedDescriptor:
 
     def inject(self, klass: type) -> None:
         setattr(klass, self.attr_name, self)
+
+
+__all__ = ["DEPRECATION_MESSAGES", "DeprecatedDescriptor"]

strawberry/utils/graphql_lexer.py

@@ -28,3 +28,6 @@ class GraphQLLexer(RegexLexer):
             (r"(\s|,)", token.Text),
         ]
     }
+
+
+__all__ = ["GraphQLLexer"]

strawberry/utils/importer.py

@@ -19,3 +19,6 @@ def import_module_symbol(
         symbol = getattr(symbol, attribute_name)
 
     return symbol
+
+
+__all__ = ["import_module_symbol"]

strawberry/utils/inspect.py

@@ -12,7 +12,6 @@ from typing import (
 )
 from typing_extensions import get_args
 
-from strawberry.type import has_object_definition
 from strawberry.utils.typing import is_generic_alias
 
 
@@ -29,8 +28,7 @@ def in_async_context() -> bool:
 
 @lru_cache(maxsize=250)
 def get_func_args(func: Callable[[Any], Any]) -> List[str]:
-    """Returns a list of arguments for the function"""
-
+    """Returns a list of arguments for the function."""
     sig = inspect.signature(func)
 
     return [
@@ -45,38 +43,46 @@ def get_specialized_type_var_map(cls: type) -> Optional[Dict[str, type]]:
 
     Consider the following:
 
-        >>> class Foo(Generic[T]):
-        ...     ...
-        ...
-        >>> class Bar(Generic[K]):
-        ...     ...
-        ...
-        >>> class IntBar(Bar[int]):
-        ...     ...
-        ...
-        >>> class IntBarSubclass(IntBar):
-        ...     ...
-        ...
-        >>> class IntBarFoo(IntBar, Foo[str]):
-        ...     ...
-        ...
+    ```python
+    class Foo(Generic[T]): ...
+
+
+    class Bar(Generic[K]): ...
+
+
+    class IntBar(Bar[int]): ...
+
+
+    class IntBarSubclass(IntBar): ...
+
+
+    class IntBarFoo(IntBar, Foo[str]): ...
+    ```
 
     This would return:
 
-        >>> get_specialized_type_var_map(object)
-        None
-        >>> get_specialized_type_var_map(Foo)
-        {}
-        >>> get_specialized_type_var_map(Bar)
-        {~T: ~T}
-        >>> get_specialized_type_var_map(IntBar)
-        {~T: int}
-        >>> get_specialized_type_var_map(IntBarSubclass)
-        {~T: int}
-        >>> get_specialized_type_var_map(IntBarFoo)
-        {~T: int, ~K: str}
+    ```python
+    get_specialized_type_var_map(object)
+    # None
+
+    get_specialized_type_var_map(Foo)
+    # {}
+
+    get_specialized_type_var_map(Bar)
+    # {~T: ~T}
+
+    get_specialized_type_var_map(IntBar)
+    # {~T: int}
 
+    get_specialized_type_var_map(IntBarSubclass)
+    # {~T: int}
+
+    get_specialized_type_var_map(IntBarFoo)
+    # {~T: int, ~K: str}
+    ```
     """
+    from strawberry.types.base import has_object_definition
+
     orig_bases = getattr(cls, "__orig_bases__", None)
     if orig_bases is None:
         # Specialized generic aliases will not have __orig_bases__
@@ -114,3 +120,6 @@ def get_specialized_type_var_map(cls: type) -> Optional[Dict[str, type]]:
         )
 
     return type_var_map
+
+
+__all__ = ["in_async_context", "get_func_args", "get_specialized_type_var_map"]

strawberry/utils/logging.py

@@ -23,3 +23,6 @@ class StrawberryLogger:
         **logger_kwargs: Any,
     ) -> None:
         cls.logger.error(error, exc_info=error.original_error, **logger_kwargs)
+
+
+__all__ = ["StrawberryLogger"]

strawberry/utils/operation.py

@@ -38,3 +38,6 @@ def get_operation_type(
         raise RuntimeError("Can't get GraphQL operation type")
 
     return OperationType(definition.operation.value)
+
+
+__all__ = ["get_first_operation", "get_operation_type"]

strawberry/utils/str_converters.py

@@ -24,3 +24,6 @@ def capitalize_first(name: str) -> str:
 def to_snake_case(name: str) -> str:
     name = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
     return re.sub("([a-z0-9])([A-Z])", r"\1_\2", name).lower()
+
+
+__all__ = ["to_camel_case", "to_kebab_case", "capitalize_first", "to_snake_case"]