Merge pull request #243 from jdkandersson/enhancement/236-extension-property-cleanup

Enhancement/236 extension property cleanup

Author: jdkandersson

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add support for namespaced `x-open-alchemy-` prefix on top of the shorter
+  `x-` prefix for extension properties. [#236]
+
 ## [v2.0.2] - 2020-12-19
 
 ### Changed
@@ -483,3 +488,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#198]: https://github.com/jdkandersson/OpenAlchemy/issues/198
 [#201]: https://github.com/jdkandersson/OpenAlchemy/issues/201
 [#202]: https://github.com/jdkandersson/OpenAlchemy/issues/202
+[#236]: https://github.com/jdkandersson/OpenAlchemy/issues/236

README.md

@@ -137,7 +137,8 @@ An example API has been defined using connexion and Flask here:
 - `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 on the same file system
+  (_not supported on Windows_),
 - remote `$ref` to other files at a URL,
 - primary keys,
 - auto incrementing,
@@ -163,10 +164,13 @@ An example API has been defined using connexion and Flask here:
 - `__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,
+- `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 and
-- ability to mix in arbitrary classes into a model.
+  `models.py` files,
+- ability to mix in arbitrary classes into a model and
+- can use the short `x-` prefix or a namespaced `x-open-alchemy-` prefix for
+  extension properties.
 
 ## Contributing
 

docs/source/examples/index.rst

@@ -8,6 +8,7 @@ Examples
    connexion
    alembic
    simple
+   namespaced
    default
    server_default
    read_only

docs/source/examples/namespaced.rst

@@ -0,0 +1,33 @@
+Namespaced
+==========
+
+OpenAlchemy supports namespaced extension properties. The default is to prefix
+extension properties with :samp:`x-`. To avoid clashes with other tools, the
+:samp:`x-open-alchemy-` prefix is also supported:
+
+.. literalinclude:: ../../../examples/namespaced/example-spec.yml
+    :language: yaml
+    :linenos:
+
+The behavior of OpenAlchemy is identical.
+
+The following example models file makes use of the OpenAPI specification to
+define the SQLAlchemy models:
+
+.. literalinclude:: ../../../examples/namespaced/models.py
+    :language: python
+    :linenos:
+
+This models file instructs OpenAlchemy to construct the SQLAlchemy models
+equivalent to the following traditional SQLAlchemy models.py file:
+
+.. literalinclude:: ../../../examples/namespaced/models_traditional.py
+    :language: python
+    :linenos:
+
+OpenAlchemy also generates a fully type hinted version of the generated
+SQLAlchemy models:
+
+.. literalinclude:: ../../../examples/namespaced/models_auto.py
+    :language: python
+    :linenos:

docs/source/index.rst

@@ -374,6 +374,17 @@ alembic is supported. The following instructions show how to get started:
 .. literalinclude:: ../../examples/alembic/readme.md
     :language: md
 
+Extension Property Prefix
+-------------------------
+
+OpenAlchemy currently supports 2 extension property prefixes. The shorter
+:samp:`x-` and the longer :samp:`x-open-alchemy-`. Both prefixes behave in the
+same way. The longer prefix is offered to avoid extension property name clashes
+with other tools.
+
+For example, the tablename can be specified either using the
+:samp:`x-tablename` or the :samp:`x-open-alchemy-tablename` extension property.
+
 .. _how-does-it-work:
 
 How Does It Work?

examples/namespaced/example-spec.yml

@@ -0,0 +1,51 @@
+openapi: "3.0.0"
+
+info:
+  title: Test Schema
+  description: API to illustrate OpenAlchemy using namespaced extension properties (x-open-alchemy* instead of x-*).
+  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-open-alchemy-tablename: employee
+      properties:
+        id:
+          type: integer
+          description: Unique identifier for the employee.
+          example: 0
+          x-open-alchemy-primary-key: true
+          x-open-alchemy-autoincrement: true
+        name:
+          type: string
+          description: The name of the employee.
+          example: David Andersson
+          x-open-alchemy-index: true
+        division:
+          type: string
+          description: The part of the company the employee works in.
+          example: Engineering
+          x-open-alchemy-index: true
+        salary:
+          type: number
+          description: The amount of money the employee is paid.
+          example: 1000000.00
+      required:
+        - name
+        - division

examples/namespaced/models.py

@@ -0,0 +1,3 @@
+from open_alchemy import init_yaml
+
+init_yaml("example-spec.yml", models_filename="models_auto.py")

examples/namespaced/models_auto.py

@@ -0,0 +1,127 @@
+"""Autogenerated SQLAlchemy models based on OpenAlchemy models."""
+# pylint: disable=no-member,super-init-not-called,unused-argument
+
+import typing
+
+import sqlalchemy
+from sqlalchemy import orm
+
+from open_alchemy import models
+
+Base = models.Base  # type: ignore
+
+
+class _EmployeeDictBase(typing.TypedDict, total=True):
+    """TypedDict for properties that are required."""
+
+    name: str
+    division: str
+
+
+class EmployeeDict(_EmployeeDictBase, total=False):
+    """TypedDict for properties that are not required."""
+
+    id: int
+    salary: typing.Optional[float]
+
+
+class TEmployee(typing.Protocol):
+    """
+    SQLAlchemy model protocol.
+
+    Person that works for a company.
+
+    Attrs:
+        id: Unique identifier for the employee.
+        name: The name of the employee.
+        division: The part of the company the employee works in.
+        salary: The amount of money the employee is paid.
+
+    """
+
+    # SQLAlchemy properties
+    __table__: sqlalchemy.Table
+    __tablename__: str
+    query: orm.Query
+
+    # Model properties
+    id: "sqlalchemy.Column[int]"
+    name: "sqlalchemy.Column[str]"
+    division: "sqlalchemy.Column[str]"
+    salary: "sqlalchemy.Column[typing.Optional[float]]"
+
+    def __init__(
+        self,
+        name: str,
+        division: str,
+        id: typing.Optional[int] = None,
+        salary: typing.Optional[float] = None,
+    ) -> None:
+        """
+        Construct.
+
+        Args:
+            id: Unique identifier for the employee.
+            name: The name of the employee.
+            division: The part of the company the employee works in.
+            salary: The amount of money the employee is paid.
+
+        """
+        ...
+
+    @classmethod
+    def from_dict(
+        cls,
+        name: str,
+        division: str,
+        id: typing.Optional[int] = None,
+        salary: typing.Optional[float] = None,
+    ) -> "TEmployee":
+        """
+        Construct from a dictionary (eg. a POST payload).
+
+        Args:
+            id: Unique identifier for the employee.
+            name: The name of the employee.
+            division: The part of the company the employee works in.
+            salary: The amount of money the employee is paid.
+
+        Returns:
+            Model instance based on the dictionary.
+
+        """
+        ...
+
+    @classmethod
+    def from_str(cls, value: str) -> "TEmployee":
+        """
+        Construct from a JSON string (eg. a POST payload).
+
+        Returns:
+            Model instance based on the JSON string.
+
+        """
+        ...
+
+    def to_dict(self) -> EmployeeDict:
+        """
+        Convert to a dictionary (eg. to send back for a GET request).
+
+        Returns:
+            Dictionary based on the model instance.
+
+        """
+        ...
+
+    def to_str(self) -> str:
+        """
+        Convert to a JSON string (eg. to send back for a GET request).
+
+        Returns:
+            JSON string based on the model instance.
+
+        """
+        ...
+
+
+Employee: typing.Type[TEmployee] = models.Employee  # type: ignore

examples/namespaced/models_traditional.py

@@ -0,0 +1,14 @@
+import sqlalchemy as sa
+from sqlalchemy.ext.declarative import declarative_base
+
+Base = declarative_base()
+
+
+class Employee(Base):
+    """Person that works for a company."""
+
+    __tablename__ = "employee"
+    id = sa.Column(sa.Integer, primary_key=True, autoincrement=True)
+    name = sa.Column(sa.String, index=True)
+    division = sa.Column(sa.String, index=True)
+    salary = sa.Column(sa.Float)

open_alchemy/helpers/all_of.py

@@ -50,14 +50,14 @@ def _merge(
         merged_sub_schema = _merge(ref_schema, schemas, skip_name)
 
         # Capturing required arrays
-        merged_required = merged_schema.get("required")
-        sub_required = merged_sub_schema.get("required")
+        merged_required = merged_schema.get(types.OpenApiProperties.REQUIRED)
+        sub_required = merged_sub_schema.get(types.OpenApiProperties.REQUIRED)
         # Capturing properties
-        merged_properties = merged_schema.get("properties")
-        sub_properties = merged_sub_schema.get("properties")
+        merged_properties = merged_schema.get(types.OpenApiProperties.PROPERTIES)
+        sub_properties = merged_sub_schema.get(types.OpenApiProperties.PROPERTIES)
         # Capturing backrefs
-        merged_backrefs = merged_schema.get("x-backrefs")
-        sub_backrefs = merged_sub_schema.get("x-backrefs")
+        merged_backrefs = merged_schema.get(types.ExtensionProperties.BACKREFS)
+        sub_backrefs = merged_sub_schema.get(types.ExtensionProperties.BACKREFS)
 
         # Combining sub into merged specification
         merged_schema = {**merged_schema, **merged_sub_schema}
@@ -66,16 +66,22 @@ def _merge(
         if merged_required is not None and sub_required is not None:
             # Both have a required array, need to merge them together
             required_set = set(merged_required).union(sub_required)
-            merged_schema["required"] = list(required_set)
+            merged_schema[types.OpenApiProperties.REQUIRED] = list(required_set)
 
         # Checking whether properties was present on both specs
         if merged_properties is not None and sub_properties is not None:
             # Both have properties, merge properties
-            merged_schema["properties"] = {**merged_properties, **sub_properties}
+            merged_schema[types.OpenApiProperties.PROPERTIES] = {
+                **merged_properties,
+                **sub_properties,
+            }
 
         # Checking whether backrefs was present on both specs
         if merged_backrefs is not None and sub_backrefs is not None:
             # Both have backrefs, merge backrefs
-            merged_schema["x-backrefs"] = {**merged_backrefs, **sub_backrefs}
+            merged_schema[types.ExtensionProperties.BACKREFS] = {
+                **merged_backrefs,
+                **sub_backrefs,
+            }
 
     return merged_schema