Metadata-Version: 1.1
Name: pypolyback
Version: 0.12.4
Summary: A simple back-end rest framework in python using twisted and cyclone
Home-page: https://github.com/seijihirao/pypolyback
Author: Rodrigo Seiji Piubeli Hirao
Author-email: rodrigo.seiji.hirao@gmail.com
License: MIT
Description: PYPOLY BACK - v0.12
        ===================
        
        Wellcome to Pypoly Back! A simple backend restful framework!
        
        LANGUAGE
        --------
        
        `Python 2.7 <https://docs.python.org/2/tutorial/index.html>`__
        
        LIBRARIES
        ---------
        
        -  `twisted <https://twistedmatrix.com/trac/>`__ - Web event-handling
           Framework (Low Level)
        -  `cyclone <http://cyclone.io/documentation/>`__ - Http framework (High
           Level)
        
        --------------
        
        INSTALATION
        -----------
        
        1. Install python 2.7
        
           -  Windows - `Link <https://www.python.org/download/releases/2.7/>`__
           -  Ubuntu - ``sudo apt-get install python2``
           -  Fedora - ``sudo yum install python2``
           -  Arch - ``sudo pacman -S python2``
        
        2. Install PIP - Python libraries manager
        
           -  Windows -
              `Link <http://www.lfd.uci.edu/~gohlke/pythonlibs/#pip>`__
           -  Ubuntu - ``sudo apt-get install pip2``
           -  Fedora - ``sudo yum install pip2``
           -  Arch - ``sudo pacman -S pip2``
        
        3. Install this framework using PIP
        
           -  ``pip2 install pypolyback``
        
        --------------
        
        INITIALIZATING PROJECT
        ----------------------
        
        ::
        
            $ pypolyback --init
        
        --------------
        
        USING
        -----
        
        DIRECTORIES
        ~~~~~~~~~~~
        
        ::
        
            /pypolyback (*) - api internal files
            /config - json configuration files
            /endpoints - backend endpoints
            /utils - helper script files
        
            Note (\*): The dir pypolyback will only exists if you didn't install
            ``pypolyback``'s library from pip
        
        API
        ~~~
        
        Here is present all api files that work behind the endpoints
        
        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:: 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/test/helloworld.py`` will generate an
        endpoint ``/test/helloworld``
        
        The file's code will be the following:
        
        .. code:: python
        
        
            utils = [
                '[util1]',
                '[util2]'
            ]
            [@async]
            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 *cyclone*'s request, with these properties included: \*
        params - arguments received from request, an object (primitive, list or
        dictionary) \* send - function to respond the request with an object
        
            ``req``'s complete documentatios in present on cyclone's site
            http://cyclone.io/documentation/web.html
        
        ``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
        
        ``[@async]`` is an optional annotation, that makes this method
        asynchronous.
        
        Note: if async is used you will need to import it
        (``from pypolyback import async``)
        
            ``async`` complete doc is the same as twisted's ``inlineCallback``
            https://twistedmatrix.com/documents/current/api/twisted.internet.defer.html#inlineCallbacks
        
        UTILS
        ~~~~~
        
        Python files with reusable code, to be called on endpoints.
        
        It will be a normal cod, but with some special funcions:
        
        init(api)
        
        ::
        
            The function that will be executed on server startup
            Only one time.
        
        ``[method]``\ (req, api) - ``[method]`` being the type of http request
        
        ::
        
            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)
        
        ::
        
            The function that will be executed before any request.
            Note: thids function will be executed before the later.
        
        APP.py
        ~~~~~~
        
            This file is not needed if you installed from pip
        
        An executable to start your server
        
        EXAMPLE
        -------
        
        To have a feeling of how things are working take a look at the file
        ``endpoints/example/ex_endpoint.py``
        
        It should be like this:
        
        .. code:: python
        
            #!/usr/bin/env python
            # -*- coding: utf-8 -*-
        
            from pypolyback import async
        
            utils = [
                'example_util'
            ]
        
            @async  #método asíncrono
            def get(req, api):
                """
                Start the server
                Then go, from your browser, in `localhost:8888/example/ex_endpoint`
                There shoud open a page with the content `Success in method get!`
                
                Output:
                    string
                """
                
                result = yield api.example_util.write(req) #coletando dados de forma asíncrona
                
                req.send(result) #retornando os dados
        
            def post(req, api):
                """
                Start the server
                Then make a post http request to `localhost:8888/example/ex_endpoint`
                Sending the documented object as input 
                It should be returned `{"message": input.message, "status":"Sucess in method post!"}`
                
                Input:
                    message: string
                    
                Output:
                    message: string
                    request: string
                """
                
                message = req.params['message'] #coletando dados da requisição
                
                #retornando os dados
                req.send({
                    'message': api.example_util.write(req),
                    'request': message
                })
        
        Now follow instructions to test it and see how the endpoint works
        
        --------------
        
        STARTING THE SERVER
        ~~~~~~~~~~~~~~~~~~~
        
        There are 2 ways to start the server
        
        1. Execute ``pypolyback --start`` from terminal on your root project
           folder (Recomended)
        
        2. Call the method ``start()`` from module ``pypolyback.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.
        
Keywords: backend rest web service
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
