django-cattrs-fields 0.0.1__tar.gz

django_cattrs_fields-0.0.1/.github/workflows/ci.yaml

@@ -0,0 +1,49 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - '3.12'
+          - '3.13'
+          - '3.14'
+        django-version:
+          - 'django==5.2'
+          - 'django==6.0'
+
+        include:
+          - python-version: '3.13'
+            django-version: "git+https://github.com/django/django.git@main#egg=Django"
+            experimental: true
+          - python-version: '3.14'
+            django-version: "git+https://github.com/django/django.git@main#egg=Django"
+            experimental: true
+
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with: 
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with: 
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras --group test
+
+      - name: Install django
+        run: |
+          uv pip install ${{ matrix.django-version }}
+
+      - name: Run tests
+        run: uv run pytest

django_cattrs_fields-0.0.1/.github/workflows/pre_commit.yaml

@@ -0,0 +1,9 @@
+name: pre-commit
+on: [push, pull_request]
+
+jobs:
+  prek:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: j178/prek-action@v1

django_cattrs_fields-0.0.1/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.python-version
+uv.lock
+
+**/media

django_cattrs_fields-0.0.1/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
+# Editor-based HTTP Client requests
+/httpRequests/

django_cattrs_fields-0.0.1/.idea/django-cattrs-fields.iml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="Python 3.14 virtualenv at ~/projects/django-cattrs-fields/.venv" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="PyDocumentationSettings">
+    <option name="format" value="PLAIN" />
+    <option name="myDocStringFormat" value="Plain" />
+  </component>
+  <component name="TestRunnerService">
+    <option name="PROJECT_TEST_RUNNER" value="py.test" />
+  </component>
+</module>

django_cattrs_fields-0.0.1/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+  </profile>
+</component>

django_cattrs_fields-0.0.1/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

django_cattrs_fields-0.0.1/.idea/misc.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="Python 3.14 virtualenv at ~/projects/django-cattrs-fields/.venv" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.14 virtualenv at ~/projects/django-cattrs-fields/.venv" project-jdk-type="Python SDK" />
+  <component name="TyConfiguration">
+    <option name="enabled" value="true" />
+  </component>
+</project>

django_cattrs_fields-0.0.1/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/django-cattrs-fields.iml" filepath="$PROJECT_DIR$/.idea/django-cattrs-fields.iml" />
+    </modules>
+  </component>
+</project>

django_cattrs_fields-0.0.1/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

django_cattrs_fields-0.0.1/.idea/workspace.xml

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="4c34166b-f80c-4abf-aed1-4ad30d8c216e" name="Changes" comment="">
+      <change beforePath="$PROJECT_DIR$/django_cattrs_fields/converters/register_hooks.py" beforeDir="false" afterPath="$PROJECT_DIR$/django_cattrs_fields/converters/register_hooks.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/django_cattrs_fields/fields/__init__.py" beforeDir="false" afterPath="$PROJECT_DIR$/django_cattrs_fields/fields/__init__.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/django_cattrs_fields/hooks/__init__.py" beforeDir="false" afterPath="$PROJECT_DIR$/django_cattrs_fields/hooks/__init__.py" afterDir="false" />
+    </list>
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="Git.Settings">
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="ProjectColorInfo">{
+  &quot;associatedIndex&quot;: 6
+}</component>
+  <component name="ProjectId" id="38z4h3JEueKZmfomoDq5O48s8JO" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.git.unshallow": "true",
+    "RunOnceActivity.typescript.service.memoryLimit.init": "true",
+    "ai.playground.ignore.import.keys.banner.in.settings": "true",
+    "git-widget-placeholder": "time",
+    "node.js.detected.package.eslint": "true",
+    "node.js.detected.package.tslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "node.js.selected.package.tslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm",
+    "settings.editor.selected.configurable": "com.intellij.python.ty.TyConfigurable",
+    "vue.rearranger.settings.migration": "true"
+  }
+}]]></component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-js-predefined-d6986cc7102b-9b0f141eb926-JavaScript-PY-253.30387.127" />
+        <option value="bundled-python-sdk-3944b0c99280-6d6dccd035ac-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-253.30387.127" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="4c34166b-f80c-4abf-aed1-4ad30d8c216e" name="Changes" comment="" />
+      <created>1769789183472</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1769789183472</updated>
+      <workItem from="1769789185755" duration="2847000" />
+      <workItem from="1769792956034" duration="1857000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

django_cattrs_fields-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+repos:
+  - repo: https://github.com/adamchainz/django-upgrade
+    rev: 1.29.1
+    hooks:
+      - id: django-upgrade
+        args: [--target-version, "4.2"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.10
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell # See pyproject.toml for args
+        additional_dependencies:
+          - tomli
+
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.24.1
+    hooks:
+      - id: validate-pyproject
+
+  -   repo: https://github.com/asottile/pyupgrade
+      rev: v3.21.2
+      hooks:
+      -   id: pyupgrade

django_cattrs_fields-0.0.1/LICENSE

@@ -0,0 +1,27 @@
+Copyright <2026> Amirrza Sohrabi far and individual contributors.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright 
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used
+  to endorse or promote products derived from this software without 
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

django_cattrs_fields-0.0.1/PKG-INFO

@@ -0,0 +1,404 @@
+Metadata-Version: 2.4
+Name: django-cattrs-fields
+Version: 0.0.1
+Summary: django data type support for cattrs
+Author-email: amirreza <amir.rsf1380@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: cattrs>=25.3.0
+Requires-Dist: django>=6.0
+Provides-Extra: bson
+Requires-Dist: pymongo>=4.4.0; extra == 'bson'
+Provides-Extra: cbor2
+Requires-Dist: cbor2>=5.4.6; extra == 'cbor2'
+Provides-Extra: msgpack
+Requires-Dist: msgpack>=1.0.5; extra == 'msgpack'
+Provides-Extra: msgspec
+Requires-Dist: msgspec>=0.19.0; (implementation_name == 'cpython') and extra == 'msgspec'
+Provides-Extra: orjson
+Requires-Dist: orjson>=3.11.3; (implementation_name == 'cpython') and extra == 'orjson'
+Provides-Extra: pyyaml
+Requires-Dist: pyyaml>=6.0; extra == 'pyyaml'
+Provides-Extra: tomlkit
+Requires-Dist: tomlkit>=0.11.8; extra == 'tomlkit'
+Provides-Extra: ujson
+Requires-Dist: ujson>=5.10.0; extra == 'ujson'
+Description-Content-Type: text/markdown
+
+# django-cattrs-fields
+
+**Note**: this is a very experimental project, I'm mostly navigating and discovering how this could work,
+as much as any help and feedback is appreciated, please do not use in a production environment.
+
+Brings [cattrs](https://github.com/python-attrs/cattrs) support to the django world.
+
+this project is the first step of many, it is intended to be minimal, only adding data type support.
+
+### current data types
+* BooleanField
+* CharField
+* DecimalField
+* EmailField
+* SlugField
+* URLField
+* UUIDField
+* IntegerField
+* FloatField
+* DateField
+* DateTimeField
+* FileField
+* TimeField
+* EmptyField
+
+## installing
+this is not packaged to PyPI yet, for using you need to clone the repository first.
+
+then install the package by running `uv sync` or `uv sync --extra <group name>` where group name is one of optional-dependencies listed in pyproject.toml.
+
+if you want a one-shot install use `uv sync --all-extras`
+
+
+
+## basic usage:
+data model classes are `attrs` classes, so anything you find in [attrs](https://www.attrs.org/en/stable/index.html) docs also applies here.
+we also follow cattrs, so anything in their [docs](https://catt.rs/en/stable/index.html) also applies
+
+```py
+import uuid
+from datetime import date, datetime, time
+from decimal import Decimal
+
+from attrs import define
+
+from django.core.files.uploadedfile import SimpleUploadedFile
+
+from django-cattrs-fields.converters import converter
+from django_cattrs_fields.fields import (
+  BooleanField, 
+  CharField, 
+  DecimalField,
+  EmailField, 
+  SlugField, 
+  URLField, 
+  UUIDField, 
+  IntegerField, 
+  FloatField, 
+  DateField,
+  DateTimeField,
+  TimeField,
+)
+from django_cattrs_fields.fields.files import FileField
+
+@define
+class Human:
+    id: UUIDField
+    username: CharField
+    email: EmailField
+    slug: SlugField
+    website: URLField
+    age: IntegerField
+    salary: FloatField
+    birth_date: DateField
+    signup_date: DateTimeField
+    picture: FileField
+    accurate_salary: DecimalField
+    lunch_time: TimeField
+
+
+human = {
+    "id": uuid.uuid4(),
+    "username": "bob",
+    "email": "bob@email.com",
+    "slug": "bo-b",
+    "website": "https://bob.com",
+    "age": 25,
+    "salary": 1000.43,
+    "birth_date": date(year=2000, month=7, day=3),
+    "signup_date": datetime.now(),
+    "picture": SimpleUploadedFile(name="test_image.jpeg", content=b"wheeee", content_type="image/jpeg"),
+    "accurate_salary": Decimal("1000.43"),
+    "lunch_time": time(14, 30, 0),
+}
+
+structure = converter.structure(human, Human)  # runs structure hooks and validators, then creates an instance of `Human`
+normal_data = converter.unstructure(structure)  # runs unstructure hooks, then makes a dict similar to `human` (or what you tell it to), no validators run.
+```
+
+### Comparison
+in comparison with how django forms and DRF serializers work, see the examples below
+
+in django forms we do:
+```py
+form = MyForm(data)
+form.is_valid()
+clean_data = form.cleaned_data
+```
+
+in drf we do:
+```py
+serializer = MySerializer(data)
+serializer.is_valid()
+clean_data = serializer.validated_data
+
+# to serialize data
+content = JSONRenderer().render(serializer.data)
+```
+
+the cattrs equivalent of forms is like this:
+```py
+try:
+    form = converter.structure(data, MyForm)  # where `MyForm` is a cattrs supported class (usually and attrs class)
+except* ValueError:  # notice the `*`, this is an exception group (unless you configure cattrs otherwise)
+    pass
+clean_data = converter.unstructure(form)
+```
+
+or if working with json (or other formats)
+```py
+try:
+    form = converter.loads(data, MyForm)  # take a json data and load it to python
+except* ValueError:  # notice the `*`, this is an exception group (unless you configure cattrs otherwise)
+    pass
+clean_data = converter.unstructure(form)
+
+# to serialize data
+data = converter.structure(clean_data, MyForm)  # to dump data, structure it first
+content = converter.dumps(data)
+```
+
+structuring and loading also validates the data, so no need for the extra step.
+
+note that `converter.structure` raises `ValueError` as an exception group.
+
+
+### serializers
+the basic `converter` you saw in basic usage section can only structure and unstructure, which is powerful, but we can do more.
+
+`cattrs` comes with a set of [preconfigured converters](https://catt.rs/en/stable/preconf.html).
+
+we ship our own version of these converters, which extends on top of cattrs' version, though we call them `serializer` to avoid some confusion.
+these are available in `django_cattrs_fields.converters` directory:
+
+* django_cattrs_fields.converters.bson
+* django_cattrs_fields.converters.cbor2
+* django_cattrs_fields.converters.json
+* django_cattrs_fields.converters.msgpack
+* django_cattrs_fields.converters.msgspec
+* django_cattrs_fields.converters.orjson
+* django_cattrs_fields.converters.pyyaml
+* django_cattrs_fields.converters.tomlkit
+* django_cattrs_fields.converters.ujson
+
+just import `serializer` from each of these modules:
+
+```py
+from django_cattrs_fields.converters import converter
+from django_cattrs_fields.converters.json import serializer
+
+
+structure = converter.structure(human, Human)
+dump: str | bytes = serializer.dumps(structure)  # takes an structured data, dumps a json string
+load: Human = serializers.loads(dump, Human)  # takes a dumped data, and loads that as a structured data
+data = converter.unstructure(load)  # a dictionary of the data, ready to be used.
+```
+
+it is important to note, while `serializer` objects also have `structure` and `unstructure` methods, they are considered internal API, 
+since they are configured to feed encoding and decoding functionalities, 
+they don't necessarily behave the way you would expect them to.
+
+so in most scenarios you should import a `converter` and a `serializer` to handle their specific task, unless you are fully aware how your `serializer` behaves and can handle it yourself.
+
+the only exception (currently) is the msgspec serializer, which doesn't implement any additional logic and works like a normal `converter`, 
+tho if the need arises, this could change.
+
+### work with django views
+you can use the data models you made with this package instead of django forms or serializers
+
+```py
+from django_cattrs_fields.converters import converter
+from django_cattrs_fields.converters.json import serializer
+
+
+@define
+class Human:
+    id: UUIDField
+    username: CharField
+    email: EmailField
+    slug: SlugField
+    website: URLField
+    age: IntegerField
+    salary: FloatField
+    birth_date: DateField
+    signup_date: DateTimeField
+    accurate_salary: DecimalField
+    lunch_time: TimeField
+
+
+def get_data(request):
+    if request.method == "POST":
+        if request.content_type in {"application/x-www-form-urlencoded", "multipart/form-data"}:
+            structured_data = converter.structure({**request.POST.dict(), **request.FILES.dict()}, Human)  # handle html forms, and multipart data
+        else:
+            structured_data = serializer.loads(request.body, Human)  # handle json (or anything else)
+
+        data: dict[str, Any] = converter.unstructure(structured_data)  # a dictionary of all the POST data (excluding data not covered by Human)
+
+        return HttpResponse("done")
+```
+and just like that you have one view that handles html forms and json in one place
+
+note that if `POST` data contains anything not in `Human`, it won't show up in the output data (such as csrf token, in this case)
+
+also note that when working with APIs, depending on your client you might need to add `csrf_exempt` on you view.
+
+
+### saving to database
+one you unstructure your data, you have a dictionary of cleaned data.
+then you can just pass that to your model and create your data
+
+```py
+data: dict[str, Any] = converter.unstructure(structured_data)
+
+# either
+obj = HumanModel(**dict)
+obj.save()
+
+# or
+HumanModel.objects.create(**dict)
+```
+
+
+### nullable fields
+by default all fields are required and passing a `None` value will raise an error
+to make a field nullable, you can use a union 
+
+```py
+@define
+class Product:
+    name: CharField  # required
+    discount: FloatField | None  # optional
+```
+
+
+### default values
+to add a default value, the simplest way is to just add it via assignment
+
+```py
+@define
+class Product:
+    name: CharField  # required
+    discount: FloatField = 5.1
+```
+for more advanced use check [default docs](https://www.attrs.org/en/stable/examples.html#defaults)
+
+### field params
+some fields like `DecimalField` can take some parameter about their data using `typing.Annotated`.
+
+```py
+from typing import Annotated
+
+from attrs import define
+
+from django_cattrs_fields.fields import DecimalField, CharField, Params
+
+@define
+class Product:
+  name: CharField
+  discount: Annotated[DecimalField, Params(decimal_max_digits=5, decimal_places=3)]
+```
+
+the use case of params differs depending on the field, in the case of Decimal field, `decimal_max_digits` as equivalent to django's DecimalField's `max_digits` parameter
+and `decimal_places` is equivalent to `decimal_places` parameter, and are used when structuring the data to validate the decimal value.
+
+like django, DecimalField's params are optional, some fields may require some params in the future.
+
+
+### EmptyField
+`EmptyField` is useful when supporting PATCH requests.
+
+if a field doesn't receive any data and has `Empty` as its value, it will be omitted when unstructuring.
+
+```py
+from django_cattrs_fields.fields import CharField, EmptyField, Empty
+
+@define
+class Human:
+  name: CharField 
+  age: IntegerField | EmptyField = Empty  # default to Empty, or provide Empty manually
+
+
+struct = converter.structure({"name": "bob"})
+# Human(name='bob', age=Empty)
+unstruct = converter.unstructure(struct)
+# {'name': 'bob'}
+```
+
+as you can see, since age is `Empty`, it won't be included in the resulting dictionary.
+
+**Warning**: at the moment, `EmptyField` is only supported in unions that have only one other type, tho None is also supported, so:
+
+* `CharField | EmptyField` works.
+* `CharField | EmptyField | None` works.
+* `CharField | IntegerField | EmptyField` doesn't work.
+
+if complex types are required, register your custom hooks until we can figure out how to properly support this.
+for inspiration, you can check `django_cattrs_fields.hooks.empty_hooks` to see how other hooks are made.
+
+### validation
+by default this package runs some validation when you are structuring your data
+but to add any custom validators you can use attrs [built-in](https://www.attrs.org/en/stable/examples.html#validators) validation mechanism.
+
+note that the validations we run are baked in structure hooks, so they will run in any situation.
+these are validations that django also runs every time you use it's data fields.
+if you need to turn this off, just create a [new converter](https://catt.rs/en/stable/basics.html#converters-and-hooks)
+
+### File Handling
+this package comes with FileField you can use to work with files.
+when an uploaded file is passed to this field (e.g: user POSTs some file), it goes through validation,
+then an instance of django's `UploadedFile` is returned (usually a subclass of UploadedFile is used like `InMemoryUploadedFile`).
+
+you can save this using the ORM or any other way you do with django.
+
+when serving a File (e.g: user sends a GET request), an instance of django's `FieldFile` should be passed (django ORM does this automatically)
+in this case our hooks will return the url of the file.
+
+note that this behavior is different in django and DRF
+django returns the whole `FieldFile` object (could be useful with templates), DRF is configurable, it either returns the url or the file name.
+
+if you require a different behaviour, you can change this by hooking your logic and set `DCF_FILE_HOOKS` to False in your settings file, 
+this will disable all file related hooks.
+
+
+
+## contribution
+I appreciate any help with this project, but please follow Django's Code of Conduct
+if you have ideas or have found a bug please open an [issue on github](https://github.com/amirreza8002/django-cattrs-fields/issues/new)
+
+to help with development follow these steps:
+1. fork the repository from [github](https://github.com/amirreza8002/django-cattrs-fields).
+2. clone the project from your fork.
+3. install the package with one of the following commands:
+  * `uv sync --group dev`
+  * `uv sync --group dev --group ipython`
+  * `uv sync --group dev --group prek`
+  * `uv sync --group dev --group test`
+you can combine them together or just use `uv sync --all-groups` to one-shot.
+4. run `prek install` or `pre-commit install` depending on your choice.
+
+if you are contributing new code, please make sure to add some tests for it.