Support Annotated field configuration everywhere (#4594)

Co-authored-by: Patrick Arminio <patrick.arminio@gmail.com>
Co-authored-by: Amp <amp@ampcode.com>

Author: patrick91

RELEASE.md

@@ -0,0 +1,40 @@
+---
+release type: patch
+social_messages:
+  x: >-
+    {project_name} {version} is out! Fields defined with typing.Annotated now
+    support the full strawberry.field API across object, input, and interface
+    types.
+    https://strawberry.rocks/release/{version}
+  linkedin: >-
+    {project_name} {version} is out. You can now configure fields with
+    strawberry.field inside typing.Annotated consistently across object, input,
+    and interface types, including defaults and combined metadata.
+---
+
+This release fixes fields configured with `strawberry.field()` inside
+`typing.Annotated`.
+
+You can now use this syntax consistently on object types, input types, and
+interfaces, including in projects that use `from __future__ import annotations`:
+
+```python
+from typing import Annotated
+
+import strawberry
+
+Name = Annotated[
+    str,
+    strawberry.field(name="displayName", default="Anonymous"),
+]
+
+
+@strawberry.type
+class User:
+    name: Name
+```
+
+All `strawberry.field()` options are supported. Fields with `default` or
+`default_factory` can be omitted when creating an instance, and field
+configuration can be combined with other Strawberry metadata such as named
+unions.

docs/types/object-types.md

@@ -90,6 +90,74 @@ type Book {
 
 </CodeGrid>
 
+## Customizing fields with `Annotated`
+
+You can configure fields by adding `strawberry.field()` to
+[`typing.Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated).
+This syntax works on object types, input types, and interfaces, including when
+using `from __future__ import annotations`:
+
+```python
+from typing import Annotated
+
+import strawberry
+
+
+@strawberry.type
+class User:
+    name: Annotated[
+        str,
+        strawberry.field(name="displayName", description="The displayed name"),
+    ]
+    tags: Annotated[list[str], strawberry.field(default_factory=list)]
+```
+
+All `strawberry.field()` options are supported. In particular, `default` and
+`default_factory` also configure the generated dataclass constructor, so
+`User(name="Patrick")` in the example above gets a new empty `tags` list.
+
+On Python 3.10 through 3.13, use `strawberry.lazy()` when the field type is only
+imported under `TYPE_CHECKING` or otherwise unavailable at runtime. This form
+works together with field metadata:
+
+```python
+from typing import TYPE_CHECKING, Annotated
+
+import strawberry
+
+if TYPE_CHECKING:
+    from .users import User
+
+
+@strawberry.type
+class Post:
+    author: Annotated[
+        "User",
+        strawberry.lazy(".users"),
+        strawberry.field(description="The post author"),
+    ]
+```
+
+Python 3.14 and newer can also preserve the field metadata on a direct
+unresolved reference without `strawberry.lazy()`.
+
+The field configuration can be combined with other Strawberry metadata. The
+order of the metadata does not matter:
+
+```python
+@strawberry.type
+class Query:
+    result: Annotated[
+        Success | Failure,
+        strawberry.union("Result"),
+        strawberry.field(description="The operation result"),
+    ]
+```
+
+Use only one `strawberry.field()` for each field. You can alternatively use the
+equivalent assignment syntax, such as
+`name: str = strawberry.field(description="The displayed name")`.
+
 ## API
 
 `@strawberry.type(name: str = None, description: str = None)`

strawberry/types/field.py

@@ -174,18 +174,17 @@ def __copy__(self) -> Self:
             is_subscription=self.is_subscription,
             description=self.description,
             base_resolver=self.base_resolver,
-            permission_classes=(
-                self.permission_classes[:]
-                if self.permission_classes is not None
-                else []
-            ),
-            default=self.default_value,
+            permission_classes=[],
+            default=self.default,
             default_factory=self.default_factory,
             metadata=self.metadata.copy() if self.metadata is not None else None,
             deprecation_reason=self.deprecation_reason,
             directives=self.directives[:] if self.directives is not None else [],
             extensions=self.extensions[:] if self.extensions is not None else [],
         )
+        new_field.permission_classes = (
+            self.permission_classes[:] if self.permission_classes is not None else []
+        )
         new_field._arguments = (
             self._arguments[:] if self._arguments is not None else None
         )

strawberry/types/object_type.py

@@ -2,20 +2,32 @@
 import copy
 import dataclasses
 import inspect
+import sys
 import types
 from collections.abc import Callable, Sequence
 from typing import (
+    Annotated,
     Any,
+    ForwardRef,
     TypeVar,
     cast,
+    get_args,
+    get_origin,
     overload,
 )
-from typing_extensions import dataclass_transform, get_annotations
+from typing_extensions import (
+    Format,
+    dataclass_transform,
+    evaluate_forward_ref,
+    get_annotations,
+)
 
+from strawberry.annotation import StrawberryAnnotation
 from strawberry.exceptions import (
     InvalidSuperclassInterfaceError,
     MissingFieldAnnotationError,
     MissingReturnAnnotationError,
+    MultipleStrawberryFieldsError,
     ObjectIsNotClassError,
 )
 from strawberry.types.base import get_object_definition
@@ -30,6 +42,103 @@
 T = TypeVar("T", bound=builtins.type)
 
 
+def _process_annotated_fields(cls: T) -> dict[str, StrawberryAnnotation]:
+    """Make StrawberryFields in Annotated available to dataclasses."""
+    module_namespace = sys.modules[cls.__module__].__dict__
+    type_annotations: dict[str, StrawberryAnnotation] = {}
+
+    annotations = get_annotations(cls, format=Format.FORWARDREF)
+
+    for field_name, raw_annotation in annotations.items():
+        annotation: object
+        if isinstance(raw_annotation, str):
+            try:
+                annotation = evaluate_forward_ref(
+                    ForwardRef(raw_annotation),
+                    owner=cls,
+                    globals=module_namespace,
+                    locals=dict(vars(cls)),
+                    format=Format.FORWARDREF,
+                )
+                if isinstance(annotation, ForwardRef):
+                    annotation = StrawberryAnnotation(
+                        raw_annotation,
+                        namespace=module_namespace,
+                    ).evaluate()
+            except (NameError, TypeError):
+                continue
+        else:
+            annotation = raw_annotation
+
+        if get_origin(annotation) is not Annotated:
+            continue
+
+        first, *rest = get_args(annotation)
+        strawberry_fields = [arg for arg in rest if isinstance(arg, StrawberryField)]
+
+        if len(strawberry_fields) > 1 or (
+            strawberry_fields
+            and isinstance(cls.__dict__.get(field_name), StrawberryField)
+        ):
+            raise MultipleStrawberryFieldsError(field_name=field_name, cls=cls)
+
+        if not strawberry_fields:
+            continue
+
+        source_field = strawberry_fields[0]
+        field = copy.copy(source_field)
+
+        default = cls.__dict__.get(field_name, dataclasses.MISSING)
+        if (
+            field.default is dataclasses.MISSING
+            and field.default_factory is dataclasses.MISSING
+            and default is not dataclasses.MISSING
+        ):
+            if isinstance(default, dataclasses.Field):
+                field.default = default.default
+                field.default_factory = default.default_factory
+                if default.default is not dataclasses.MISSING:
+                    field.default_value = default.default
+                elif callable(default.default_factory):
+                    field.default_value = default.default_factory()
+            else:
+                field.default = default
+                field.default_value = default
+
+        remaining_metadata = [
+            arg for arg in rest if not isinstance(arg, StrawberryField)
+        ]
+        field_type = (
+            field.type_annotation.raw_annotation
+            if field.type_annotation is not None
+            else first
+        )
+        field_type = (
+            Annotated[(field_type, *remaining_metadata)]
+            if remaining_metadata
+            else field_type
+        )
+        type_annotation = (
+            field.type_annotation
+            if field.type_annotation is not None and not remaining_metadata
+            else StrawberryAnnotation(
+                field_type,
+                namespace=(
+                    field.type_annotation.namespace
+                    if field.type_annotation is not None
+                    and field.type_annotation.namespace is not None
+                    else module_namespace
+                ),
+            )
+        )
+        field.type_annotation = type_annotation
+
+        setattr(cls, field_name, field)
+        type_annotations[field_name] = type_annotation
+
+    return type_annotations
+
+
 def _get_interfaces(cls: builtins.type[Any]) -> list[StrawberryObjectDefinition]:
     interfaces: list[StrawberryObjectDefinition] = []
     for base in cls.__mro__[1:]:  # Exclude current class
@@ -108,9 +217,19 @@ def _check_field_annotations(cls: builtins.type[Any]) -> None:
 
 def _wrap_dataclass(cls: T) -> T:
     """Wrap a strawberry.type class with a dataclass and check for any issues before doing so."""
+    annotated_field_types = _process_annotated_fields(cls)
+
     # Ensure all Fields have been properly type-annotated
     _check_field_annotations(cls)
-    return cast("T", dataclasses.dataclass(kw_only=True)(cls))
+    wrapped = cast("T", dataclasses.dataclass(kw_only=True)(cls))
+
+    # dataclasses replaces each StrawberryField's type with the class annotation.
+    # Restore the type with only the StrawberryField metadata removed, keeping any
+    # other Annotated metadata and explicit graphql_type override intact.
+    for field_name, type_annotation in annotated_field_types.items():
+        wrapped.__dataclass_fields__[field_name].type_annotation = type_annotation  # type: ignore[attr-defined]
+
+    return wrapped
 
 
 def _inject_default_for_maybe_annotations(cls: T, annotations: dict[str, Any]) -> None: