Metadata-Version: 2.0
Name: pypolyback
Version: 0.5.0
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
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
Requires-Dist: cyclone
Requires-Dist: twisted

# PYPOLY BACK - v0.5
Bem vindo ao Pypoly Back! A framework usada no backend do site da Discipuluz!

## Linguagem
[Python 2.7](https://docs.python.org/2/tutorial/index.html)

## Bibliotecas
* [twisted](https://twistedmatrix.com/trac/) - Ferramenta de eventos de redes (Low Level)
* [tornado](http://www.tornadoweb.org/en/stable/) - Framework de apps web (High Level)
* [cyclone](http://cyclone.io/documentation/) - Implementação do Tornado como um protocolo do Twisted

---

## Instalação
1. Instale o 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. Instale o PIP - gerenciador de bibliotcas do python
    * 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. Instale as bibliotecas usando o PIP
    * `pip install twisted`
    * `pip install tornado`
    * `pip install cyclone`

---

## Utilização

### Pastas
    /pypolyback - arquivos internos da api (Essa pasta só existirá se você não instalou a biblioteca `pypoly-back` pelo pip)
    /config - arquivos json de configuração
    /endpoints - endpoints do backend
    /utils - arquivos de scripts para auxílio
    app.py - executável do servidor

### API
Aqui estão contidas os arquivos da api, que gerenciam todo o funcionamento por trás dos endpoints

### CONFIG
Aqui estão os arquivos com variáveis de configuração usados no aplicativo.
Eles serão disponibilizados para o endpoint por meio do parâmetro `api.config`

Estão contidos 2 arquivos:
* `prod.json` - arquivo de configuração do site oficial
* `dev.json` - arquivo de configuração usado no desenvolvimento

E é recomendado que seja adicionado um outro:
* `local.json` - arquivo local de configuração

### ENDPOINTS
Esta será a pasta principal de desenvolvimento.

Todo arquivo adicionado aqui já é automaticamente um endpoint

Por exemplo, o arquivo `endpoints/test/helloworld.py` gerará um endpoint `/test/helloworld`

O código do arquivo endpoint será:
```python

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

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

Onde `[method]` é o tipo de requisição, podendo ser:
* post
* get
* put
* patch
* delete

`[process]` é o que você deseja que o endpoint faça

`[util1]` e `[util2]` são os nomes dos arquivos (sem o `.json`) dos scripts feitos na pasta *utils*

`req` é o request do cyclone, com as propriedades a mais:
* params - argumentos recebidos pela requisição, dicionário onde as chaves são os nomes do argumentos
* respond - função para retornar um dicionário na requisição

> A documentação completa do `req` está contida no site http://cyclone.io/documentation/web.html

`api` é o objeto que contém as funciionalidades da api, como:
* config - dicionário da config usada no escopo atual
* debug - função para logar uma mensagem
* error - função para logar um erro

> A documentação completa do `api` não existe :D

### UTILS

Arquivos de python com código reutilizável, para serem usados em múltiplos endpoints.

Ele será um código comum, mas com alguns métodos especiais, sendo esses:

init(api)

    A função que será executada no início da compilação.
    Ou seja, apenas uma vez, que será quando o programa for executado.

`[method]`(req, api) - Sendo `[method]` o tipo de requisição

    A função que será executada antes que qualquer requisição ao método escolhido do endpoint.
    Note que qualquer resultado deve ser retornado ou guardado na variável `req`, por serem as únicas variáveis locais da requisição.

any(req, api)

    A função que será executada antes todas as requisições ao endpoint.
    Observação: esse método será executado antes dos de método específico.


### APP.py

Executável do servidor!

Abra um terminal e execute `python2 app.py`

Então abra seu navegador ou uma requisição http e entre em `localhost:[porta]/[página]`

Onde `[porta]` é a porta no seu arquivo de configuração (`8888` se nada foi mudado)

E `[página]` é a url do seu arquivo, como explicado na sessão #endpoint

## EXEMPLO

Para tentar ter uma pequena sensação de que as coisas estão funcionando dê uma olhada no arquivo `endpoints/example/ex_endpoint.py` 

Ele deve estar assim:
```python
#!/usr/bin/env python
# -*- coding: utf-8 -*-

utils = [
    'example_util'
]

def get(req, api):
    """
    Execute `python2 appp.py`
    E entre, pelo seu browser em `localhost:8888/example/ex_endpoint`
    Deverá abrir uma página escrita `sucesso!`

    Output:
        string
    """

    return api.example_util.write('sucesso!')

def post(req, api):
    """
    Execute `python2 appp.py`
    E faça uma requisição http post em `localhost:8888/example/ex_endpoint`
    passando o objeto documentado como entrada
    Deverá ser retornado `{"message": input.message, "status":"sucesso!"}`

    Input:
        message: string

    Output:
        message: string
        status: string
    """

    message = req.params['message']

    return api.example_util.write({
        'message': message,
        'status': 'sucessso!'
    })
``` 

Agora siga as instruções para testar e ver como funciona o endpoint.

---

## AGRADECIMENTOS

https://youtu.be/oAhvQoLpvsM

## OBSERVAÇÃO

Tanto a framework quanto essa página estão ainda em fase de desenvolvimento e, por tanto, sujeitos a mudança.

