hug
2.6.0
Lea la última documentación: navegar por el repositorio de código GitHub
Hug tiene como objetivo hacer que el desarrollo de API impulsadas por Python sea lo más simple posible, pero no es más simple. Como resultado, simplifica drásticamente el desarrollo de la API de Python.
Objetivos de diseño de Hug:
Haga que el desarrollo de una API impulsada por Python sea tan sucinta como una definición escrita.
El marco debe alentar el código que se autodocumenta.
Debería ser rápido. Un desarrollador nunca debe sentir la necesidad de buscar en otro lugar por razones de rendimiento.
Las pruebas de escritura para API escritas en el abrazo deben ser fáciles e intuitivas.
La magia hecha una vez, en un marco API, es mejor que presionar el problema establecido al usuario del marco API.
Sea la base de las API de Python de próxima generación, adoptando la última tecnología.
Como resultado de estos objetivos, Hug es solo Python 3+ y se basa en la biblioteca HTTP de alto rendimiento de Falcon
Obtenga un abrazo profesionalmente apoyado con la suscripción de TidElift
El apoyo profesional para Hug está disponible como parte de la suscripción de TidElift. TidElift ofrece a los equipos de desarrollo de software una fuente única para comprar y mantener su software, con garantías de calificaciones profesionales de los expertos que lo conocen mejor, al tiempo que se integran sin problemas con las herramientas existentes.
Instalar abrazo es tan simple como:
PIP3 Instalar abrazo -Upgrade
Idealmente, dentro de un entorno virtual.
Cree una API de ejemplo con un punto final simple en solo unas pocas líneas.
# FileName: Happy_birthday.py "" "Una API básica (función única) escrita usando el abrazo" "" import [email protected] ('/Happy_birthday') def happy_birthday (nombre, edad: hug.types.number = 1): "" "Dice feliz cumpleaños a un usuario" "" return "feliz {edad} cumpleaños {nombre}!". Format (** locales ())
Para ejecutarse, desde el tipo de línea de comando:
abrazo -f happy_birthday.py
Puede acceder al ejemplo en su navegador en: localhost:8000/happy_birthday?name=hug&age=1 . Luego, consulte la documentación de su API en localhost:8000/documentation
Los parámetros también se pueden codificar en la URL (consulte happy_birthday.py para obtener todo el ejemplo).
@hug.get ('/greet/{event}') def greet (evento: str): "" "Greets apropiadamente (de http://blog.ketchum.com/how-to-write-10common-holiday vidental -greetings/) "" "Greetings =" Happy "if Event ==" Christmas ": Greetings =" Merry "if Event ==" Kwanzaa ": Greetings =" Joyous "If Event ==" Deseos ": Saludos =" cálido "Return" {Greetings} {Event}! ". Format (** locals ())Que, una vez que ejecuta el servidor como se indica, puede usar de esta manera:
curl http://localhost:8000/greet/wishes "Warm wishes!"
# FileName: versioning_example.py "" "Un ejemplo simple de una llamada de API de abrazo con la versión" "" Importar [email protected] ('/echo', versiones = 1) def echo (texto): return [email protected] ('/echo', versiones = rango (2, 5)) def echo (texto): return "echo: {text}". format (** locals ())
Para ejecutar el ejemplo:
abrazo -f versión_example.py
Entonces puede acceder al ejemplo desde localhost:8000/v1/echo?text=Hi / localhost:8000/v2/echo?text=Hi o acceder a la documentación de su API desde localhost:8000
Nota: El versículo en Hug es compatible automáticamente tanto el encabezado de la versión como la especificación basada en URL directa.
Los decoradores del método http de HTTP no modifican sus funciones originales. Esto hace que las API de abrazo de abrazo sean tan simples como probar cualquier otra función de Python. Además, esto significa que interactuar con sus funciones API en otro código de Python es tan sencillo como llamar a las funciones de API de Python. Hug hace que sea fácil probar la pitina de Python completa de su API usando el módulo hug.test :
import hugimport happy_birthdayhug.test.get (happy_birthday, 'happy_birthay', {'name': 'timothy', 'edad': 25}) # Devuelve un objeto de respuesta Puede usar este objeto Response para las afirmaciones de prueba (consulte test_happy_birthday.py ):
def tests_happy_birthday (): respuesta = hug.test.get (happy_birthay, 'happy_birtday', {'name': 'timothy', 'edad': 25}) afirmar respuesta.status == http_200assert.data no es ninguno no es ninguno El abrazo expone un método mágico __hug_wsgi__ en cada módulo API automáticamente. Ejecutar su API basada en abrazo en cualquier servidor WSGI estándar debe ser tan simple como señalarla a module_name : __hug_wsgi__ .
Por ejemplo:
UWSGI--HTTP 0.0.0.0:8000-WSGI-File Ejemplos/Hello_world.py --Callable __hug_wsgi__
Para ejecutar la API de Hello World Hug Ejemplo.
Al construir una API usando el marco de abrazo, usará los siguientes conceptos:
Los decoradores de métodos get , post , update , etc. Decoradores de métodos HTTP que exponen su función de Python como una API mientras mantienen su método Python sin cambios
@hug.get () # <- es el método de abrazo decoratordef hello_world (): return "hola"
Hug utiliza la estructura de la función que decora para generar automáticamente la documentación para los usuarios de su API. El abrazo siempre pasa una variable de solicitud, respuesta y api_version a su función si son parámetros definidos en la definición de su función.
Tipo de anotaciones Funciones que opcionalmente se adjuntan a sus métodos argumentos para especificar cómo el argumento se valida y se convierte en un tipo de python
@hug.get () def Math (number_1: int, number_2: int): #the: int después de ambos argumentos es el tipo annotationreturn number_1 + number_2
Las anotaciones de tipo también alimentan la generación de documentación automática de hug para que los usuarios de su API sepan qué datos suministrar.
Las funciones de las directivas que se ejecutan con los datos de solicitud / respuesta basados en ser solicitados como un argumento en su API_Function. Estos se aplican solo como parámetros de entrada, y no se pueden aplicar actualmente como formatos de salida o transformaciones.
@hug.get () def test_time (hug_timer): return {'time_taken': float (hug_timer)} Se puede acceder a las directivas a través de un argumento con un prefijo hug_ , o mediante el uso de anotaciones de tipo Python 3. Este último es el enfoque más moderno y se recomienda. Se puede acceder a las directivas declaradas en un módulo utilizando su nombre totalmente calificado como la anotación tipo (ex: module.directive_name ).
Además del obvio caso de uso de transformación de entrada, las directivas se pueden usar para conectar datos en sus funciones de API, incluso si no están presentes en la cadena de consulta de solicitud, el cuerpo posterior, etc. para un ejemplo de cómo usar las directivas de esta manera, Vea el ejemplo de autenticación en la carpeta de ejemplos.
Agregar sus propias directivas es sencillo:
@hug.directive () def square (valor = 1, ** kwargs): '' 'retornos aprobados en parámetro multiplicado por sí mismo' '' Valor de retorno *[email protected] ()@hug.local () def tester ( Valor: cuadrado = 10): return valuetester () == 100
Para completar, aquí hay un ejemplo de acceder a la directiva a través del enfoque de nombre mágico:
@hug.directive () def multiply (valor = 1, ** kwargs): '' 'retornos aprobados en parámetro multiplicado por sí mismo' '' Valor de retorno *[email protected] ()@hug.local () def tester ( hug_multiply = 10): return hug_multiplytester () == 100
La salida forma una función que toma la salida de su función API y la formatea para el transporte al usuario de la API.
@hug.default_output_format () def my_output_formatter (data): return "String: {0}". Format (data)@hug.get (output = hug.output_format.json) def hello (): return {'hola': ' mundo'}Como se muestra, puede cambiar fácilmente el formato de salida tanto para una API completa como para una llamada de API individual
La entrada forma una función que toma el cuerpo de datos dado a un usuario de su API y lo formatea para manejar.
@hug.default_input_format ("aplicación/json") def my_input_formatter (datos): return ('resultados', hug.input_format.json (datos))) Los formateros de entrada se asignan en función del content_type de los datos de solicitud, y solo realizan un análisis básico. Se debe realizar un análisis más detallado mediante las anotaciones de tipo presentes en su api_function
Funciones de middleware que se requieren para cada solicitud de procesos de API de abrazo
@hug.request_middleware () def process_data (solicitud, respuesta): request.env ['server_name'] = 'cambia'@hug.response_middleware () def process_data (solicitud, respuesta, recursos): respuesta.set_header (' myheader ',,,, 'Valor')También puede agregar fácilmente cualquier middleware estilo Falcon usando:
__hug __. http.add_middleware (middlewareObject ())
El mapeo de parámetros se puede usar para anular los nombres de los parámetros inferidos, por ejemplo. Para palabras clave reservadas:
import marshmallow.fields como campos [email protected] ('/foo', map_params = {'from': 'from_date'}) # api la llamada usa 'from'def get_foo_by_date (from_date: fields.datetime ():):): return find_foo (from_date)
Los formateros de entrada se asignan en función del content_type de los datos de solicitud, y solo realizan un análisis básico. Se debe realizar un análisis más detallado mediante las anotaciones de tipo presentes en su api_function
Hug le permite organizar grandes proyectos de cualquier manera que mejor le parezca. Puede importar cualquier módulo que contenga funciones decoradas de abrazo (manejo de solicitudes, directivas, tipo manejadores, etc.) y extienda su API base con ese módulo.
Por ejemplo:
something.py
Importar [email protected] ('/') def say_hi (): Devuelve 'hola de algo'
Se puede importar al archivo API principal:
__init__.py
Importar abrazo. Importar [email protected] ('/') def say_hi (): return "Hi de root"@hug.extend_api ('/something') def something_api (): return [something]
O alternativamente, para casos como este, donde solo se incluye un módulo por ruta URL:
#alternativamentehug.api (__ nombre __). extender (algo, '/algo')
De forma predeterminada, Hug devuelve una especificación API generada automáticamente cuando un usuario intenta acceder a un punto final que no está definido. Si no desea devolver esta especificación, puede desactivar la documentación 404:
Desde la aplicación de la línea de comandos:
Hug -nd -f {File} #ND Flag le dice a Hug que no genere documentación en 404 Además, puede crear fácilmente un manejador 404 personalizado usando el decorador hug.not_found :
@hug.not_found () def non_found_handler (): return "no encontrado"
Este decorador funciona de la misma manera que los decoradores de métodos HTTP HTTP, e incluso está al tanto de la versión:
@hug.not_found (versions = 1) def not_found_handler (): return ""@hug.not_found (versiones = 2) def non_found_handler (): return "no encontrado"
Al usar el Decorador de métodos get y cli en Coroutinas, Hug programará la ejecución de la Coroutina.
Usando el decorador de Coroutine de Asyncio
@hug.get ()@asyncio.coroutinedef hello_world (): return "hola"
Uso de la palabra clave Python 3.5 Async.
@hug.get () async def hello_world (): return "hola"
Nota: Hug se ejecuta en Top Falcon, que no es un servidor asíncrono. Incluso si usa Asyncio, las solicitudes aún se procesarán sincrónicamente.
Si desea desarrollarse en Docker y mantener su sistema limpio, puede hacerlo, pero primero deberá instalar Docker Compose.
Una vez que haya hecho eso, deberá cd en el directorio docker y ejecutar el servidor web (Gunicorn) especificado en ./docker/gunicorn/Dockerfile , después de lo cual puede obtener una vista previa de la salida de su API en el navegador de su máquina anfitriona.
$ CD ./docker# Esto ejecutará Gunicorn en el puerto 8000 del contenedor Docker. $ Docker-compuesto up gunicorn# Desde la máquina host, encuentre la dirección IP de sus Dockers.# para Windows & Mac: $ Docker-Machine IP# para Linux: $ ifconfig Docker0 | Grep 'inet' | CUT -D: -F2 | Awk '{imprimir $ 1}' | cabeza -n1 Por defecto, la IP es 172.17.0.1. Suponiendo que esa sea la IP que ves, también, irías a http://172.17.0.1:8000/ en tu navegador para ver tu API.
También puede iniciar sesión en un contenedor Docker que pueda considerar su espacio de trabajo. Este espacio de trabajo tiene Python y PIP instalados para que pueda usar esas herramientas dentro de Docker. Si necesita probar la interfaz CLI, por ejemplo, lo usaría.
$ Docker-Compose Run Workspace Bash
En su contenedor Docker workspace , el directorio ./docker/templates en su computadora host está montado a /src en el contenedor Docker. Esto se especifica en services > app de ./docker/docker-compose.yml .
Bash-4.3# CD /SRC
bash-4.3# árbol.├── __init__.py
Manyadores
├── Cumpleaños.py
└iqute Hello.py
1 directorio, 3 archivosHug toma en serio la seguridad y la calidad. Este enfoque es la razón por la que dependemos solo de componentes completamente probados y utilizamos herramientas de análisis estático (como bandidos y seguridad) para verificar la seguridad de nuestra base de código. Si encuentra o encuentra problemas potenciales de seguridad, háganoslo saber de inmediato para que podamos resolverlos.
Para informar una vulnerabilidad de seguridad, utilice el contacto de seguridad de TidElift. TidElift coordinará la solución y la divulgación.
Hug simplemente representa una guía útil con suerte. Esto representa el objetivo del proyecto para ayudar a guiar a los desarrolladores a crear API bien escritas e intuitivas.
¡Gracias y espero que encuentres este abrazo útil mientras desarrollas tu próxima API de Python!
~ Timothy Crosley
