## Core modules and concepts

This page summarizes the core building blocks in `src/pydantic2django/core/`, what they do, and the most important classes and methods to be aware of.

For full, up-to-date API details, see the API Reference generated by mkdocstrings: [API Reference](/reference/).

### `base_generator.py`
- **purpose**: Shared orchestration for generating static Django `models.py` from source models.
- **key class**: `BaseStaticGenerator[SourceModelType, FieldInfoType]`
  - **generate()**: Top-level entrypoint; writes the rendered models file.
  - **generate_models_file()**: Orchestrates discovery, field/model setup, import dedupe, and template rendering.
  - **discover_models()**: Uses a `BaseDiscovery` to find candidate models and analyze dependencies.
  - **setup_django_model(source_model)**: Runs the configured `BaseModelFactory` to populate a `ConversionCarrier`.
  - **generate_model_definition(carrier)**: Renders a single model using `model_definition.py.j2`.
  - Abstract hooks to implement in concrete generators:
    - `_get_source_model_name(carrier)`, `_add_source_model_import(carrier)`, `_prepare_template_context(defs, names, imports)`, `_get_models_in_processing_order()`, `_get_model_definition_extra_context(carrier)`.
- **templates**: Uses Jinja2 with templates under `django/templates/`.

### `discovery.py`
- **purpose**: Pluggable model discovery for different source types.
- **key class**: `BaseDiscovery[TModel]`
  - **discover_models(packages, app_label, user_filters)**: Scans packages/modules, applies built-in and user filters.
  - **analyze_dependencies()**: Build dependency graph (abstract).
  - **get_models_in_registration_order()**: Topological order (abstract).
  - Protected hooks: `_is_target_model(obj)`, `_default_eligibility_filter(model)`, `_post_discovery_hook()`, `_resolve_forward_refs()`.

### `factories.py`
- **purpose**: Convert a source model and its fields into an in-memory Django model representation.
- **data objects**:
  - `ConversionCarrier[SourceModelType]`: Conversion state (django fields, relationships, context, Meta, etc.).
  - `FieldConversionResult`: Result of converting a single field, including kwargs and imports.
- **base classes**:
  - `BaseFieldFactory[SourceFieldType]`: `create_field(field_info, model_name, carrier)` (abstract).
  - `BaseModelFactory[SourceModelType, SourceFieldType]`: Implements orchestration via `make_django_model(carrier)` and common helpers:
    - `_process_source_fields(carrier)` (abstract)
    - `_handle_field_collisions(carrier)`
    - `_create_django_meta(carrier)`
    - `_assemble_django_model_class(carrier)`
    - `_build_model_context(carrier)` (abstract)

### `bidirectional_mapper.py`
- **purpose**: Central, bidirectional mapping between Python/Pydantic types and Django `Field`s.
- **key class**: `BidirectionalTypeMapper`
  - **get_django_mapping(python_type, field_info, parent_pydantic_model=None)** → `(FieldType, kwargs)`
  - **get_pydantic_mapping(django_field)** → `(python_type, field_info_kwargs)`
  - Internals: `_find_unit_for_pydantic_type`, `_find_unit_for_django_field`, registry of `TypeMappingUnit` implementations.
- **exceptions**: `MappingError` for invalid/unsupported cases.

### `mapping_units.py`
- **purpose**: Concrete `TypeMappingUnit` classes that implement mapping rules.
- **base class**: `TypeMappingUnit`
  - `matches(py_type, field_info)` scoring; `pydantic_to_django_kwargs(...)`; `django_to_pydantic_field_info_kwargs(dj_field)`.
- **notable units**: primitives (`IntFieldMapping`, `StrFieldMapping`, `TextFieldMapping`, `BoolFieldMapping`, `FloatFieldMapping`), numerics (`DecimalFieldMapping`), dates (`DateFieldMapping`, `DateTimeFieldMapping`, `TimeFieldMapping`, `DurationFieldMapping`), identifiers (`UUIDFieldMapping`), network/paths (`EmailFieldMapping`, `URLFieldMapping`, `IPAddressFieldMapping`, `FilePathFieldMapping`), files (`FileFieldMapping`, `ImageFieldMapping`), JSON (`JsonFieldMapping`), enums/choices (`EnumFieldMapping`), relationships (`ForeignKeyMapping`, `OneToOneFieldMapping`, `ManyToManyFieldMapping`), and the conceptual `GenericForeignKeyMappingUnit`.

### `typing.py`
- **purpose**: Type processing utilities for introspection and code generation.
- **key class**: `TypeHandler`
  - **process_field_type(field_type)**: Normalize Optional/List/Union/Annotated; produce simplified type object and metadata.
  - **get_required_imports(type_obj)**: Compute import map for a type (including nested generics).
  - **format_type_string(type_obj)**: Render a readable type string for generated code.
  - **get_class_name(type_obj)**: Extract a canonical type name.
  - Logging helper: `configure_core_typing_logging(...)`.

### `imports.py`
- **purpose**: Collect, categorize, and de-duplicate imports used in generated code.
- **key class**: `ImportHandler`
  - **add_import(module, name)**, **add_pydantic_model_import(model_class)**, **add_context_field_type_import(field_type)**
  - **deduplicate_imports()**: Merge and flatten import statements for output.
  - Helpers for nested/generic types and cleaning generic names.

### `relationships.py`
- **purpose**: Track and resolve mappings between source models and generated Django models.
- **key classes**:
  - `RelationshipMapper`: Holds a single mapping between a source model and a Django model.
  - `RelationshipConversionAccessor`: Registry and lookup utilities:
    - `map_relationship(source_model, django_model)`, `is_source_model_known(model)`
    - `get_django_model_for_pydantic(pydantic_model)`, `get_pydantic_model_for_django(django_model)`
    - `get_django_model_for_dataclass(dataclass_model)`, `available_source_models`, `available_django_models`

### `context.py`
- **purpose**: Context storage and codegen for data that cannot be represented as first-class Django fields.
- **key classes**:
  - `FieldContext`: Per-field context metadata and value.
  - `ModelContext[SourceModelType]`: Collection of context fields for a model; import synthesis; serialization helpers.
    - Methods: `add_field(...)`, `validate_context(...)`, `get_required_imports()`, `to_conversion_dict()`.
  - `ContextClassGenerator`: Renders a context dataclass using the `context_class.py.j2` template.

### `serialization.py`
- **purpose**: Safe value serialization utilities.
- **API**: `SerializationMethod` enum, `get_serialization_method(obj)`, `serialize_value(value)`, `is_serializable(obj)`.

### `defs.py`
- **purpose**: Shared type helpers and mapping definition structure.
- **API**: `is_serializable_type(field_type)`, `is_pydantic_model(obj)`, `TypeMappingDefinition`.

### `filter_helpers.py`
- **purpose**: Small helpers to build discovery filters.
- **API**: `exclude_models([...])`, `include_models([...])`, `has_field(name)`, `always_include(...)`.

### `utils/`
- **strings.py**: `sanitize_string(value)` for safe codegen strings; `balanced(s)` for quick bracket balance checks.
- **relationships.py**: `get_relationship_metadata(field_type)` and type aliases for relationship detection.

---

See also the detailed API pages for these modules under the site’s API section: [API Reference](/reference/).
