Added documentation about model serializing

aiorest_ws/db/orm/serializers.py

@@ -11,7 +11,7 @@
 from aiorest_ws.exceptions import ImproperlyConfigured
 from aiorest_ws.db.orm.abstract import AbstractSerializer, AbstractField, \
     empty, SkipField
-from aiorest_ws.db.orm.fields import HiddenField
+from aiorest_ws.db.orm.fields import *  # NOQA
 from aiorest_ws.db.orm.exceptions import ValidationError
 from aiorest_ws.utils.fields import set_value, get_attribute
 from aiorest_ws.utils.functional import cached_property

docs/source/index.rst

@@ -157,7 +157,7 @@ Contents:
 ---------
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 4
 
    auth
    app

docs/source/serializing.rst

@@ -11,8 +11,8 @@ of this processing can be returned to a user in JSON, XML or any other formats.
 also provide deserializing mechanisms which can be used for parsing and validating user input data
 that will be used for to work with ORMs further.
 
-These serializers largely based on ideas of Django REST Framework. In this way a lot of
-functionality that will be described further will coincide with this library.
+These serializers largely based on ideas and concepts of Django REST Framework. In this way a lot
+of functionality that will be described further will coincide with this library.
 
 At the moment aiorest-ws have support with the following ORMs:
 
@@ -21,20 +21,92 @@ At the moment aiorest-ws have support with the following ORMs:
 
 You can find corresponding modules for each of mentioned ORMs in ``aiorest_ws.db.orm.*`` namespace.
 
-Serializers
------------
+Model serializers
+-----------------
+The aiorest-ws library provides :class:`ModelSerializer` classes which can be used for serializing
+(or deserializing) your model instances to a some specific format. Its can be used for processing
+of model instances which have taken from a database.
 
 Defining model serializer
 ^^^^^^^^^^^^^^^^^^^^^^^^^
+Let's suppose that we have a some class which has certain functionality. For example it could be a
+class that storing data about a current user:
+
+.. code-block:: python
+
+    from django.db import models
+
+    class User(models.Model):
+        self.username = models.CharField(max_length=255)
+        self.email = models.EmailField()
+        self.logged_at = models.DateTimeField(auto_now=True)
+
+After this we will declare a serializer class which is used for serializing and deserializing
+some data that converted to :class:`User` objects:
+
+.. code-block:: python
+
+   from aiorest_ws.db.orm.django import serializers
+
+    class UserSerializer(serializers.ModelSerializer):
+        class Meta:
+            model = User
+
+That's all! We have described our simplest serializer class that giving opportunities to work
+with :class:`User` instances. As you can see there, we have declared :class:`Meta` class, that is
+storing a link to the :class:`User` model. When we will put some data to the serializer instance
+(or otherwise, update data), serializer will parse specified model and extract fields that will
+be processed.
 
 Serializing
 ^^^^^^^^^^^
+Serialization mechanism let us to convert complex types into Python language types. So for it is
+enough pass an existing object into a serializer instance and get `data` attribute after creating
+serializer. For example:
+
+.. code-block:: python
+
+    user = User.objects.create(username='nayton', email='nayton@example.com')
+    serializer = UserSerializer(user)
+    serializer.data
+    # {'pk': 1, 'username': 'nayton', 'email': 'nayton@example.com', 'logged_at': '2016-11-29T21:13:31.039488'}
+
+As you can see, we have converted passed object into dictionary. So it now remains to make an
+additional step, that allow to transmit the data through a network. For instance we can render it
+into JSON:
+
+.. code-block:: python
+
+    from aiorest_ws.renderers import JSONRenderer
+
+    json = JSONRenderer().render(serializer.data)
+    json
+    # b'{"pk": 1, "username": "nayton", "email": "nayton@example.com", "logged_at": "2016-11-29T21:13:31.039488"}'
 
 Deserializing
 ^^^^^^^^^^^^^
+Deserializing data is very useful feature when you want to get information after users action or
+from 3rd party APIs and save it in a database as some model instances. For using this feature
+enough to use already declared serializer class:
+
+.. code-block:: python
+
+    data = {"username": "new_user", "email": "new_user@example.com", "logged_at": "2016-11-29T21:15:31.078217"}
+    serializer = UserSerializer(data=data)
+    serializer.is_valid()
+    # True
+    serializer.validated_data
+    # {'username': 'new_user', 'email': 'new_user@example.com', 'logged_at': datetime.datetime(2012, 08, 22, 16, 20, 09, 78217)}
+
+
+Saving instances
+^^^^^^^^^^^^^^^^
+In some cases if you want to return created object instances which based on the validated data then you will need to implement ``.create()`` and/or ``.update()`` methods.
+
+~~~~~~~~~~~
 
-Validating and saving instances
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Validating
+^^^^^^^^^^
 
 Partial instance updates
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -45,6 +117,12 @@ Work with multiple objects
 Work with nested objects
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
+Additional keyword arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+HyperlinkedModelSerializer
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Serializer fields
 -----------------
 

docs/source/wrappers.rst

@@ -26,21 +26,21 @@ Properties:
 
     Returns dictionary of arguments for request.
 
-    For instance in the "classical REST" you can send the HTTP request by certain URL
-    like http://mywebsite.com/api/user/?name=admin&password=mysecretpassword where with ``?`` separator
-    and ``&`` symbols you can specify all required arguments where it necessary. In our case for
-    aiorest-ws library you should specify all this arguments in request as a dictionary. For example:
-
-.. code-block:: javascript
-
-    {
-        "method": "GET",
-        "url": "/api/user,
-        "args": {
-            "name": "admin",
-            "password": "mysecretpassword"
+    For instance in the "classical REST" you can send the HTTP request by certain URL like
+    http://mywebsite.com/api/user/?name=admin&password=mysecretpassword where with ``?`` and ``&``
+    symbols you can specify all required arguments when it is necessary. For the following example
+    we specify all the same arguments in request at the dictionary:
+
+    .. code-block:: python
+
+        {
+            "method": "GET",
+            "url": "/api/user,
+            "args": {
+                "name": "admin",
+                "password": "mysecretpassword"
+            }
         }
-    }
 
 - data