swapper

library1.4.0pypypiunverified

Swapper is an unofficial API for Django's powerful but undocumented swappable models feature. It facilitates implementing arbitrary swappable models in reusable Django applications, akin to how `auth.User` is swappable. The library is actively maintained by the OpenWISP project with a moderate release cadence, with the latest major version being 1.4.0.

web-framework database

pip install swapper

github ↗package ↗

INSTALL

IMPORT

SIG · SWAPPER

swapper

web-frameworkpythonv1.4.0

Install

1.5s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

swapper

✓ import swapper

✗ import swapper

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()

Debug

Known issues

gotchaDo 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()`).

affects: All versions

breakingMigrating 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.

affects: All versions

breakingSwapper 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.

affects: >=1.4.0

breakingSwapper 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`.

affects: >=1.4.0

gotchaWhen 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.

affects: All versions

gotchaWhen 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).

affects: All versions

Upgrade

Version history

1.4.0latest on PyPI · released Aug 14, 2024

Audit

Dependencies

DjangorequiredCore functionality for swappable models is built on Django's internal features.

Agent activity

32 hits · last 30 days

node