Merge pull request #186 from jdkandersson/enhancement/185-package-build

Enhancement/185 package build

Author: jdkandersson

.gitignore

@@ -9,8 +9,13 @@
 *.pyc
 *.pyo
 build/
+!open_alchemy/build/
+!tests/open_alchemy/build/
 dist/
+!examples/**/dist/
+examples/**/dist/dist
 htmlcov/
 venv
+venv36
 coverage.xml
 docs/source/_*

.pre-commit-config.yaml

@@ -4,6 +4,7 @@ repos:
     hooks:
       - id: black
         language_version: python3.7
+        exclude: "models_auto.py$|models_autogenerated.py$"
   - repo: https://github.com/pre-commit/mirrors-isort
     rev: v5.4.2
     hooks:
@@ -35,3 +36,8 @@ repos:
     hooks:
       - exclude: "^docs.*.yaml$"
         id: prettier
+  - repo: https://github.com/codespell-project/codespell
+    rev: v1.17.1
+    hooks:
+      - id: codespell
+        args: [-L connexion]

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release Notes
 
+## Version _next_
+
+- Refactor the models file generation to use the artifacts from the schemas.
+- Add `build_json` and `build_yaml` interfaces which can be used to produce a package with the models.
+
 ## Version 1.5.4 - 2020-08-30
 
 - Move `description` to be a top level property artifact for every property.

README.md

@@ -115,6 +115,7 @@ An example API has been defined using connexion and Flask here:
 
 - initializing from JSON,
 - initializing from YAML,
+- build a package with the models for distribution,
 - automatically generate a models file,
 - `integer` (32 and 64 bit),
 - `number` (float only),

docs/source/index.rst

@@ -52,6 +52,9 @@ friendly.
 :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:
 
@@ -113,6 +116,36 @@ does not construct a declarative base. It accepts the following parameters:
 The return value is the :samp:`model_factory` as defined as part of the return
 value of :ref:`init-yaml`.
 
+.. _build-yaml:
+
+: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.
+
+The :samp:`build_yaml` interface requires the :samp:`PyYAML` library to be
+installed. The :samp:`build_yaml` interface accepts the following arguments:
+
+* :samp:`spec_filename`: The name of the OpenAPI specification file. The file
+  must by a YAML file.
+* :samp:`package_name`: The name of the package to be produced. This will be
+
+  1. the name of the package if it is uploaded to a package index and
+  2. the name that is used to import the models after they have been installed).
+
+* :samp:`dist_path`: The directory to output the package files.
+
+.. _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:
 
 Models File

examples/all_of/column_models_auto.py

@@ -8,6 +8,8 @@
 
 from open_alchemy import models
 
+Base = models.Base  # type: ignore
+
 
 class EmployeeDict(typing.TypedDict, total=False):
     """TypedDict for properties that are not required."""

examples/all_of/model_models_auto.py

@@ -8,6 +8,8 @@
 
 from open_alchemy import models
 
+Base = models.Base  # type: ignore
+
 
 class DivisionDict(typing.TypedDict, total=False):
     """TypedDict for properties that are not required."""
@@ -105,9 +107,9 @@ def to_str(self) -> str:
 class EmployeeDict(typing.TypedDict, total=False):
     """TypedDict for properties that are not required."""
 
+    salary: typing.Optional[float]
     id: typing.Optional[int]
     name: typing.Optional[str]
-    salary: typing.Optional[float]
 
 
 class TEmployee(typing.Protocol):
@@ -117,9 +119,9 @@ class TEmployee(typing.Protocol):
     Person that works for a company.
 
     Attrs:
+        salary: The amount of money the employee is paid.
         id: Unique identifier for the object.
         name: The name of the object.
-        salary: The amount of money the employee is paid.
 
     """
 
@@ -129,41 +131,41 @@ class TEmployee(typing.Protocol):
     query: orm.Query
 
     # Model properties
+    salary: "sqlalchemy.Column[typing.Optional[float]]"
     id: "sqlalchemy.Column[typing.Optional[int]]"
     name: "sqlalchemy.Column[typing.Optional[str]]"
-    salary: "sqlalchemy.Column[typing.Optional[float]]"
 
     def __init__(
         self,
+        salary: typing.Optional[float] = None,
         id: typing.Optional[int] = None,
         name: typing.Optional[str] = None,
-        salary: typing.Optional[float] = None,
     ) -> None:
         """
         Construct.
 
         Args:
+            salary: The amount of money the employee is paid.
             id: Unique identifier for the object.
             name: The name of the object.
-            salary: The amount of money the employee is paid.
 
         """
         ...
 
     @classmethod
     def from_dict(
         cls,
+        salary: typing.Optional[float] = None,
         id: typing.Optional[int] = None,
         name: typing.Optional[str] = None,
-        salary: typing.Optional[float] = None,
     ) -> "TEmployee":
         """
         Construct from a dictionary (eg. a POST payload).
 
         Args:
+            salary: The amount of money the employee is paid.
             id: Unique identifier for the object.
             name: The name of the object.
-            salary: The amount of money the employee is paid.
 
         Returns:
             Model instance based on the dictionary.

examples/app/models_autogenerated.py

@@ -8,6 +8,8 @@
 
 from open_alchemy import models
 
+Base = models.Base  # type: ignore
+
 
 class _EmployeeDictBase(typing.TypedDict, total=True):
     """TypedDict for properties that are required."""

examples/composite_index/models_auto.py

@@ -8,6 +8,8 @@
 
 from open_alchemy import models
 
+Base = models.Base  # type: ignore
+
 
 class EmployeeDict(typing.TypedDict, total=False):
     """TypedDict for properties that are not required."""

examples/composite_unique/models_auto.py

@@ -8,6 +8,8 @@
 
 from open_alchemy import models
 
+Base = models.Base  # type: ignore
+
 
 class EmployeeDict(typing.TypedDict, total=False):
     """TypedDict for properties that are not required."""

examples/default/models_auto.py

@@ -8,6 +8,8 @@
 
 from open_alchemy import models
 
+Base = models.Base  # type: ignore
+
 
 class EmployeeDict(typing.TypedDict, total=False):
     """TypedDict for properties that are not required."""

examples/inheritance/joined_models_auto.py

@@ -8,6 +8,8 @@
 
 from open_alchemy import models
 
+Base = models.Base  # type: ignore
+
 
 class EmployeeDict(typing.TypedDict, total=False):
     """TypedDict for properties that are not required."""
@@ -117,9 +119,9 @@ class ManagerDict(typing.TypedDict, total=False):
     """TypedDict for properties that are not required."""
 
     id: typing.Optional[int]
+    manager_data: typing.Optional[str]
     name: typing.Optional[str]
     type: typing.Optional[str]
-    manager_data: typing.Optional[str]
 
 
 class TManager(typing.Protocol):
@@ -130,9 +132,9 @@ class TManager(typing.Protocol):
 
     Attrs:
         id: Unique identifier for the manager.
+        manager_data: Data for the manager.
         name: The name of the employee.
         type: The type of the employee.
-        manager_data: Data for the manager.
 
     """
 
@@ -143,25 +145,25 @@ class TManager(typing.Protocol):
 
     # Model properties
     id: "sqlalchemy.Column[typing.Optional[int]]"
+    manager_data: "sqlalchemy.Column[typing.Optional[str]]"
     name: "sqlalchemy.Column[typing.Optional[str]]"
     type: "sqlalchemy.Column[typing.Optional[str]]"
-    manager_data: "sqlalchemy.Column[typing.Optional[str]]"
 
     def __init__(
         self,
         id: typing.Optional[int] = None,
+        manager_data: typing.Optional[str] = None,
         name: typing.Optional[str] = None,
         type: typing.Optional[str] = None,
-        manager_data: typing.Optional[str] = None,
     ) -> None:
         """
         Construct.
 
         Args:
             id: Unique identifier for the manager.
+            manager_data: Data for the manager.
             name: The name of the employee.
             type: The type of the employee.
-            manager_data: Data for the manager.
 
         """
         ...
@@ -170,18 +172,18 @@ def __init__(
     def from_dict(
         cls,
         id: typing.Optional[int] = None,
+        manager_data: typing.Optional[str] = None,
         name: typing.Optional[str] = None,
         type: typing.Optional[str] = None,
-        manager_data: typing.Optional[str] = None,
     ) -> "TManager":
         """
         Construct from a dictionary (eg. a POST payload).
 
         Args:
             id: Unique identifier for the manager.
+            manager_data: Data for the manager.
             name: The name of the employee.
             type: The type of the employee.
-            manager_data: Data for the manager.
 
         Returns:
             Model instance based on the dictionary.
@@ -228,9 +230,9 @@ class EngineerDict(typing.TypedDict, total=False):
     """TypedDict for properties that are not required."""
 
     id: typing.Optional[int]
+    engineer_info: typing.Optional[str]
     name: typing.Optional[str]
     type: typing.Optional[str]
-    engineer_info: typing.Optional[str]
 
 
 class TEngineer(typing.Protocol):
@@ -241,9 +243,9 @@ class TEngineer(typing.Protocol):
 
     Attrs:
         id: Unique identifier for the engineer.
+        engineer_info: Information for the manager.
         name: The name of the employee.
         type: The type of the employee.
-        engineer_info: Information for the manager.
 
     """
 
@@ -254,25 +256,25 @@ class TEngineer(typing.Protocol):
 
     # Model properties
     id: "sqlalchemy.Column[typing.Optional[int]]"
+    engineer_info: "sqlalchemy.Column[typing.Optional[str]]"
     name: "sqlalchemy.Column[typing.Optional[str]]"
     type: "sqlalchemy.Column[typing.Optional[str]]"
-    engineer_info: "sqlalchemy.Column[typing.Optional[str]]"
 
     def __init__(
         self,
         id: typing.Optional[int] = None,
+        engineer_info: typing.Optional[str] = None,
         name: typing.Optional[str] = None,
         type: typing.Optional[str] = None,
-        engineer_info: typing.Optional[str] = None,
     ) -> None:
         """
         Construct.
 
         Args:
             id: Unique identifier for the engineer.
+            engineer_info: Information for the manager.
             name: The name of the employee.
             type: The type of the employee.
-            engineer_info: Information for the manager.
 
         """
         ...
@@ -281,18 +283,18 @@ def __init__(
     def from_dict(
         cls,
         id: typing.Optional[int] = None,
+        engineer_info: typing.Optional[str] = None,
         name: typing.Optional[str] = None,
         type: typing.Optional[str] = None,
-        engineer_info: typing.Optional[str] = None,
     ) -> "TEngineer":
         """
         Construct from a dictionary (eg. a POST payload).
 
         Args:
             id: Unique identifier for the engineer.
+            engineer_info: Information for the manager.
             name: The name of the employee.
             type: The type of the employee.
-            engineer_info: Information for the manager.
 
         Returns:
             Model instance based on the dictionary.