Add simple but funcitonal example app.

Author: andrew-chang-dewitt

example/.mypy.ini

@@ -0,0 +1,26 @@
+[mypy]
+
+;
+; Import discovery
+;
+; tell mypy where the project root is for module resolution
+mypy_path=$PYTHONPATH,$PYTHONPATH/stubs
+; tell mypy to look at namespace packages (ones without an __init__.py)
+namespace_packages = True
+
+;
+; Strict mode, almost
+;
+disallow_any_generics = True
+disallow_subclassing_any = True
+disallow_untyped_calls = True
+disallow_untyped_defs = True
+disallow_incomplete_defs = True
+check_untyped_defs = True
+disallow_untyped_decorators = True
+no_implicit_optional = True
+warn_redundant_casts = True
+warn_unused_ignores = True
+warn_return_any = True
+warn_unreachable = True
+strict_equality = True

example/.python-version

@@ -0,0 +1 @@
+3.9.1

example/Dockerfile

@@ -0,0 +1,30 @@
+FROM python:3.9.1-alpine3.12
+
+# load source code
+RUN mkdir /app
+COPY example /app
+COPY requirements/prod.txt /app/requirements.txt
+COPY requirements/db_wrapper-0.1.0a0.tar.gz /app/requirements/db_wrapper-0.1.0a0.tar.gz
+
+VOLUME /app
+WORKDIR /app
+
+# install python dependencies
+RUN apk add --no-cache --virtual .build-deps \
+    # needed to build psycopg2 & yarl
+    gcc \
+    # needed to build yarl
+    musl-dev \
+    # needed to build psycopg2
+    postgresql-dev \
+    # runtime dependency for psycopg2
+    && apk add --no-cache libpq \
+    # install python packages
+    && ls -la requirements \
+    && pip install -r requirements.txt \
+    # then remove build dependencies
+    && apk del .build-deps
+
+# start server
+ENTRYPOINT ["python"]
+CMD ["example.py"]

example/docker-compose.yml

@@ -0,0 +1,28 @@
+version: "3" # this is the Docker Compose specification
+               # version, not the app stack version
+
+services:
+
+  # seed:
+  #   build: .
+  #   environment:
+  #     MODE: development
+  #     DB_HOST: db
+  #     DB_USER: test
+  #     DB_PASS: pass
+  #     DB_NAME: dev
+  #   volumes:
+  #     - ./example:/app
+
+  db:
+    image: postgres:13-alpine
+    restart: always
+    ports:
+      - 5432:5432
+    environment:
+      POSTGRES_DB: dev
+      POSTGRES_USER: test
+      POSTGRES_PASSWORD: pass # DONT DO THIS IN PROD -- acceptable in dev,
+                              # but docker secrets should be used in prod
+                              # in conjunction with docker swarm in place
+                              # of docker compose

example/example/example.py

@@ -0,0 +1,120 @@
+"""An example of how to use Client & Model together."""
+
+import asyncio
+import json
+import os
+from uuid import uuid4, UUID
+from typing import Any, List
+
+from db_wrapper import ConnectionParameters, Client, Model
+
+from models import AModel, ExtendedModel, ExtendedModelData
+
+
+class UUIDJsonEncoder(json.JSONEncoder):
+    """Extended Json Encoder to allow encoding of objects containing UUID."""
+
+    def default(self, obj: Any) -> Any:
+        if isinstance(obj, UUID):
+            return str(obj)
+
+        return obj
+
+
+conn_params = ConnectionParameters(
+    host=os.getenv('DB_HOST', 'localhost'),
+    # user=os.getenv('DB_USER', 'postgres'),
+    # password=os.getenv('DB_PASS', 'postgres'),
+    # database=os.getenv('DB_NAME', 'postgres'))
+    user=os.getenv('DB_USER', 'test'),
+    password=os.getenv('DB_PASS', 'pass'),
+    database=os.getenv('DB_NAME', 'dev'))
+client = Client(conn_params)
+
+a_model = Model[AModel](client, 'a_model')
+extended_model = ExtendedModel(client)
+
+
+async def create_a_model_record() -> UUID:
+    """
+    Show how to use a simple Model instance.
+
+    Create a new record using the default Model.create.one method.
+    """
+    new_record: AModel = {
+        '_id': uuid4(),
+        'string': 'some string',
+        'integer': 1,
+        'array': ['an', 'array', 'of', 'strings'],
+    }
+
+    await a_model.create.one(new_record)
+
+    return new_record['_id']
+
+
+async def read_a_model(id_value: UUID) -> AModel:
+    """Show how to read a record with a given id value."""
+    # read.one_by_id expects a string, so UUID values need
+    # converted using str()
+    return await a_model.read.one_by_id(str(id_value))
+
+
+async def create_extended_models() -> None:
+    """Show how using an extended Model can be the same as the defaults."""
+    new_records: List[ExtendedModelData] = [{
+        '_id': uuid4(),
+        'string': 'something',
+        'integer': 1,
+        'json': {'a': 1, 'b': 2, 'c': True}
+    }, {
+        '_id': uuid4(),
+        'string': 'something',
+        'integer': 1,
+        'json': {'a': 1, 'b': 2, 'c': True}
+    }, {
+        '_id': uuid4(),
+        'string': 'something',
+        'integer': 1,
+        'json': {'a': 1, 'b': 2, 'c': True}
+    }, {
+        '_id': uuid4(),
+        'string': 'something',
+        'integer': 1,
+        'json': {'a': 1, 'b': 2, 'c': True}
+    }]
+
+    # by looping over a list of records, you can use the default create.one
+    # method to create each record as a separate transaction
+    for record in new_records:
+        await extended_model.create.one(record)
+
+
+async def read_extended_models() -> List[ExtendedModelData]:
+    """Show how to use an extended Model's new methods."""
+    # We defined read.all in ./models/extended_model.py's ExtendedRead class,
+    # then replaced ExtendedModel's read property with ExtendedRead.
+    # As a result, we can call it just like any other method on Model.read.
+    return await extended_model.read.all()
+
+
+async def run() -> None:
+    """Show how to make a connection, execute queries, & disconnect."""
+    await client.connect()
+
+    try:
+        new_id = await create_a_model_record()
+        created_a_model = await read_a_model(new_id)
+        await create_extended_models()
+        extended_models = await read_extended_models()
+    finally:
+        await client.disconnect()
+
+    print(json.dumps(created_a_model, cls=UUIDJsonEncoder))
+    print(json.dumps(extended_models, cls=UUIDJsonEncoder))
+
+if __name__ == '__main__':
+    # A simple app can be run using asyncio's run method.
+    # Sometimes, you may need more advanced loop management; look into
+    # asyncio.get_event_loop for more.
+    asyncio.run(run())

example/example/models/__init__.py

@@ -0,0 +1,2 @@
+from .a_model import AModel
+from .extended_model import ExtendedModelData, ExtendedModel

example/example/models/a_model.py

@@ -0,0 +1,17 @@
+"""Define a simple Model data type."""
+
+from typing import List
+
+from db_wrapper.model import ModelData
+
+
+class AModel(ModelData):
+    """An example Item."""
+
+    # PENDS python 3.9 support in pylint,
+    # ModelData inherits from TypedDict
+    # pylint: disable=too-few-public-methods
+
+    string: str
+    integer: int
+    array: List[str]

example/example/models/a_model.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS "a_model" (
+    "_id" uuid PRIMARY KEY,
+    "string" varchar(255),
+    "integer" smallint,
+    "array" varchar(255) []
+);

example/example/models/extended_model.py

@@ -0,0 +1,102 @@
+"""An example implementation of custom object Model."""
+
+import json
+from typing import Any, List, Dict
+
+from psycopg2 import sql
+from psycopg2.extensions import register_adapter
+from psycopg2.extras import Json
+
+from db_wrapper.model import ModelData, Model, Read, Create, Client
+
+# tell psycopg2 to adapt all dictionaries to json instead of
+# the default hstore
+register_adapter(dict, Json)
+
+
+class ExtendedModelData(ModelData):
+    """An example Item."""
+
+    # PENDS python 3.9 support in pylint,
+    # ModelData inherits from TypedDict
+    # pylint: disable=too-few-public-methods
+
+    string: str
+    integer: int
+    json: Dict[str, Any]
+
+
+class ExtendedCreator(Create[ExtendedModelData]):
+    """Add custom json loading to Model.create."""
+
+    # pylint: disable=too-few-public-methods
+
+    async def one(self, item: ExtendedModelData) -> ExtendedModelData:
+        """Override default Model.create.one method."""
+        columns: List[sql.Identifier] = []
+        values: List[sql.Identifier] = []
+
+        for column, value in item.items():
+            if column == 'json':
+                values.append(sql.Literal(json.dumps(value)))
+            else:
+                values.append(sql.Literal(value))
+
+            columns.append(sql.Identifier(column))
+
+        query = sql.SQL(
+            'INSERT INTO {table} ({columns}) '
+            'VALUES ({values}) '
+            'RETURNING *;'
+        ).format(
+            table=self._table,
+            columns=sql.SQL(',').join(columns),
+            values=sql.SQL(',').join(values),
+        )
+
+        result: List[ExtendedModelData] = \
+            await self._client.execute_and_return(query)
+
+        return result[0]
+
+
+class ExtendedReader(Read[ExtendedModelData]):
+    """Add custom method to Model.read."""
+
+    async def all_by_string(self, string: str) -> List[ExtendedModelData]:
+        """Read all rows with matching `string` value."""
+        query = sql.SQL(
+            'SELECT * '
+            'FROM {table} '
+            'WHERE string = {string};'
+        ).format(
+            table=self._table,
+            string=sql.Identifier(string)
+        )
+
+        result: List[ExtendedModelData] = await self \
+            ._client.execute_and_return(query)
+
+        return result
+
+    async def all(self) -> List[ExtendedModelData]:
+        """Read all rows."""
+        query = sql.SQL('SELECT * FROM {table}').format(
+            table=self._table)
+
+        result: List[ExtendedModelData] = await self \
+            ._client.execute_and_return(query)
+
+        return result
+
+
+class ExtendedModel(Model[ExtendedModelData]):
+    """Build an ExampleItem Model instance."""
+
+    read: ExtendedReader
+    create: ExtendedCreator
+
+    def __init__(self, client: Client) -> None:
+        super().__init__(client, 'extended_model')
+        self.read = ExtendedReader(self.client, self.table)
+        self.create = ExtendedCreator(self.client, self.table)

example/example/models/extended_model.sql

@@ -0,0 +1,8 @@
+CREATE EXTENSION hstore;
+
+CREATE TABLE IF NOT EXISTS "extended_model" (
+    "_id" uuid PRIMARY KEY,
+    "string" varchar(255),
+    "integer" smallint,
+    "json" jsonb
+);

example/example/py.typed

@@ -0,0 +1 @@
+Marker