feat: alias generator (#449)

* feat: add use_alias_generator setting

* fix: don't silently ship wrong aliases or unformatted code

* fix: keep fragment forward references resolvable in operation modules

A generated client whose operation spreads a fragment could not be imported
on Python 3.10, with or without `defer_model_build`:

    PydanticUndefinedAnnotation: name 'UserFieldsFriends' is not defined

A fragment names its nested selections by forward reference, and an operation
that spreads it subclasses the fragment class from another module:

    # fragments.py
    class UserFields(BaseModel):
        friends: list["UserFieldsFriends"]

    # list_users.py
    class ListUsersUsers(UserFields):
        pass

Pydantic resolves the annotations a subclass inherits against the subclass's
own module, and `UserFieldsFriends` lives in `fragments`. On 3.11+ the
inherited `ForwardRef` evaluation is reused and this happens to work; on 3.10
it is re-evaluated and fails. `requires-python` is `>= 3.10` and the default
hatch environment pins 3.10, so this failed on the version CI runs.

With `defer_model_build` the same shape failed on every supported version,
because dropping the eager `model_rebuild()` calls removes the only thing
that ever resolved those references.

Emit the names the mixin bases need into the module that has to resolve them:

    from .fragments import (
        UserFields,
        UserFieldsFriends,  # noqa: F401
    )

The `noqa` is required because the name appears only inside an inherited
annotation. Keeping the build deferred rather than restoring the eager
fragment rebuilds preserves the whole import-time win - `defer_model_build`
now measures 1.79x faster to import on a 1448-type schema, against 1.74x
before, because no fragment models are built at import.

Add `ForwardRefNamesVisitor` and `collect_class_forward_ref_names()` in
`codegen.py`; `_map_fragment_forward_refs()` and `_mixin_forward_ref_import()`
in `package.py`. `ast.unparse` drops comments, so the line is injected as raw
source through the new `prepend_code` argument of `_queue_module`. Clients
with no fragment mixin are byte-for-byte unchanged.

The suite never caught this because every `expected_client` fixture is inert:
the tests diff generated source and never import it. Add two tests that
import a generated package and validate a payload, one per path. Both fail
only on Python 3.10, which the default hatch environment provides.

* docs: record graphql-core dependency and the two import-performance settings

`enable_custom_operations` makes the generated `base_operation.py` and
`client.py` import graphql-core to build and print a query AST at runtime, so
the generated package needs it alongside pydantic and httpx. It was missing
from "Generated code dependencies" and costs roughly 25 ms of import.

`defer_model_build` and `use_alias_generator` were documented in the README
but absent from the optional-settings list in `docs/02-configuration.md`,
where every other setting lives.

Also describe the `# noqa: F401` fragment import that generated operation
modules now carry, so it does not read as a code-generation bug to anyone
running a linter over the output.

* test: cover alias_generator in the multipart_uploads=false base-model test

Now that use_alias_generator exists, extend the no-upload base-model config test
to also enable it and assert alias_generator=to_camel lands on the generated
BaseModel - exercising the base-model source-path detection for all three
config rewrites in the uploads-disabled path.

* build: require pydantic >=2.8 for use_alias_generator

`use_alias_generator` sets `alias_generator=to_camel` and omits the explicit
`Field(alias=...)` for fields whose GraphQL name `to_camel` can reconstruct.
`to_camel`'s case handling was fixed in pydantic 2.8 (pydantic/pydantic#9561);
on earlier versions it could mangle names, so the generated package would
rebuild the wrong aliases. Raise the floor to 2.8 to match.

* docs: tighten the to_camel / pydantic 2.8 floor comments

* docs: move import-performance and fragments docs out of README

* fix: don't let the BaseModel config rewrite go missing unnoticed

* docs: drop the defer_model_build aside from the fragments page

* test: consolidate the rewrite_base_model config tests

* docs: place the import-performance and fragments guides in the docs site

The use_alias_generator branch predates the docs-site refactor (#446), so it
added these two guides as flat docs/07 and docs/08 pages and linked them from a
monolithic README. Move them under docs/02-guides/ to match the current
structure and repoint the config-reference links.

* fix: satisfy ty 0.0.62 in extract_operations and shorter_results

ty 0.0.62 (stricter than the version CI ran previously) flags two spots in
existing contrib plugins: the `ast.Constant.value` union widens the list
passed to `sorted()` past `SupportsRichComparison`, and `ImportFrom.module`
is `str | None` so indexing the `dict[str, set]` of extended imports with it
is rejected. Narrow the constant to `str` and bind/guard the module name.
No behaviour change.

Author: DamianCzajkowski

CONTRIBUTING.md

@@ -19,7 +19,8 @@ We use [Hatch](https://github.com/pypa/hatch) for project management.
 Formatting and linting (including typing-related rules) use [ruff](https://github.com/astral-sh/ruff). To format the code, run:
 
 ```bash
-hatch fmt
+hatch check code --fix
+hatch check fmt --fix
 ```
 
 The contents of the `ariadne-codegen` package are annotated with types and validated using [ty](https://github.com/astral-sh/ty). To run type checking, use:

ariadne_codegen/client_generators/fragments.py

@@ -23,6 +23,7 @@ def __init__(
         default_optional_fields_to_none: bool = False,
         include_typename: bool = True,
         defer_model_build: bool = False,
+        use_alias_generator: bool = False,
     ) -> None:
         self.schema = schema
         self.enums_module_name = enums_module_name
@@ -34,6 +35,7 @@ def __init__(
         self.default_optional_fields_to_none = default_optional_fields_to_none
         self.include_typename = include_typename
         self.defer_model_build = defer_model_build
+        self.use_alias_generator = use_alias_generator
 
         self._fragments_names = set(self.fragments_definitions.keys())
         self._generated_public_names: list[str] = []
@@ -60,6 +62,7 @@ def generate(self, exclude_names: Optional[set[str]] = None) -> ast.Module:
                 plugin_manager=self.plugin_manager,
                 default_optional_fields_to_none=self.default_optional_fields_to_none,
                 include_typename=self.include_typename,
+                use_alias_generator=self.use_alias_generator,
             )
             imports.extend(generator.get_imports())
             class_defs = generator.get_classes()

ariadne_codegen/client_generators/input_types.py

@@ -14,26 +14,23 @@
     generate_ann_assign,
     generate_class_def,
     generate_constant,
-    generate_expr,
     generate_import_from,
     generate_keyword,
-    generate_method_call,
+    generate_model_rebuild_calls,
     generate_module,
     generate_name,
     generate_pass,
     generate_pydantic_field,
-    model_has_forward_refs,
 )
 from ..plugins.manager import PluginManager
-from ..utils import process_name
+from ..utils import needs_explicit_alias, process_name
 from .constants import (
     ALIAS_KEYWORD,
     ANNOTATED,
     ANY,
     BASE_MODEL_CLASS_NAME,
     BASE_MODEL_IMPORT,
     FIELD_CLASS,
-    MODEL_REBUILD_METHOD,
     OPTIONAL,
     PLAIN_SERIALIZER,
     PYDANTIC_MODULE,
@@ -56,13 +53,15 @@ def __init__(
         custom_scalars: Optional[dict[str, ScalarData]] = None,
         plugin_manager: Optional[PluginManager] = None,
         defer_model_build: bool = False,
+        use_alias_generator: bool = False,
     ) -> None:
         self.schema = schema
         self.convert_to_snake_case = convert_to_snake_case
         self.enums_module = enums_module
         self.custom_scalars = custom_scalars if custom_scalars else {}
         self.plugin_manager = plugin_manager
         self.defer_model_build = defer_model_build
+        self.use_alias_generator = use_alias_generator
 
         self._imports = [
             generate_import_from([OPTIONAL, ANY, UNION, ANNOTATED], TYPING_MODULE),
@@ -91,16 +90,8 @@ def generate(self, types_to_include: Optional[list[str]] = None) -> ast.Module:
             scalar_data = self.custom_scalars[scalar_name]
             self._imports.extend(generate_scalar_imports(scalar_data))
 
-        model_rebuild_calls = (
-            []
-            if self.defer_model_build
-            else [
-                generate_expr(
-                    generate_method_call(class_def.name, MODEL_REBUILD_METHOD)
-                )
-                for class_def in class_defs
-                if model_has_forward_refs(class_def)
-            ]
+        model_rebuild_calls = generate_model_rebuild_calls(
+            class_defs, self.defer_model_build
         )
 
         module_body = (
@@ -190,7 +181,7 @@ def _parse_input_definition(
                 ),
                 lineno=lineno,
             )
-            if name != org_name:
+            if needs_explicit_alias(name, org_name, self.use_alias_generator):
                 field_implementation.value = self._process_field_value(
                     field_implementation=field_implementation, alias=org_name
                 )