.. _api:

===================
 API Documentation
===================

Resources
=========

.. automodule:: yarhp.resource
   :members:


Views
=====

Yarhp provides 3 view classes to help you to reduce lots of repetitive code in your views.
  * BaseView
  * SQLAView
  * DynamoDBView

Last two are derived from BaseView.

.. automodule:: yarhp.view
   :members:

.. automodule:: yarhp.sqla
   :members:

.. automodule:: yarhp.dynamo
   :members:


Utilities
=========

.. automodule:: yarhp.renderers
   :members:

.. automodule:: yarhp.utils
   :members:

.. TODO document the restview command

Wrappers
========

.. automodule::  yarhp.wrappers
   :members:

Validators
==========

Validators are implemented as wrappers that are before-calls. Essentially they 'wrap' your action (or any method really) and are called before the action is called.

There are two ways how validators can be involved:
   
   * Decorator
   * Subclassing from one of yarhp's base view classes
   * The Chuck Norris way

   
Decorator
---------

    .. code-block:: python

        @validator(name={'type': str, 'required': True},
                    age={'type': int, 'required': True},
                    birthdate={'type': date, 'required': False})
        def create(self):
            pass

Keyword arguments passed to the validator are the validation schema that is used to check request.params validity.


Subclassing
-----------
Yarhp provides 2 base classes one could derive from to have automated validation in the views.
``SQLAView`` and ``DynamoDBView``. The essential difference between those two is what kind of information about the underlaying schema yarhp is able to collect. In case of SQL for example it gets the type, required and also length of the field.

    .. code-block:: python

        class MyView(SQLAView):
            def create(self):
                pass

In the example above the ``create`` action is automatically gets validated by yarhp: the type and the required field. So you dont have to do anything. The way it does this magic is pulling the metadata (schema) from SQLA and comparing with request.params.
If you wish to override any default behavior, you could do:

    .. code-block:: python
   
        class MyView(SQLAView):
            @validator(name={'type':str, required=False})
            def create(self):
                ...

Here we change the ``required`` to False, thus overriding the metadata coming from the DB schema where name was required. This is obviously not recommended and should be done with care, understanding the side effects. In this case it might raise DB error since name could be NULL, but DB requires it.

The Chuck Norris way
-------------------
Now what if you write a common validator and you want to apply it to all of your actions? One way is to decorate them all. But another is “Chuck Norris way” !

Stay tuned for more..


The ``add_resource`` method
===========================

.. XXX move to design.rst or integrate with yarhp.view above

.. py:method:: config.add_resource(member_name, collection_name, **kwargs)

   defines a new resource, its named routes::

      config.add_resource("user", "users")

   view to find : UsersView

   ================= ============ =========== ===========
   URL               route name   HTTP verb   action name
   ================= ============ =========== ===========
   /users            users        GET         index
   /users            users        POST        create
   /users/:id        user         GET         show
   /users/:id        user         PUT         update
   /users/:id        user         DELETE      delete
   /users/:id/edit   edit_user    GET         edit
   /users/new        new_user     GET         new
   ================= ============ =========== ===========

   These last two are non-standard CRUD actions.

   ::

      config.add_resource("transaction", "transactions", parent="user")

   view to find: UserTransactionsView
   model: user_transaction.UserTransaction

   ================================= ====================== ========== ===========
   URL                               route name             HTTP verb  action name
   ================================= ====================== ========== ===========
   /users/:user_id/transactions      user_transactions      GET        index
   /users/:user_id/transactions      user_transactions      POST       create
   /users/:user_id/transactions/:id  user_transaction       GET        show
   /users/:user_id/transactions/:id  user_transaction       PUT        update
   /users/:user_id/transactions/:id  user_transaction       DELETE     delete
   /users/1/transactions/edit        user_edit_transaction  GET        edit
   /users/1/transactions/new         user_new_transaction   GET        new
   ================================= ====================== ========== ===========

   These last two are non-standard CRUD actions.


   singular resource::

      config.add_resource('detail', parent='transaction')

   view to find: UserTransactionDetailView

   ========================================================= ============================== ========== ==========
   URL                                                       route name                     HTTP verb  action
   ========================================================= ============================== ========== ==========
   /users/:user_id/transactions/:transaction_id/detail       user_transaction_detail        GET        show
   /users/:user_id/transactions/:transaction_id/detail       user_transaction_detail        POST       create
   /users/:user_id/transactions/:transaction_id/detail       user_transaction_detail        PUT        update
   /users/:user_id/transactions/:transaction_id/detail       user_transaction_detail        DELETE     delete
   /users/:user_id/transactions/:transaction_id/detail/edit  user_transaction_edit_detail   GET        edit
   /users/:user_id/transactions/:transaction_id/detail/new   user_transaction_new_detail    GET        new
   ========================================================= ============================== ========== ==========