Categorías
Python

Código Python documentar: Una guía completa

 

Tabla de Contenidos

  • Cómo hacer amigos e influir sobre las API
  • Hablar RESTO
  • la construcción de una biblioteca API
  • Viniendo en la parte 2
  • Apéndice: descansar en una cáscara de nuez

El siguiente es un puesto de invitado por Aaron Maxwell, autor de livecoding un servidor API REST.

Cómo hacer amigos e influir sobre las API

Cada vez más, todos estamos escribiendo código que funciona con las API remotas. Su magnífica nueva aplicación obtiene una lista de amigos de su cliente, o va a buscar las coordenadas de la cercana nocturno burrito articulaciones, o se pone en marcha un servidor de la nube, o cobra una tarjeta de crédito … se entiende la idea. Todo esto ocurre simplemente al hacer una solicitud HTTPS.

(Por lo menos, espero que sea HTTPS. Por favor, no use HTTP plano. Pero eso es un tema diferente.)

Entonces, ¿cómo utilizar esto en su código? Lo ideal sería que la gente detrás del servicio web proporcionará un SDK o biblioteca que hace todo lo anterior lo que sólo puede “pip instalar openburrito-SDK”, o algo así, y acaba de empezar a utilizar sus funciones y los métodos para encontrar nocturno burrito articulaciones inmediatamente . Entonces no tendrá que lidiar con la fabricación de las peticiones HTTP en absoluto.

eso no es siempre disponible, sin embargo, especialmente si está utilizando una API desarrollada internamente, lo cual es muy común cuando la arquitectura se basa en microservicios o tratando de basarse en microservicios.

eso es lo que trata este artículo: escribir código Python para integrarse con REST API, de manera que sea lo más divertido, fácil y rápido como sea posible, y hace que se vea bien lo hace! Bono (con suerte).

gratuito: Haga clic aquí para descargar una copia del «reposo en una cáscara de nuez» guía con una introducción práctica a los principios y ejemplos de la API REST.

sonido excitante? Grande, vamos a empezar!

Hablar RESTO

En primer lugar, si usted no está seguro de lo que significa la frase “REST API”, salto al apéndice para un curso acelerado.

Entendido? Bueno, vamos a seguir adelante. Hay muchas maneras en las que este tipo de servicios web se pueden organizar y muchos formatos en los que se lo puede transmitir datos y luego volver a obtener otros datos. En este momento, es muy popular para hacer su API REST, o al menos dicen que es reparador. En cuanto a devolver los datos a otro, el formato JSON es muy popular.

Trágicamente, hasta ahora han fracasado en mi campaña para convencer a todos a utilizar YAML en lugar de JSON. A pesar de este contratiempo desgarrador, hay un resquicio de esperanza: los mismos principios fundamentales se aplican a cualquier API HTTP, usando cualquier formato de datos.

Los ejemplos siguientes serán de una API REST, usando JSON. Pero lo que está a punto de aprender se aplicará cuando yo pudiere, y todos estamos utilizando alegremente YAML. También se aplica a los formatos XML o datos personalizados, así como arquitecturas de ONU-REST. Incluso te permite trabajar el próximo año, cuando estamos todos de correo electrónico a través de la comprobación de los implantes neurales telepáticas! el uso de un ejemplo concreto de

Let. Imagine una lista de tareas pendientes de la API, el seguimiento de sus elementos de acción en su camino hacia el éxito. Aquí están sus métodos y criterios de valoración:

  • GET / tareas / devolverá una lista de elementos en la lista de tareas pendientes, con el siguiente formato: { «id»: ««, «Resumen»: « «}
  • GET / tareas / / Recuperar toda la información disponible para un determinado elemento de tarea, en el siguiente formato: { «id»: ««, «resumen»:» «, ‘Descripción’: ‘‘}
  • de POST / tareas / Crear un nuevo elemento de tarea. La cuerpo POST es un objeto de JSON con dos campos: “Resumen” (debe ser menos de 120 caracteres, no nueva línea), y “Descripción” (campo de texto de forma libre). En caso de éxito, el código de estado es de 201, y el cuerpo de la respuesta es un objeto con un campo: el identificador creado por el servidor (por ejemplo, { «id»: 3792}).
  • BORRAR / tareas / / Marcar el artículo como hecho: la huelga fuera de la lista por lo que se interponen / tareas / no mostrarlo. El cuerpo de la respuesta está vacía.
  • PUT / tareas / / Modificar una tarea existente. El cuerpo PUT es un objeto JSON con dos campos: resumen (debe ser menos de 120 caracteres, no nueva línea), y la descripción (campo de texto de forma libre).

GET / tareas /

devolver una lista de elementos en la lista de cosas por hacer, en el siguiente formato:

{
"id": "",
"summary": ""
}

GET / tareas / /

Fetch toda la información disponible para una específica a-do artículo, con el siguiente formato:

{
"id": "",
"summary": "",
"description" : ""
}

de POST / tareas /

Crear un nuevo elemento de tarea. La cuerpo POST es un objeto de JSON con dos campos: “Resumen” (debe ser menos de 120 caracteres, no nueva línea), y “Descripción” (campo de texto de forma libre). En caso de éxito, el código de estado es de 201, y el cuerpo de la respuesta es un objeto con un campo: el identificador creado por el servidor (por ejemplo, { «id»: 3792}).

BORRAR / tareas / /

marca el artículo como hecho: la huelga fuera de la lista por lo que se interponen / tareas / no mostrarlo. El cuerpo de la respuesta está vacía.

PUT / tareas / /

modificar una tarea existente. El cuerpo PUT es un objeto JSON con dos campos: resumen (debe ser menos de 120 caracteres, no nueva línea), y la descripción (campo de texto de forma libre).

Nota: A menos que se indique lo contrario, todas las acciones de retorno 200 en el éxito; aquellos referencia a un identificador de tarea de retorno 404, si no se encuentra la ID. El cuerpo de la respuesta está vacía salvo que se especifique lo contrario. Todos los organismos de respuesta no vacíos son JSON. Todas las acciones que tienen un cuerpo de solicitud son JSON (no forma a codificar).

Grande. Ahora, ¿cómo interactúan con esta cosa? En Python, tenemos la suerte de tener una excelente biblioteca de HTTP: Kenneth solicitudes Reitz’. Es una de las pocas proyectos por valor de tratar como si fuera parte de la biblioteca estándar:

# Step one for every Python app that talks over the web
$ pip install requests

Esta es su principal herramienta para escribir código Python utilizar las API REST-o cualquier servicio expuesto a través de HTTP, para el caso. Se pone todos los detalles de la derecha, y tiene una forma brillante elegante y fácil de usar interfaz. Tú entiendes. Voy a dejar con la alabanza que brota ahora, y le mostrará cómo usarlo. digamos de

Let desea obtener una lista de elementos de acción, a través de la GET / tareas / punto final:

import requests

resp = requests.get('https:/odolist.example.comasks/')
if resp.status_code != 200:
# This means something went wrong.
raise ApiError('GET asks/ {}'.format(resp.status_code))
for todo_item in resp.json():
print('{} {}'.format(todo_item['id'], todo_item['summary']))

observa lo siguiente:

  • las solicitudes módulo tiene una llamada get función que hace un HTTP GET.
  • El objeto de respuesta tiene un método llamado JSON. Esto toma el cuerpo de la respuesta del servidor-a-secuencia de bytes y la transforma en una lista de Python de diccionarios, à la json.loads ().

Después de algunas comprobaciones de errores y procesamiento mínimo, lo que se obtiene de la llamada a la API es una lista de diccionarios de Python, cada uno representando una sola tarea. A continuación, puede procesar esta como desee (imprimirlos, por ejemplo).

Ahora supongamos que quiero crear una nueva tarea: añadir algo a mi lista de cosas por hacer. En nuestra API, esto requiere un HTTP POST. Comienzo por la creación de un diccionario de Python con los campos necesarios, “Resumen” y “Descripción”, que definen la tarea. Recuerde cómo los objetos de respuesta tienen un método conveniente .json ()? Podemos hacer algo similar en la otra dirección:

task = {"summary": "Take out trash", "description": "" }
resp = requests.post('https:/odolist.example.comasks/', json=task)
if resp.status_code != 201:
raise ApiError('POST asks/ {}'.format(resp.status_code))
print('Created task. ID: {}'.format(resp.json()["id"]))

observa lo siguiente:

  • pide sensatez proporciona una función llamada posterior, lo que hace un HTTP POST. Estimado Señor, ¿por qué no todas las bibliotecas HTTP será este cuerdo?
  • La función posterior toma un argumento JSON, cuyo valor aquí es un diccionario de Python (tarea).
  • Por la especificación API REST y mejores prácticas, sabemos que la tarea se crea debido al código 201 de respuesta.

Ahora, ya que estamos utilizando JSON como nuestro formato de datos, hemos sido capaces de tomar un buen atajo aquí: el argumento JSON para enviar entradas. Si usamos eso, las solicitudes harán lo siguiente para nosotros: Convertir

  • que en una cadena representación JSON, a la json.dumps ()
  • Conjunto tipo de contenido de las solicitudes de los de ‘application / json’ (mediante la adición de un HTTP encabezamiento).

Si está utilizando algo que no sea JSON (algunos formato personalizado, favorito XML, o de todos, YAML) entonces needto hacer esto manualmente, lo que es un poco más de trabajo. Así es como se ve:

# The shortcut
resp = requests.post('https:/odolist.example.comasks/', json=task)
# The equivalent longer version
resp = requests.post('https:/odolist.example.comasks/',
data=json.dumps(task),
headers={'Content-Type':'application/json'},

Utilizamos el argumento de datos ahora: así es como se especifica el contenido del cuerpo de la POST. Como se puede ver, requests.post toma un argumento opcional encabezados: un diccionario. Esto se suma cada tecla como un nuevo campo de encabezado a la solicitud. get () y los demás todos aceptan este argumento también, por cierto.

Construcción de una biblioteca API

Si usted está haciendo nada más que unas pocas llamadas a la API, tendrá que hacer su propia biblioteca para mantenerse cuerdo. Por supuesto, esto también se aplica si usted es el que proporciona la API y quieren desarrollar esa biblioteca para que la gente pueda usar su servicio.

La estructura de la biblioteca depende del modo de autenticación de API, si lo hace en absoluto. Por el momento, vamos a ignorar la autenticación, para obtener la estructura básica. A continuación, vamos a ver cómo instalar la capa de autenticación.

mirada de nuevo en la descripción API anteriormente. ¿Cuáles son las acciones y servicios que proporciona específicos? En otras palabras, ¿cuáles son algunas de las cosas que nos permite hacer?

  • podemos obtener una lista resumida de las tareas que hay que hacer.
  • Podemos obtener mucha más información detallada acerca de una tarea específica.
  • se puede añadir una nueva tarea a nuestra lista de cosas por hacer.
  • Nos puede marcar una tarea como hecha.
  • podemos modificar una tarea existente (cambiando su descripción, y así sucesivamente).

En lugar de pensar acerca de HTTP puntos finales, podemos crear nuestra propia API interna basada en estos conceptos. Esto nos permite integrar más fácilmente la lógica de uso de la API en nuestro código, sin ser distraído por los detalles. inicio de

Vamos con la cosa más simple que podría funcionar. Voy a crear un archivo llamado todo.py, definiendo las siguientes funciones:

# todo.py
def get_tasks():
pass
def describe_task(task_id):
pass
def add_task(summary, description=""):
pass
def task_done(task_id):
pass
def update_task(task_id, summary, description):
pass

notar algunas decisiones de diseño que hice aquí:

  • Todos los parámetros son explícitas. Para update_task (), por ejemplo, tengo tres argumentos, en lugar de un único diccionario con tres teclas.
  • En add_task (), preveo que a veces tendrá que crear una tarea con la elaboración sólo un resumen field- “obtener leche” en realidad no necesitan, por ejemplo, por lo que dar una descripción por defecto sensible.
  • Estos son funciones en un módulo. Esa es una organización útil en Python. (En Java, que tendría que crear una clase con métodos, por ejemplo.)

Todos los parámetros son explícitas. Para update_task (), por ejemplo, tengo tres argumentos, en lugar de un único diccionario con tres teclas.

En add_task (), preveo que a veces tendrá que crear una tarea con la elaboración sólo un resumen field- “obtener leche” en realidad no necesitan, por ejemplo, por lo que dar una descripción por defecto sensible.

Estos son funciones en un módulo. Esa es una organización útil en Python. (En Java, que tendría que crear una clase con métodos, por ejemplo.)

Para llenar estos fuera, voy a definir un ayudante:

def _url(path):
return 'https:/odo.example.com' + path

Esto se construye la URL completa para realizar la llamada API, relativa a la ruta. Con esto, la aplicación de la isstraightforward ayudante:

import requests

def get_tasks():
return requests.get(_url('asks/'))

def describe_task(task_id):
return requests.get(_url('asks/{:d}/'.format(task_id)))

def add_task(summary, description=""):
return requests.post(_url('asks/'), json={
'summary': summary,
'description': description,
})

def task_done(task_id):
return requests.delete(_url('asks/{:d}/'.format(task_id)))

def update_task(task_id, summary, description):
url = _url('asks/{:d}/'.format(task_id))
return requests.put(url, json={
'summary': summary,
'description': description,
})

puedo utilizar este modo:

import todo

resp = todo.add_task("Take out trash")
if resp.status_code != 201:
raise ApiError('Cannot create task: {}'.format(resp.status_code))
print('Created task. ID: {}'.format(resp.json()["id"]))

resp = todo.get_tasks()
if resp.status_code != 200:
raise ApiError('Cannot fetch all tasks: {}'.format(resp.status_code))
for todo_item in resp.json():
print('{} {}'.format(todo_item['id'], todo_item['summary']))

en cuenta que cada una de mis funciones de biblioteca devuelve un objeto de respuesta, al igual que requests.get y amigos. Esto es a menudo una opción útil. En general, cuando se trabaja con las API, tendrá que inspeccionar el código de estado y la carga útil (de resp.json () en este caso). El objeto de respuesta proporciona un fácil acceso a este, y otra información que pueda necesitar, pero no anticipó cuando por primera vez la biblioteca.

Usted podría estar pensando que esto es la exposición de los detalles de implementación. ¿No sería mejor construir algún tipo de clase ApiResponse que proporciona la información necesaria a través de una interfaz más explícito? Mientras que a veces puede ser el mejor enfoque, he encontrado más a menudo que sea el exceso de ingeniería.

Yo recomiendo que empiece con sólo devolver los objetos sencillos de respuesta. Si, posteriormente, es necesario instalar una capa de abstracción respuesta, sabrá cuando llegue el momento.

Viniendo en la parte 2

Su cabeza puede estar nadando un poco ahora, y no sólo debido a las sugerencias subliminales que he codificada en todo el CSS fondo, exaltando las virtudes de YAML!

Hemos cubierto mucho terreno importante aquí, sólidamente arraigada en los modernos mejores prácticas de ingeniería. Bono

gratuito: Haga clic aquí para descargar una copia de los «Ejemplos» API REST Guía y obtener una introducción práctica a principios del API Python + REST con ejemplos de acciones concretas.

Todavía hay más por venir. Parte 2 se extenderá nuestro trabajo para hacer frente a la paginación, o conseguir grandes masas de datos que tienen múltiples peticiones para buscar, autenticación y fiabilidad, en otras palabras, se trata de las API de hojaldre. Para ser notificado cuando está en línea, suscribirse a la Newsletter Python avanzada.

Esté seguro también echa un vistazo a los cursos real Python para aprender cómo diseñar APIs REST con tanto Frasco y Django.

Apéndice: descansar en una cáscara de nuez

REST es esencialmente un conjunto de convenciones útiles para estructurar una API web. Por “API web”, me refiero a una API que interactúan con más HTTP, haciendo peticiones a URL específicas, y con frecuencia volver a los datos relevantes en la respuesta.

Hay libros enteros escritos sobre este tema, pero les puede dar un comienzo rápido aquí. En HTTP, tenemos diferentes “métodos”, como se les llama. GET y POST son los más comunes; estos son utilizados por los navegadores web para cargar una página y enviar un formulario, respectivamente. En el estudio REST, utiliza estos para indicar diferentes acciones.

GET se utiliza generalmente para obtener información sobre algún objeto o registro que ya existe. Fundamentalmente, el GET no modifica nada, o por lo menos no se supone que es. Por ejemplo, imagina una especie de lista de tareas pendientes servicio web. Es posible hacer un HTTP GET a la URL / tareas / para obtener una lista de las tareas actuales que se haga. Por lo que puede volver algo como esto:

[
{ "id": 3643, "summary": "Wash car" },
{ "id": 3697, "summary": "Visit gym" }
]

Esta es una lista de objetos JSON. (Un “objeto JSON” es un tipo de datos muy similar a un diccionario de Python.)

Por el contrario, la POST se suele utilizar cuando se quiere crear algo. Así que para añadir un nuevo elemento a la lista de tareas, es posible desencadenar un HTTP POST / tareas /. Eso sí: es la misma URL que está permitido en REST. Los diferentes métodos GET y POST son como diferentes verbos, y la dirección URL es como un sustantivo.

Al hacer un POST, normalmente incluirá un cuerpo en la solicitud. Eso significa que usted envía a lo largo de alguna secuencia de bytes: algunos datos que definen el objeto o registro que está creando. ¿Qué tipo de datos? En estos días, es muy común que pasar objetos JSON. La API puede afirmar que un POST a / tareas / debe incluir un único objeto con dos campos, “Resumen” y “Descripción”, así:

{
"summary": "Get milk",
"description": "Need to get a half gallon of organic 2% milk."
}

Esto es una cadena, la codificación de un objeto JSON. El servidor de la API y luego lo analiza y crea el diccionario de Python equivalente.

¿Qué ocurre después? Bueno, eso depende de la API, pero en términos generales, obtendrá una copia de la respuesta con un poco de información útil, a lo largo de dos dimensiones.

En primer lugar es el código de estado. Este es un número positivo, algo así como 200 o 404 o 302. El significado de cada código de estado está bien definida por el estándar de protocolo HTTP. Búsqueda de “códigos de estado HTTP”, y el primer golpe será probablemente la referencia oficial. Cualquier cosa en los 200s indica éxito.

La otra cosa que se obtiene es el cuerpo de la respuesta. Cuando su navegador web para crear una página web, el HTML es enviado de vuelta el cuerpo de la respuesta. Para una API, el cuerpo de la respuesta puede estar vacía o no. Depende de la API y el punto final. Por ejemplo, cuando nos POST a / tareas / añadir algo a nuestra lista de tareas pendientes, podemos volver a un ID de tarea asignada automáticamente. Esto puede volver a ser en la forma de un objeto JSON:

{ "id": 3792 }

Entonces, si obtenemos / tareas / de nuevo, nuestra lista de tareas incluirá esta nueva:

[
{ "id": 3643, "summary": "Wash car" },
{ "id": 3697, "summary": "Visit gym" },
{ "id": 3792, "summary": "Get milk" }
]

Hay otros métodos, además de GET y POST. En el estándar HTTP, PUT se utiliza para modificar un recurso existente (como el cambio de una tarea de resumen). Otro método llamado eliminará … bueno, borrarlo. Se podría utilizar esta opción cuando se realiza una tarea, para eliminarlo de su lista.

Hay mucho más para descansar que esto. Sin embargo, esta información es suficiente para que usted pueda comenzar. Saltar de nuevo a “Hablar de descanso”.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *