Docs 😇

Author: Sibyx

README.md

@@ -3,56 +3,97 @@
 [![PyPI version](https://badge.fury.io/py/django-api-forms.svg)](https://badge.fury.io/py/django-api-forms)
 [![codecov](https://codecov.io/gh/Sibyx/django_api_forms/branch/master/graph/badge.svg)](https://codecov.io/gh/Sibyx/django_api_forms)
 
-[Django Forms](https://docs.djangoproject.com/en/4.1/topics/forms/) approach in the processing of a RESTful HTTP
-request payload (especially for content type like [JSON](https://www.json.org/) or [MessagePack](https://msgpack.org/))
-without HTML front-end.
+**Django API Forms** is a Python library that brings the [Django Forms](https://docs.djangoproject.com/en/4.1/topics/forms/) approach to processing RESTful HTTP request payloads (such as [JSON](https://www.json.org/) or [MessagePack](https://msgpack.org/)) without the HTML front-end overhead.
+
+## Overview
+
+Django API Forms provides a declarative way to:
+
+- Define request validation schemas using a familiar Django-like syntax
+- Parse and validate incoming API requests
+- Handle nested data structures and complex validation rules
+- Convert validated data into Python objects
+- Populate Django models or other objects with validated data
+
+[**📚 Read the full documentation**](https://sibyx.github.io/django_api_forms/)
+
+## Key Features
+
+- **Declarative Form Definition**: Define your API request schemas using a familiar Django Forms-like syntax
+- **Request Validation**: Validate incoming requests against your defined schemas
+- **Nested Data Structures**: Handle complex nested JSON objects and arrays
+- **Custom Field Types**: Specialized fields for common API use cases (BooleanField, EnumField, etc.)
+- **File Uploads**: Support for BASE64-encoded file and image uploads
+- **Object Population**: Easily populate Django models or other objects with validated data
+- **Customizable Validation**: Define custom validation rules at the field or form level
+- **Multiple Content Types**: Support for JSON, MessagePack, and extensible to other formats
 
 ## Motivation
 
-The main idea was to create a simple and declarative way to specify the format of expecting requests with the ability
+The main idea was to create a simple and declarative way to specify the format of expected requests with the ability
 to validate them. Firstly, I tried to use [Django Forms](https://docs.djangoproject.com/en/4.1/topics/forms/) to
-validate my API requests (I use pure Django in my APIs). I have encountered a problem with nesting my requests without
+validate my API requests (I use pure Django in my APIs). I encountered a problem with nesting my requests without
 a huge boilerplate. Also, the whole HTML thing was pretty useless in my RESTful APIs.
 
 I wanted to:
 
-- define my requests as object (`Form`),
-- pass the request with optional arguments to my defined object (`form = Form.create_from_request(request, param=param)`),
-- validate my request `form.is_valid()`,
-- extract data `form.clean_data` property.
+- Define my requests as objects (`Form`)
+- Pass the request to my defined object (`form = Form.create_from_request(request, param=param))`)
+  - With the ability to pass any extra optional arguments
+- Validate my request (`form.is_valid()`)
+- Extract data (`form.cleaned_data` property)
 
 I wanted to keep:
 
-- friendly declarative Django syntax,
-([DeclarativeFieldsMetaclass](https://github.com/django/django/blob/master/django/forms/forms.py#L25) is beautiful),
-- [Validators](https://docs.djangoproject.com/en/4.1/ref/validators/),
-- [ValidationError](https://docs.djangoproject.com/en/4.1/ref/exceptions/#validationerror),
-- [Form fields](https://docs.djangoproject.com/en/4.1/ref/forms/fields/) (In the end, I had to "replace" some of them).
+- Friendly declarative Django syntax
+  ([DeclarativeFieldsMetaclass](https://github.com/django/django/blob/master/django/forms/forms.py#L22) is beautiful)
+- [Validators](https://docs.djangoproject.com/en/4.1/ref/validators/)
+- [ValidationError](https://docs.djangoproject.com/en/4.1/ref/exceptions/#validationerror)
+- [Form fields](https://docs.djangoproject.com/en/4.1/ref/forms/fields/) (In the end, I had to "replace" some of them)
 
-So I have decided to create a simple Python package to cover all my expectations.
+So I created this Python package to cover all these expectations.
 
 ## Installation
 
-```shell script
+```shell
 # Using pip
 pip install django-api-forms
 
 # Using poetry
 poetry add django-api-forms
 
-# Local installation
+# Local installation from source
 python -m pip install .
 ```
 
-Optional:
-```shell script
-# msgpack support (for requests with Content-Type: application/x-msgpack)
-poetry add msgpack
+### Requirements
+
+- Python 3.9+
+- Django 2.0+
 
-# ImageField support
-poetry add Pillow
+### Optional Dependencies
+
+Django API Forms supports additional functionality through optional dependencies:
+
+```shell
+# MessagePack support (for Content-Type: application/x-msgpack)
+pip install django-api-forms[msgpack]
+
+# File and Image Fields support
+pip install django-api-forms[Pillow]
+
+# RRule Field support
+pip install django-api-forms[rrule]
+
+# GeoJSON Field support
+pip install django-api-forms[gdal]
+
+# Install multiple extras at once
+pip install django-api-forms[Pillow,msgpack]
 ```
 
+For more detailed installation instructions, see the [Installation Guide](https://sibyx.github.io/django_api_forms/install/).
+
 Install application in your Django project by adding `django_api_forms` to yours `INSTALLED_APPS`:
 
 ```python
@@ -88,146 +129,98 @@ DJANGO_API_FORMS_PARSERS = {
 }
 ```
 
-## Example
+## Quick Example
 
-**Simple nested JSON request**
-
-```json
-{
-  "title": "Unknown Pleasures",
-  "type": "vinyl",
-  "artist": {
-    "_name": "Joy Division",
-    "genres": [
-      "rock",
-      "punk"
-    ],
-    "members": 4
-  },
-  "year": 1979,
-  "songs": [
-    {
-      "title": "Disorder",
-      "duration": "3:29"
-    },
-    {
-      "title": "Day of the Lords",
-      "duration": "4:48",
-      "metadata": {
-        "_section": {
-          "type": "ID3v2",
-          "offset": 0,
-          "byteLength": 2048
-        },
-        "header": {
-          "majorVersion": 3,
-          "minorRevision": 0,
-          "size": 2038
-        }
-      }
-    }
-  ],
-  "metadata": {
-    "created_at": "2019-10-21T18:57:03+0100",
-    "updated_at": "2019-10-21T18:57:03+0100"
-  }
-}
-```
-
-**Django API Forms equivalent + validation**
+Here's a simple example demonstrating how to use Django API Forms:
 
 ```python
-from enum import Enum
-
-from django.core.exceptions import ValidationError
 from django.forms import fields
+from django.http import JsonResponse
+from django_api_forms import Form, FormField, FieldList
 
-from django_api_forms import FieldList, FormField, FormFieldList, DictionaryField, EnumField, AnyField, Form
-
-
-class AlbumType(Enum):
-    CD = 'cd'
-    VINYL = 'vinyl'
-
-
+# Define a nested form
 class ArtistForm(Form):
-    class Meta:
-        mapping = {
-            '_name': 'name'
-        }
-
     name = fields.CharField(required=True, max_length=100)
     genres = FieldList(field=fields.CharField(max_length=30))
     members = fields.IntegerField()
 
-
-class SongForm(Form):
-    title = fields.CharField(required=True, max_length=100)
-    duration = fields.DurationField(required=False)
-    metadata = AnyField(required=False)
-
-
+# Define the main form
 class AlbumForm(Form):
     title = fields.CharField(max_length=100)
     year = fields.IntegerField()
     artist = FormField(form=ArtistForm)
-    songs = FormFieldList(form=SongForm)
-    type = EnumField(enum=AlbumType, required=True)
-    metadata = DictionaryField(value_field=fields.DateTimeField())
-
-    def clean_year(self):
-        if self.cleaned_data['year'] == 1992:
-            raise ValidationError("Year 1992 is forbidden!", 'forbidden-value')
-        if 'param' not in self.extras:
-            self.add_error(
-                ('param', ),
-                ValidationError("You can use extra optional arguments in form validation!", code='param-where')
-            )
-        return self.cleaned_data['year']
-
-    def clean(self):
-        if (self.cleaned_data['year'] == 1998) and (self.cleaned_data['artist']['name'] == "Nirvana"):
-            raise ValidationError("Sounds like a bullshit", code='time-traveling')
-        if not self._request.user.is_authenticated():
-            raise ValidationError("You can use request in form validation!")
-        if 'param' not in self.extras:
-            raise ValidationError("You can use extra optional arguments in form validation!")
-        return self.cleaned_data
-
-
-
-"""
-Django view example
-"""
+
+# In your view
 def create_album(request):
-    form = AlbumForm.create_from_request(request, param=request.GET.get('param'))
+    form = AlbumForm.create_from_request(request)
     if not form.is_valid():
-        # Process your validation error
-        print(form.errors)
+        # Handle validation errors
+        return JsonResponse({"errors": form.errors}, status=400)
 
-    # Cleaned valid payload
-    payload = form.cleaned_data
-    print(payload)
+    # Access validated data
+    album_data = form.cleaned_data
+    # Do something with the data...
+
+    return JsonResponse({"status": "success"})
+```
+
+This form can validate a JSON request like:
+
+```json
+{
+  "title": "Unknown Pleasures",
+  "year": 1979,
+  "artist": {
+    "name": "Joy Division",
+    "genres": ["rock", "punk"],
+    "members": 4
+  }
+}
 ```
 
-If you want example with whole Django project, check out repository created by [pawl](https://github.com/pawl)
-[django_api_forms_modelchoicefield_example](https://github.com/pawl/django_api_forms_modelchoicefield_example), where
-he uses library with
-[ModelChoiceField](https://docs.djangoproject.com/en/4.1/ref/forms/fields/#django.forms.ModelChoiceField).
+### More Examples
+
+For more comprehensive examples, check out the documentation:
+
+- [Basic Example with Nested Data](https://sibyx.github.io/django_api_forms/example/#basic-example-music-album-api)
+- [User Registration with File Upload](https://sibyx.github.io/django_api_forms/example/#example-user-registration-with-file-upload)
+- [API with Django Models](https://sibyx.github.io/django_api_forms/example/#example-api-with-django-models)
+- [ModelChoiceField Example](https://github.com/pawl/django_api_forms_modelchoicefield_example) - External repository by [pawl](https://github.com/pawl)
+
+## Documentation
+
+Comprehensive documentation is available at [https://sibyx.github.io/django_api_forms/](https://sibyx.github.io/django_api_forms/)
+
+The documentation includes:
+
+- [Installation Guide](https://sibyx.github.io/django_api_forms/install/)
+- [Tutorial](https://sibyx.github.io/django_api_forms/tutorial/)
+- [Field Reference](https://sibyx.github.io/django_api_forms/fields/)
+- [Examples](https://sibyx.github.io/django_api_forms/example/)
+- [API Reference](https://sibyx.github.io/django_api_forms/api_reference/)
+- [Contributing Guide](https://sibyx.github.io/django_api_forms/contributing/)
 
 ## Running Tests
 
-```shell script
-# install all dependencies
+```shell
+# Install all dependencies
 poetry install
 
-# run code-style check
+# Run code-style check
 poetry run flake8 .
 
-# run the tests
+# Run the tests
 poetry run python runtests.py
+
+# Run tests with coverage
+poetry run coverage run runtests.py
+poetry run coverage report
 ```
 
+## License
+
+Django API Forms is released under the MIT License.
+
 ---
 Made with ❤️ and ☕️ by Jakub Dubec, [BACKBONE s.r.o.](https://www.backbone.sk/en/) &
 [contributors](https://github.com/Sibyx/django_api_forms/graphs/contributors).