Code Quality Status Azure DevOps coverage Documentation Status Code Climate maintainability Code Climate technical debt LGTM Grade

Translates an OpenAPI schema to SQLAlchemy models.

Supports OpenAPI 3.0 and 3.1.

python -m pip install OpenAlchemy
# To be able to load YAML file
python -m pip install OpenAlchemy[yaml]

For example, given the following OpenAPI specification:

# ./examples/simple/example-spec.yml
openapi: "3.0.0"
info:
 title: Test Schema
 description: API to illustrate OpenAlchemy MVP.
 version: "0.1"
paths:
 /employee:
 get:
 summary: Used to retrieve all employees.
 responses:
 200:
 description: Return all employees from the database.
 content:
 application/json:
 schema:
 type: array
 items:
 "$ref": "#/components/schemas/Employee"
components:
 schemas:
 Employee:
 description: Person that works for a company.
 type: object
 x-tablename: employee
 properties:
 id:
 type: integer
 description: Unique identifier for the employee.
 example: 0
 x-primary-key: true
 x-autoincrement: true
 name:
 type: string
 description: The name of the employee.
 example: David Andersson
 x-index: true
 division:
 type: string
 description: The part of the company the employee works in.
 example: Engineering
 x-index: true
 salary:
 type: number
 description: The amount of money the employee is paid.
 example: 1000000.00
 required:
 - id
 - name
 - division

The SQLALchemy models file then becomes:

# models.py
from open_alchemy import init_yaml
init_yaml("./examples/simple/example-spec.yml")

The Base and Employee objects can be accessed:

from open_alchemy.models import Base
from open_alchemy.models import Employee

With the models_filename parameter a file is auto generated with type hints for the SQLAlchemy models at the specified location, for example: type hinted models example. This adds support for IDE auto complete, for example for the model initialization:

autocomplete init

and for properties and methods available on an instance:

autocomplete instance

An extensive set of examples with a range of features is here:

examples for main features

An example API has been defined using connexion and Flask here:

example connexion app

Read the Docs

Buy Me A Coffee

• initializing from JSON,
• initializing from YAML,
• build a package with the models for distribution, packaged as sdist or wheel,
• automatically generate a models file,
• integer (32 and 64 bit),
• number (float only),
• boolean,
• string,
• password,
• byte,
• binary,
• date,
• date-time,
• generic JSON data,
• $ref references for columns and models,
• remote $ref to other files on the same file system (not supported on Windows),
• remote $ref to other files at a URL,
• primary keys,
• auto incrementing,
• indexes,
• composite indexes,
• unique constraints,
• composite unique constraints,
• column nullability,
• foreign keys,
• default values for columns (both application and database side),
• many to one relationships,
• one to one relationships,
• one to many relationships,
• many to many relationships,
• many to many relationships with custom association tables,
• custom foreign keys for relationships,
• back references for relationships,
• allOf inheritance for columns and models,
• joined and single table inheritance,
• from_str model methods to construct from JSON string,
• from_dict model methods to construct from dictionaries,
• to_str model methods to convert instances to JSON string,
• __str__ model methods to support the python str function,
• __repr__ model methods to support the python repr function,
• to_dict model methods to convert instances to dictionaries,
• readOnly and writeOnly for influence the conversion to and from dictionaries,
• exposing created models under open_alchemy.models removing the need for models.py files,
• ability to mix in arbitrary classes into a model,
• can use the short x- prefix or a namespaced x-open-alchemy- prefix for extension properties and
• grouping models into schemas.

Fork and checkout the repository. To install:

poetry install

To run tests:

poetry run pytest

Make your changes and raise a pull request.

poetry shell
cd docs
make html

This creates the index.html file in docs/build/html/index.html.

rm -r dist/*
poetry build
poetry publish