.. role:: python(code) :language: python OpenAlchemy =========== OpenAlchemy translates OpenAPI schemas to SQLAlchemy models to reduce duplication when defining your API and database models. Any required additions to the OpenAPI specification are compliant with the OpenAPI standard. .. seealso:: `Online Editor `_ Online editor including schema validation. .. _getting-started: Getting Started --------------- If you have the following OpenAPI specification: .. literalinclude:: ../../examples/simple/example-spec.yml :language: yaml :linenos: To use SQLAlchemy to retrieve :samp:`Employees` from a database you need the following :samp:`models.py` file: .. literalinclude:: ../../examples/simple/models.py :language: python :linenos: The :samp:`Base` for the SQLAlchemy models and the :samp:`Employee` model is now available from :samp:`open_alchemy.models`:: from open_alchemy.models import Base from open_alchemy.models import Employee Interfaces ---------- The most user friendly interfaces are the :ref:`init-yaml` and :ref:`init-json` interfaces. The :ref:`init-model-factory` interface is a lower level interface which has fewer dependencies but is not as user friendly. .. _init-yaml: :samp:`init_yaml` ^^^^^^^^^^^^^^^^^ Used to initialize the SQLAlchemy models based on a YAML OpenAPI specification which has been extended with any relevant OpenAlchemy extension properties. The :samp:`init_yaml` interface requires the :samp:`PyYAML` library to be installed. The :samp:`init_yaml` interface accepts the following arguments: * :samp:`spec_filename`: The name of the file as a positional argument. The file must by a YAML file. * :samp:`base`: The SQLAlchemy declarative base as an optional keyword only argument. It is used to as the base class for all SQLAlchemy models. If it is not passed in, a new declarative base is constructed. * :samp:`models_filename`: The name of the file where the SQLAlchemy models will be written as an optional keyword only argument. * :samp:`spec_path`: The path to the OpenAPI specification (what would need to be passed to the :samp:`open` function to read the file) as an optional keyword only argument. Used to support remote references. .. note:: the :samp:`define_all` parameter has been removed and OpenAlchemy behaves as though it is set to :samp:`True`. The return value is a tuple consisting of: * :samp:`Base`: The SQLAlchemy declarative based used for the models. It is also importable: :python:`from open_alchemy.models import Base`. * :samp:`model_factory`: The factory that can be used to construct the SQLAlchemy models using the name of the schema in the OpenAPI specification. All constructed models are added to the :samp:`open_alchemy.models` module and are importable. For example: :python:`from open_alchemy.models import Employee`. .. _init-json: :samp:`init_json` ^^^^^^^^^^^^^^^^^ The :samp:`init_json` interface is similar to the :ref:`init-yaml` interface except that :samp:`spec_filename` must be a JSON file and :samp:`PyYAML` is not a required dependency. :samp:`build_yaml` ^^^^^^^^^^^^^^^^^^ Used to build a package with the SQLAlchemy models (including type hints) based on a YAML OpenAPI specification which has been extended with any relevant OpenAlchemy extension properties. To build models from the command line, run:: openalchemy build openapi.yml simple dist This interface is described in details in the :ref:`build-yaml` section of the Advanced chapter. .. _build-json: :samp:`build_json` ^^^^^^^^^^^^^^^^^^ The :samp:`build_json` interface is similar to the :ref:`build-yaml` interface except that :samp:`spec_filename` must be a JSON file and :samp:`PyYAML` is not a required dependency. Models File ----------- Optionally, model definitions can be persisted to disk, mainly for type hinting and IDE auto-completion. To discover the internal details of the models file, refer to the :ref:`models-file` section in the Advanced chapter. .. _alembic: Alembic ------- The standard method for automatically generating database migrations for alembic is supported. The following instructions show how to get started: .. literalinclude:: ../../examples/alembic/readme.md :language: md How Does It Work? ----------------- Helped by a series of extension properties, OpenAlchemy turns `OpenAPI schemas `_ into SQL entities. To understand how all this works under the hood, refer to :ref:`how-does-it-work` section in the Advanced chapter. Table of Content ---------------- .. toctree:: :caption: GENERAL :maxdepth: 1 technical_details/index examples/index cli advanced package_service CHANGELOG .. toctree:: :caption: DEVELOPMENT :maxdepth: 1 CONTRIBUTING