Merge remote-tracking branch 'origin/master'

* origin/master:
  documenting features to wrapper makers
  documenting tapioca features
  adding note about features section in the quickstart
  renaming new flavours to building a wrapper
  improving new flavor and features docs
  bootstraping features document

docs/source/newflavour.rst → docs/source/buildingawrapper.rst

@@ -1,6 +1,6 @@
-============
-New Flavours
-============
+==================
+Building a wrapper
+==================
 
 
 Wrapping an API with Tapioca
@@ -40,6 +40,8 @@ Plase refer to the :doc:`TapiocaAdapter class <adapter_class>` document for more
 Features
 ========
 
+Here is some information you should know when building your wrapper. You may chose to or not to support features marked with `(optional)`.
+
 Resource Mapping
 ----------------
 
@@ -48,17 +50,43 @@ The resource mapping is a very simple dictionary which will tell your tapioca cl
 Tapioca uses `requests <http://docs.python-requests.org/en/latest/>`_ to perform HTTP requests. This is important to know because you will be using the method ``get_request_kwargs`` to set authentication details and return a dictionary that will be passed directly to ther request method. 
 
 
-Data formatting Mixins
-----------------------
+Formating data
+--------------
+
+Use the methods ``format_data_to_request`` and ``response_to_native`` to correctly treat data leaving and being received in your wrapper.
+
+**TODO: add examples**
 
 You might want to use one of the following mixins to help you with data format handling in your wrapper: 
 
 - ``FormAdapterMixin`` 
 - ``JSONAdapterMixin``
 
 
-Refreshing Authentication
--------------------------
+Exceptions
+----------
+
+Overwrite the ``process_response`` method to identify API server and client errors raising the correct exception accordingly. Please refer to the :doc:`exceptions <exceptions>` for more information about exceptions.
+
+**TODO: add examples**
+
+Pagination (optional)
+---------------------
+
+``get_iterator_list`` and ``get_iterator_next_request_kwargs`` are the two methods you will need to implement for the executor ``pages()`` method to work.
+
+**TODO: add examples**
+
+Serializers (optional)
+----------------------
+
+Set a ``serializer_class`` attribute or overwrite the ``get_serializer()`` method in your wrapper for it to have a default serializer. Please refer to the :doc:`serializers <serializers>` for more information about serializers.
+
+**TODO: add examples**
+
+
+Refreshing Authentication (optional)
+------------------------------------
 
 You can implement the ```refresh_authentication``` and ```is_authentication_expired``` methods in your Tapioca Client to refresh your authentication token every time that it expires.
 ```is_authentication_expired``` receives an error object from the request method (it contains the server response and HTTP Status code). You can use it to decide if a request failed because of the token. This method should return true if the authentication is expired or false otherwise. If the authentication is expired, ```refresh_authentication``` is called automatically.

docs/source/features.rst

@@ -0,0 +1,78 @@
+========
+Features
+========
+
+Here are some features tapioca supports. The wrapper you are using may support them or not, it will depend on the `tapioca-wrapper` version it is tied to and if the developer implemented the methods needed to support the feature. Either way, if you find yourself in a situation where you need one of these features, clone the wrapper, update the `tapioca-wrapper` version to the latest one, implement the features you need and submit a pull request to the developer. You will be helping a lot of people!
+
+
+TapiocaClient
+=============
+
+The first object you get after you instanciate a tapioca wrapper is an instance of the ``TapiocaClient`` class. This class is capable of accessing the API endpoints of the wrapper and traversing respose objects. No other action besides those can be achieved from a ``TapiocaClient``. To retrieve the raw data returned from the API call you will need to transform it in a ``TapiocaClientExecutor``.
+
+**TODO: add examples**
+
+TapiocaClientExecutor
+=====================
+
+Everytive you ``call`` in ``TapiocaClient`` you will get a ``TapiocaClientExecutor``. Here are the features available in a ``TapiocaClientExecutor``:
+
+Accessing raw response data
+---------------------------
+
+To access the raw data contained in the executor, use the ``data`` **attribute**. To access the raw response, use the ``response`` **attribute**. To access the status code of the response, use the ``status_code`` **attribute**.
+
+**TODO: add examples**
+
+HTTP calls
+----------
+
+Executors have access to make HTTP calls using the current data it possesses as the URL. `requests <http://docs.python-requests.org/en/latest/>`_ library, is used as the engine to perform API calls. Every key word parameter you pass to: ``get()``, ``post()``, ``put()``, ``patch()``, ``delete()`` methods will be directly passed to the request library call. This means you will be using ``params={'myparam': 'paramvalue'}`` to send querystring arguments in the url and ``data={'datakey': 'keyvalue'}`` to send data in the body of the request.
+
+**TODO: add examples**
+
+Auth refreshing (\*)
+--------------------
+
+Make any HTTP call passing ``refresh_auth=True`` and in case you have an expired API token, it will automatically be refreshed and the call retried.
+
+**TODO: add examples**
+
+*the wrapper you are current using may not support this feature
+
+Pagination (\*)
+---------------
+
+Use ``pages()`` method to call an endpoint that returns a collection of objects in batches. This will make your client automatically fetch more data untill there is none more left. You may use ``max_pages`` and/or ``max_items`` to limit the number of items you want to iterate over.
+
+**TODO: add examples**
+
+*the wrapper you are current using may not support this feature
+
+Open docs (\*)
+--------------
+
+When accessing an endpoint, you may want to read it's documentation in the internet. By calling ``open_docs()`` in a python interactive session, the doc page will be openned in a browser.
+
+**TODO: add examples**
+
+*the wrapper you are current using may not support this feature
+
+Open in the browser (\*)
+------------------------
+
+Whenever the data contained in the executor is a URL, you can directly open it in the browser from an interactive session by calling ``open_in_browser()``
+
+**TODO: add examples**
+
+*the wrapper you are current using may not support this feature
+
+Exceptions
+==========
+
+Tapioca built in exceptions will help you to beautifuly catch and handle whenever there is a client or server error. Make sure the wrapper you are using correctly raises exceptions, the developer might not have treated this. Please refer to the :doc:`exceptions <exceptions>` for more information about exceptions.
+
+Serializers
+===========
+
+Serializers will help you processing data before it is sent to the endpoint and transforming data from responses into python objects. Please refer to the :doc:`serializers <serializers>` for more information about serializers.

docs/source/flavours.rst

@@ -11,7 +11,6 @@ Facebook
 --------
 `<https://github.com/vintasoftware/tapioca-facebook>`_
 
-
 .. _flavour-twitter:
 Twitter
 -------
@@ -59,4 +58,4 @@ Toggl
 
 Your flavour
 ============
-Send a pull request to add new ones to the list.
+To create a new wrapper, please refer to :doc:`Building a wrapper <buildingawrapper>`. Upload it to pypi and send a pull request here for it to be added to the list.

docs/source/index.rst

@@ -9,10 +9,11 @@ Contents:
 
 	about
 	quickstart
+	features
 	serializers
 	exceptions
 	flavours
-	newflavour
+	buildingawrapper
 	adapter_class
 	contributors
 	changelog

docs/source/quickstart.rst

@@ -239,3 +239,6 @@ Opening any link in the browser
 -------------------------------
 
 Whenever the data contained in a tapioca object is a URL, you can open it in a browser by using the ``open_in_browser()`` method.
+
+
+For more information on what wrappers are capable of, please refer to the :doc:`features <features>` section.