Welcome to Django Stuff’s documentation!¶
Django Stuff is a collection of tools and utilities to make your development with Django simpler.
Features¶
- TimeStamp and History models to giving you information like when your record wore created/updated and History Changes
- UUID Model as primary key or not instead of sequence ID.
- Serializer model to return a dict with all data of your django instance.
- Signals model to add any task before or after you save, update or delete your model
- And many other stuff. For more information, see our documentation following the links below.
- Backend to Login using email or username
Quickstart¶
Installation¶
Requirements¶
- Python 3.x
- Django 1.11 or later
Install¶
You can get Django Stuff by using pip:
$ pip install django-stuff
If you want to install it from source, grab the git repository from Gitlab and run setup.py:
$ git clone git@github.com:rhenter/django_stuff.git
$ cd django_stuff
$ python setup.py install
Enable¶
To enable django_stuff in your project you need to add it to INSTALLED_APPS in your projects settings.py file:
INSTALLED_APPS = (
...
'django_stuff',
...
)
User Guide¶
Backends¶
EmailOrUsernameModelBackend¶
Backend to login using email or username.
Usage:
Add before the default ModelBackend
AUTHENTICATION_BACKENDS = (
'django_stuff.backends.auth.EmailOrUsernameModelBackend',
'django.contrib.auth.backends.ModelBackend'
)
Fields¶
UUIDPrimaryKeyField¶
Field to use UUID as Primary Key of your model instead of the sequential
usage:
from django_stuff.fields import UUIDPrimaryKeyField
...
class TestModel(models.Model):
id = UUIDPrimaryKeyField()
...
CharFieldDigitsOnly¶
Field to use only digits but with zero on left.
usage:
from django_stuff.fields import CharFieldDigitsOnly
...
class TestModel(models.Model):
code = CharFieldDigitsOnly(max_length=10)
...
Forms¶
Like django-localflavors the CPFField and CNPJField are validators to Brazilian CPF and CNPJ with a big difference, It removes repeated sequences and undue values.
Usage:
Your Just need to add your form class. Example using ModelForm:
CPFField¶
from django_stuff.forms import CPFField
...
class TestForm(forms.ModelForm):
class Meta:
model = YourModel
fields = [..., 'cpf']
widgets = {
'cpf': CNPJField(),
}
CNPJField¶
from django_stuff.forms import CNPJField
...
class TestForm(forms.ModelForm):
class Meta:
model = YourModel
fields = [..., 'cnpj']
widgets = {
'cnpj': CNPJField(),
}
Models¶
Generic Models¶
You just need to add to your template to get the behaviors below. Use as many models as you want.
SerializerModel¶
Model with serialize method making possible serializer your instance data returning a dict.
Usage:
from django_stuff.models import SerializerModel
...
class YourModel(SerializerModel)
...
Example of a instance from a Model using the SerializerModel
instance.serialize()
{
'id': 1,
'name': 'Test'
}
TimestampedModel¶
Model with created_at and updated_at fields to let you know when your instance wore created and updated
Usage:
from django_stuff.models import TimestampedModel
...
class YourModel(TimestampedModel)
...
UUIDModel¶
Model with UUIDPrimaryKeyField already implemented
Usage:
from django_stuff.models import UUIDModel
...
class YourModel(UUIDModel)
...
History Model¶
Model to save changes to specific fields any time the template is saved
Required fields¶
history_model
Field with the model where will save the changes
history_parent_field_name
Field used in the foreign key in the template where the changes will be stored. The default value is parent
Example¶
from django_stuff.models import HistoryModel
class HistoryTestModel(models.Model):
parent = models.ForeignKey('TestHistoryModel', related_name='history', on_delete=models.CASCADE)
name = models.CharField(max_length=128)
email = models.CharField(max_length=32, default='example@example.com')
class TestHistoryModel(HistoryModel):
history_model = HistoryTestModel
name = models.CharField(max_length=128)
email = models.CharField(max_length=32, default='example@example.com')
description = models.CharField(max_length=32,blank=True)
Note: In this example, only the name and email will only be saved in the change history.
Signals Model¶
Model that makes it possible to add any task before or after you save, update or delete your model, just adding a method in your model
Usage:
Pre-save¶
Note: This will be made before you save your model
from django_stuff.models import SignalsModel
...
class YourModel(SignalsModel)
...
def pre_save(self):
do_something()
Pos-save¶
Note: This will be made after you save your model
from django_stuff.models import SignalsModel
...
class YourModel(SignalsModel)
...
def pos_save(self):
do_something()
Pre-delete¶
Note: This will be made before you delete your model
from django_stuff.models import SignalsModel
...
class YourModel(SignalsModel)
...
def pre_delete(self):
do_something()
Pos-delete¶
Note: This will be made after you delete your model
from django_stuff.models import SignalsModel
...
class YourModel(SignalsModel)
...
def pos_delete(self):
do_something()
Utils¶
generate_md5_hashcode¶
Generates an MD5 hash code from a key word
Usage:
In[0]: from django_stuff.utils import generate_md5_hashcode
In[1]: generate_md5_hashcode('test')
Out[1]: '39df5136522809aafdf726f1a8a7d00d'
generate_random_code¶
Generates an random code with a specific length
Usage:
In[0]: from django_stuff.utils import generate_random_code
In[1]: generate_random_code(16) # with 16 length
Out[1]: 'U7Q2M1FW79WIGSW0'
In[2]: generate_random_code(10) # with 10 length
Out[2]: 'D2U2PHUSBD'
generate_datetime¶
Generates an random datetime
Usage:
In[0]: from django_stuff.utils import generate_datetime
In[1]: generate_datetime()
Out[1]: datetime.datetime(1995, 4, 6, 21, 42, 32, 955163)
In[2]: generate_datetime(min_year=2019) # with min_year
Out[2]: datetime.datetime(2019, 9, 26, 1, 17, 38, 303408)
is_equal¶
Checks if the word are formed with the same character
Usage:
In[0]: from django_stuff.utils import is_equal
In[1]: is_equal('asdfgh')
Out[1]: False
In[2]: is_equal('aaaaaaaaaa')
Out[2]: True
sanitize_digits¶
Removes all non digits characters from a string
Usage:
In[0]: from django_stuff.utils import sanitize_digits
In[1]: sanitize_digits('123.123.123-23')
Out[1]: '12312312323'
In[2]: sanitize_digits('123ASDF')
Out[2]: '123'
validate_cpf¶
Validates CPF code and return the original number
Ps: doesn’t matter if you use a masked number or not
Usage:
In[0]: from django_stuff.utils import validate_cpf
In[1]: validate_cnpj('01212312312') # Invalid
Out[1]: False
In[2]: validate_cpf('062.265.326-10') # Valid
Out[2]: '062.265.326-10'
validate_cnpj¶
Validates CNPJ code and return the original number
Ps: doesn’t matter if you use a masked number or not
Usage:
In[0]: from django_stuff.utils import validate_cnpj
In[1]: validate_cnpj('12345123/000000') # Invalid
Out[1]: False
In[2]: validate_cnpj('61.553.678/0001-96') # Valid
Out[2]: '61.553.678/0001-96'
Development¶
Development Installation¶
Requirements¶
- Python 3.x
- Django 1.11 or later
Development install¶
After forking or checking out:
$ cd django-stuff/
$ pip install -r requirements-dev.txt
$ pre-commit install
The requirements-dev are only used for development, so we can easily install/track dependencies required to run the tests using continuous integration platforms.
The official entrypoint for distritubution is the requirements.txt
which
contains the minimum requirements to execute the tests.
Generating documentation¶
$ cd docs/
$ make html
Release¶
To release a new version, a few steps are required:
- Add entry to
CHANGES.rst
and documentation - Review changes in test requirements
requirements.txt
- Test build with
make build
- Commit and push changes
- Release with
make release
Other¶
Changelog¶
0.7.2¶
- Update delete with force hard_delete
0.7.1¶
- Rename SoftDeleteManager to SoftDeleteSignalsManager
0.7.0¶
- Add restore method to Model and Manager to restore a record
0.6.2¶
- Add Missing Argument to delete on softdelete manager
0.6.1¶
- Fix tests with Signal using create method
0.6.0¶
- Add SoftDeleteSignalModel and Manager to apply Soft delete
0.5.1¶
- Change ugettext_lazy to gettext_lazy cause django 3.0 support
0.5.0¶
- Add sequential values on CPF to set as invalid on CPF validation
0.4.3¶
- Add CPF and CNPJ validation when the values wore equals
0.4.2¶
- Remove unnecessary code
0.4.1¶
- Fix tests and remove Manager.
0.4.0¶
- Add trigger options on save
0.3.0¶
- Refactor Utils
- Add CPF and CNPJ generators
0.2.1¶
- Remove Swagger render.
0.2.0¶
- Add swagger render
0.1.12¶
- Add remove special characters function
0.1.12¶
- Add random datetime generator
0.1.11¶
- BugFix: Change how to get a new version from changes
0.1.10¶
- BugFix: Get version from changes
0.1.9¶
- Finish all base documentation
0.1.8¶
- Update Readme
- Increase test coverage
0.1.7¶
- Updates functions names on utlils to be more clear
- Documentation: Add forms, fields and utils
0.1.6¶
- BugFix: Models SignalsModel and HistoryModel
- Fix tests
- Increase tests coverage
0.1.5¶
- BugFix: Models SignalsModel and HistoryModel
- Fix tests
- Increase tests coverage
0.1.5¶
- Add a centered version command
- Add Sphinx docs base
- Update dev requirements with Sphinx
0.1.4¶
- Update documentation
0.1.3¶
- Add noqa imports to models
0.1.2¶
- Add license on setup.py
0.1.1¶
- Refactor Structure
- Fix CI
- Add new requirements
0.1.0¶
- Initial release