hug
2.6.0
Leia a documentação mais recente - Procure o repositório de código do GitHub
O HUG visa simplificar o desenvolvimento de APIs impulsionadas pelo Python, mas não mais simples. Como resultado, simplifica drasticamente o desenvolvimento da API do Python.
Objetivos de design do HUG:
Torne o desenvolvimento de uma API impulsionada por Python tão sucinta quanto uma definição por escrito.
A estrutura deve incentivar o código que se auto-documentos.
Deve ser rápido. Um desenvolvedor nunca deve sentir a necessidade de procurar em outro lugar por razões de desempenho.
Os testes de escrita para APIs escritos no topo do abraço devem ser fáceis e intuitivos.
A mágica feita uma vez, em uma estrutura de API, é melhor do que empurrar o problema definido para o usuário da estrutura da API.
Seja a base para as APIs do Python da próxima geração, adotando a mais recente tecnologia.
Como resultado desses objetivos, o Hug é apenas o Python 3+ e construiu na biblioteca HTTP de alto desempenho da Falcon
Obtenha um abraço de suporte profissionalmente com a assinatura do Tidelift
O suporte profissional ao HUG está disponível como parte da assinatura do Tidelift. O Tidelift oferece às equipes de desenvolvimento de software uma única fonte para comprar e manter seu software, com garantias profissionais dos especialistas que o conhecem melhor, enquanto integrando perfeitamente as ferramentas existentes.
Instalar o abraço é tão simples quanto:
PIP3 Instale o abraço -upgrade
Idealmente, dentro de um ambiente virtual.
Crie uma API de exemplo com um ponto de extremidade simples em apenas algumas linhas.
# nome do arquivo: happy_birthday.py "" "Uma API básica (função única) escrita usando o abraço" "import [email protected] ('/happy_birthday') def happy_birthday (nome, idade: hug.types.number = 1): "" "Diz feliz aniversário para um usuário" "Retornar" feliz {idade} aniversário {nome}! ". Formato (** locals ()))
Para executar, a partir do tipo de linha de comando:
HAG -F happy_birthday.py
Você pode acessar o exemplo no seu navegador em: localhost:8000/happy_birthday?name=hug&age=1 . Em seguida, confira a documentação da sua API no localhost:8000/documentation
Os parâmetros também podem ser codificados no URL (confira happy_birthday.py para todo o exemplo).
@hug.get ('/greet/{event}') def greet (evento: str): "" "" -Greetings/) "" "Greetings =" feliz "se event ==" natal ": cumprimentos =" Merry "se event ==" kwanzaa ": cumprimentos =" Joyous "se event ==" desejos ": saudações =" Warm " "Return" {cumprimentos} {event}! ". Format (** Locals ()))Qual, depois de executar o servidor como acima, você pode usar da seguinte maneira:
curl http://localhost:8000/greet/wishes "Warm wishes!"
# FileName: Versioning_Example.py "" "Um exemplo simples de uma chamada API de abraço com versão" "importar [email protected] ('/echo', versions = 1) def echo (text): return [email protected] ('/eco', versions = range (2, 5)) def echo (text): retornar "eco: {text}". formato (** locais ())
Para executar o exemplo:
HUG -F Versioning_Example.py
Então você pode acessar o exemplo do localhost:8000/v1/echo?text=Hi / localhost:8000/v2/echo?text=Hi ou acesse a documentação para sua API do localhost:8000
Nota: A versão no HUG suporta automaticamente o cabeçalho da versão e a especificação direta baseada em URL.
Os decoradores do método http do HUG não modificam suas funções originais. Isso torna as APIs de abraço de teste tão simples quanto testar quaisquer outras funções do Python. Além disso, isso significa interagir com suas funções da API em outro código Python é tão direto quanto chamando as funções da API Python. O abraço facilita testar a pilha completa do Python da sua API usando o módulo hug.test :
importar happy_birthdayhug.test.get (happy_birthday, 'happy_birthday', {'name': 'timothy', 'idade': 25}) # retorna um objeto de resposta Você pode usar este objeto Response para asserções de teste (confira test_happy_birthday.py ):
def tests_happy_birthday (): resposta = hug.test.get (happy_birthday, 'happy_birthday', {'name': 'timothy', 'idade': 25}) afirmam resposta.status == http_200ssert Response.data não é nenhum HUG expõe um método mágico __hug_wsgi__ em todos os módulos API automaticamente. Executar sua API baseada em HUG em qualquer servidor WSGI padrão deve ser tão simples quanto apontá -la para module_name : __hug_wsgi__ .
Por exemplo:
UWSGI--HTTP 0.0.0.0:8000-Exemplos de arquivo-wsgi/hello_world.py-Callable __hug_wsgi__
Para executar a API Hello World Hug Exemplo.
Ao criar uma API usando a estrutura do abraço, você usará os seguintes conceitos:
Os decoradores de métodos get , post , update , etc. Decoradores de métodos HTTP que expõem sua função python como uma API, mantendo seu método python inalterado
@hug.get () # <- é o método de abraço decoratordef hello_world (): retornar "hello"
O HUG usa a estrutura da função que você decora para gerar automaticamente a documentação para os usuários da sua API. O abraço sempre passa uma variável de solicitação, resposta e api_version para sua função se eles forem definidos parâmetros em sua definição de função.
Tipo de anotações funções que opcionalmente são anexadas aos seus métodos argumentos para especificar como o argumento é validado e convertido em um tipo python
@hug.get () def math (número_1: int, número_2: int): #the: int após os dois argumentos é o tipo de anotação número_1 + number_2
As anotações de tipo também alimentam a geração automática de documentação do hug para que os usuários da sua API saibam quais dados fornecer.
Funções das diretivas que são executadas com os dados de solicitação / resposta com base em serem solicitados como um argumento em sua API_FUNCTION. Eles se aplicam apenas como parâmetros de entrada e não podem ser aplicados atualmente como formatos ou transformações de saída.
@hug.get () def test_time (hug_timer): return {'time_taken': float (hug_timer)} As diretivas podem ser acessadas por meio de um argumento com um prefixo hug_ ou usando anotações do tipo Python 3. Este último é a abordagem mais moderna e é recomendada. As diretivas declaradas em um módulo podem ser acessadas usando seu nome totalmente qualificado como anotação de tipo (ex: module.directive_name ).
Além do caso de uso óbvio de transformação de entrada, as diretivas podem ser usadas para colocar dados em suas funções da API, mesmo que não estejam presentes na sequência de consulta de solicitação, pós -corpo, etc. Para um exemplo de como usar as diretrizes dessa maneira, Veja o exemplo de autenticação na pasta Exemplos.
Adicionar suas próprias diretivas é direto:
@hug.directive () def square (value = 1, ** kwargs): '' 'Retornos passados no parâmetro multiplicados por si mesmo' '' Valor de retorno *[email protected] ()@hug.local () def tester ( Valor: Square = 10): Return valuetester () == 100
Para completude, aqui está um exemplo de acesso à diretiva através da abordagem de nome mágico:
@hug.directive () def multiply (value = 1, ** kwargs): '' 'Retornos passados em parâmetros multiplicados por si mesmo' '' Valor de retorno *[email protected] ()@hug.local () def tester ( hug_multiply = 10): retornar hug_multiplytester () == 100
A saída formates uma função que leva a saída da sua função da API e a formata para transporte para o usuário da API.
@hug.default_output_format () def my_output_formatter (data): return "string: {0}". mundo'}Como mostrado, você pode alterar facilmente o formato de saída para uma API inteira, bem como uma chamada de API individual
A entrada formates uma função que leva o corpo de dados fornecidos de um usuário da sua API e o formam para manuseio.
@hug.default_input_format ("Application/json") def My_input_formatter (Data): return ('Results', hug.input_format.json (dados)) Os formatados de entrada são mapeados com base no content_type dos dados da solicitação e executam apenas a análise básica. A análise mais detalhada deve ser feita pelas anotações de tipo presente em sua api_function
Funções de middleware que são chamadas para todos os pedidos de um abraço de processos da API
@hug.request_middleware () def process_data (request, resposta): request.env ['server_name'] = 'alterações'@hug.rosponse_middleware () def process_data (solicitação, resposta, recurso): resposta.set_header (' myHeader ', 'Valor')Você também pode adicionar facilmente qualquer middleware do estilo Falcon usando:
__hug __. http.add_middleware (middlewareObject ())
O mapeamento de parâmetros pode ser usado para substituir nomes de parâmetros inferidos, por exemplo. Para palavras -chave reservadas:
importar marshmallow.fields como campos [email protected] ('/foo', map_params = {'de': 'from_date'}) # API Call usa 'de'def get_foo_by_date (from_date: fields.dateTime ()): Retorne Find_foo (From_date)
Os formatados de entrada são mapeados com base no content_type dos dados da solicitação e executam apenas a análise básica. A análise mais detalhada deve ser feita pelas anotações de tipo presente em sua api_function
O abraço permite que você organize grandes projetos da maneira que achar melhor. Você pode importar qualquer módulo que contenha funções decoradas de abraço (manuseio de solicitações, diretrizes, manipuladores de tipo, etc.) e estender sua API básica com esse módulo.
Por exemplo:
something.py
importar [email protected] ('/') def say_hi (): retornar 'olá de algo'
Pode ser importado para o arquivo API principal:
__init__.py
importar hagfrom. Importar [email protected] ('/') def say_hi (): retornar "hi from root"@hug.extend_api ('/something') def algo_api (): retornar [algo]
Ou alternativamente - para casos como este - onde apenas um módulo está sendo incluído de acordo com uma rota de URL:
#alternativamentehug.api (__ nome __).
Por padrão, o HUG retorna uma especificação de API gerada automaticamente quando um usuário tenta acessar um terminal que não é definido. Se você não gostaria de retornar esta especificação, pode desativar a documentação 404:
No aplicativo da linha de comando:
HUG -ND -F {FILE} #nd Flag Diz Hug não para gerar documentação em 404 Além disso, você pode criar facilmente um manipulador 404 personalizado usando o hug.not_found Decorator:
@hug.not_found () def not_found_handler (): retornar "não encontrado"
Este decorador funciona da mesma maneira que os decoradores HTTP HTTP abraçados, e está ciente da versão:
@hug.not_found (versions = 1) def not_found_handler (): return
Ao usar o Decorador de Método get e cli em Coroutines, o HUG agende a execução da coroutina.
Usando o Asyncio Coroutine Decorator
@hug.get ()@asyncio.coroutinedf hello_world (): retornar "hello"
Usando a palavra -chave Python 3.5 ASYNC.
@hug.get () assync def hello_world (): retornar "hello"
Nota: O HUG está sendo executado no topo Falcon, que não é um servidor assíncrono. Mesmo se usar o Asyncio, as solicitações ainda serão processadas de maneira síncrona.
Se você gosta de desenvolver no Docker e manter seu sistema limpo, pode fazer isso, mas precisará primeiro instalar o Docker Compose.
Depois de fazer isso, você precisará cd no diretório docker e executar o servidor da web (Gunicorn) especificado em ./docker/gunicorn/Dockerfile , após o que você pode visualizar a saída da sua API no navegador no seu Máquina de host.
$ CD ./docker# Isso será executado no Gunicorn na porta 8000 do contêiner do docker. Linux: $ ifconfig Docker0 | Grep 'Inet' | corte -d: -f2 | awk '{print $ 1}' | Cabeça -n1 Por padrão, o IP é 172.17.0.1. Supondo que esse seja o IP que você vê também, você iria para http://172.17.0.1:8000/ no seu navegador para visualizar sua API.
Você também pode fazer login em um contêiner do Docker que você pode considerar seu espaço de trabalho. Este espaço de trabalho possui o Python e o PIP instalado para que você possa usar essas ferramentas no Docker. Se você precisar testar a interface da CLI, por exemplo, você usaria isso.
$ Docker-Compose Run Workspace Bash
No seu contêiner Docker workspace , o diretório ./docker/templates no seu computador host é montado para /src no recipiente do docker. Isso é especificado em services > app de ./docker/docker-compose.yml .
Bash-4.3# CD /SRC
BASH-4.3# TREE.├── __init__.py
└── Manipuladores
├── Birthday.py
└── Hello.py
1 diretório, 3 arquivosO abraço leva segurança e qualidade a sério. Esse foco é o motivo pelo qual dependemos apenas de componentes minuciosamente testados e utilizamos ferramentas de análise estática (como bandidos e segurança) para verificar a segurança de nossa base de código. Se você encontrar ou encontrar algum problema de segurança em potencial, informe -nos imediatamente para que possamos resolvê -los.
Para relatar uma vulnerabilidade de segurança, use o contato de segurança Tidelift. O Tidelift coordenará a correção e a divulgação.
O abraço simplesmente significa guia esperançosamente útil. Isso representa o objetivo do projeto de ajudar a orientar os desenvolvedores a criar APIs bem escritas e intuitivas.
Obrigado e espero que você ache este abraço útil ao desenvolver sua próxima API do Python!
~ Timothy Crosley
