%global _empty_manifest_terminate_build 0 Name: python-swapper Version: 1.3.0 Release: 1 Summary: The unofficial Django swappable models API. License: MIT URL: https://github.com/openwisp/django-swappable-models Source0: https://mirrors.nju.edu.cn/pypi/web/packages/4b/21/4c1df375fbb1df34a8910a46810933594c802175518d22307f9aa058300c/swapper-1.3.0.tar.gz BuildArch: noarch %description [![Dependency monitoring](https://img.shields.io/librariesio/release/github/openwisp/django-swappable-models)](https://libraries.io/github/openwisp/django-swappable-models) #### Django Swappable Models - No longer only for auth.User! Swapper is an unofficial API for the [undocumented] but very powerful Django feature: swappable models. Swapper facilitates implementing arbitrary swappable models in your own reusable apps. [![Latest PyPI Release](https://img.shields.io/pypi/v/swapper.svg)](https://pypi.org/project/swapper) [![Release Notes](https://img.shields.io/github/release/openwisp/django-swappable-models.svg )](https://github.com/wq/django-swappable-models/releases) [![License](https://img.shields.io/pypi/l/swapper.svg)](https://github.com/openwisp/django-swappable-models/blob/master/LICENSE) [![GitHub Stars](https://img.shields.io/github/stars/openwisp/django-swappable-models.svg)](https://github.com/openwisp/django-swappable-models/stargazers) [![GitHub Forks](https://img.shields.io/github/forks/openwisp/django-swappable-models.svg)](https://github.com/openwisp/django-swappable-models/network) [![GitHub Issues](https://img.shields.io/github/issues/openwisp/django-swappable-models.svg)](https://github.com/openwisp/django-swappable-models/issues) [![Build Status](https://github.com/openwisp/django-swappable-models/actions/workflows/ci.yml/badge.svg)](https://github.com/openwisp/django-swappable-models/actions/workflows/ci.yml) [![Python Support](https://img.shields.io/pypi/pyversions/swapper.svg)](https://pypi.org/project/swapper) [![Django Support](https://img.shields.io/pypi/djversions/swapper.svg)](https://pypi.org/project/swapper) ## Motivation Suppose your reusable app has two related tables: ```python from django.db import models class Parent(models.Model): name = models.TextField() class Child(models.Model): name = models.TextField() parent = models.ForeignKey(Parent) ``` Suppose further that you want to allow the user to subclass either or both of these models and supplement them with their own additional fields. You could use Abstract classes (e.g. `BaseParent` and `BaseChild`) for this, but then you would either need to: 1. Avoid putting the foreign key on `BaseChild` and tell the user they need to do it. 2. Put the foreign key on `BaseChild`, but make `Parent` a concrete model that can't be swapped 3. Use swappable models, together with `ForeignKeys` that read the swappable settings. This third approach is taken by Django to facilitate [swapping the auth.User model]. The `auth.User` swappable code was implemented in a generic way that allows it to be used for any model. Although this capability is currently [undocumented] while any remaining issues are being sorted out, it has proven to be very stable and useful in our experience. Swapper is essentially a simple API wrapper around this existing functionality. Note that Swapper is primarily a tool for library authors; users of your reusable app generally should not need to know about Swapper in order to use it. (See the notes on [End User Documentation](#end-user-documentation) below.) ### Real-World Examples Swapper is used extensively in several OpenWISP packages to facilitate customization and extension. Notable examples include: * [openwisp-users] * [openwisp-controller] * [openwisp-radius] The use of swapper in these packages promotes [Software Reusability][reusability], one of the core values of the OpenWISP project. ## Creating a Reusable App First, make sure you have `swapper` installed. If you are publishing your reusable app as a Python package, be sure to add `swapper` to your project's dependencies (e.g. `setup.py`) to ensure that users of your app don't have errors integrating it. ```bash pip3 install swapper ``` Extending the above example, you might create two abstract base classes and corresponding default implementations: ```python # reusableapp/models.py from django.db import models import swapper class BaseParent(models.Model): # minimal base implementation ... class Meta: abstract = True class Parent(BaseParent): # default (swappable) implementation ... class Meta: swappable = swapper.swappable_setting('reusableapp', 'Parent') class BaseChild(models.Model): parent = models.ForeignKey(swapper.get_model_name('reusableapp', 'Parent')) # minimal base implementation ... class Meta: abstract = True class Child(BaseChild): # default (swappable) implementation ... class Meta: swappable = swapper.swappable_setting('reusableapp', 'Child') ``` ### Loading Swapped Models In your reusable views and other functions, always use the swapper instead of importing swappable models directly. This is because you might not know whether the user of your app is using your default implementation or their own version. ```python # reusableapp/views.py # Might work, might not # from .models import Parent import swapper Parent = swapper.load_model("reusableapp", "Parent") Child = swapper.load_model("reusableapp", "Child") def view(request, *args, **kwargs): qs = Parent.objects.all() # ... ``` > Note: `swapper.load_model()` is the general equivalent of [get_user_model()] and subject to the same constraints: e.g. it should not be used until after the model system has fully initialized. ### Migration Scripts Swapper can also be used in migration scripts to facilitate dependency ordering and foreign key references. To use this feature in your library, generate a migration script with `makemigrations` and make the following changes. In general, users of your library should not need to make any similar changes to their own migration scripts. The one exception is if you have multiple levels of swappable models with foreign keys pointing to each other. ```diff # reusableapp/migrations/0001_initial.py from django.db import models, migrations < from django.conf import settings > import swapper class Migration(migrations.Migration): dependencies = [ < migrations.swappable_dependency(settings.REUSABLEAPP_PARENT_MODEL), > swapper.dependency('reusableapp', 'Parent') ] operations = [ migrations.CreateModel( name='Child', fields=[ ('id', models.AutoField(auto_created=True, serialize=False, primary_key=True, verbose_name='ID')), ], options={ < 'swappable': 'REUSABLEAPP_CHILD_MODEL', > 'swappable': swapper.swappable_setting('reusableapp', 'Child'), }, bases=(models.Model,), ), migrations.CreateModel( name='Parent', fields=[ ('id', models.AutoField(auto_created=True, serialize=False, primary_key=True, verbose_name='ID')), ], options={ < 'swappable': 'REUSABLEAPP_PARENT_MODEL', > 'swappable': swapper.swappable_setting('reusableapp', 'Parent'), }, bases=(models.Model,), ), migrations.AddField( model_name='child', name='parent', < field=models.ForeignKey(to=settings.REUSABLEAPP_PARENT_MODEL), > field=models.ForeignKey(to=swapper.get_model_name('reusableapp', 'Parent')), preserve_default=True, ), ] ``` ## End User Documentation With the above setup, the user of your app can override one or both models in their own app. You might provide them with an example like this: ```python # myapp/models.py from reusableapp.models import BaseParent class Parent(BaseParent): # custom implementation ... ``` Then, tell your users to update their settings to trigger the swap. ```python # myproject/settings.py REUSABLEAPP_PARENT_MODEL = "myapp.Parent" ``` The goal is to make this process just as easy for your end user as [swapping the auth.User model] is. As with `auth.User`, there are some important caveats that you may want to inform your users about. The biggest issue is that your users will probably need to define the swapped model settings **before creating any migrations** for their implementation of `myapp`. Due to key assumptions made within Django's migration infrastructure, it is difficult to start out with a default (non-swapped) model and then later to switch to a swapped implementation without doing some migration hacking. This is somewhat awkward - as your users will most likely want to try out your default implementation before deciding to customize it. Unfortunately, there isn't an easy workaround due to how the swappable setting is currently implemented in Django core. This will likely be addressed in future Django versions (see [#10] and [Django ticket #25313]). ## API Documentation Here is the full API for `swapper`, which you may find useful in creating your reusable app code. End users of your library should generally not need to reference this API. %package -n python3-swapper Summary: The unofficial Django swappable models API. Provides: python-swapper BuildRequires: python3-devel BuildRequires: python3-setuptools BuildRequires: python3-pip %description -n python3-swapper [![Dependency monitoring](https://img.shields.io/librariesio/release/github/openwisp/django-swappable-models)](https://libraries.io/github/openwisp/django-swappable-models) #### Django Swappable Models - No longer only for auth.User! Swapper is an unofficial API for the [undocumented] but very powerful Django feature: swappable models. Swapper facilitates implementing arbitrary swappable models in your own reusable apps. [![Latest PyPI Release](https://img.shields.io/pypi/v/swapper.svg)](https://pypi.org/project/swapper) [![Release Notes](https://img.shields.io/github/release/openwisp/django-swappable-models.svg )](https://github.com/wq/django-swappable-models/releases) [![License](https://img.shields.io/pypi/l/swapper.svg)](https://github.com/openwisp/django-swappable-models/blob/master/LICENSE) [![GitHub Stars](https://img.shields.io/github/stars/openwisp/django-swappable-models.svg)](https://github.com/openwisp/django-swappable-models/stargazers) [![GitHub Forks](https://img.shields.io/github/forks/openwisp/django-swappable-models.svg)](https://github.com/openwisp/django-swappable-models/network) [![GitHub Issues](https://img.shields.io/github/issues/openwisp/django-swappable-models.svg)](https://github.com/openwisp/django-swappable-models/issues) [![Build Status](https://github.com/openwisp/django-swappable-models/actions/workflows/ci.yml/badge.svg)](https://github.com/openwisp/django-swappable-models/actions/workflows/ci.yml) [![Python Support](https://img.shields.io/pypi/pyversions/swapper.svg)](https://pypi.org/project/swapper) [![Django Support](https://img.shields.io/pypi/djversions/swapper.svg)](https://pypi.org/project/swapper) ## Motivation Suppose your reusable app has two related tables: ```python from django.db import models class Parent(models.Model): name = models.TextField() class Child(models.Model): name = models.TextField() parent = models.ForeignKey(Parent) ``` Suppose further that you want to allow the user to subclass either or both of these models and supplement them with their own additional fields. You could use Abstract classes (e.g. `BaseParent` and `BaseChild`) for this, but then you would either need to: 1. Avoid putting the foreign key on `BaseChild` and tell the user they need to do it. 2. Put the foreign key on `BaseChild`, but make `Parent` a concrete model that can't be swapped 3. Use swappable models, together with `ForeignKeys` that read the swappable settings. This third approach is taken by Django to facilitate [swapping the auth.User model]. The `auth.User` swappable code was implemented in a generic way that allows it to be used for any model. Although this capability is currently [undocumented] while any remaining issues are being sorted out, it has proven to be very stable and useful in our experience. Swapper is essentially a simple API wrapper around this existing functionality. Note that Swapper is primarily a tool for library authors; users of your reusable app generally should not need to know about Swapper in order to use it. (See the notes on [End User Documentation](#end-user-documentation) below.) ### Real-World Examples Swapper is used extensively in several OpenWISP packages to facilitate customization and extension. Notable examples include: * [openwisp-users] * [openwisp-controller] * [openwisp-radius] The use of swapper in these packages promotes [Software Reusability][reusability], one of the core values of the OpenWISP project. ## Creating a Reusable App First, make sure you have `swapper` installed. If you are publishing your reusable app as a Python package, be sure to add `swapper` to your project's dependencies (e.g. `setup.py`) to ensure that users of your app don't have errors integrating it. ```bash pip3 install swapper ``` Extending the above example, you might create two abstract base classes and corresponding default implementations: ```python # reusableapp/models.py from django.db import models import swapper class BaseParent(models.Model): # minimal base implementation ... class Meta: abstract = True class Parent(BaseParent): # default (swappable) implementation ... class Meta: swappable = swapper.swappable_setting('reusableapp', 'Parent') class BaseChild(models.Model): parent = models.ForeignKey(swapper.get_model_name('reusableapp', 'Parent')) # minimal base implementation ... class Meta: abstract = True class Child(BaseChild): # default (swappable) implementation ... class Meta: swappable = swapper.swappable_setting('reusableapp', 'Child') ``` ### Loading Swapped Models In your reusable views and other functions, always use the swapper instead of importing swappable models directly. This is because you might not know whether the user of your app is using your default implementation or their own version. ```python # reusableapp/views.py # Might work, might not # from .models import Parent import swapper Parent = swapper.load_model("reusableapp", "Parent") Child = swapper.load_model("reusableapp", "Child") def view(request, *args, **kwargs): qs = Parent.objects.all() # ... ``` > Note: `swapper.load_model()` is the general equivalent of [get_user_model()] and subject to the same constraints: e.g. it should not be used until after the model system has fully initialized. ### Migration Scripts Swapper can also be used in migration scripts to facilitate dependency ordering and foreign key references. To use this feature in your library, generate a migration script with `makemigrations` and make the following changes. In general, users of your library should not need to make any similar changes to their own migration scripts. The one exception is if you have multiple levels of swappable models with foreign keys pointing to each other. ```diff # reusableapp/migrations/0001_initial.py from django.db import models, migrations < from django.conf import settings > import swapper class Migration(migrations.Migration): dependencies = [ < migrations.swappable_dependency(settings.REUSABLEAPP_PARENT_MODEL), > swapper.dependency('reusableapp', 'Parent') ] operations = [ migrations.CreateModel( name='Child', fields=[ ('id', models.AutoField(auto_created=True, serialize=False, primary_key=True, verbose_name='ID')), ], options={ < 'swappable': 'REUSABLEAPP_CHILD_MODEL', > 'swappable': swapper.swappable_setting('reusableapp', 'Child'), }, bases=(models.Model,), ), migrations.CreateModel( name='Parent', fields=[ ('id', models.AutoField(auto_created=True, serialize=False, primary_key=True, verbose_name='ID')), ], options={ < 'swappable': 'REUSABLEAPP_PARENT_MODEL', > 'swappable': swapper.swappable_setting('reusableapp', 'Parent'), }, bases=(models.Model,), ), migrations.AddField( model_name='child', name='parent', < field=models.ForeignKey(to=settings.REUSABLEAPP_PARENT_MODEL), > field=models.ForeignKey(to=swapper.get_model_name('reusableapp', 'Parent')), preserve_default=True, ), ] ``` ## End User Documentation With the above setup, the user of your app can override one or both models in their own app. You might provide them with an example like this: ```python # myapp/models.py from reusableapp.models import BaseParent class Parent(BaseParent): # custom implementation ... ``` Then, tell your users to update their settings to trigger the swap. ```python # myproject/settings.py REUSABLEAPP_PARENT_MODEL = "myapp.Parent" ``` The goal is to make this process just as easy for your end user as [swapping the auth.User model] is. As with `auth.User`, there are some important caveats that you may want to inform your users about. The biggest issue is that your users will probably need to define the swapped model settings **before creating any migrations** for their implementation of `myapp`. Due to key assumptions made within Django's migration infrastructure, it is difficult to start out with a default (non-swapped) model and then later to switch to a swapped implementation without doing some migration hacking. This is somewhat awkward - as your users will most likely want to try out your default implementation before deciding to customize it. Unfortunately, there isn't an easy workaround due to how the swappable setting is currently implemented in Django core. This will likely be addressed in future Django versions (see [#10] and [Django ticket #25313]). ## API Documentation Here is the full API for `swapper`, which you may find useful in creating your reusable app code. End users of your library should generally not need to reference this API. %package help Summary: Development documents and examples for swapper Provides: python3-swapper-doc %description help [![Dependency monitoring](https://img.shields.io/librariesio/release/github/openwisp/django-swappable-models)](https://libraries.io/github/openwisp/django-swappable-models) #### Django Swappable Models - No longer only for auth.User! Swapper is an unofficial API for the [undocumented] but very powerful Django feature: swappable models. Swapper facilitates implementing arbitrary swappable models in your own reusable apps. [![Latest PyPI Release](https://img.shields.io/pypi/v/swapper.svg)](https://pypi.org/project/swapper) [![Release Notes](https://img.shields.io/github/release/openwisp/django-swappable-models.svg )](https://github.com/wq/django-swappable-models/releases) [![License](https://img.shields.io/pypi/l/swapper.svg)](https://github.com/openwisp/django-swappable-models/blob/master/LICENSE) [![GitHub Stars](https://img.shields.io/github/stars/openwisp/django-swappable-models.svg)](https://github.com/openwisp/django-swappable-models/stargazers) [![GitHub Forks](https://img.shields.io/github/forks/openwisp/django-swappable-models.svg)](https://github.com/openwisp/django-swappable-models/network) [![GitHub Issues](https://img.shields.io/github/issues/openwisp/django-swappable-models.svg)](https://github.com/openwisp/django-swappable-models/issues) [![Build Status](https://github.com/openwisp/django-swappable-models/actions/workflows/ci.yml/badge.svg)](https://github.com/openwisp/django-swappable-models/actions/workflows/ci.yml) [![Python Support](https://img.shields.io/pypi/pyversions/swapper.svg)](https://pypi.org/project/swapper) [![Django Support](https://img.shields.io/pypi/djversions/swapper.svg)](https://pypi.org/project/swapper) ## Motivation Suppose your reusable app has two related tables: ```python from django.db import models class Parent(models.Model): name = models.TextField() class Child(models.Model): name = models.TextField() parent = models.ForeignKey(Parent) ``` Suppose further that you want to allow the user to subclass either or both of these models and supplement them with their own additional fields. You could use Abstract classes (e.g. `BaseParent` and `BaseChild`) for this, but then you would either need to: 1. Avoid putting the foreign key on `BaseChild` and tell the user they need to do it. 2. Put the foreign key on `BaseChild`, but make `Parent` a concrete model that can't be swapped 3. Use swappable models, together with `ForeignKeys` that read the swappable settings. This third approach is taken by Django to facilitate [swapping the auth.User model]. The `auth.User` swappable code was implemented in a generic way that allows it to be used for any model. Although this capability is currently [undocumented] while any remaining issues are being sorted out, it has proven to be very stable and useful in our experience. Swapper is essentially a simple API wrapper around this existing functionality. Note that Swapper is primarily a tool for library authors; users of your reusable app generally should not need to know about Swapper in order to use it. (See the notes on [End User Documentation](#end-user-documentation) below.) ### Real-World Examples Swapper is used extensively in several OpenWISP packages to facilitate customization and extension. Notable examples include: * [openwisp-users] * [openwisp-controller] * [openwisp-radius] The use of swapper in these packages promotes [Software Reusability][reusability], one of the core values of the OpenWISP project. ## Creating a Reusable App First, make sure you have `swapper` installed. If you are publishing your reusable app as a Python package, be sure to add `swapper` to your project's dependencies (e.g. `setup.py`) to ensure that users of your app don't have errors integrating it. ```bash pip3 install swapper ``` Extending the above example, you might create two abstract base classes and corresponding default implementations: ```python # reusableapp/models.py from django.db import models import swapper class BaseParent(models.Model): # minimal base implementation ... class Meta: abstract = True class Parent(BaseParent): # default (swappable) implementation ... class Meta: swappable = swapper.swappable_setting('reusableapp', 'Parent') class BaseChild(models.Model): parent = models.ForeignKey(swapper.get_model_name('reusableapp', 'Parent')) # minimal base implementation ... class Meta: abstract = True class Child(BaseChild): # default (swappable) implementation ... class Meta: swappable = swapper.swappable_setting('reusableapp', 'Child') ``` ### Loading Swapped Models In your reusable views and other functions, always use the swapper instead of importing swappable models directly. This is because you might not know whether the user of your app is using your default implementation or their own version. ```python # reusableapp/views.py # Might work, might not # from .models import Parent import swapper Parent = swapper.load_model("reusableapp", "Parent") Child = swapper.load_model("reusableapp", "Child") def view(request, *args, **kwargs): qs = Parent.objects.all() # ... ``` > Note: `swapper.load_model()` is the general equivalent of [get_user_model()] and subject to the same constraints: e.g. it should not be used until after the model system has fully initialized. ### Migration Scripts Swapper can also be used in migration scripts to facilitate dependency ordering and foreign key references. To use this feature in your library, generate a migration script with `makemigrations` and make the following changes. In general, users of your library should not need to make any similar changes to their own migration scripts. The one exception is if you have multiple levels of swappable models with foreign keys pointing to each other. ```diff # reusableapp/migrations/0001_initial.py from django.db import models, migrations < from django.conf import settings > import swapper class Migration(migrations.Migration): dependencies = [ < migrations.swappable_dependency(settings.REUSABLEAPP_PARENT_MODEL), > swapper.dependency('reusableapp', 'Parent') ] operations = [ migrations.CreateModel( name='Child', fields=[ ('id', models.AutoField(auto_created=True, serialize=False, primary_key=True, verbose_name='ID')), ], options={ < 'swappable': 'REUSABLEAPP_CHILD_MODEL', > 'swappable': swapper.swappable_setting('reusableapp', 'Child'), }, bases=(models.Model,), ), migrations.CreateModel( name='Parent', fields=[ ('id', models.AutoField(auto_created=True, serialize=False, primary_key=True, verbose_name='ID')), ], options={ < 'swappable': 'REUSABLEAPP_PARENT_MODEL', > 'swappable': swapper.swappable_setting('reusableapp', 'Parent'), }, bases=(models.Model,), ), migrations.AddField( model_name='child', name='parent', < field=models.ForeignKey(to=settings.REUSABLEAPP_PARENT_MODEL), > field=models.ForeignKey(to=swapper.get_model_name('reusableapp', 'Parent')), preserve_default=True, ), ] ``` ## End User Documentation With the above setup, the user of your app can override one or both models in their own app. You might provide them with an example like this: ```python # myapp/models.py from reusableapp.models import BaseParent class Parent(BaseParent): # custom implementation ... ``` Then, tell your users to update their settings to trigger the swap. ```python # myproject/settings.py REUSABLEAPP_PARENT_MODEL = "myapp.Parent" ``` The goal is to make this process just as easy for your end user as [swapping the auth.User model] is. As with `auth.User`, there are some important caveats that you may want to inform your users about. The biggest issue is that your users will probably need to define the swapped model settings **before creating any migrations** for their implementation of `myapp`. Due to key assumptions made within Django's migration infrastructure, it is difficult to start out with a default (non-swapped) model and then later to switch to a swapped implementation without doing some migration hacking. This is somewhat awkward - as your users will most likely want to try out your default implementation before deciding to customize it. Unfortunately, there isn't an easy workaround due to how the swappable setting is currently implemented in Django core. This will likely be addressed in future Django versions (see [#10] and [Django ticket #25313]). ## API Documentation Here is the full API for `swapper`, which you may find useful in creating your reusable app code. End users of your library should generally not need to reference this API. %prep %autosetup -n swapper-1.3.0 %build %py3_build %install %py3_install install -d -m755 %{buildroot}/%{_pkgdocdir} if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi pushd %{buildroot} if [ -d usr/lib ]; then find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/lib64 ]; then find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/bin ]; then find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/sbin ]; then find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst fi touch doclist.lst if [ -d usr/share/man ]; then find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst fi popd mv %{buildroot}/filelist.lst . mv %{buildroot}/doclist.lst . %files -n python3-swapper -f filelist.lst %dir %{python3_sitelib}/* %files help -f doclist.lst %{_docdir}/* %changelog * Tue Apr 11 2023 Python_Bot - 1.3.0-1 - Package Spec generated