updated the docs, bugfixes

docs/build/_sources/index.txt

@@ -3,8 +3,15 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Python Rest Api Framework's documentation!
-=====================================================
+Python Rest Api Framework's documentation
+=========================================
+
+Python REST API framework is a set of utilities based on werkzeug to
+easily build Restful API with a MVC pattern. Main features includes:
+Pagination, Authentication, Authorization, Filters, Partials Response,
+Error handling, data validators, data formaters...
+and more...
+
 
 Contents:
 
@@ -13,12 +20,12 @@ Contents:
 
    introduction
    tutorial
-   datastore
-   controller
-   pagination
-   authentication
-   multiple_endpoint
-   references
+..   datastore
+..   controller
+..   pagination
+..   authentication
+..   multiple_endpoint
+..   references
 
 Indices and tables
 ==================
@@ -27,3 +34,62 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+
+
+
+A Full working example
+----------------------
+
+.. code-block:: python
+
+    from rest_api_framework import models
+    from rest_api_framework.datastore import SQLiteDataStore
+    from rest_api_framework.views import JsonResponse
+    from rest_api_framework.controllers import Controller
+    from rest_api_framework.datastore.validators import UniqueTogether
+    from rest_api_framework.pagination import Pagination
+
+
+    class UserModel(models.Model):
+        """
+        Define how to handle and validate your data.
+        """
+        fields = [models.StringField(name="first_name", required=True),
+                  models.StringField(name="last_name", required=True),
+                  models.PkField(name="id", required=True)
+                  ]
+
+
+    def remove_id(response, obj):
+        """
+        Do not show the id in the response.
+        """
+        obj.pop(response.model.pk_field.name)
+        return obj
+
+
+    class UserEndPoint(Controller):
+        ressource = {
+            "ressource_name": "users",
+            "ressource": {"name": "adress_book.db", "table": "users"},
+            "model": UserModel,
+            "datastore": SQLiteDataStore,
+            "options": {"validators": [UniqueTogether("first_name", "last_name")]}
+            }
+
+        controller = {
+            "list_verbs": ["GET", "POST"],
+            "unique_verbs": ["GET", "PUT", "DElETE"],
+            "options": {"pagination": Pagination(20)}
+            }
+
+        view = {"response_class": JsonResponse,
+                "options": {"formaters": ["add_ressource_uri", remove_id]}}
+
+
+    if __name__ == '__main__':
+
+        from werkzeug.serving import run_simple
+        from rest_api_framework.controllers import WSGIDispatcher
+        app = WSGIDispatcher([UserEndPoint])
+        run_simple('127.0.0.1', 5000, app, use_debugger=True, use_reloader=True)

docs/build/_sources/introduction.txt

@@ -346,5 +346,5 @@ is the same as with the PythonListDataStore.
 Where to go from here
 ---------------------
 
-* :doc:`Authentication and Authorization </authentication>`
-* :doc:`multiple_endpoint`
+.. * :doc:`Authentication and Authorization </authentication>`
+.. * :doc:`multiple_endpoint`

docs/build/_sources/representing_data.txt

@@ -48,7 +48,7 @@ You can check that it work as expected:
     Server: Werkzeug/0.8.3 Python/2.7.2
     Date: Mon, 14 Oct 2013 23:41:55 GMT
 
-    {"first_name": "Cap tain", "last_name": "America",
+    {"first_name": "Captain", "last_name": "America",
     "ressource_uri": "/users/1/"}
 
 Make things generics
@@ -77,6 +77,11 @@ Your code then become:
         obj.pop(response.model.pk_field.name)
         return obj
 
-And reuse this formatter as long as you need
+And reuse this formatter as long as you need.
 
-Next :doc:`related_ressources`
+Formaters are here to help you build clean and meaningful ressources
+representations. It should hide internal representation of your
+ressources and return all of the fields needed to manipulate and
+represent your data.
+
+Next :doc:`work_with_pagination`

docs/build/_sources/tutorial.txt

@@ -8,4 +8,5 @@ Tutorial building an adressebook API
    using_user_endpoint
    adding_validator_datastore
    representing_data
+   work_with_pagination
    related_ressources

docs/build/_sources/using_user_endpoint.txt

@@ -9,9 +9,11 @@ First you can check that your endpoint is up
 
     HTTP/1.0 200 OK
     Content-Type: application/json
-    Content-Length: 2
+    Content-Length: 44
     Server: Werkzeug/0.8.3 Python/2.7.2
-    Date: Mon, 14 Oct 2013 12:52:22 GMT
+    Date: Tue, 15 Oct 2013 11:13:44 GMT
+
+    {"meta": {"filters": {}}, "object_list": []}
 
 Your endpoint is responding but does not have any data. Let's add
 some:
@@ -59,14 +61,14 @@ The list of users is also updated:
 
 .. code-block:: bash
 
-    curl -i "http://localhost:5000/users/1/"
+    curl -i "http://localhost:5000/users/"
     HTTP/1.0 200 OK
     Content-Type: application/json
     Content-Length: 83
     Server: Werkzeug/0.8.3 Python/2.7.2
     Date: Mon, 14 Oct 2013 17:03:00 GMT
 
-    [{"first_name": "John", "last_name": "Doe", "id": 1, "ressource_uri": "/users/1/"}]
+    {"meta": {"filters": {}}, "object_list": [{"first_name": "John", "last_name": "Doe", "id": 1, "ressource_uri": "/users/1/"}]}
 
 Delete a user
 -------------
@@ -94,8 +96,35 @@ and now delete it:
     Server: Werkzeug/0.8.3 Python/2.7.2
     Date: Mon, 14 Oct 2013 20:41:46 GMT
 
+You can check that the user no longer exists:
+
+.. code-block:: bash
+
+    curl -i "http://localhost:5000/users/2/"
+    HTTP/1.0 404 NOT FOUND
+    Content-Type: application/json
+    Connection: close
+    Server: Werkzeug/0.8.3 Python/2.7.2
+    Date: Tue, 15 Oct 2013 11:16:33 GMT
+
+    {"error": "<p>The requested URL was not found on the server.</p><p>If you entered the URL manually please check your spelling and try again.</p>"}
+
+And the list is also updated:
+
+.. code-block:: bash
+
+    curl -i "http://localhost:5000/users/"
+    HTTP/1.0 200 OK
+    Content-Type: application/json
+    Content-Length: 125
+    Server: Werkzeug/0.8.3 Python/2.7.2
+    Date: Tue, 15 Oct 2013 11:17:46 GMT
+
+    {"meta": {"filters": {}}, "object_list": [{"first_name": "John", "last_name": "Doe", "id": 1, "ressource_uri": "/users/1/"}]}
+
+
 Update a User
-=============
+-------------
 
 Let's go another time to the creation process:
 
@@ -114,24 +143,63 @@ America. Let's update this user:
 
 .. code-block:: bash
 
-    curl -i -H "Content-type: application/json" -X PUT -d '{"first_name":"Captain", "last_name": "America"}'  http://localhost:5000/users/3/
+    curl -i -H "Content-type: application/json" -X PUT -d '{"first_name":"Capitain", "last_name": "America"}'  http://localhost:5000/users/3/
     HTTP/1.0 200 OK
     Content-Type: application/json
     Content-Length: 58
     Server: Werkzeug/0.8.3 Python/2.7.2
     Date: Mon, 14 Oct 2013 20:57:47 GMT
 
-Partial update is also possible:
+    {"first_name": "Capitain", "last_name": "America", "id": 3, "ressource_uri": "/users/3/"}
+
+Argh! Thats a typo. the fist name is "Captain", not "Capitain". Let's
+correct this:
 
 .. code-block:: bash
 
-    curl -i -H "Content-type: application/json" -X PUT -d '{"first_name":"Cap tain"}'  http://localhost:5000/users/3/
+    curl -i -H "Content-type: application/json" -X PUT -d '{"first_name":"Captain"}'  http://localhost:5000/users/3/
     HTTP/1.0 200 OK
     Content-Type: application/json
     Content-Length: 59
     Server: Werkzeug/0.8.3 Python/2.7.2
     Date: Mon, 14 Oct 2013 21:08:04 GMT
 
+    {"first_name": "Captain", "last_name": "America", "id": 3, "ressource_uri": "/users/3/"}
+
+
+Filtering
+---------
+
+Ressources can be filtered easily using parameters:
+
+.. code-block:: bash
+
+    curl -i "http://localhost:5000/users/?last_name=America"
+    HTTP/1.0 200 OK
+    Content-Type: application/json
+    Content-Length: 236
+    Server: Werkzeug/0.8.3 Python/2.7.2
+    Date: Tue, 15 Oct 2013 12:07:21 GMT
+
+    {"meta": {"filters": {"last_name": "America"}}, "object_list":
+    [{"first_name": "Joe", "last_name": "America", "id": 1,
+    "ressource_uri": "/users/1/"}, {"first_name": "Bob", "last_name":
+    "America", "id": 3, "ressource_uri": "/users/3/"}]
+
+Multiple filters are allowed:
+
+.. code-block:: bash
+
+    curl -i "http://localhost:5000/users/?last_name=America&first_name=Joe"
+    HTTP/1.0 200 OK
+    Content-Type: application/json
+    Content-Length: 171
+    Server: Werkzeug/0.8.3 Python/2.7.2
+    Date: Tue, 15 Oct 2013 12:09:32 GMT
+
+    {"meta": {"filters": {"first_name": "Joe", "last_name": "America"}},
+    "object_list": [{"first_name": "Joe", "last_name": "America", "id": 1,
+    "ressource_uri": "/users/1/"}]}
 
 Error handling
 --------------