[](https://travis-ci.org/ambitioninc/django-activatable-model)
# Django Activatable Model
Provides functionality for Django models that have active and inactive states.
Features of this app are:
1. An abstract BaseActivatableModel that allows the user to specify an
'activatable' (i.e. Boolean) field
1. A model_activations_changed signal that fires when models' activatable field
are changed or bulk updated
1. Validation to ensure activatable models cannot be cascade deleted
1. Overriding of delete methods so that the activatable flag is set to False
instead of the model(s) being deleted (unless force=True)
1. Manager/QuerySet methods to activate and deactivate models
## Installation
```bash
pip install django-activatable-model
```
Add `activatable_model` to the list of `INSTALLED_APPS`. Although this app does
not define any concrete models, it does connect signals that Django needs to
know about.
## Basic Usage
Assume you have a model called `Account` in your app, and it is an activatable
model that has a `name` field and a `ForeignKey` to a `Group` model.
```python
from activatable_model.models import BaseActivatableModel
class Account(BaseActivatableModel):
is_active = models.BooleanField(default=False)
name = models.CharField(max_length=64)
group = models.ForeignKey(Group)
```
By just inheriting `BaseActivatableModel`, your model will need to define an
`is_active` boolean field (this field name can be changed, more on that later).
If you create an `Account` model, the `model_activations_changed` signal will
be sent with an `is_active` keyword argument set to False and an `instance_ids`
keyword argument that is a list of the single created account id. Similarly, if
you updated the `is_active` flag at any time via the `.save()` method, the
`model_activations_changed` signal will be emitted again. This allows the user
to do things like this:
```python
from django.dispatch import receiver
from activatable_model import model_activations_changed
@receiver(model_activations_changed, sender=Account)
def do_something_on_deactivation(sender, instance_ids, is_active, **kwargs):
if not is_active:
# Either an account was deactivated or an inactive account was created...
for account in Account.objects.filter(id__in=instance_ids):
# Do something with every deactivated account
```
## Activatable Model Deletion
Django activatable model is meant for models that should never be deleted but
rather activated/deactivated instead. Given the assumption that activatable
models should never be deleted, Django activatable model does some magic
underneath to ensure your activatable models are properly updated when the user
calls `.delete()`. Instead of deleting the object(s) directly, the `is_active`
flag is set to False and `model_activations_changed` is fired.
```python
account = Account.objects.create(is_active=True)
account.delete() # Or Account.objects.all().delete()
# The account still exists
print Account.objects.count()
1
# But it is deactivated
print Account.objects.get().is_active
False
```
The user can override this behavior by passing `force=True` to the model or
queryset's `.delete()` method.
Along with overriding deletion, Django activatable model also overrides cascade
deletion. No model that inherits `BaseActivatableModel` can be cascade deleted
by another model. This is accomplished by connecting to Django's `pre_syncdb`
signal and verifying that all `ForeignKey` and `OneToOneField` fields of
activatable models have their `on_delete` arguments set to something other than
the default of `models.CASCADE`.
In fact, our `Account` model will not pass validation. In order to make it
validate properly on syncdb, it must do the following:
```python
from django.db import models
class Account(BaseActivatableModel):
is_active = models.BooleanField(default=False)
name = models.CharField(max_length=64)
group = models.ForeignKey(Group, on_delete=models.PROTECT)
```
This will ensure a `ProtectedError` is thrown every time a Group is deleted.
For other options on foreign key deletion behavior, see
[Django's docs](https://docs.djangoproject.com/en/1.7/ref/models/fields/#django.db.models.ForeignKey.on_delete).
### Cascade Overrides (new in version 0.8.0 )
As mentioned above, activatable models cannot be cascade deleted. However,
this default behavior can be overridden by setting the the class variable,
`ALLOW_CASCADE_DELETE = True`. If set to True, than cascade deletion will
be allowed. Note however, that this will be a hard delete, meaning that
cascade deletion will completely remove your record from the database rather
than applying the ActivatibleModel magic of simply marking it as inactive.
## Manager and QuerySet methods
Django activatable models automatically use an `ActivatableManager` manager
that uses an `ActivatableQuerySet` queryset. This provides the following
functionality:
1. Two methods - `activate()` and `deactivate()` that can be applied to a
queryset
1. Overriding the `update()` method so that it emits
`model_activations_changed` when the `is_active` flag is updated
1. Overriding the `delete()` method so that it calls `deactivate()` unless
`force=True`
## Overriding the activatable field name
The name of the activatable field can be overridden by defining the
`ACTIVATABLE_FIELD_NAME` constant on the model to something else. By default,
this constant is set to `is_active`. An example is as follows:
```python
from activatable_model import BaseActivatableModel
class Account(BaseActivatableModel):
ACTIVATABLE_FIELD_NAME = 'active'
active = models.BooleanField(default=False)
```
In the above example, the model instructs the activatable model app to use
`active` as the activatable field on the model. If the user does not define a
`BooleanField` on the model with the same name as `ACTIVATABLE_FIELD_NAME`, a
`ValidationError` is raised during syncdb / migrate.
## Release Notes
* 0.5.1
* Optimize individual saves so that they dont perform an additional query when checking if model activations have been updated
* 0.5.0
* Changed the signal to send instance_ids as a keyword argument rather than the instances. This pushes fetching the updated models in signal handlers onto the application
* 0.4.2
* Fixed bug when activating a queryset that was filtered by the active flag
* 0.3.1
* Added Django 1.7 app config
* 0.3.0
* Added Django 1.7 support and backwards compatibility with Django 1.6
* 0.2.0
* When upgrading to this version, users will have to explicitly add the
`is_active` field to any models that inherited `BaseActivatableModel`. This
field had a default value of False before, so be sure to add that as the
default for the boolean field.
## License
MIT License (see the [LICENSE](LICENSE) file in this repo)
Raw data
{
"_id": null,
"home_page": "https://github.com/ambitioninc/django-activatable-model",
"name": "django-activatable-model",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Django,Model,Activatable",
"author": "Wes Kendall",
"author_email": "opensource@ambition.com",
"download_url": "https://files.pythonhosted.org/packages/dc/99/90194718892e1069ec149212898a5bfb91c7048744f6fbc3b223ac06622b/django-activatable-model-3.1.0.tar.gz",
"platform": null,
"description": "[](https://travis-ci.org/ambitioninc/django-activatable-model)\n# Django Activatable Model\n\nProvides functionality for Django models that have active and inactive states. \nFeatures of this app are:\n\n1. An abstract BaseActivatableModel that allows the user to specify an \n'activatable' (i.e. Boolean) field\n1. A model_activations_changed signal that fires when models' activatable field\nare changed or bulk updated\n1. Validation to ensure activatable models cannot be cascade deleted\n1. Overriding of delete methods so that the activatable flag is set to False \ninstead of the model(s) being deleted (unless force=True)\n1. Manager/QuerySet methods to activate and deactivate models\n\n## Installation\n```bash\npip install django-activatable-model\n```\n\nAdd `activatable_model` to the list of `INSTALLED_APPS`. Although this app does\nnot define any concrete models, it does connect signals that Django needs to \nknow about.\n\n## Basic Usage\nAssume you have a model called `Account` in your app, and it is an activatable \nmodel that has a `name` field and a `ForeignKey` to a `Group` model.\n\n```python\nfrom activatable_model.models import BaseActivatableModel\n\nclass Account(BaseActivatableModel):\n is_active = models.BooleanField(default=False)\n name = models.CharField(max_length=64)\n group = models.ForeignKey(Group)\n```\n\nBy just inheriting `BaseActivatableModel`, your model will need to define an \n`is_active` boolean field (this field name can be changed, more on that later).\nIf you create an `Account` model, the `model_activations_changed` signal will \nbe sent with an `is_active` keyword argument set to False and an `instance_ids` \nkeyword argument that is a list of the single created account id. Similarly, if \nyou updated the `is_active` flag at any time via the `.save()` method, the \n`model_activations_changed` signal will be emitted again. This allows the user \nto do things like this:\n\n```python\nfrom django.dispatch import receiver\nfrom activatable_model import model_activations_changed\n\n@receiver(model_activations_changed, sender=Account)\ndef do_something_on_deactivation(sender, instance_ids, is_active, **kwargs):\n if not is_active:\n # Either an account was deactivated or an inactive account was created...\n for account in Account.objects.filter(id__in=instance_ids):\n # Do something with every deactivated account\n```\n\n## Activatable Model Deletion\nDjango activatable model is meant for models that should never be deleted but \nrather activated/deactivated instead. Given the assumption that activatable \nmodels should never be deleted, Django activatable model does some magic \nunderneath to ensure your activatable models are properly updated when the user\ncalls `.delete()`. Instead of deleting the object(s) directly, the `is_active` \nflag is set to False and `model_activations_changed` is fired.\n\n```python\naccount = Account.objects.create(is_active=True)\naccount.delete() # Or Account.objects.all().delete()\n\n# The account still exists\nprint Account.objects.count()\n1\n\n# But it is deactivated\nprint Account.objects.get().is_active\nFalse\n```\n\nThe user can override this behavior by passing `force=True` to the model or \nqueryset's `.delete()` method.\n\nAlong with overriding deletion, Django activatable model also overrides cascade\ndeletion. No model that inherits `BaseActivatableModel` can be cascade deleted \nby another model. This is accomplished by connecting to Django's `pre_syncdb` \nsignal and verifying that all `ForeignKey` and `OneToOneField` fields of \nactivatable models have their `on_delete` arguments set to something other than\nthe default of `models.CASCADE`.\n\nIn fact, our `Account` model will not pass validation. In order to make it \nvalidate properly on syncdb, it must do the following:\n\n```python\nfrom django.db import models\n\nclass Account(BaseActivatableModel):\n is_active = models.BooleanField(default=False)\n name = models.CharField(max_length=64)\n group = models.ForeignKey(Group, on_delete=models.PROTECT)\n```\n\nThis will ensure a `ProtectedError` is thrown every time a Group is deleted. \nFor other options on foreign key deletion behavior, see \n[Django's docs](https://docs.djangoproject.com/en/1.7/ref/models/fields/#django.db.models.ForeignKey.on_delete).\n\n### Cascade Overrides (new in version 0.8.0 )\nAs mentioned above, activatable models cannot be cascade deleted. However,\nthis default behavior can be overridden by setting the the class variable,\n`ALLOW_CASCADE_DELETE = True`. If set to True, than cascade deletion will\nbe allowed. Note however, that this will be a hard delete, meaning that\ncascade deletion will completely remove your record from the database rather\nthan applying the ActivatibleModel magic of simply marking it as inactive.\n\n## Manager and QuerySet methods\nDjango activatable models automatically use an `ActivatableManager` manager\nthat uses an `ActivatableQuerySet` queryset. This provides the following \nfunctionality:\n\n1. Two methods - `activate()` and `deactivate()` that can be applied to a \nqueryset\n1. Overriding the `update()` method so that it emits \n`model_activations_changed` when the `is_active` flag is updated\n1. Overriding the `delete()` method so that it calls `deactivate()` unless \n`force=True`\n\n## Overriding the activatable field name\nThe name of the activatable field can be overridden by defining the \n`ACTIVATABLE_FIELD_NAME` constant on the model to something else. By default, \nthis constant is set to `is_active`. An example is as follows:\n\n```python\nfrom activatable_model import BaseActivatableModel\n\nclass Account(BaseActivatableModel):\n ACTIVATABLE_FIELD_NAME = 'active'\n active = models.BooleanField(default=False)\n```\n\nIn the above example, the model instructs the activatable model app to use \n`active` as the activatable field on the model. If the user does not define a \n`BooleanField` on the model with the same name as `ACTIVATABLE_FIELD_NAME`, a\n`ValidationError` is raised during syncdb / migrate.\n\n## Release Notes\n* 0.5.1\n * Optimize individual saves so that they dont perform an additional query when checking if model activations have been updated\n* 0.5.0\n * Changed the signal to send instance_ids as a keyword argument rather than the instances. This pushes fetching the updated models in signal handlers onto the application\n* 0.4.2\n * Fixed bug when activating a queryset that was filtered by the active flag\n* 0.3.1\n * Added Django 1.7 app config\n* 0.3.0\n * Added Django 1.7 support and backwards compatibility with Django 1.6\n\n* 0.2.0\n * When upgrading to this version, users will have to explicitly add the \n `is_active` field to any models that inherited `BaseActivatableModel`. This \n field had a default value of False before, so be sure to add that as the \n default for the boolean field.\n\n## License\nMIT License (see the [LICENSE](LICENSE) file in this repo)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django Activatable Model",
"version": "3.1.0",
"project_urls": {
"Homepage": "https://github.com/ambitioninc/django-activatable-model"
},
"split_keywords": [
"django",
"model",
"activatable"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "467525e616ca93619818e3dcd0ecb7a2e6f158b9f2bf613ba4bf991992dd4212",
"md5": "9b740cf7efa991739a8e9be0f1374ee2",
"sha256": "2b7e422735c40e21159d4a3e93f969fded58022d7def8f4853ee3410efd30067"
},
"downloads": -1,
"filename": "django_activatable_model-3.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "9b740cf7efa991739a8e9be0f1374ee2",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 13605,
"upload_time": "2023-06-29T14:46:29",
"upload_time_iso_8601": "2023-06-29T14:46:29.946997Z",
"url": "https://files.pythonhosted.org/packages/46/75/25e616ca93619818e3dcd0ecb7a2e6f158b9f2bf613ba4bf991992dd4212/django_activatable_model-3.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dc9990194718892e1069ec149212898a5bfb91c7048744f6fbc3b223ac06622b",
"md5": "5d98af1af18471fdc62b4d447f0f44c4",
"sha256": "bd0c7e5a91c678e7b2e37e172ed29ffa9b730b55659e024f1612dbcc5ae778f8"
},
"downloads": -1,
"filename": "django-activatable-model-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "5d98af1af18471fdc62b4d447f0f44c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13591,
"upload_time": "2023-06-29T14:46:31",
"upload_time_iso_8601": "2023-06-29T14:46:31.647757Z",
"url": "https://files.pythonhosted.org/packages/dc/99/90194718892e1069ec149212898a5bfb91c7048744f6fbc3b223ac06622b/django-activatable-model-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-29 14:46:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ambitioninc",
"github_project": "django-activatable-model",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "django-activatable-model"
}
JSON
