# Django Timestamps
Timestamps and Soft Delete Patterns in Django Models.
## How to install
### Option a)
````bash
$ pip install django-timestampable
````
### Option b)
To install django-timestampable with [Django Rest Framework](https://www.django-rest-framework.org/) included:
````bash
$ pip install "django-timestampable[drf]"
````
*You can use the first option if you have Django Rest Framework already installed.*
#### And add "timestamps" to your INSTALLED_APPS settings
```python
INSTALLED_APPS = [
# ...
'timestamps',
]
```
#### Or, if you installed with [Django Rest Framework](https://www.django-rest-framework.org/):
```python
INSTALLED_APPS = [
# ...
'rest_framework',
'timestamps',
]
```
## Usage
a) For models you want timestamps, just inherit Timestampable:
```python
from timestamps.models import models, Timestampable
class YourModel(Timestampable):
# your fields here ...
```
b) For models you want soft-delete, just inherit SoftDeletes:
```python
from timestamps.models import models, SoftDeletes
class YourModel(SoftDeletes):
# your fields here ...
```
c) If you want both, you can also inherit from Model for shorter convenience:
```python
# to this:
from timestamps.models import models, Model # explicit import Model (which contains timestamps)
# instead of:
# from django.db import models
# Explicitly import of "Model" is required
# because models.Model is the original from Django models module
class YourModel(Model):
# your fields here ...
```
### Soft Deleting
- To get all objects without the deleted ones:
```queryset = YourModel.objects```
- To get only deleted objects:
```queryset = YourModel.objects_deleted```
- To get all the objects, including deleted ones:
```queryset = YourModel.objects_with_deleted```
#### To soft delete an instance
```python
some_model = MyModel.objects.first()
some_model.delete() # or some_model.delete(hard=False)
```
#### To restore an instance
```python
some_model = MyModel.objects_deleted.first()
some_model.restore()
```
#### To hard delete an instance
```python
some_model = MyModel.objects.first()
some_model.delete(hard=True)
```
#### To bulk soft delete a queryset
```python
qs = MyModel.objects # you can also apply filters to bulk delete a subset: qs = MyModel.objects.filter(...)
qs.delete() # or qs.delete(hard=False)
```
#### To bulk hard delete a queryset
```python
qs = MyModel.objects # ... bulk hard delete a subset: qs = MyModel.objects.filter(...)
qs.delete(hard=True)
```
#### To bulk restore a queryset
```python
qs = MyModel.objects_deleted # ... bulk restore a subset: qs = MyModel.objects_deleted.filter(...)
qs.restore() # or qs.delete(hard=False)
```
---
### Signals for Soft Deleting and Restoring
You have 4 signals available that you can listen in your project:
- pre_soft_delete
- post_soft_delete
- pre_restore
- post_restore
To use them, just import the signals and register listeners for them. Eg:
#### Pre Soft Delete
```python3
from timestamps.signals import pre_soft_delete
from django.dispatch import receiver
@receiver(pre_soft_delete)
def on_pre_soft_delete(sender, instance, **kwargs):
print(f"Model {sender} with id {instance.pk} will be deleted!")
```
#### Post Soft Delete
```python3
from timestamps.signals import post_soft_delete
from django.dispatch import receiver
@receiver(post_soft_delete)
def on_post_soft_delete(sender, instance, **kwargs):
print(f"Model {sender} with id {instance.pk} was deleted at {instance.deleted_at}!")
```
#### Pre Restore
```python3
from timestamps.signals import pre_restore
from django.dispatch import receiver
@receiver(pre_restore)
def on_pre_restore(sender, instance, **kwargs):
print(f"Model {sender} with id {instance.pk} deleted at {instance.deleted_at} will be restored!")
```
#### Post Restore
```python3
from timestamps.signals import post_restore
from django.dispatch import receiver
@receiver(post_restore)
def on_post_restore(sender, instance, **kwargs):
print(f"Model {sender} with id {instance.pk} restored!")
```
---
### If you're using DRF
You can use the SoftDeleteModelViewSet along with DefaultRouter present in this package
and you will have access to a complete CRUD on soft deleted objects as well.
This 2 classes allows you to expose:
Consider a Dummy Model that inherits from SoftDelete.
You can have all routes for CRUD operations on this model:
| VERB | URL PATH | DESCRIPTION |
| ---- | -------- | ----------- |
| GET | /dummy/ | gets all the objects, without the deleted ones |
| POST | /dummy/ | creates a new object |
| DELETE | /dummy/[?permanent=\<true,false>] | deletes all objects (or a filtered subject). allows hard-delete. Default: soft-delete |
| GET | /dummy/\<pk\>/ | gets a non-deleted object (by primary key) |
| POST | /dummy/\<pk\>/ | updates an object (by primary key) |
| PATCH | /dummy/\<pk\>/ | partial updates an object (by primary key) |
| DELETE | /dummy/\<pk\>/[?permanent=\<true,false>] | deletes a non-deleted object (by primary key) |
| PATCH | /dummy/restore/ | restore all objects (or a filtered subject) |
| PATCH | /dummy/\<pk\>/restore/ | restores a soft-deleted object (by primary key) |
| GET | /dummy/deleted/ | gets all deleted objects |
| GET | /dummy/deleted/\<pk\>/ | gets a deleted object (by primary key) |
| GET | /dummy/with-deleted/ | get all objects, deleted included |
| GET | /dummy/with-deleted/\<pk\>/ | get an object (by primary key) |
The query parameter "permanent" it's case-sensitive and can also be one of the values:
```python
truthful_options = [
't', 'T',
'y', 'Y', 'yes', 'Yes', 'YES',
'true', 'True', 'TRUE',
'on', 'On', 'ON',
'1', 1,
True
]
```
```python
falsely_options = [
'f', 'F',
'n', 'N', 'no', 'No', 'NO',
'false', 'False', 'FALSE',
'off', 'Off', 'OFF',
'0', 0,
'null',
False
]
```
#### How to expose all CRUD operations
```python
# dummy/views.py
from timestamps.drf import viewsets # instead of: from rest_framework import viewsets
from .models import Dummy
from .serializers import DummySerializer
class DummyModelViewSet(viewsets.ModelViewSet):
queryset = Dummy.objects.all()
serializer_class = DummySerializer
```
````python
# dummy/urls.py
from timestamps.drf import routers # instead of: from rest_framework import routers
from .views import DummyModelViewSet
router = routers.DefaultRouter()
router.register(r'dummy', DummyModelViewSet)
urlpatterns = router.urls
````
#### Note A
For security reasons, by default, if you pass to the query parameter "?permanent=true" on a bulk destroy,
the view will not let you hard-delete, raising a PermissionDenied.
If you want to enable it on your project, just add to the project settings:
```python
TIMESTAMPS__BULK_HARD_DELETE = True
```
It's here to prevent users of "forgetting" that the routes also expose bulk hard-delete by default.
In production, you can set this flag to True and manage hard-deleting using DRF permissions.
*Hard-deleting one object at time is allowed by default.*
#### NOTE B
Bulk actions of restoring and deleting returns no content (status code 204) by default.
If you want to return a response with the number of deleted/restored objects, just add this setting:
```python
TIMESTAMPS__BULK_RESPONSE_CONTENT = True
```
Example of returned response: ```{"count": 3 }```
#### Note C
If you don't want to expose all the crud operations, be free to register as:
```python
router.register(r'dummy', DummyModelViewSet.as_view({'get': 'list_with_deleted'})) # e.g.
```
And you can always use the mixins instead and create your APIViews:
````python
from rest_framework import generic
from timestamps.drf.mixins import ListDeletedModelMixin
from .models import Dummy
from .serializers import DummySerializer
class MyView(ListDeletedModelMixin, generic.GenericAPIView):
queryset = Dummy.objects.all()
serializer_class = DummySerializer
def list_deleted(self, request, *args, **kwargs):
# optional. your code goes here...
````
Internally, the ListDeletedModelMixin just calls the method ListModelMixin.list(self, request, *args, **kwargs).
The method of determining if the queryset must get all objects, only the deleted or all with deleted is done using AOP,
which means that the method GenericAPIView.get_queryset() is advised at runtime to map the current action
to the correct queryset the view needs.
If you don't inherit from generic.GenericAPIView, you must be aware that, for this type of scenarios,
you need to override the method get_queryset() to return the objects that matches your needs.
Raw data
{
"_id": null,
"home_page": "https://github.com/xgeekshq/django-timestampable/",
"name": "django-timestampable",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Daniel Pinto",
"author_email": "dmp593@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a5/96/8be5ed4c068bf313f2442cf27cd09adeb94d5dc68f2682098b4fee6ccd30/django-timestampable-1.1.4.tar.gz",
"platform": null,
"description": "# Django Timestamps\n\nTimestamps and Soft Delete Patterns in Django Models.\n\n\n## How to install\n\n### Option a)\n````bash\n$ pip install django-timestampable\n````\n\n\n### Option b)\nTo install django-timestampable with [Django Rest Framework](https://www.django-rest-framework.org/) included:\n````bash\n$ pip install \"django-timestampable[drf]\"\n````\n*You can use the first option if you have Django Rest Framework already installed.*\n\n \n\n#### And add \"timestamps\" to your INSTALLED_APPS settings\n\n```python\nINSTALLED_APPS = [\n # ...\n 'timestamps',\n]\n```\n\n#### Or, if you installed with [Django Rest Framework](https://www.django-rest-framework.org/):\n```python\nINSTALLED_APPS = [\n # ...\n 'rest_framework',\n 'timestamps',\n]\n```\n\n## Usage\n\na) For models you want timestamps, just inherit Timestampable:\n\n```python\nfrom timestamps.models import models, Timestampable\n\n\nclass YourModel(Timestampable):\n # your fields here ...\n\n```\n\nb) For models you want soft-delete, just inherit SoftDeletes:\n\n```python\nfrom timestamps.models import models, SoftDeletes\n\n\nclass YourModel(SoftDeletes):\n # your fields here ...\n\n```\n\nc) If you want both, you can also inherit from Model for shorter convenience:\n\n```python\n# to this:\nfrom timestamps.models import models, Model # explicit import Model (which contains timestamps)\n\n# instead of:\n# from django.db import models\n\n# Explicitly import of \"Model\" is required\n# because models.Model is the original from Django models module\n\n\nclass YourModel(Model):\n # your fields here ...\n\n```\n\n\n### Soft Deleting\n\n- To get all objects without the deleted ones:\n\n```queryset = YourModel.objects```\n\n- To get only deleted objects:\n\n```queryset = YourModel.objects_deleted```\n\n- To get all the objects, including deleted ones:\n\n```queryset = YourModel.objects_with_deleted```\n\n\n#### To soft delete an instance\n\n```python\nsome_model = MyModel.objects.first()\nsome_model.delete() # or some_model.delete(hard=False)\n```\n\n#### To restore an instance\n\n```python\nsome_model = MyModel.objects_deleted.first()\nsome_model.restore()\n```\n\n#### To hard delete an instance\n\n```python\nsome_model = MyModel.objects.first()\nsome_model.delete(hard=True)\n```\n\n#### To bulk soft delete a queryset\n\n```python\nqs = MyModel.objects # you can also apply filters to bulk delete a subset: qs = MyModel.objects.filter(...)\nqs.delete() # or qs.delete(hard=False)\n```\n\n#### To bulk hard delete a queryset\n\n```python\nqs = MyModel.objects # ... bulk hard delete a subset: qs = MyModel.objects.filter(...)\nqs.delete(hard=True)\n```\n\n#### To bulk restore a queryset\n\n```python\nqs = MyModel.objects_deleted # ... bulk restore a subset: qs = MyModel.objects_deleted.filter(...)\nqs.restore() # or qs.delete(hard=False)\n```\n\n \n\n---\n\n \n\n### Signals for Soft Deleting and Restoring\n\nYou have 4 signals available that you can listen in your project:\n\n- pre_soft_delete\n- post_soft_delete\n- pre_restore\n- post_restore\n\nTo use them, just import the signals and register listeners for them. Eg:\n\n#### Pre Soft Delete\n\n```python3\nfrom timestamps.signals import pre_soft_delete\nfrom django.dispatch import receiver\n\n@receiver(pre_soft_delete)\ndef on_pre_soft_delete(sender, instance, **kwargs):\n print(f\"Model {sender} with id {instance.pk} will be deleted!\")\n```\n\n#### Post Soft Delete\n\n```python3\nfrom timestamps.signals import post_soft_delete\nfrom django.dispatch import receiver\n\n@receiver(post_soft_delete)\ndef on_post_soft_delete(sender, instance, **kwargs):\n print(f\"Model {sender} with id {instance.pk} was deleted at {instance.deleted_at}!\")\n```\n\n#### Pre Restore\n\n```python3\nfrom timestamps.signals import pre_restore\nfrom django.dispatch import receiver\n\n@receiver(pre_restore)\ndef on_pre_restore(sender, instance, **kwargs):\n print(f\"Model {sender} with id {instance.pk} deleted at {instance.deleted_at} will be restored!\")\n```\n\n#### Post Restore\n\n```python3\nfrom timestamps.signals import post_restore\nfrom django.dispatch import receiver\n\n@receiver(post_restore)\ndef on_post_restore(sender, instance, **kwargs):\n print(f\"Model {sender} with id {instance.pk} restored!\")\n```\n\n \n\n---\n\n \n\n### If you're using DRF\n\nYou can use the SoftDeleteModelViewSet along with DefaultRouter present in this package\nand you will have access to a complete CRUD on soft deleted objects as well.\nThis 2 classes allows you to expose:\n\nConsider a Dummy Model that inherits from SoftDelete.\n\nYou can have all routes for CRUD operations on this model:\n\n| VERB | URL PATH | DESCRIPTION |\n| ---- | -------- | ----------- |\n| GET | /dummy/ | gets all the objects, without the deleted ones |\n| POST | /dummy/ | creates a new object |\n| DELETE | /dummy/[?permanent=\\<true,false>] | deletes all objects (or a filtered subject). allows hard-delete. Default: soft-delete |\n| GET | /dummy/\\<pk\\>/ | gets a non-deleted object (by primary key) |\n| POST | /dummy/\\<pk\\>/ | updates an object (by primary key) |\n| PATCH | /dummy/\\<pk\\>/ | partial updates an object (by primary key) |\n| DELETE | /dummy/\\<pk\\>/[?permanent=\\<true,false>] | deletes a non-deleted object (by primary key) |\n| PATCH | /dummy/restore/ | restore all objects (or a filtered subject) |\n| PATCH | /dummy/\\<pk\\>/restore/ | restores a soft-deleted object (by primary key) |\n| GET | /dummy/deleted/ | gets all deleted objects |\n| GET | /dummy/deleted/\\<pk\\>/ | gets a deleted object (by primary key) |\n| GET | /dummy/with-deleted/ | get all objects, deleted included |\n| GET | /dummy/with-deleted/\\<pk\\>/ | get an object (by primary key) |\n\n \n\nThe query parameter \"permanent\" it's case-sensitive and can also be one of the values:\n\n```python\ntruthful_options = [\n 't', 'T',\n 'y', 'Y', 'yes', 'Yes', 'YES',\n 'true', 'True', 'TRUE',\n 'on', 'On', 'ON',\n '1', 1,\n True\n]\n```\n\n```python\nfalsely_options = [\n 'f', 'F',\n 'n', 'N', 'no', 'No', 'NO',\n 'false', 'False', 'FALSE',\n 'off', 'Off', 'OFF',\n '0', 0,\n 'null',\n False\n]\n```\n\n#### How to expose all CRUD operations\n\n```python\n# dummy/views.py\nfrom timestamps.drf import viewsets # instead of: from rest_framework import viewsets\nfrom .models import Dummy\nfrom .serializers import DummySerializer\n\n\nclass DummyModelViewSet(viewsets.ModelViewSet):\n queryset = Dummy.objects.all()\n serializer_class = DummySerializer\n\n```\n\n````python\n# dummy/urls.py\nfrom timestamps.drf import routers # instead of: from rest_framework import routers\nfrom .views import DummyModelViewSet\n\n\nrouter = routers.DefaultRouter()\nrouter.register(r'dummy', DummyModelViewSet)\n\n\nurlpatterns = router.urls\n\n````\n\n#### Note A\n\nFor security reasons, by default, if you pass to the query parameter \"?permanent=true\" on a bulk destroy, \nthe view will not let you hard-delete, raising a PermissionDenied.\nIf you want to enable it on your project, just add to the project settings:\n\n```python\nTIMESTAMPS__BULK_HARD_DELETE = True\n```\n\nIt's here to prevent users of \"forgetting\" that the routes also expose bulk hard-delete by default.\nIn production, you can set this flag to True and manage hard-deleting using DRF permissions.\n\n*Hard-deleting one object at time is allowed by default.*\n\n \n\n#### NOTE B\n\nBulk actions of restoring and deleting returns no content (status code 204) by default.\nIf you want to return a response with the number of deleted/restored objects, just add this setting:\n\n```python\nTIMESTAMPS__BULK_RESPONSE_CONTENT = True\n```\n\nExample of returned response: ```{\"count\": 3 }```\n\n \n\n#### Note C\n\nIf you don't want to expose all the crud operations, be free to register as:\n\n```python\nrouter.register(r'dummy', DummyModelViewSet.as_view({'get': 'list_with_deleted'})) # e.g.\n```\n\nAnd you can always use the mixins instead and create your APIViews:\n\n````python\nfrom rest_framework import generic\nfrom timestamps.drf.mixins import ListDeletedModelMixin\nfrom .models import Dummy\nfrom .serializers import DummySerializer\n\nclass MyView(ListDeletedModelMixin, generic.GenericAPIView):\n queryset = Dummy.objects.all()\n serializer_class = DummySerializer\n \n def list_deleted(self, request, *args, **kwargs):\n # optional. your code goes here...\n\n````\n\nInternally, the ListDeletedModelMixin just calls the method ListModelMixin.list(self, request, *args, **kwargs).\nThe method of determining if the queryset must get all objects, only the deleted or all with deleted is done using AOP,\nwhich means that the method GenericAPIView.get_queryset() is advised at runtime to map the current action\nto the correct queryset the view needs.\n\nIf you don't inherit from generic.GenericAPIView, you must be aware that, for this type of scenarios,\nyou need to override the method get_queryset() to return the objects that matches your needs.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Timestamps and Soft Delete Patterns in Django Models",
"version": "1.1.4",
"project_urls": {
"Homepage": "https://github.com/xgeekshq/django-timestampable/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a5968be5ed4c068bf313f2442cf27cd09adeb94d5dc68f2682098b4fee6ccd30",
"md5": "9e3c5958d954e9dac50443bad2bd8b8f",
"sha256": "3391a672a7a1e144ed61fa7fb7722404add400f9eb0ad3287a988f19785d1762"
},
"downloads": -1,
"filename": "django-timestampable-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "9e3c5958d954e9dac50443bad2bd8b8f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 8488,
"upload_time": "2024-04-12T10:14:48",
"upload_time_iso_8601": "2024-04-12T10:14:48.809807Z",
"url": "https://files.pythonhosted.org/packages/a5/96/8be5ed4c068bf313f2442cf27cd09adeb94d5dc68f2682098b4fee6ccd30/django-timestampable-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-12 10:14:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xgeekshq",
"github_project": "django-timestampable",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Django",
"specs": [
[
">=",
"3.1"
]
]
},
{
"name": "djangorestframework",
"specs": [
[
">=",
"3.12"
]
]
},
{
"name": "aspectlib",
"specs": [
[
">=",
"1.5"
]
]
},
{
"name": "coverage",
"specs": [
[
">=",
"5.5"
]
]
},
{
"name": "django-fake-model",
"specs": [
[
">=",
"0.1.4"
]
]
},
{
"name": "django-extensions",
"specs": [
[
">=",
"3.1"
]
]
},
{
"name": "twine",
"specs": [
[
">=",
"3.4"
]
]
}
],
"lcname": "django-timestampable"
}
JSON
