Add support for defining fields using Annotated (#4059)

Co-authored-by: Thiago Bellini Ribeiro <thiago@bellini.dev>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

RELEASE.md

@@ -0,0 +1,37 @@
+Release type: minor
+
+This release adds support for defining fields using the `Annotated` syntax. This provides an
+alternative way to specify field metadata alongside the type annotation.
+
+Example usage:
+
+```python
+from typing import Annotated
+
+import strawberry
+
+
+@strawberry.type
+class Query:
+    name: Annotated[str, strawberry.field(description="The name")]
+    age: Annotated[int, strawberry.field(deprecation_reason="Use birthDate instead")]
+
+
+@strawberry.input
+class CreateUserInput:
+    name: Annotated[str, strawberry.field(description="User's name")]
+    email: Annotated[str, strawberry.field(description="User's email")]
+```
+
+This syntax works alongside the existing assignment syntax:
+
+```python
+@strawberry.type
+class Query:
+    # Both styles work
+    field1: Annotated[str, strawberry.field(description="Using Annotated")]
+    field2: str = strawberry.field(description="Using assignment")
+```
+
+All `strawberry.field()` options are supported including `description`, `name`,
+`deprecation_reason`, `directives`, `metadata`, and `permission_classes`.

docs/errors/multiple-strawberry-fields.md

@@ -0,0 +1,58 @@
+---
+title: Multiple Strawberry Fields Error
+---
+
+# Multiple Strawberry Fields Error
+
+## Description
+
+This error is raised when using multiple `strawberry.field()` annotations inside
+an `Annotated` type. For example, the following code will raise this error:
+
+```python
+from typing import Annotated
+
+import strawberry
+
+
+@strawberry.type
+class Query:
+    name: Annotated[
+        str,
+        strawberry.field(description="First"),
+        strawberry.field(description="Second"),
+    ]
+
+
+schema = strawberry.Schema(query=Query)
+```
+
+This happens because Strawberry only allows one `strawberry.field()` per field
+when using the `Annotated` syntax. Having multiple would create ambiguity about
+which field configuration to use.
+
+## How to fix this error
+
+You can fix this error by using only one `strawberry.field()` in your
+`Annotated` type annotation. Combine all the options you need into a single
+`strawberry.field()` call:
+
+```python
+from typing import Annotated
+
+import strawberry
+
+
+@strawberry.type
+class Query:
+    name: Annotated[
+        str,
+        strawberry.field(
+            description="The name",
+            deprecation_reason="Use fullName instead",
+        ),
+    ]
+
+
+schema = strawberry.Schema(query=Query)
+```

strawberry/exceptions/__init__.py

@@ -16,6 +16,7 @@
 from .missing_dependencies import MissingOptionalDependenciesError
 from .missing_field_annotation import MissingFieldAnnotationError
 from .missing_return_annotation import MissingReturnAnnotationError
+from .multiple_strawberry_fields import MultipleStrawberryFieldsError
 from .object_is_not_a_class import ObjectIsNotClassError
 from .object_is_not_an_enum import ObjectIsNotAnEnumError
 from .private_strawberry_field import PrivateStrawberryFieldError
@@ -185,6 +186,7 @@ def __init__(self, payload: dict[str, object] | None = None) -> None:
     "MissingReturnAnnotationError",
     "MissingTypesForGenericError",
     "MultipleStrawberryArgumentsError",
+    "MultipleStrawberryFieldsError",
     "ObjectIsNotAnEnumError",
     "ObjectIsNotClassError",
     "PrivateStrawberryFieldError",

strawberry/exceptions/multiple_strawberry_fields.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+from .exception import StrawberryException
+from .utils.source_finder import SourceFinder
+
+if TYPE_CHECKING:
+    from .exception_source import ExceptionSource
+
+
+class MultipleStrawberryFieldsError(StrawberryException):
+    def __init__(self, field_name: str, cls: type) -> None:
+        self.cls = cls
+        self.field_name = field_name
+
+        self.message = (
+            f"Annotation for field `{field_name}` on type `{cls.__name__}` "
+            "cannot have multiple `strawberry.field`s"
+        )
+        self.rich_message = (
+            f"Field `[underline]{self.field_name}[/]` on type "
+            f"`[underline]{self.cls.__name__}[/]` cannot have multiple "
+            "`strawberry.field`s"
+        )
+        self.annotation_message = "field with multiple strawberry.field annotations"
+        self.suggestion = (
+            "To fix this error you should use only one `strawberry.field()` "
+            "in the `Annotated` type annotation."
+        )
+
+        super().__init__(self.message)
+
+    @cached_property
+    def exception_source(self) -> ExceptionSource | None:
+        if self.cls is None:
+            return None  # pragma: no cover
+
+        source_finder = SourceFinder()
+
+        return source_finder.find_class_attribute_from_object(self.cls, self.field_name)

strawberry/types/type_resolver.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
+import copy
 import dataclasses
 import sys
-from typing import Any
+from typing import Annotated, Any, get_args, get_origin
 
 from strawberry.annotation import StrawberryAnnotation
 from strawberry.exceptions import (
     FieldWithResolverAndDefaultFactoryError,
     FieldWithResolverAndDefaultValueError,
+    MultipleStrawberryFieldsError,
     PrivateStrawberryFieldError,
 )
 from strawberry.types.base import has_object_definition
@@ -16,6 +18,49 @@
 from strawberry.types.unset import UNSET
 
 
+def _get_field_from_annotated(
+    field: dataclasses.Field,
+    origin: type,
+    module_namespace: dict[str, Any],
+    cls: type,
+) -> StrawberryField | None:
+    """Extract a StrawberryField from an Annotated type annotation.
+
+    Returns a configured StrawberryField if the annotation contains one,
+    or None if no StrawberryField is found in the Annotated args.
+    Raises MultipleStrawberryFieldsError if more than one is found.
+    """
+    field_type = field.type
+
+    if get_origin(field_type) is not Annotated:
+        return None
+
+    first, *rest = get_args(field_type)
+
+    strawberry_fields = [arg for arg in rest if isinstance(arg, StrawberryField)]
+
+    if len(strawberry_fields) > 1:
+        raise MultipleStrawberryFieldsError(field_name=field.name, cls=cls)
+
+    if not strawberry_fields:
+        return None
+
+    result = copy.copy(strawberry_fields[0])
+    result.python_name = field.name
+    result.type_annotation = StrawberryAnnotation(
+        annotation=first,
+        namespace=module_namespace,
+    )
+    result.origin = origin
+
+    # Transfer default from dataclass field if not set in strawberry.field()
+    if result.default is dataclasses.MISSING:
+        result.default = field.default
+        result.default_value = field.default
+
+    return result
+
+
 def _get_fields(
     cls: type[Any], original_type_annotations: dict[str, type[Any]]
 ) -> list[StrawberryField]:
@@ -82,6 +127,19 @@ class if one is not set by either using an explicit strawberry.field(name=...) o
     # then we can proceed with finding the fields for the current class
     for field in dataclasses.fields(cls):  # type: ignore
         if isinstance(field, StrawberryField):
+            # Check for conflict: strawberry.field in both Annotated and assignment
+            annotation = (
+                field.type_annotation.annotation
+                if isinstance(field.type_annotation, StrawberryAnnotation)
+                else field.type
+            )
+            if get_origin(annotation) is Annotated:
+                annotated_args = get_args(annotation)
+                if any(isinstance(arg, StrawberryField) for arg in annotated_args[1:]):
+                    raise MultipleStrawberryFieldsError(
+                        field_name=field.python_name or field.name, cls=cls
+                    )
+
             # Check that the field type is not Private
             if is_private(field.type):
                 raise PrivateStrawberryFieldError(field.python_name, cls)
@@ -140,18 +198,24 @@ class if one is not set by either using an explicit strawberry.field(name=...) o
             origin = origins.get(field.name, cls)
             module = sys.modules[origin.__module__]
 
-            # Create a StrawberryField, for fields of Types #1 and #2a
-            field = StrawberryField(  # noqa: PLW2901
-                python_name=field.name,
-                graphql_name=None,
-                type_annotation=StrawberryAnnotation(
-                    annotation=field.type,
-                    namespace=module.__dict__,
-                ),
-                origin=origin,
-                default=getattr(cls, field.name, dataclasses.MISSING),
+            annotated_field = _get_field_from_annotated(
+                field, origin, module.__dict__, cls
             )
 
+            if annotated_field is not None:
+                field = annotated_field  # noqa: PLW2901
+            else:
+                field = StrawberryField(  # noqa: PLW2901
+                    python_name=field.name,
+                    graphql_name=None,
+                    type_annotation=StrawberryAnnotation(
+                        annotation=field.type,
+                        namespace=module.__dict__,
+                    ),
+                    origin=origin,
+                    default=getattr(cls, field.name, dataclasses.MISSING),
+                )
+
         field_name = field.python_name
 
         assert_message = "Field must have a name by the time the schema is generated"