django-tortoise-objects 0.1.0__py3-none-any.whl

django_tortoise/generator.py

@@ -0,0 +1,206 @@
+"""
+Dynamic Tortoise model class generation.
+
+Creates Tortoise ORM model classes at runtime from ``ModelInfo`` objects
+produced by the introspection module, using ``type()`` with Tortoise's
+``Model`` as the base class.  The ``ModelMeta`` metaclass (inherited from
+``tortoise.models.Model``) handles field registration automatically.
+
+Two functions are provided:
+  - ``generate_tortoise_model()`` -- creates data-field-only models (Phase 2).
+  - ``generate_tortoise_model_full()`` -- creates models with data + relational
+    fields, used by ``AppConfig.ready()`` after pre-registration.
+"""
+
+import logging
+from typing import Any
+
+from tortoise import models as tortoise_models
+
+from django_tortoise.fields import convert_field, convert_relation_field_by_name
+from django_tortoise.introspection import ModelInfo
+
+logger = logging.getLogger("django_tortoise")
+
+
+def generate_tortoise_model(
+    model_info: ModelInfo,
+    tortoise_app_name: str = "django_tortoise",
+) -> type | None:
+    """
+    Generate a Tortoise ORM model class from Django model metadata.
+
+    Iterates over the non-relational fields in *model_info*, converts each
+    to a Tortoise field via ``convert_field()``, and constructs a new
+    ``tortoise.models.Model`` subclass with ``type()``.
+
+    Returns ``None`` if the model has no convertible data fields.
+    """
+    tortoise_fields, skipped_fields = _build_data_fields(model_info)
+
+    if not tortoise_fields:
+        logger.warning(
+            "Model '%s.%s' has no convertible fields. Skipping.",
+            model_info.app_label,
+            model_info.model_name,
+        )
+        return None
+
+    if skipped_fields:
+        logger.info(
+            "Skipped fields %s on model '%s.%s' (unsupported types).",
+            skipped_fields,
+            model_info.app_label,
+            model_info.model_name,
+        )
+
+    meta_class = _build_meta_class(model_info, tortoise_fields, tortoise_app_name)
+    class_name = f"{model_info.model_class.__name__}Tortoise"
+
+    tortoise_model = type(
+        class_name,
+        (tortoise_models.Model,),
+        {
+            "Meta": meta_class,
+            **tortoise_fields,
+        },
+    )
+
+    logger.debug(
+        "Generated Tortoise model '%s' for Django model '%s.%s' (table: %s, fields: %d)",
+        class_name,
+        model_info.app_label,
+        model_info.model_name,
+        model_info.db_table,
+        len(tortoise_fields),
+    )
+
+    return tortoise_model
+
+
+def generate_tortoise_model_full(
+    model_info: ModelInfo,
+    tortoise_app_name: str = "django_tortoise",
+    class_name_map: dict[type, str] | None = None,
+) -> type | None:
+    """
+    Generate a Tortoise ORM model class with ALL fields (data + relational).
+
+    Uses *class_name_map* to resolve FK/O2O/M2M string references without
+    requiring the target Tortoise models to exist yet.  The map is keyed
+    by Django model class and valued by the planned Tortoise class name.
+
+    Returns ``None`` if the model has no convertible data fields.
+    """
+    tortoise_fields, skipped_fields = _build_data_fields(model_info)
+
+    if not tortoise_fields:
+        logger.warning(
+            "Model '%s.%s' has no convertible fields. Skipping.",
+            model_info.app_label,
+            model_info.model_name,
+        )
+        return None
+
+    if skipped_fields:
+        logger.info(
+            "Skipped fields %s on model '%s.%s' (unsupported types).",
+            skipped_fields,
+            model_info.app_label,
+            model_info.model_name,
+        )
+
+    # Add relational fields
+    for field_info in model_info.fields:
+        if not field_info.is_relation:
+            continue
+        result = convert_relation_field_by_name(
+            field_info,
+            tortoise_app_name=tortoise_app_name,
+            class_name_map=class_name_map,
+        )
+        if result is None:
+            continue
+        field_name, tortoise_field = result
+        tortoise_fields[field_name] = tortoise_field
+
+    meta_class = _build_meta_class(model_info, tortoise_fields, tortoise_app_name)
+    class_name = f"{model_info.model_class.__name__}Tortoise"
+
+    tortoise_model = type(
+        class_name,
+        (tortoise_models.Model,),
+        {
+            "Meta": meta_class,
+            **tortoise_fields,
+        },
+    )
+
+    logger.debug(
+        "Generated Tortoise model '%s' for Django model '%s.%s' "
+        "(table: %s, data fields: %d, total fields: %d)",
+        class_name,
+        model_info.app_label,
+        model_info.model_name,
+        model_info.db_table,
+        len([f for f in tortoise_fields.values() if not hasattr(f, "related_model")]),
+        len(tortoise_fields),
+    )
+
+    return tortoise_model
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_data_fields(model_info: ModelInfo) -> tuple[dict[str, object], list[str]]:
+    """Convert non-relational fields to Tortoise fields."""
+    tortoise_fields: dict[str, object] = {}
+    skipped_fields: list[str] = []
+
+    for field_info in model_info.fields:
+        if field_info.is_relation:
+            continue
+
+        tortoise_field = convert_field(field_info)
+        if tortoise_field is None:
+            skipped_fields.append(field_info.name)
+            continue
+        tortoise_fields[field_info.name] = tortoise_field
+
+    return tortoise_fields, skipped_fields
+
+
+def _build_meta_class(
+    model_info: ModelInfo,
+    tortoise_fields: dict[str, object],
+    tortoise_app_name: str,
+) -> type:
+    """Build the inner Meta class for a Tortoise model."""
+    meta_attrs: dict[str, Any] = {
+        "table": model_info.db_table,
+        "app": tortoise_app_name,
+    }
+
+    if model_info.unique_together:
+        valid_constraints: list[tuple[str, ...]] = []
+        converted_names = set(tortoise_fields.keys())
+        for constraint in model_info.unique_together:
+            missing = [f for f in constraint if f not in converted_names]
+            if missing:
+                logger.warning(
+                    "unique_together constraint %s on '%s.%s' references "
+                    "unconverted fields %s; omitting constraint.",
+                    constraint,
+                    model_info.app_label,
+                    model_info.model_name,
+                    missing,
+                )
+            else:
+                valid_constraints.append(tuple(constraint))
+        if valid_constraints:
+            meta_attrs["unique_together"] = tuple(valid_constraints)
+
+    return type("Meta", (), meta_attrs)

django_tortoise/initialization.py

@@ -0,0 +1,102 @@
+"""
+Lazy async initialization and explicit init/close for Tortoise ORM.
+
+Provides ``init()`` and ``close()`` coroutines that manage the Tortoise
+ORM lifecycle, including double-check locking for thread-safe lazy init.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from tortoise import Tortoise
+
+from django_tortoise.db_config import build_tortoise_config
+from django_tortoise.exceptions import ConnectionError
+
+logger = logging.getLogger("django_tortoise")
+
+_initialized: bool = False
+_init_lock: asyncio.Lock | None = None
+
+
+async def _ensure_lock() -> asyncio.Lock:
+    """Get or create the init lock (lazily, to avoid event loop binding at import time)."""
+    global _init_lock
+    if _init_lock is None:
+        _init_lock = asyncio.Lock()
+    return _init_lock
+
+
+async def ensure_initialized() -> None:
+    """
+    Ensure Tortoise ORM is initialized. Called automatically before queries.
+
+    Uses double-check locking with ``asyncio.Lock`` for safety.
+    """
+    global _initialized
+    if _initialized:
+        return
+
+    lock = await _ensure_lock()
+    async with lock:
+        if _initialized:
+            return  # Another coroutine already initialized
+        await init()
+
+
+async def init() -> None:
+    """
+    Explicitly initialize Tortoise ORM connections using Django's DATABASES config.
+
+    Idempotent: calling multiple times is a no-op after the first success.
+    Can be called from ASGI lifespan handler for pre-warming connections.
+    """
+    global _initialized
+    if _initialized:
+        logger.debug("Tortoise already initialized, skipping.")
+        return
+
+    logger.info("Initializing Tortoise ORM connections...")
+
+    try:
+        config = build_tortoise_config()
+        await Tortoise.init(config=config)
+        _initialized = True
+        logger.info("Tortoise ORM initialized successfully.")
+    except Exception as exc:
+        raise ConnectionError(f"Failed to initialize Tortoise ORM: {exc}") from exc
+
+
+async def close() -> None:
+    """
+    Close all Tortoise ORM connections.
+
+    Call this during ASGI shutdown or when cleaning up.
+    """
+    global _initialized
+    if not _initialized:
+        return
+
+    logger.info("Closing Tortoise ORM connections...")
+    try:
+        await Tortoise.close_connections()
+    except RuntimeError:
+        # Handle case where Tortoise context is no longer active
+        # (e.g., in test teardown scenarios)
+        logger.debug("Tortoise context already closed.")
+    _initialized = False
+    logger.info("Tortoise ORM connections closed.")
+
+
+def is_initialized() -> bool:
+    """Check if Tortoise ORM has been initialized."""
+    return _initialized
+
+
+def _reset_for_testing() -> None:
+    """Reset initialization state. For testing only."""
+    global _initialized, _init_lock
+    _initialized = False
+    _init_lock = None

django_tortoise/introspection.py

@@ -0,0 +1,280 @@
+"""
+Django model introspection logic.
+
+Extracts schema metadata from Django models using the ``_meta`` API,
+producing ``ModelInfo`` and ``FieldInfo`` dataclasses consumed by the
+Tortoise model generator.
+"""
+
+import enum
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from django.db import models
+
+logger = logging.getLogger("django_tortoise")
+
+
+@dataclass
+class FieldInfo:
+    """Extracted metadata for a single Django model field."""
+
+    name: str
+    internal_type: str  # from get_internal_type()
+    column: str  # actual DB column name
+    primary_key: bool
+    null: bool
+    unique: bool
+    has_default: bool
+    default: Any
+    max_length: int | None
+    max_digits: int | None
+    decimal_places: int | None
+    db_index: bool
+    choices: list | None
+    enum_type: type | None  # Python Enum class backing choices, if any
+    # Relational field info
+    is_relation: bool
+    related_model: type | None  # Django model class
+    related_model_label: str | None  # "app_label.ModelName"
+    on_delete: str | None  # e.g. "CASCADE"
+    related_name: str | None
+    is_self_referential: bool
+    # M2M specific
+    many_to_many: bool
+    through_model: type | None
+    through_db_table: str | None
+    # Auto field detection
+    is_auto_field: bool
+    # Original Django field reference
+    django_field: models.Field | None
+
+
+@dataclass
+class ModelInfo:
+    """Extracted metadata for a single Django model."""
+
+    model_class: type
+    app_label: str
+    model_name: str
+    db_table: str
+    fields: list[FieldInfo]
+    unique_together: list[tuple[str, ...]]
+    is_abstract: bool
+    is_proxy: bool
+    is_managed: bool
+    pk_name: str
+
+
+def _detect_enum_type(django_field) -> type | None:
+    """Detect a Python Enum class backing a Django field's choices.
+
+    Django 6.0+ normalizes enum choices to plain ``(value, label)`` tuples
+    via ``normalize_choices``, so the enum class cannot be recovered from
+    ``field.choices`` alone.  Instead we check the field's default value:
+    when an ``IntegerChoices`` / ``TextChoices`` default is set, Django
+    preserves the enum member as the default.
+
+    Returns the Enum subclass when found, otherwise None.
+    """
+    if not getattr(django_field, "choices", None):
+        return None
+
+    # The default value is an enum member when choices=SomeEnum was used
+    if django_field.has_default():
+        default = django_field.default
+        if isinstance(default, enum.Enum):
+            return type(default)
+
+    return None
+
+
+def introspect_field(django_field) -> FieldInfo | None:
+    """
+    Extract metadata from a single Django field.
+
+    Returns None for reverse relations (fields where ``field.concrete`` is
+    False and the field is not a forward ManyToManyField).
+    """
+    # Skip reverse relations: they are not concrete and not forward M2M
+    is_m2m = getattr(django_field, "many_to_many", False)
+    is_concrete = getattr(django_field, "concrete", False)
+
+    if not is_concrete and not is_m2m:
+        return None
+
+    # For M2M fields, only include forward relations (not reverse).
+    # Reverse M2M (ManyToManyRel) has a 'field' attribute pointing back.
+    if is_m2m and not is_concrete and hasattr(django_field, "field"):
+        return None
+
+    name = django_field.name
+    internal_type = django_field.get_internal_type()
+
+    # Get DB column name. M2M fields don't have a column attribute.
+    try:
+        column = django_field.column or name
+    except AttributeError:
+        column = name
+
+    primary_key = getattr(django_field, "primary_key", False)
+    null = getattr(django_field, "null", False)
+    unique = getattr(django_field, "unique", False)
+    db_index = getattr(django_field, "db_index", False)
+
+    # Default handling
+    has_default = django_field.has_default()
+    default = None
+    if has_default:
+        default = django_field.default
+
+    max_length = getattr(django_field, "max_length", None)
+    max_digits = getattr(django_field, "max_digits", None)
+    decimal_places = getattr(django_field, "decimal_places", None)
+
+    choices = list(django_field.choices) if django_field.choices else None
+    enum_type = _detect_enum_type(django_field)
+
+    # Relational field info
+    is_relation = getattr(django_field, "is_relation", False)
+    related_model = None
+    related_model_label = None
+    on_delete = None
+    related_name = None
+    is_self_referential = False
+    many_to_many = is_m2m
+    through_model = None
+    through_db_table = None
+
+    if is_relation:
+        related_model = getattr(django_field, "related_model", None)
+
+        if related_model is not None:
+            try:
+                related_model_label = f"{related_model._meta.app_label}.{related_model.__name__}"
+            except AttributeError:
+                related_model_label = None
+
+        # on_delete from remote_field
+        remote_field = getattr(django_field, "remote_field", None)
+        if remote_field is not None:
+            on_delete_func = getattr(remote_field, "on_delete", None)
+            if on_delete_func is not None:
+                # Extract the name from the on_delete callable
+                # Django's on_delete functions have __name__ like 'CASCADE', 'SET_NULL', etc.
+                on_delete = getattr(on_delete_func, "__name__", None)
+
+        # related_name
+        related_name_val = getattr(django_field, "related_query_name", None)
+        if related_name_val and callable(related_name_val):
+            # related_query_name() returns the related name
+            pass
+        # Use remote_field.related_name for the actual related_name
+        if remote_field is not None:
+            related_name = getattr(remote_field, "related_name", None)
+
+        # Self-referential detection
+        if related_model is not None:
+            # Get the model that owns this field
+            owner_model = getattr(django_field, "model", None)
+            if owner_model is not None and related_model is owner_model:
+                is_self_referential = True
+
+        # M2M specific
+        if many_to_many and remote_field is not None:
+            through_model = getattr(remote_field, "through", None)
+            if through_model is not None:
+                try:
+                    through_db_table = through_model._meta.db_table
+                except AttributeError:
+                    through_db_table = None
+
+    # Auto field detection
+    is_auto_field = isinstance(
+        django_field,
+        (models.AutoField, models.BigAutoField, models.SmallAutoField),
+    )
+
+    return FieldInfo(
+        name=name,
+        internal_type=internal_type,
+        column=column,
+        primary_key=primary_key,
+        null=null,
+        unique=unique,
+        has_default=has_default,
+        default=default,
+        max_length=max_length,
+        max_digits=max_digits,
+        decimal_places=decimal_places,
+        db_index=db_index,
+        choices=choices,
+        enum_type=enum_type,
+        is_relation=is_relation,
+        related_model=related_model,
+        related_model_label=related_model_label,
+        on_delete=on_delete,
+        related_name=related_name,
+        is_self_referential=is_self_referential,
+        many_to_many=many_to_many,
+        through_model=through_model,
+        through_db_table=through_db_table,
+        is_auto_field=is_auto_field,
+        django_field=django_field,
+    )
+
+
+def introspect_model(django_model: type) -> ModelInfo:
+    """
+    Extract all schema metadata from a Django model.
+
+    Iterates over all fields returned by ``_meta.get_fields()`` and produces
+    a ``ModelInfo`` containing ``FieldInfo`` for each concrete or forward-M2M
+    field.
+    """
+    meta = django_model._meta  # type: ignore[attr-defined]
+
+    fields: list[FieldInfo] = []
+    for django_field in meta.get_fields():
+        field_info = introspect_field(django_field)
+        if field_info is not None:
+            fields.append(field_info)
+
+    # Extract unique_together as a list of tuples
+    unique_together = [tuple(ut) for ut in meta.unique_together]
+
+    # Primary key name
+    pk_name = meta.pk.name if meta.pk is not None else "id"
+
+    return ModelInfo(
+        model_class=django_model,
+        app_label=meta.app_label,
+        model_name=meta.model_name,
+        db_table=meta.db_table,
+        fields=fields,
+        unique_together=unique_together,
+        is_abstract=meta.abstract,
+        is_proxy=meta.proxy,
+        is_managed=meta.managed,
+        pk_name=pk_name,
+    )
+
+
+def should_skip_model(model_info: ModelInfo) -> tuple[bool, str]:
+    """
+    Check if a model should be skipped during Tortoise model generation.
+
+    Returns a ``(skip, reason)`` tuple. If ``skip`` is True, ``reason``
+    contains a human-readable explanation.
+    """
+    if model_info.is_abstract:
+        return True, f"Model '{model_info.model_name}' is abstract."
+
+    if model_info.is_proxy:
+        return True, f"Model '{model_info.model_name}' is a proxy model."
+
+    if not model_info.fields:
+        return True, f"Model '{model_info.model_name}' has no concrete fields."
+
+    return False, ""

django_tortoise/management/commands/generate_tortoise_models.py

@@ -0,0 +1,113 @@
+"""
+Management command to generate static Tortoise ORM model source files.
+
+Usage::
+
+    python manage.py generate_tortoise_models [--output-dir DIR] [--app-label APP ...]
+                                               [--tortoise-app-name NAME]
+
+Produces one Python file per Django app containing Tortoise ORM model classes
+that mirror the Django models.  The generated files can be inspected,
+customized, and version-controlled.
+"""
+
+import os
+from collections import defaultdict
+
+from django.apps import apps
+from django.core.management.base import BaseCommand
+
+from django_tortoise.code_generator import render_app_module, render_model_source
+from django_tortoise.conf import get_config, should_include
+from django_tortoise.introspection import introspect_model, should_skip_model
+
+
+class Command(BaseCommand):
+    help = "Generate static Tortoise ORM model source files from Django models."
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--output-dir",
+            default=".",
+            help='Directory where generated files are written (default: ".").',
+        )
+        parser.add_argument(
+            "--app-label",
+            nargs="*",
+            default=None,
+            help="Restrict generation to specific Django app(s).",
+        )
+        parser.add_argument(
+            "--tortoise-app-name",
+            default="django_tortoise",
+            help='Tortoise app name used in Meta.app and FK references (default: "django_tortoise").',
+        )
+
+    def handle(self, *args, **options):
+        output_dir = options["output_dir"]
+        app_labels = options["app_label"]
+        tortoise_app_name = options["tortoise_app_name"]
+
+        config = get_config()
+        include_patterns = config.get("INCLUDE_MODELS")
+        exclude_patterns = config.get("EXCLUDE_MODELS")
+
+        all_models = apps.get_models()
+
+        # Filter by --app-label if specified
+        if app_labels:
+            all_models = [m for m in all_models if m._meta.app_label in app_labels]
+
+        # Two-pass approach mirroring apps.py
+        # Pass 1: Introspect and build class_name_map
+        eligible = []  # list of (django_model, label, model_info)
+        class_name_map = {}  # django_model -> tortoise class name
+
+        for django_model in all_models:
+            label = f"{django_model._meta.app_label}.{django_model.__name__}"
+
+            if not should_include(label, include_patterns, exclude_patterns):
+                continue
+
+            model_info = introspect_model(django_model)
+
+            skip, _reason = should_skip_model(model_info)
+            if skip:
+                continue
+
+            tortoise_class_name = f"{django_model.__name__}Tortoise"
+            class_name_map[django_model] = tortoise_class_name
+            eligible.append((django_model, label, model_info))
+
+        # Pass 2: Render source code grouped by app_label
+        models_by_app = defaultdict(list)
+        for _django_model, _label, model_info in eligible:
+            result = render_model_source(model_info, tortoise_app_name, class_name_map)
+            if result is not None:
+                models_by_app[model_info.app_label].append(result)
+
+        # Create output directory if needed
+        os.makedirs(output_dir, exist_ok=True)
+
+        # Write files
+        files_written = []
+        total_models = 0
+        for app_label, model_results in sorted(models_by_app.items()):
+            filename = f"tortoise_models_{app_label}.py"
+            filepath = os.path.join(output_dir, filename)
+            source = render_app_module(model_results, app_label)
+
+            with open(filepath, "w") as f:
+                f.write(source)
+
+            files_written.append(filename)
+            total_models += len(model_results)
+
+        # Print summary
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"Generated {total_models} Tortoise model(s) in {len(files_written)} file(s)."
+            )
+        )
+        for filename in files_written:
+            self.stdout.write(f"  {filename}")