+
-
+
- π The Starlette events bridge you need. π + π The Starlette events bridge that you need. π
@@ -54,3 +54,128 @@ To install Starlette Bridge, simply run: ```shell $ pip install starlette-bridge ``` + +## How to use + +This is actually very simple to do it. You don't need to do anything particularly difficult, in +fact, you only need to update where your Starlette object comes from. + +```python hl_lines="1" +from starlette_bridge import Starlette + +app = Starlette() +``` + +And that is pretty much it. + +### How does it work + +Starlette bridge simply maps your `on_startup` and `on_shutdown` events and converts them into +the new `lifespan` async generator from `Starlette`. + +This way you can continue to use your preferred way of assembling the events while maintaining +the new structure required by Starlette for managing events. + +### on_event and add_event_handler + +These two pieces of functionality are also supported by the bridge making sure that what you had +in the past, still remains working as is without changing the syntax. + +Let us see an example how it works. We will be using [Starlette Bridge](https://saffier.tarsild.io) because +already contains events we want to use. + +#### on_startup/on_shutdown + +Using the `on_startup` and `on_shutdown`. + +```python hl_lines="3 10-11" +from saffier import Database, Registry + +from starlette_bridge import Starlette + +database = Database("sqlite:///db.sqlite") +models = Registry(database=database) + + +app = Starlette( + on_startup=[database.connect], + on_shutdown=[database.disconnect], +) +``` + +#### Lifespan + +You can, of course, use the lifespan as well. + +```python hl_lines="5 20" +from contextlib import asynccontextmanager + +from saffier import Database, Registry + +from starlette_bridge import Starlette + +database = Database("sqlite:///db.sqlite") +models = Registry(database=database) + + +@asynccontextmanager +async def lifespan(app: Starlette): + # On startup + await database.connect() + yield + # On shutdown + await database.disconnect() + + +app = Starlette(lifespan=lifespan) +``` + +#### on_event and add_event_handler + +As mentioned before, those two functionalities are also available. + +##### on_event + +```python hl_lines="3 12 17" +from saffier import Database, Registry + +from starlette_bridge import Starlette + +database = Database("sqlite:///db.sqlite") +models = Registry(database=database) + + +app = Starlette() + + +@app.on_event("startup") +async def start_database(): + await database.connect() + + +@app.on_event("shutdown") +async def close_database(): + await database.disconnect() +``` + +##### add_event_handler + +```python hl_lines="3 10-11" +from saffier import Database, Registry + +from starlette_bridge import Starlette + +database = Database("sqlite:///db.sqlite") +models = Registry(database=database) + + +app = Starlette() +app.add_event_handler("startup", database.connect) +app.add_event_handler("shutdown", database.disconnect) +``` + +## Notes + +This is from the same author of [Esmerald](https://esmerald.dev), +[Starlette Bridge](https://saffier.tarsild.io) and [Asyncz](https://asyncz.tarsild.io). Have a look around +those techologies as well π. diff --git a/docs/contributing.md b/docs/contributing.md index 8e9137f..3b2a6d8 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,23 +1,23 @@ # Contributing -Thank you for showing interes in contributing to Saffier. There are many ways you can help and contribute to the +Thank you for showing interes in contributing to Starlette Bridge. There are many ways you can help and contribute to the project. -* Try Saffier and [report bugs and issues](https://github.com/tarsil/starlette_bridge/issues/new) you find. -* [Implement new features](https://github.com/tarsil/starlette_bridge/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) -* Help othes by [reviewing pull requests](https://github.com/tarsil/starlette_bridge/pulls) +* Try Starlette Bridge and [report bugs and issues](https://github.com/tarsil/starlette-bridge/issues/new) you find. +* [Implement new features](https://github.com/tarsil/starlette-bridge/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) +* Help othes by [reviewing pull requests](https://github.com/tarsil/starlette-bridge/pulls) * Help writting documentation * Use the discussions and actively participate on them. -* Become an contributor by helping Saffier growing and spread the words across small, medium, large or any company +* Become an contributor by helping Starlette Bridge growing and spread the words across small, medium, large or any company size. ## Reporting possible bugs and issues -It is natural that you might find something that Saffier should support or even experience some sorte of unexpected +It is natural that you might find something that Starlette Bridge should support or even experience some sorte of unexpected behaviour that needs addressing. The way we love doing things is very simple, contributions should start out with a -[discussion](https://github.com/tarsil/starlette_bridge/discussions). The potential bugs shall be raised as "Potential Issue" +[discussion](https://github.com/tarsil/starlette-bridge/discussions). The potential bugs shall be raised as "Potential Issue" in the discussions, the feature requests may be raised as "Ideas". We can then decide if the discussion needs to be escalated into an "Issue" or not. @@ -37,18 +37,18 @@ it clear to understand and get the required help. ## Development -To develop for Saffier, create a fork of the [Saffier repository](https://github.com/tarsil/starlette_bridge) on GitHub. +To develop for Starlette Bridge, create a fork of the [Starlette Bridge repository](https://github.com/tarsil/starlette-bridge) on GitHub. After, clone your fork with the follow command replacing `YOUR-USERNAME` wih your GitHub username: ```shell -$ git clone https://github.com/YOUR-USERNAME/starlette_bridge +$ git clone https://github.com/YOUR-USERNAME/starlette-bridge ``` ### Install the project dependencies ```shell -$ cd starlette_bridge +$ cd starlette-bridge $ scripts/install ``` @@ -60,7 +60,7 @@ To run the tests, use: $ scripts/test ``` -Because Saffier uses pytest, any additional arguments will be passed. More info within the +Because Starlette Bridge uses pytest, any additional arguments will be passed. More info within the [pytest documentation](https://docs.pytest.org/en/latest/how-to/usage.html) For example, to run a single test_script: @@ -72,12 +72,12 @@ $ scripts/test tests/test_apiviews.py To run the linting, use: ```shell -$ scripts/lint +$ scripts/format ``` ### Documentation -Improving the documentation is quite easy and it is placed inside the `starlette_bridge/docs` folder. +Improving the documentation is quite easy and it is placed inside the `starlette-bridge/docs` folder. To start the docs, run: @@ -85,7 +85,7 @@ To start the docs, run: $ scripts/docs ``` -## Building Saffier +## Building Starlette Bridge To build a package locally, run: @@ -103,15 +103,15 @@ It will install the requirements and create a local build in your virtual enviro ## Releasing -*This section is for the maintainers of `Saffier`*. +*This section is for the maintainers of `Starlette Bridge`*. -### Building the Saffier for release +### Building the Starlette Bridge for release Before releasing a new package into production some considerations need to be taken into account. * **Changelog** * Like many projects, we follow the format from [keepchangelog](https://keepachangelog.com/en/1.0.0/). - * [Compare](https://github.com/tarsil/starlette_bridge/compare/) `main` with the release tag and list of the entries + * [Compare](https://github.com/tarsil/starlette-bridge/compare/) `main` with the release tag and list of the entries that are of interest to the users of the framework. * What **must** go in the changelog? added, changed, removed or deprecated features and the bug fixes. * What is **should not go** in the changelog? Documentation changes, tests or anything not specified in the @@ -124,7 +124,7 @@ point above. #### Releasing -Once the `release` PR is merged, create a new [release](https://github.com/tarsil/starlette_bridge/releases/new) +Once the `release` PR is merged, create a new [release](https://github.com/tarsil/starlette-bridge/releases/new) that includes: Example: diff --git a/docs/index.md b/docs/index.md index 1f966ff..3d55a49 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,24 +1,24 @@ -# Saffier +# Starlette Bridge
- 
+
- π The only Async ORM you need. π + π The Starlette events bridge that you need. π
@@ -26,7 +26,7 @@ **Documentation**: [https://starlette-bridge.tarsild.io](https://starlette-bridge.tarsild.io) π -**Source Code**: [https://github.com/tarsil/starlette_bridge](https://github.com/tarsil/starlette_bridge) +**Source Code**: [https://github.com/tarsil/starlette-bridge](https://github.com/tarsil/starlette-bridge) --- @@ -54,3 +54,68 @@ To install Starlette Bridge, simply run: ```shell $ pip install starlette-bridge ``` + +## How to use + +This is actually very simple to do it. You don't need to do anything particularly difficult, in +fact, you only need to update where your Starlette object comes from. + +```python hl_lines="1" +{! ../docs_src/quickstart.py !} +``` + +And that is pretty much it. + +### How does it work + +Starlette bridge simply maps your `on_startup` and `on_shutdown` events and converts them into +the new `lifespan` async generator from `Starlette`. + +This way you can continue to use your preferred way of assembling the events while maintaining +the new structure required by Starlette for managing events. + +### on_event and add_event_handler + +These two pieces of functionality are also supported by the bridge making sure that what you had +in the past, still remains working as is without changing the syntax. + +Let us see an example how it works. We will be using [Starlette Bridge](https://saffier.tarsild.io) because +already contains events we want to use. + +#### on_startup/on_shutdown + +Using the `on_startup` and `on_shutdown`. + +```python hl_lines="3 10-11" +{! ../docs_src/events.py !} +``` + +#### Lifespan + +You can, of course, use the lifespan as well. + +```python hl_lines="5 20" +{! ../docs_src/lifespan.py !} +``` + +#### on_event and add_event_handler + +As mentioned before, those two functionalities are also available. + +##### on_event + +```python hl_lines="3 12 17" +{! ../docs_src/on_event.py !} +``` + +##### add_event_handler + +```python hl_lines="3 10-11" +{! ../docs_src/add_event_handler.py !} +``` + +## Notes + +This is from the same author of [Esmerald](https://esmerald.dev), +[Starlette Bridge](https://saffier.tarsild.io) and [Asyncz](https://asyncz.tarsild.io). Have a look around +those techologies as well π. diff --git a/docs/release-notes.md b/docs/release-notes.md index 03d5f2d..fb05e65 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -2,8 +2,8 @@ ## 0.1.0 - This is the initial release of Starlette Bridge. -* Simmple bridge allowing to keep individual `on_startup`/`on_shutdown` events even those +* Simple bridge allowing to keep individual `on_startup`/`on_shutdown` events even those where depracated by `Starlette`. +* `on_event` and `add_event_handler` available to be used like Starlette. \ No newline at end of file diff --git a/docs/sponsorship.md b/docs/sponsorship.md index 5de81e5..aebef66 100644 --- a/docs/sponsorship.md +++ b/docs/sponsorship.md @@ -1,35 +1,28 @@ -# Help Saffier +# Help Starlette Bridge -Do you like **Saffier** and would like to help Saffier, other userd and the author? +Do you like **Starlette Bridge** and would like to help Starlette Bridge, other userd and the author? -## π¦ Follow Saffier and Esmerald on Twitter +## π¦ Follow Starlette Bridge and Esmerald on Twitter [Follow @apiesmerald on Twitter](https://twitter.com/apiesmerald) to get the latest news. -## β Star **Saffier** on GitHub +## β Star **Starlette Bridge** on GitHub -Giving a start to Saffier is very simple and helps promoting the work across the developers around the world. +Giving a start to Starlette Bridge is very simple and helps promoting the work across the developers around the world. The button is located at the top right. -[https://github.com/tarsil/starlette_bridge](https://github.com/tarsil/starlette_bridge). +[https://github.com/tarsil/starlette-bridge](https://github.com/tarsil/starlette-bridge). This will help spreading the word about the tool and how helpful has been. ## π Follow the GitHub repo -Following the GitHub repo will allow you to "watch" for any new release of Saffier and be always up to date. +Following the GitHub repo will allow you to "watch" for any new release of Starlette Bridge and be always up to date. You can click on "***watch***" and select "***custom***" -> "***Releases***"or any other you may find particular interesting to you. -## π¬ Join the official Saffier discord channel - -Our official chat is on discord, we find it very useful and free for people to discuss issues, helping and contributing -in a more organised manner. - -Saffier discord channel. Join us! πΈ - ## π₯ Sponsor the author The author built this framework with all of his heart and dedication and will continue to do it so but that also @@ -41,12 +34,6 @@ He can afterwards go for a coffeeβ, on him, to say thanksπ. You can become a [**Special One**](https://github.com/sponsors/tarsil/sponsorships?sponsor=tarsil&tier_id=230059&preview=false) or a [**Legend**](https://github.com/sponsors/tarsil/sponsorships?sponsor=tarsil&tier_id=230042&preview=false) -sponsor for Saffier. - -## βοΈ Sponsor the tools that made Saffier possible - -As you have seen in the documentation, Saffier stands on the shoulders of giants, Starlette and Pydantic. - -You can also sponsor: +sponsor for Starlette Bridge. -* Samuel Colvin (Pydantic) +This is also for Esmerald, Starlette Bridge, Asyncz and any other solution π. diff --git a/docs_src/add_event_handler.py b/docs_src/add_event_handler.py new file mode 100644 index 0000000..c1ea11e --- /dev/null +++ b/docs_src/add_event_handler.py @@ -0,0 +1,11 @@ +from saffier import Database, Registry + +from starlette_bridge import Starlette + +database = Database("sqlite:///db.sqlite") +models = Registry(database=database) + + +app = Starlette() +app.add_event_handler("startup", database.connect) +app.add_event_handler("shutdown", database.disconnect) diff --git a/docs_src/events.py b/docs_src/events.py new file mode 100644 index 0000000..468746f --- /dev/null +++ b/docs_src/events.py @@ -0,0 +1,12 @@ +from saffier import Database, Registry + +from starlette_bridge import Starlette + +database = Database("sqlite:///db.sqlite") +models = Registry(database=database) + + +app = Starlette( + on_startup=[database.connect], + on_shutdown=[database.disconnect], +) diff --git a/docs_src/lifespan.py b/docs_src/lifespan.py new file mode 100644 index 0000000..23727aa --- /dev/null +++ b/docs_src/lifespan.py @@ -0,0 +1,20 @@ +from contextlib import asynccontextmanager + +from saffier import Database, Registry + +from starlette_bridge import Starlette + +database = Database("sqlite:///db.sqlite") +models = Registry(database=database) + + +@asynccontextmanager +async def lifespan(app: Starlette): + # On startup + await database.connect() + yield + # On shutdown + await database.disconnect() + + +app = Starlette(lifespan=lifespan) diff --git a/docs_src/on_event.py b/docs_src/on_event.py new file mode 100644 index 0000000..c8d2e25 --- /dev/null +++ b/docs_src/on_event.py @@ -0,0 +1,19 @@ +from saffier import Database, Registry + +from starlette_bridge import Starlette + +database = Database("sqlite:///db.sqlite") +models = Registry(database=database) + + +app = Starlette() + + +@app.on_event("startup") +async def start_database(): + await database.connect() + + +@app.on_event("shutdown") +async def close_database(): + await database.disconnect() diff --git a/docs_src/quickstart.py b/docs_src/quickstart.py index e69de29..b9af20a 100644 --- a/docs_src/quickstart.py +++ b/docs_src/quickstart.py @@ -0,0 +1,3 @@ +from starlette_bridge import Starlette + +app = Starlette() diff --git a/mkdocs.yml b/mkdocs.yml index cdc91c5..a1ebe0c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ -site_name: Saffier -site_description: The only python ORM you will ever need. +site_name: Starlette Bridge +site_description: The Starlette events bridge that you need. site_url: https://starlette-bridge.tarsild.io theme: @@ -8,7 +8,7 @@ theme: language: en palette: - scheme: "default" - primary: "purple" + primary: "green" accent: "amber" media: "(prefers-color-scheme: light)" toggle: @@ -21,15 +21,13 @@ theme: toggle: icon: "material/lightbulb-outline" name: "Switch to light mode" - favicon: statics/images/favicon.ico - logo: statics/images/logo-white.svg features: - search.suggest - search.highlight - content.tabs.link -repo_name: tarsil/starlette_bridge -repo_url: https://github.com/tarsil/starlette_bridge +repo_name: tarsil/starlette-bridge +repo_url: https://github.com/tarsil/starlette-bridge edit_uri: "" plugins: - search @@ -37,7 +35,7 @@ plugins: data: data nav: - - Saffier: "index.md" + - Starlette Bridge: "index.md" - Contributing: "contributing.md" - Sponsorship: "sponsorship.md" - Release Notes: "release-notes.md" diff --git a/pyproject.toml b/pyproject.toml index f15b072..416b7c7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,8 +4,8 @@ build-backend = "hatchling.build" [project] name = "starlette_bridge" -description = "The Starlette events bridge you need." -long_description = "The Starlette events bridge you need." +description = "The Starlette events bridge that you need." +long_description = "The Starlette events bridge that you need." readme = "README.md" requires-python = ">=3.8" dynamic = ['version']
+
+
+