APIs REST Python com Flask, Connexion e SQLAlchemy – Parte 2

Para quem é este artigo

Dependências Adicionais

$ pip install Flask-SQLAlchemy flask-marshmallow marshmallow-sqlalchemy marshmallow

1. 
   Flask-SQLAlchemy adiciona SQLAlchemy, junto com alguns tie-ins para Flask, permitindo que programas acessem bancos de dados.
   
2. 
   flask-marshmallow adiciona as partes Flask do Marshmallow, que permite que os programas convertam objetos Python de e para estruturas serializáveis.
   
3. 
   marshmallow-sqlalchemy adiciona alguns ganchos Marshmallow no SQLAlchemy para permitir que os programas serializem e desserializem objetos Python gerados pelo SQLAlchemy.
   
4. 
   marshmallow adiciona a maior parte da funcionalidade Marshmallow.
   

Dados de pessoas

# Data to serve with our API
PEOPLE = {
    "Farrell": {
        "fname": "Doug",
        "lname": "Farrell",
        "timestamp": get_timestamp()
    },
    "Brockman": {
        "fname": "Kent",
        "lname": "Brockman",
        "timestamp": get_timestamp()
    },
    "Easter": {
        "fname": "Bunny",
        "lname": "Easter",
        "timestamp": get_timestamp()
    }
}

• Incrementar o maior campo de chave primária existente sempre que um novo registro for inserido na tabela
• Usando esse valor como chave primária para os dados recém-inseridos

• person_id : campo de chave primária para cada pessoa
• lname : sobrenome da pessoa
• fname : nome da pessoa
• timestamp : carimbo de data/hora associado a ações de inserção/atualização

Interação do banco de dados

SELECT * FROM person ORDER BY 'lname';

sqlite> SELECT * FROM person ORDER BY lname;
2|Brockman|Kent|2018-08-08 21:16:01.888444
3|Easter|Bunny|2018-08-08 21:16:01.889060
1|Farrell|Doug|2018-08-08 21:16:01.886834

 1import sqlite3
 2
 3conn = sqlite3.connect('people.db')
 4cur = conn.cursor()
 5cur.execute('SELECT * FROM person ORDER BY lname')
 6people = cur.fetchall()
 7for person in people:
 8    print(f'{person[2]} {person[1]}')

• 
  Linha 1 importa o sqlite3 módulo.
  
• 
  Linha 3 cria uma conexão com o arquivo de banco de dados.
  
• 
  Linha 4 cria um cursor a partir da conexão.
  
• 
  Linha 5 usa o cursor para executar um SQL consulta expressa como uma string.
  
• 
  Linha 6 obtém todos os registros retornados pelo SQL consulta e os atribui às people variável.
  
• 
  Linha 7 e 8 iterar sobre as people list e imprima o nome e sobrenome de cada pessoa.
  

people = [
    (2, 'Brockman', 'Kent', '2018-08-08 21:16:01.888444'), 
    (3, 'Easter', 'Bunny', '2018-08-08 21:16:01.889060'), 
    (1, 'Farrell', 'Doug', '2018-08-08 21:16:01.886834')
]

Kent Brockman
Bunny Easter
Doug Farrell

Mesinhas do pequeno Bobby

GET /api/people/{lname}

 1lname = 'Farrell'
 2cur.execute('SELECT * FROM person WHERE lname = \'{}\''.format(lname))

• 
  Linha 1 define o lname variável para 'Farrell' . Isso viria do caminho do endpoint da URL da API REST.
  
• 
  Linha 2 usa a formatação de string Python para criar uma string SQL e executá-la.
  

SELECT * FROM person WHERE lname = 'Farrell'

GET /api/people/Farrell');DROP TABLE person;

SELECT * FROM person WHERE lname = 'Farrell');DROP TABLE person;

Modelagem de dados com SQLAlchemy

class Person(db.Model):
    __tablename__ = 'person'
    person_id = db.Column(db.Integer, 
                          primary_key=True)
    lname = db.Column(db.String)
    fname = db.Column(db.String)
    timestamp = db.Column(db.DateTime, 
                          default=datetime.utcnow, 
                          onupdate=datetime.utcnow)

• 
  __tablename__ = 'person' conecta a definição de classe à person tabela de banco de dados.
  
• 
  person_id = db.Column(db.Integer, primary_key=True) cria uma coluna de banco de dados contendo um inteiro atuando como chave primária para a tabela. Isso também informa ao banco de dados que person_id será um valor inteiro de autoincremento.
  
• 
  lname = db.Column(db.String) cria o campo de sobrenome, uma coluna de banco de dados contendo um valor de string.
  
• 
  fname = db.Column(db.String) cria o campo de nome, uma coluna de banco de dados contendo um valor de string.
  
• 
  timestamp = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow) cria um campo de carimbo de data/hora, uma coluna de banco de dados contendo um valor de data/hora. O default=datetime.utcnow O parâmetro padroniza o valor do timestamp para o utcnow atual valor quando um registro é criado. O onupdate=datetime.utcnow O parâmetro atualiza o timestamp com o atual utcnow valor quando o registro é atualizado.
  

SELECT * FROM people ORDER BY lname;

 1from models import Person
 2
 3people = Person.query.order_by(Person.lname).all()
 4for person in people:
 5    print(f'{person.fname} {person.lname}')

Serialização/desserialização de dados modelados

• string : um tipo de string
• number : números suportados pelo Python (inteiros, floats, longs)
• object : um objeto JSON, que é aproximadamente equivalente a um dicionário Python
• array : aproximadamente equivalente a uma lista Python
• boolean : representado em JSON como true ou false , mas em Python como True ou False
• null : essencialmente um None em Python

class PersonSchema(ma.ModelSchema):
    class Meta:
        model = Person
        sqla_session = db.session

• 
  class Meta define uma classe chamada Meta dentro de sua classe. O ModelSchema classe que o PersonSchema classe herda de procura por este Meta interno class e a usa para encontrar o modelo SQLAlchemy Person e o db.session . É assim que o Marshmallow encontra atributos no Person class e o tipo desses atributos para que saiba como serializá-los/desserializá-los.
  
• 
  model informa à classe qual modelo SQLAlchemy usar para serializar/desserializar dados de e para.
  
• 
  db.session informa à classe qual sessão de banco de dados usar para introspecção e determinar tipos de dados de atributo.
  

Criar o banco de dados inicializado

• 
  config.py obtém os módulos necessários importados para o programa e configurados. Isso inclui Flask, Connexion, SQLAlchemy e Marshmallow. Porque será usado tanto por build_database.py e server.py , algumas partes da configuração serão aplicadas apenas ao server.py inscrição.
  
• 
  models.py é o módulo onde você criará a Person SQLAlchemy e PersonSchema Definições de classe de marshmallow descritas acima. Este módulo depende de config.py para alguns dos objetos criados e configurados lá.
  

Módulo de configuração

 1import os
 2import connexion
 3from flask_sqlalchemy import SQLAlchemy
 4from flask_marshmallow import Marshmallow
 5
 6basedir = os.path.abspath(os.path.dirname(__file__))
 7
 8# Create the Connexion application instance
 9connex_app = connexion.App(__name__, specification_dir=basedir)
10
11# Get the underlying Flask app instance
12app = connex_app.app
13
14# Configure the SQLAlchemy part of the app instance
15app.config['SQLALCHEMY_ECHO'] = True
16app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:////' + os.path.join(basedir, 'people.db')
17app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
18
19# Create the SQLAlchemy db instance
20db = SQLAlchemy(app)
21
22# Initialize Marshmallow
23ma = Marshmallow(app)

• 
  Linhas 2 a 4 importe o Connexion como você fez no server.py programa da Parte 1. Ele também importa SQLAlchemy do flask_sqlalchemy módulo. Isso dá acesso ao banco de dados do seu programa. Por fim, importa Marshmallow do flask_marshamllow módulo.
  
• 
  Linha 6 cria a variável basedir apontando para o diretório em que o programa está sendo executado.
  
• 
  Linha 9 usa o basedir variável para criar a instância do aplicativo Connexion e fornecer o caminho para o swagger.yml Arquivo.
  
• 
  Linha 12 cria uma variável app , que é a instância do Flask inicializada pelo Connexion.
  
• 
  Linhas 15 usa o app variável para configurar os valores usados ​​pelo SQLAlchemy. Primeiro ele define SQLALCHEMY_ECHO para True . Isso faz com que o SQLAlchemy ecoe as instruções SQL que ele executa no console. Isso é muito útil para depurar problemas ao construir programas de banco de dados. Defina isso como False para ambientes de produção.
  
• 
  Linha 16 define SQLALCHEMY_DATABASE_URI para sqlite:////' + os.path.join(basedir, 'people.db') . Isso diz ao SQLAlchemy para usar o SQLite como banco de dados e um arquivo chamado people.db no diretório atual como o arquivo de banco de dados. Diferentes mecanismos de banco de dados, como MySQL e PostgreSQL, terão diferentes SQLALCHEMY_DATABASE_URI strings para configurá-los.
  
• 
  Linha 17 define SQLALCHEMY_TRACK_MODIFICATIONS para False , desativando o sistema de eventos SQLAlchemy, que está ativado por padrão. O sistema de eventos gera eventos úteis em programas orientados a eventos, mas adiciona uma sobrecarga significativa. Como você não está criando um programa orientado a eventos, desative esse recurso.
  
• 
  Linha 19 cria o db variável chamando SQLAlchemy(app) . Isso inicializa o SQLAlchemy passando o app informações de configuração acabou de definir. O db variável é o que é importado para o build_database.py programa para dar acesso ao SQLAlchemy e ao banco de dados. Ele servirá ao mesmo propósito no server.py program e people.py módulo.
  
• 
  Linha 23 cria o ma variável chamando Marshmallow(app) . Isso inicializa o Marshmallow e permite que ele introspecione os componentes SQLAlchemy anexados ao aplicativo. É por isso que o Marshmallow é inicializado após o SQLAlchemy.
  

Módulo de modelos

 1from datetime import datetime
 2from config import db, ma
 3
 4class Person(db.Model):
 5    __tablename__ = 'person'
 6    person_id = db.Column(db.Integer, primary_key=True)
 7    lname = db.Column(db.String(32), index=True)
 8    fname = db.Column(db.String(32))
 9    timestamp = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
10
11class PersonSchema(ma.ModelSchema):
12    class Meta:
13        model = Person
14        sqla_session = db.session    

• 
  Linha 1 importa o datetime objeto do datetime módulo que vem com o Python. Isso oferece uma maneira de criar um carimbo de data/hora no Person aula.
  
• 
  Linha 2 importa o db e ma variáveis ​​de instância definidas no config.py módulo. Isso dá ao módulo acesso aos atributos e métodos SQLAlchemy anexados ao db variável e os atributos e métodos do Marshmallow anexados ao ma variável.
  
• 
  Linhas 4 a 9 defina a Person class conforme discutido na seção de modelagem de dados acima, mas agora você sabe onde o db.Model que a classe herda origina. Isso dá à Person recursos de classe SQLAlchemy, como uma conexão com o banco de dados e acesso às suas tabelas.
  
• 
  Linhas 11 a 14 defina o PersonSchema class como foi discutido na seção de serialização de dados acima. Esta classe herda de ma.ModelSchema e fornece o PersonSchema recursos de classe Marshmallow, como introspecção da Person class para ajudar a serializar/desserializar instâncias dessa classe.
  

Criando o banco de dados

 1import os
 2from config import db
 3from models import Person
 4
 5# Data to initialize database with
 6PEOPLE = [
 7    {'fname': 'Doug', 'lname': 'Farrell'},
 8    {'fname': 'Kent', 'lname': 'Brockman'},
 9    {'fname': 'Bunny','lname': 'Easter'}
10]
11
12# Delete database file if it exists currently
13if os.path.exists('people.db'):
14    os.remove('people.db')
15
16# Create the database
17db.create_all()
18
19# Iterate over the PEOPLE structure and populate the database
20for person in PEOPLE:
21    p = Person(lname=person['lname'], fname=person['fname'])
22    db.session.add(p)
23
24db.session.commit()

• 
  Line 2 imports the db instance from the config.py module.
  
• 
  Line 3 imports the Person class definition from the models.py module.
  
• 
  Lines 6 – 10 create the PEOPLE data structure, which is a list of dictionaries containing your data. The structure has been condensed to save presentation space.
  
• 
  Lines 13 &14 perform some simple housekeeping to delete the people.db file, if it exists. This file is where the SQLite database is maintained. If you ever have to re-initialize the database to get a clean start, this makes sure you’re starting from scratch when you build the database.
  
• 
  Line 17 creates the database with the db.create_all() ligar. This creates the database by using the db instance imported from the config module. O db instance is our connection to the database.
  
• 
  Lines 20 – 22 iterate over the PEOPLE list and use the dictionaries within to instantiate a Person aula. After it is instantiated, you call the db.session.add(p) function. This uses the database connection instance db to access the session objeto. The session is what manages the database actions, which are recorded in the session. In this case, you are executing the add(p) method to add the new Person instance to the session objeto.
  
• 
  Line 24 calls db.session.commit() to actually save all the person objects created to the database.
  

python build_database.py

2018-09-11 22:20:29,951 INFO sqlalchemy.engine.base.Engine SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
2018-09-11 22:20:29,951 INFO sqlalchemy.engine.base.Engine ()
2018-09-11 22:20:29,952 INFO sqlalchemy.engine.base.Engine SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
2018-09-11 22:20:29,952 INFO sqlalchemy.engine.base.Engine ()
2018-09-11 22:20:29,956 INFO sqlalchemy.engine.base.Engine PRAGMA table_info("person")
2018-09-11 22:20:29,956 INFO sqlalchemy.engine.base.Engine ()
2018-09-11 22:20:29,959 INFO sqlalchemy.engine.base.Engine 
CREATE TABLE person (
    person_id INTEGER NOT NULL, 
    lname VARCHAR, 
    fname VARCHAR, 
    timestamp DATETIME, 
    PRIMARY KEY (person_id)
)
2018-09-11 22:20:29,959 INFO sqlalchemy.engine.base.Engine ()
2018-09-11 22:20:29,975 INFO sqlalchemy.engine.base.Engine COMMIT
2018-09-11 22:20:29,980 INFO sqlalchemy.engine.base.Engine BEGIN (implicit)
2018-09-11 22:20:29,983 INFO sqlalchemy.engine.base.Engine INSERT INTO person (lname, fname, timestamp) VALUES (?, ?, ?)
2018-09-11 22:20:29,983 INFO sqlalchemy.engine.base.Engine ('Farrell', 'Doug', '2018-09-12 02:20:29.983143')
2018-09-11 22:20:29,984 INFO sqlalchemy.engine.base.Engine INSERT INTO person (lname, fname, timestamp) VALUES (?, ?, ?)
2018-09-11 22:20:29,985 INFO sqlalchemy.engine.base.Engine ('Brockman', 'Kent', '2018-09-12 02:20:29.984821')
2018-09-11 22:20:29,985 INFO sqlalchemy.engine.base.Engine INSERT INTO person (lname, fname, timestamp) VALUES (?, ?, ?)
2018-09-11 22:20:29,985 INFO sqlalchemy.engine.base.Engine ('Easter', 'Bunny', '2018-09-12 02:20:29.985462')
2018-09-11 22:20:29,986 INFO sqlalchemy.engine.base.Engine COMMIT

Using the Database

Update the REST API

Update the REST API Handlers

 1from flask import (
 2    make_response,
 3    abort,
 4)
 5from config import db
 6from models import (
 7    Person,
 8    PersonSchema,
 9)
10
11def read_all():
12    """
13    This function responds to a request for /api/people
14    with the complete lists of people
15
16    :return:        json string of list of people
17    """
18    # Create the list of people from our data
19    people = Person.query \
20        .order_by(Person.lname) \
21        .all()
22
23    # Serialize the data for the response
24    person_schema = PersonSchema(many=True)
25    return person_schema.dump(people).data

• 
  Lines 1 – 9 import some Flask modules to create the REST API responses, as well as importing the db instance from the config.py module. In addition, it imports the SQLAlchemy Person and Marshmallow PersonSchema classes to access the person database table and serialize the results.
  
• 
  Line 11 starts the definition of read_all() that responds to the REST API URL endpoint GET /api/people and returns all the records in the person database table sorted in ascending order by last name.
  
• 
  Lines 19 – 22 tell SQLAlchemy to query the person database table for all the records, sort them in ascending order (the default sorting order), and return a list of Person Python objects as the variable people .
  
• 
  Line 24 is where the Marshmallow PersonSchema class definition becomes valuable. You create an instance of the PersonSchema , passing it the parameter many=True . This tells PersonSchema to expect an interable to serialize, which is what the people variable is.
  
• 
  Line 25 uses the PersonSchema instance variable (person_schema ), calling its dump() method with the people list. The result is an object having a data attribute, an object containing a people list that can be converted to JSON. This is returned and converted by Connexion to JSON as the response to the REST API call.
  

TypeError: Object of type Person is not JSON serializable

 1def read_one(person_id):
 2    """
 3    This function responds to a request for /api/people/{person_id}
 4    with one matching person from people
 5
 6    :param person_id:   ID of person to find
 7    :return:            person matching ID
 8    """
 9    # Get the person requested
10    person = Person.query \
11        .filter(Person.person_id == person_id) \
12        .one_or_none()
13
14    # Did we find a person?
15    if person is not None:
16
17        # Serialize the data for the response
18        person_schema = PersonSchema()
19        return person_schema.dump(person).data
20
21    # Otherwise, nope, didn't find that person
22    else:
23        abort(404, 'Person not found for Id: {person_id}'.format(person_id=person_id))

• 
  Lines 10 – 12 use the person_id parameter in a SQLAlchemy query using the filter method of the query object to search for a person with a person_id attribute matching the passed-in person_id . Rather than using the all() query method, use the one_or_none() method to get one person, or return None if no match is found.
  
• 
  Line 15 determines whether a person was found or not.
  
• 
  Line 17 shows that, if person was not None (a matching person was found), then serializing the data is a little different. You don’t pass the many=True parameter to the creation of the PersonSchema() instância. Instead, you pass many=False because only a single object is passed in to serialize.
  
• 
  Line 18 is where the dump method of person_schema is called, and the data attribute of the resulting object is returned.
  
• 
  Line 23 shows that, if person was None (a matching person wasn’t found), then the Flask abort() method is called to return an error.
  

 1def create(person):
 2    """
 3    This function creates a new person in the people structure
 4    based on the passed-in person data
 5
 6    :param person:  person to create in people structure
 7    :return:        201 on success, 406 on person exists
 8    """
 9    fname = person.get('fname')
10    lname = person.get('lname')
11
12    existing_person = Person.query \
13        .filter(Person.fname == fname) \
14        .filter(Person.lname == lname) \
15        .one_or_none()
16
17    # Can we insert this person?
18    if existing_person is None:
19
20        # Create a person instance using the schema and the passed-in person
21        schema = PersonSchema()
22        new_person = schema.load(person, session=db.session).data
23
24        # Add the person to the database
25        db.session.add(new_person)
26        db.session.commit()
27
28        # Serialize and return the newly created person in the response
29        return schema.dump(new_person).data, 201
30
31    # Otherwise, nope, person exists already
32    else:
33        abort(409, f'Person {fname} {lname} exists already')

• 
  Line 9 &10 set the fname and lname variables based on the Person data structure sent as the POST body of the HTTP request.
  
• 
  Lines 12 – 15 use the SQLAlchemy Person class to query the database for the existence of a person with the same fname and lname as the passed-in person .
  
• 
  Line 18 addresses whether existing_person is None . (existing_person was not found.)
  
• 
  Line 21 creates a PersonSchema() instance called schema .
  
• 
  Line 22 uses the schema variable to load the data contained in the person parameter variable and create a new SQLAlchemy Person instance variable called new_person .
  
• 
  Line 25 adds the new_person instance to the db.session .
  
• 
  Line 26 commits the new_person instance to the database, which also assigns it a new primary key value (based on the auto-incrementing integer) and a UTC-based timestamp.
  
• 
  Line 33 shows that, if existing_person is not None (a matching person was found), then the Flask abort() method is called to return an error.
  

Update the Swagger UI

Update the Web Application

Example Code

Conclusão