# PyDReF - Serializers
## Description
This library contains a set of tools to help you create simple serializers for Django models. It was inspired by the [Django REST Framework](https://www.django-rest-framework.org/) and [Pydantic](https://pydantic.dev/) projects.
## Motivation
The main motivation for creating this library was to have a simple and easy to use tool to serialize Django models. The library is designed to be used in projects where you need to serialize Django models, but you don't want to use the Django REST Framework.
DRF is a great tool, but it is not always necessary to use it. For example, if you need to create a simple API for a small project, you can use this library instead of the DRFfor the serialization of your models.
Also, though DRF is a great tool, I've never enjoy the heavy responsibility added to its Serializers. Pydantic keeps this simplicity, where the serializers (Pydantic models) are just a simple class that you can use to serialize your data.
## Installation
You can install this library using pip:
```bash
pip install pydref-serializers
```
## Usage
### Creating a serializer class
For creating a serializer for a Django model, you can use the `ModelSerializerBuilder` class. This class will create a Pydantic model based on the Django model that you pass to it.
```python
from pydref_serializers import ModelSerializerBuilder
from myapp.models import MyModel
MyModelSerializer = ModelSerializerBuilder.from_model_class(MyModel)
```
The builder will return a class created based on the specified model. If you want to set the fields to be added to the serializer, you can specify them during the creation of the serializer, using the kwargs `include_fields` or `exclude_fields`:
```python
from pydref_serializers import ModelSerializerBuilder
from myapp.models import MyModel
MyModelSerializer = ModelSerializerBuilder.from_model_class(
MyModel,
include_fields=['field1', 'field2', 'field3'],
# exclude_fields=['field1', 'field2', 'field3'],
)
```
The `ModelSerializerBuilder` also has a few kwargs for configuration how the builder get the fields from the Django model, and also how it maps the fields to the Pydantic model fields.
```python
from pydref_serializers import ModelSerializerBuilder
from myapp.models import MyModel
_FieldMapper = Callable[[DjangoField], tuple[type, Any]]
_FieldGetter = Callable[[type[DjangoModel], Collection[str] | None, Collection[str] | None], dict[type, Any]]
MyModelSerializer = ModelSerializerBuilder.from_model_class(
MyModel,
..., # include_fields or exclude_fields
fields_getter:_FieldGetter = ...,
field_mapper:_FieldMapper = ...,
)
```
### Using the serializer
For using the serializer, you can use it as a normal Pydantic model, passing the fields to be serialized as kwargs to the constructor:
```python
from myapp.serializers import MyModelSerializer
serializer = MyModelSerializer(
field1='value1',
field2='value2',
field3='value3',
)
```
The serializer will validate the fields based on the validators created during the Django Fields to Pydantic annotations mapping.
You can also use the serializer to serialize a Django model instance:
```python
from myapp.serializers import MyModelSerializer
from myapp.models import MyModel
my_model_instance = MyModel.objects.get(pk=1)
serializer = MyModelSerializer.from_model(my_model_instance)
```
The class method `from_model` will create a serializer instance based on the Django model instance passed to it. It will convert the model to dict using the django utility `model_to_dict` located at `django.forms.models`, and then it will pass the dict to the serializer constructor. You can change this behavior passing a custom function to the `model_to_dict` kwarg of the `from_model` method:
```python
from myapp.serializers import MyModelSerializer
from myapp.models import MyModel
my_model_instance = MyModel.objects.get(pk=1)
serializer = MyModelSerializer.from_model(
my_model_instance,
model_to_dict=lambda model_instance: model_instance.to_dict(),
)
```
### Field mapping
Fields are transformed based on the following rules:
* Field types are mapped from Django Field to Pydantic annotations based on the dictionary below:
```python
DJANGO_FIELD_MAP = {
# Numerical related fields
"AutoField": int,
"BigAutoField": int,
"IntegerField": int,
"SmallIntegerField": int,
"BigIntegerField": int,
"PositiveIntegerField": PositiveInt,
"PositiveSmallIntegerField": PositiveInt,
"FloatField": float,
"DecimalField": Decimal,
# String related fields
"CharField": str,
"TextField": str,
"SlugField": str,
"EmailField": EmailStr,
"URLField": AnyUrl,
"FilePathField": FilePath,
"FileField": FilePath,
"ImageField": FilePath,
# Other built-in fields
"BooleanField": bool,
"BinaryField": bytes,
"DateField": date,
"DateTimeField": datetime,
"DurationField": timedelta,
"TimeField": time,
"UUIDField": UUID,
"GenericIPAddressField": IPvAnyAddress,
"JSONField": Json,
}
```
* If Django field `max_length` is set, the Pydantic field will also be set with `max_length` equal to the Django field `max_length`.
* If Django field has `blank=True`, the Pydantic field will have `min_length=0`.
* If Django field has `blank=False`, the Pydantic field will have `min_length=1`.
* If Django field has `null=True`, the Pydantic field will have `field_type | None`.
* If Django field has `default` value set, the Pydantic field will have `default` set to the Django field `default`. In case this value is a callable, it will be used for the pydantic field `default_factory`.
* If Django field has `choices` set, the Pydantic field will sue as a type an created Enum based on the specified `choices` set to the Django field. If the field is int based, the Enum will be an IntEnum. If the field is str based, the Enum will be StrEnum, otherwise it will be an Enum.
## TODO
* Add support for lower Python versions (3.6+).
* Add support for Django model relations.
* Add support for Django model inheritance.
* Add support for Django model fields with custom validators.
* Add support to customize the serializer fields.
* Add support to serialize model properties.
Raw data
{
"_id": null,
"home_page": "https://github.com/acuriel/pydref-serializers",
"name": "pydref-serializers",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "",
"keywords": "django,pydantic,serialization,deserialization,pydref",
"author": "Aryan Curiel",
"author_email": "aryan.curiel@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/38/db/0428bb102d5407993c1911fcf6ba2e16f326a558f39d8b5f7535ac827064/pydref_serializers-0.2.4.tar.gz",
"platform": null,
"description": "# PyDReF - Serializers\n\n## Description\nThis library contains a set of tools to help you create simple serializers for Django models. It was inspired by the [Django REST Framework](https://www.django-rest-framework.org/) and [Pydantic](https://pydantic.dev/) projects.\n\n## Motivation\nThe main motivation for creating this library was to have a simple and easy to use tool to serialize Django models. The library is designed to be used in projects where you need to serialize Django models, but you don't want to use the Django REST Framework.\n\nDRF is a great tool, but it is not always necessary to use it. For example, if you need to create a simple API for a small project, you can use this library instead of the DRFfor the serialization of your models.\n\nAlso, though DRF is a great tool, I've never enjoy the heavy responsibility added to its Serializers. Pydantic keeps this simplicity, where the serializers (Pydantic models) are just a simple class that you can use to serialize your data.\n\n## Installation\nYou can install this library using pip:\n```bash\npip install pydref-serializers\n```\n\n## Usage\n\n### Creating a serializer class\nFor creating a serializer for a Django model, you can use the `ModelSerializerBuilder` class. This class will create a Pydantic model based on the Django model that you pass to it.\n\n```python\nfrom pydref_serializers import ModelSerializerBuilder\nfrom myapp.models import MyModel\n\nMyModelSerializer = ModelSerializerBuilder.from_model_class(MyModel)\n```\n\nThe builder will return a class created based on the specified model. If you want to set the fields to be added to the serializer, you can specify them during the creation of the serializer, using the kwargs `include_fields` or `exclude_fields`:\n\n```python\nfrom pydref_serializers import ModelSerializerBuilder\nfrom myapp.models import MyModel\n\nMyModelSerializer = ModelSerializerBuilder.from_model_class(\n MyModel,\n include_fields=['field1', 'field2', 'field3'],\n # exclude_fields=['field1', 'field2', 'field3'],\n)\n```\n\nThe `ModelSerializerBuilder` also has a few kwargs for configuration how the builder get the fields from the Django model, and also how it maps the fields to the Pydantic model fields.\n\n```python\nfrom pydref_serializers import ModelSerializerBuilder\nfrom myapp.models import MyModel\n\n\n_FieldMapper = Callable[[DjangoField], tuple[type, Any]]\n_FieldGetter = Callable[[type[DjangoModel], Collection[str] | None, Collection[str] | None], dict[type, Any]]\n\nMyModelSerializer = ModelSerializerBuilder.from_model_class(\n MyModel,\n ..., # include_fields or exclude_fields\n fields_getter:_FieldGetter = ...,\n field_mapper:_FieldMapper = ...,\n)\n```\n\n### Using the serializer\n\nFor using the serializer, you can use it as a normal Pydantic model, passing the fields to be serialized as kwargs to the constructor:\n\n```python\nfrom myapp.serializers import MyModelSerializer\n\nserializer = MyModelSerializer(\n field1='value1',\n field2='value2',\n field3='value3',\n)\n```\n\nThe serializer will validate the fields based on the validators created during the Django Fields to Pydantic annotations mapping.\n\nYou can also use the serializer to serialize a Django model instance:\n\n```python\nfrom myapp.serializers import MyModelSerializer\nfrom myapp.models import MyModel\n\nmy_model_instance = MyModel.objects.get(pk=1)\nserializer = MyModelSerializer.from_model(my_model_instance)\n```\n\nThe class method `from_model` will create a serializer instance based on the Django model instance passed to it. It will convert the model to dict using the django utility `model_to_dict` located at `django.forms.models`, and then it will pass the dict to the serializer constructor. You can change this behavior passing a custom function to the `model_to_dict` kwarg of the `from_model` method:\n\n```python\nfrom myapp.serializers import MyModelSerializer\nfrom myapp.models import MyModel\n\nmy_model_instance = MyModel.objects.get(pk=1)\nserializer = MyModelSerializer.from_model(\n my_model_instance,\n model_to_dict=lambda model_instance: model_instance.to_dict(),\n)\n```\n\n### Field mapping\n\nFields are transformed based on the following rules:\n\n* Field types are mapped from Django Field to Pydantic annotations based on the dictionary below:\n\n```python\nDJANGO_FIELD_MAP = {\n # Numerical related fields\n \"AutoField\": int,\n \"BigAutoField\": int,\n \"IntegerField\": int,\n \"SmallIntegerField\": int,\n \"BigIntegerField\": int,\n \"PositiveIntegerField\": PositiveInt,\n \"PositiveSmallIntegerField\": PositiveInt,\n \"FloatField\": float,\n \"DecimalField\": Decimal,\n # String related fields\n \"CharField\": str,\n \"TextField\": str,\n \"SlugField\": str,\n \"EmailField\": EmailStr,\n \"URLField\": AnyUrl,\n \"FilePathField\": FilePath,\n \"FileField\": FilePath,\n \"ImageField\": FilePath,\n # Other built-in fields\n \"BooleanField\": bool,\n \"BinaryField\": bytes,\n \"DateField\": date,\n \"DateTimeField\": datetime,\n \"DurationField\": timedelta,\n \"TimeField\": time,\n \"UUIDField\": UUID,\n \"GenericIPAddressField\": IPvAnyAddress,\n \"JSONField\": Json,\n}\n```\n\n* If Django field `max_length` is set, the Pydantic field will also be set with `max_length` equal to the Django field `max_length`.\n* If Django field has `blank=True`, the Pydantic field will have `min_length=0`.\n* If Django field has `blank=False`, the Pydantic field will have `min_length=1`.\n* If Django field has `null=True`, the Pydantic field will have `field_type | None`.\n* If Django field has `default` value set, the Pydantic field will have `default` set to the Django field `default`. In case this value is a callable, it will be used for the pydantic field `default_factory`.\n* If Django field has `choices` set, the Pydantic field will sue as a type an created Enum based on the specified `choices` set to the Django field. If the field is int based, the Enum will be an IntEnum. If the field is str based, the Enum will be StrEnum, otherwise it will be an Enum.\n\n## TODO\n* Add support for lower Python versions (3.6+).\n* Add support for Django model relations.\n* Add support for Django model inheritance.\n* Add support for Django model fields with custom validators.\n* Add support to customize the serializer fields.\n* Add support to serialize model properties.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A clean and simple serialization tool for Django models using Pydantic 2.",
"version": "0.2.4",
"project_urls": {
"Homepage": "https://github.com/acuriel/pydref-serializers",
"Repository": "https://github.com/acuriel/pydref-serializers"
},
"split_keywords": [
"django",
"pydantic",
"serialization",
"deserialization",
"pydref"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "28b167febc5afa744c4cfa6d405651f7110d11df68979cead014e4f9ab60fc2f",
"md5": "9592f882890b38ab0a6e7dc0903a1103",
"sha256": "5857803f634358324415c24dff961080175e8592faeb518495d7ab65faad6856"
},
"downloads": -1,
"filename": "pydref_serializers-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9592f882890b38ab0a6e7dc0903a1103",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 8701,
"upload_time": "2023-09-01T14:42:02",
"upload_time_iso_8601": "2023-09-01T14:42:02.149648Z",
"url": "https://files.pythonhosted.org/packages/28/b1/67febc5afa744c4cfa6d405651f7110d11df68979cead014e4f9ab60fc2f/pydref_serializers-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "38db0428bb102d5407993c1911fcf6ba2e16f326a558f39d8b5f7535ac827064",
"md5": "904f6e2820eefdee66f2889bc5b293c4",
"sha256": "c739cc216c04820b6be3a4661cb33c9173f86d24392564026cb2abc3e0647d25"
},
"downloads": -1,
"filename": "pydref_serializers-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "904f6e2820eefdee66f2889bc5b293c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 8234,
"upload_time": "2023-09-01T14:42:03",
"upload_time_iso_8601": "2023-09-01T14:42:03.401300Z",
"url": "https://files.pythonhosted.org/packages/38/db/0428bb102d5407993c1911fcf6ba2e16f326a558f39d8b5f7535ac827064/pydref_serializers-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-01 14:42:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "acuriel",
"github_project": "pydref-serializers",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "pydref-serializers"
}
JSON
