Metadata-Version: 2.1
Name: blacksheep-sqlalchemy
Version: 0.0.1
Summary: Extension for BlackSheep to use SQLAlchemy
Home-page: https://github.com/Neoteroi/BlackSheep-SQLAlchemy
Author: RobertoPrevato
Author-email: roberto.prevato@gmail.com
License: MIT
Keywords: blacksheep sqlalchemy orm database
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
Requires-Dist: blacksheep
Requires-Dist: SQLAlchemy (==1.4.15)

[![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](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/).


