v0.0.1 🍀

Author: RobertoPrevato

.flake8

@@ -0,0 +1,9 @@
+[flake8]
+exclude = __pycache__,built,build,venv
+ignore = E203, E266, W503
+max-line-length = 88
+max-complexity = 18
+select = B,C,E,F,W,T4,B9
+per-file-ignores =
+    tests/app.py:E402
+    tests/migrations/env.py:E402

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: RobertoPrevato

.github/workflows/build.yml

@@ -0,0 +1,107 @@
+name: Build
+
+on:
+  release:
+    types: [published]
+  push:
+    branches:
+      - main
+      - dev
+  pull_request:
+    branches:
+      - "*"
+
+env:
+  PROJECT_NAME: blacksheepsqlalchemy
+
+jobs:
+  build:
+    runs-on: ubuntu-18.04
+    strategy:
+      matrix:
+        python-version: [3.7, 3.8, 3.9]
+
+    steps:
+      - uses: actions/checkout@v1
+        with:
+          fetch-depth: 9
+          submodules: false
+
+      - name: Use Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v1
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: actions/cache@v1
+        id: depcache
+        with:
+          path: deps
+          key: requirements-pip-${{ matrix.python-version }}-${{ hashFiles('requirements.txt') }}
+
+      - name: Download dependencies
+        if: steps.depcache.outputs.cache-hit != 'true'
+        run: |
+          pip download --dest=deps -r dev-requirements.txt
+
+      - name: Install dependencies
+        run: |
+          pip install -U --no-index --find-links=deps deps/*
+
+      - name: Prepare test database
+        run: |
+          cd tests
+          alembic upgrade head
+          cp example.db ../
+
+      - name: Run tests
+        run: |
+          flake8 && pytest --doctest-modules --junitxml=junit/pytest-results-${{ matrix.python-version }}.xml --cov=$PROJECT_NAME --cov-report=xml --ignore=tests/migrations tests/
+
+      - name: Upload pytest test results
+        uses: actions/upload-artifact@master
+        with:
+          name: pytest-results-${{ matrix.python-version }}
+          path: junit/pytest-results-${{ matrix.python-version }}.xml
+        if: always()
+
+      - name: Codecov
+        run: |
+          bash <(curl -s https://codecov.io/bash)
+
+      - name: Install distribution dependencies
+        run: pip install --upgrade twine setuptools wheel
+        if: matrix.python-version == 3.8 || matrix.python-version == 3.9
+
+      - name: Create distribution package
+        run: python setup.py sdist bdist_wheel
+        if: matrix.python-version == 3.8 || matrix.python-version == 3.9
+
+      - name: Upload distribution package
+        uses: actions/upload-artifact@master
+        with:
+          name: dist-package-${{ matrix.python-version }}
+          path: dist
+        if: matrix.python-version == 3.8 || matrix.python-version == 3.9
+
+  publish:
+    runs-on: ubuntu-18.04
+    needs: build
+    if: github.event_name == 'release'
+    steps:
+      - name: Download a distribution artifact
+        uses: actions/download-artifact@v2
+        with:
+          name: dist-package-3.9
+          path: dist
+      - name: Publish distribution 📦 to Test PyPI
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          skip_existing: true
+          user: __token__
+          password: ${{ secrets.test_pypi_password }}
+          repository_url: https://test.pypi.org/legacy/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          user: __token__
+          password: ${{ secrets.pypi_password }}

.gitignore

@@ -127,3 +127,4 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+/tests/example.db

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2021-05-22 :four_leaf_clover:
+- First working implementation, with integration offering injection of
+  db connections and ORM sessions provided by SQLAlchemy

Makefile

@@ -0,0 +1,29 @@
+.PHONY: release test
+
+
+artifacts: test
+	python setup.py sdist bdist_wheel
+
+
+clean:
+	rm -rf dist/
+
+
+prepforbuild:
+	pip install --upgrade twine setuptools wheel
+
+
+uploadtest:
+	twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+
+
+release: clean artifacts
+	twine upload --repository-url https://upload.pypi.org/legacy/ dist/*
+
+
+test:
+	flake8 blacksheepsqlalchemy && pytest tests/
+
+
+testcov:
+	pytest --cov-report html --cov=blacksheepsqlalchemy tests/

README.md

@@ -1,2 +1,82 @@
+[![Build](https://github.com/Neoteroi/BlackSheep-SQLAlchemy/actions/workflows/build.yml/badge.svg)](https://github.com/Neoteroi/BlackSheep-SQLAlchemy/actions/workflows/build.yml)
+[![pypi](https://img.shields.io/pypi/v/BlackSheep-SQLAlchemy.svg?color=blue)](https://pypi.org/project/BlackSheep-SQLAlchemy/)
+[![versions](https://img.shields.io/pypi/pyversions/blacksheep-sqlalchemy.svg)](https://github.com/Neoteroi/BlackSheep-SQLAlchemy/)
+[![license](https://img.shields.io/github/license/Neoteroi/blacksheep-sqlalchemy.svg)](https://github.com/Neoteroi/BlackSheep-SQLAlchemy/blob/main/LICENSE)
+
 # BlackSheep-SQLAlchemy
-Extension for BlackSheep that simplifies the use of SQLAlchemy in the web framework.
+Extension for [BlackSheep](https://github.com/Neoteroi/BlackSheep) that
+simplifies the use of SQLAlchemy in the web framework.
+
+```bash
+pip install blacksheep-sqlalchemy
+```
+
+## How to use
+
+```python
+from blacksheep.server import Application
+from blacksheepsqlalchemy import use_sqlalchemy
+
+app = Application()
+
+use_sqlalchemy(app, connection_string="<CONNECTION_STRING>")
+
+```
+
+After registering SQLAlchemy, services are configured in the application, so
+they are automatically resolved in any request handler requiring a SQLAlchemy
+db connections or db sessions; for example:
+
+```python
+
+@get("/api/countries")
+async def get_countries(db_connection) -> List[CountryData]:
+    """
+    Fetches the countries using a database connection.
+    """
+    result = []
+    async with db_connection:
+        items = await db_connection.execute(text("SELECT * FROM country"))
+        for item in items.fetchall():
+            result.append(CountryData(item["id"], item["name"]))
+    return result
+
+```
+
+Services can be injected at any level of the resolution graph, so `BlackSheep`
+and `rodi` support out of the box the scenario of db connections or db sessions
+referenced in the business logic but not directly by the front-end layer
+(depending on programmers' preference and their notion of best practices when
+building web apps).
+
+Services can be injected in the following ways:
+
+| By alias      | By type annotation | Value                                               |
+| ------------- | ------------------ | --------------------------------------------------- |
+| db_connection | AsyncConnection    | instance of AsyncConnection (scoped to web request) |
+| db_session    | AsyncSession       | instance of AsyncSession (scoped to web request)    |
+| db_engine     | AsyncEngine        | instance of AsyncEngine (singleton)                 |
+
+---
+
+For example, using SQLite:
+
+* requires driver: `pip install aiosqlite`
+* connection string: `sqlite+aiosqlite:///example.db`
+
+See the `tests` folder for a working example using database migrations applied
+with `Alembic`, and a documented API that offers methods to fetch, create,
+delete countries objects.
+
+---
+
+### Note
+BlackSheep is designed to be used in `async` way, therefore this library
+requires the use of an asynchronous driver.
+
+## References
+
+* [SQLAlchemy - support for asyncio](https://docs.sqlalchemy.org/en/14/orm/extensions/asyncio.html)
+
+## Documentation
+Please refer to the [documentation website](https://www.neoteroi.dev/blacksheep/).

blacksheepsqlalchemy/__init__.py

@@ -0,0 +1,73 @@
+from typing import Optional
+
+from sqlalchemy.ext.asyncio import (
+    create_async_engine,
+    AsyncEngine,
+    AsyncSession,
+    AsyncConnection,
+)
+from blacksheep.server import Application
+
+
+def __configure_services(
+    app: Application,
+    engine: AsyncEngine,
+    db_engine_alias: str,
+    db_connection_alias: str,
+    db_session_alias: str,
+) -> None:
+    # Note: pytest-cov generates false negatives for the following three functions
+    # defined locally; they work and this is verified by tests
+
+    async def dispose_engine(_):
+        nonlocal engine
+        await engine.dispose()
+
+    app.on_stop += dispose_engine
+
+    def connection_factory() -> AsyncConnection:
+        return engine.connect()
+
+    def session_factory() -> AsyncSession:
+        return AsyncSession(engine, expire_on_commit=False)
+
+    app.services.add_instance(engine)
+    app.services.add_alias(db_engine_alias, AsyncEngine)
+
+    app.services.add_scoped_by_factory(connection_factory)
+    app.services.add_alias(db_connection_alias, AsyncConnection)
+
+    app.services.add_scoped_by_factory(session_factory)
+    app.services.add_alias(db_session_alias, AsyncSession)
+
+    # TODO: configure an exception handler for
+    # sqlalchemy.exc.IntegrityError: (sqlite3.IntegrityError) UNIQUE constraint failed,
+    # to return an HTTP Conflict response in such case!
+
+
+def use_sqlalchemy(
+    app: Application,
+    *,
+    connection_string: Optional[str] = None,
+    echo: bool = False,
+    engine: Optional[AsyncEngine] = None,
+    db_engine_alias: str = "db_engine",
+    db_connection_alias: str = "db_connection",
+    db_session_alias: str = "db_session",
+) -> None:
+    """
+    Configures the given application to use SQLAlchemy and provide services that can be
+    injected in request handlers.
+    """
+    if engine is None:
+        if not connection_string:
+            raise TypeError(
+                "Either pass a connection_string or an instance of "
+                "sqlalchemy.ext.asyncio.AsyncEngine"
+            )
+        engine = create_async_engine(connection_string, echo=echo)
+
+    assert engine is not None
+    __configure_services(
+        app, engine, db_engine_alias, db_connection_alias, db_session_alias
+    )

dev-requirements.txt

@@ -0,0 +1,49 @@
+aiosqlite==0.17.0
+alembic==1.6.3
+appdirs==1.4.4
+asyncpg==0.23.0
+attrs==21.2.0
+black==21.5b1
+blacksheep==1.0.5
+cchardet==2.1.7
+certifi==2020.12.5
+click==7.1.2
+coverage==5.5
+essentials==1.1.4
+essentials-openapi==0.1.2
+flake8==3.9.2
+greenlet==1.1.0
+guardpost==0.0.7
+h11==0.12.0
+httptools==0.2.0
+iniconfig==1.1.1
+itsdangerous==1.1.0
+Jinja2==2.11.3
+Mako==1.1.4
+MarkupSafe==2.0.1
+mccabe==0.6.1
+mypy==0.812
+mypy-extensions==0.4.3
+packaging==20.9
+pathspec==0.8.1
+pluggy==0.13.1
+py==1.10.0
+pycodestyle==2.7.0
+pyflakes==2.3.1
+pyparsing==2.4.7
+pytest==6.2.4
+pytest-asyncio==0.15.1
+pytest-cov==2.12.0
+python-dateutil==2.8.1
+python-editor==1.0.4
+PyYAML==5.4.1
+regex==2021.4.4
+rodi==1.1.1
+six==1.16.0
+SQLAlchemy==1.4.15
+sqlalchemy-stubs==0.4
+sqlalchemy2-stubs==0.0.2a1
+toml==0.10.2
+typed-ast==1.4.3
+typing-extensions==3.10.0.0
+uvicorn==0.13.4