Swapper

Warnings

• gotcha Do not use `swapper.load_model()` before the Django model system has fully initialized (e.g., at module level in `models.py`). It behaves similarly to `django.contrib.auth.get_user_model()` and should be called after models are ready.
  Fix: Call `swapper.load_model()` within functions, methods, or after Django's app registry is ready (e.g., in `AppConfig.ready()`).
• breaking Migrating from a non-swapped model implementation to a swapped one after initial migrations have been created for the non-swapped model is difficult and generally discouraged. Django's migration system makes assumptions that make this transition problematic.
  Fix: Plan for swappable models from the very beginning of your app's development. If retrofitting swappable models, be prepared for manual migration hacking or consider starting with a fresh database for the swapped implementation.
• breaking Swapper v1.4.0 dropped support for Python 3.7. Applications running on Python 3.7 will need to use an older version of swapper (v1.3.0 or earlier) or upgrade their Python environment.
  Fix: Upgrade Python to 3.8 or newer. If not possible, pin `swapper<1.4.0` in your dependencies.
• breaking Swapper v1.4.0 dropped support for Django 4.0a1. While this was an alpha release, any applications still using this specific Django version will experience issues.
  Fix: Upgrade Django to a stable supported version (e.g., 4.2 or 5.0). If not possible, pin `swapper<1.4.0`.
• gotcha When using `swapper.dependency()` in migrations, avoid `version='__latest__'` as it can lead to issues if new migrations are added to the depended module, potentially causing unexpected behavior or broken dependencies.
  Fix: Specify an explicit migration number for `version` if a specific migration is required, or rely on the default behavior which typically depends on the initial migration of the target app.
• gotcha When using multi-table inheritance with swappable models, ensure that any explicitly declared fields (especially those mimicking Django's auto-generated `_ptr` fields for parent links) do not clash with Django's automatically generated field names. This can lead to `FieldError` exceptions.
  Fix: If you need to override a parent link field, give it a different name than Django's default `_ptr` suffix, or ensure your custom field definition correctly aligns with the swappable model logic (e.g., referencing `swapper.get_model_name()` for the foreign key).

Install

• pip install swapper Install latest version

Imports

• swapper

  import swapper

• load_model

  from swapper import load_model

  Used to dynamically load the active model class for a swappable model, similar to `django.contrib.auth.get_user_model()`.
• swappable_setting

  from swapper import swappable_setting

  Used in model Meta options to declare a model as swappable.
• dependency

  from swapper import dependency

  Used in Django migrations to declare a swappable dependency.
• get_model_name

  from swapper import get_model_name

  Retrieves the 'app_label.ModelName' string for the currently active swappable model.

Quickstart

To create a swappable model in a reusable app, define abstract base classes and default implementations. Use `swapper.swappable_setting()` in the `Meta` class of the concrete model. When referencing swappable models (e.g., in ForeignKeys or in code), always use `swapper.get_model_name()` for string references or `swapper.load_model()` for the model class. This ensures that the user's swapped-in model is correctly referenced. Users then specify their custom model in Django settings (e.g., `REUSABLEAPP_PARENT_MODEL = 'myapp.MyCustomParent'`).

import swapper
from django.db import models

# reusableapp/models.py
class BaseParent(models.Model):
    name = models.CharField(max_length=255)

    class Meta:
        abstract = True

class Parent(BaseParent):
    class Meta:
        swappable = swapper.swappable_setting('reusableapp', 'Parent')

class BaseChild(models.Model):
    parent = models.ForeignKey(
        swapper.get_model_name('reusableapp', 'Parent'),
        on_delete=models.CASCADE
    )

    class Meta:
        abstract = True

class Child(BaseChild):
    class Meta:
        swappable = swapper.swappable_setting('reusableapp', 'Child')

# reusableapp/views.py (or any other module needing the model)
# Always use swapper.load_model() instead of direct imports
ParentModel = swapper.load_model('reusableapp', 'Parent')
ChildModel = swapper.load_model('reusableapp', 'Child')

def get_all_parents():
    return ParentModel.objects.all()