apys 0.1.5

A simple back-end rest framework in python using aiohttp lib

apys - v0.1
===========

Wellcome to apys! A simple backend restful framework!

LANGUAGE
--------

`Python >= 3.4.2 <https://docs.python.org/3/>`_

LIBRARIES
---------


* `aiohttp <https://aiohttp.readthedocs.io/>`_ - http client/server for asyncio

----

INSTALATION
-----------


#. Install python 3

* Windows - `Link <https://www.python.org/download/releases/3.5/>`_
* Ubuntu - ``sudo apt-get install python``
* Fedora - ``sudo yum install python``
* Arch - ``sudo pacman -S python``

#. Install PIP - Python libraries manager

* Windows - `Link <http://www.lfd.uci.edu/~gohlke/pythonlibs/#pip>`_
* Ubuntu - ``sudo apt-get install pip``
* Fedora - ``sudo yum install pip``
* Arch - ``sudo pacman -S pip``

#. Install this framework using PIP

* ``pip install apys``

----

INITIALIZATING PROJECT
----------------------

.. code-block::

$ apys --init

----

USING
-----

DIRECTORIES
^^^^^^^^^^^

.. code-block::

/config - json configuration files
/endpoints - backend endpoints
/utils - helper script files


CONFIG
^^^^^^

Here are the configuration files used in the app.
They will be send to the endpoint via param ``api.config``

There are 3 special filenames:


* ``prod.json`` - The oficial configuration file
* ``dev.json`` - The development configuration file
* ``local.json`` - The local configuration file (ignore in git)

..

Note: They really work as following: the api tries to load ``local.json``\ , then ``dev.json``\ , then ``prod.json``. So in the oficial release you will only have ``prod.json``


The current config special properties are the following:

.. code-block:: json

{
"log": bool, //optional. default=False
"server": {
"port": int, //optional. default=8888
"cors": string or False //optional. default=False
},
"mail": {
"host": string,
"port": int, //optional. default=25 or 587 for TLS
"tls": bool, //optional. default=False
"username?": string, //optional. no default
"password?": string //optional. no default
}
}

ENDPOINTS
^^^^^^^^^

This will be your main dev dir

All files added here will be an endpoint automatically

i.e.: the file ``endpoints/hello/world.py`` will generate an endpoint ``/hello/world``

The file's code will be the following:

.. code-block:: python


utils = [
'[util1]',
'[util2]'
]

def [method](req, api):
[process]

Where ``[method]`` is the http request type:


* post
* get
* put
* delete
* head
* options
* default - executed when a request is made for any of the above, but it is not implemented

``[process]`` is what you wan the endpoint to do (your code)

``[util1]`` and ``[util2]`` are the *utils* scripts (without ``.py``\ )

``req`` is *aiohttp*\ 's request, `documentation <http://aiohttp.readthedocs.io/en/stable/web_reference.html#request>`_

..

``req`` has the ``param`` property to read the request body


``api`` is the object that contains all api functionalities:


* config - Configuration dictionary used in the actual scope
* debug - function to log messages
* error - function to log errors

UTILS
^^^^^

Python files with reusable code, to be called on endpoints.

It will be a normal cod, but with some special funcions:

init(api)

.. code-block::

The function that will be executed on server startup
Only one time.


``[method]``\ (req, api) - ``[method]`` being the type of http request

.. code-block::

The function that will be called before every request to the function with the same name on the endpoint.
Any result should be stored on the variable `req`, because it is the only local variable on the request.


any(req, api)

.. code-block::

The function that will be executed before any request.
Note: thids function will be executed before the later.


EXAMPLE
-------

Look at the ``demos/`` for examples

----

STARTING THE SERVER
^^^^^^^^^^^^^^^^^^^

There are 2 ways to start the server


#.
Execute ``apys -s`` from terminal on your root project folder (Recomended)

#.
Call the method ``start()`` from module ``apys.server`` (Only recomended if you need to do something before starting the server)

----

OBSERVATION
-----------

Both the framework and this page are in development, so, subjected to changes.

..

Version previous to v0.1.0 vas called `pypolyback <https://github.com/seijihirao/pypolyback>`_ and used python 2.