| Name | backgrounder JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | |
| Summary | Run background tasks in asynchronous mode at all times |
| upload_time | 2024-01-05 15:13:45 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
backgrounder
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Backgrounder
<p align="center">
<a href="https://backgrounder.dymmond.com"><img src="https://res.cloudinary.com/dymmond/image/upload/v1704377775/backgrounder/logo-ext_iwwiw1.png" alt='Backgrounder'></a>
</p>
<p align="center">
<em>🚀 Run background tasks in async mode in any application. 🚀</em>
</p>
<p align="center">
<a href="https://github.com/dymmond/backgrounder/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" target="_blank">
<img src="https://github.com/dymmond/backgrounder/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" alt="Test Suite">
</a>
<a href="https://pypi.org/project/backgrounder" target="_blank">
<img src="https://img.shields.io/pypi/v/backgrounder?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
<a href="https://pypi.org/project/backgrounder" target="_blank">
<img src="https://img.shields.io/pypi/pyversions/backgrounder.svg?color=%2334D058" alt="Supported Python versions">
</a>
</p>
---
**Documentation**: [https://backgrounder.dymmond.com](https://backgrounder.dymmond.com) 📚
**Source Code**: [https://github.com/dymmond/backgrounder](https://github.com/dymmond/backgrounder)
**The official supported version is always the latest released**.
---
## Motivation
Running background tasks nowadays is a must and not a nice to have and some of the the greatest
frameworks out there implement this functionality as part of the ASGI reference.
[Esmerald][esmerald], [FastAPI][fastapi] and [Starlette][starlette] by design implement the background
tasks for you and those are great functionailties to have but what if you want to use background
tasks without any of these frameworks? What if you simply want to have something that simply
runs background tasks regardless of the framework you are using *if you are using one at all**?
Well, this is where **backgrounder** comes to play and help you.
## Compatibility
This package is 100% compatible with any ASGI framework that implements or wants to implement
background tasks, which means you can even use it with [Esmerald][esmerald], [FastAPI][fastapi] or [Starlette][starlette]
without using the native version of each framework but **also allows** to run this inside anything else
like **Django** for example.
**Due to the nature of the package, this is only available from Python 3.10+.**
## How to use it
This package is actually very simple to use it, really, there is no rocket science since the
library handles a lot of the magic for you.
For the purposes of these examples, we will be using [Esmerald][esmerald] since it belongs to the
same ecosystem but feel free to use with anything you want.
### Using the backgrounder instead of default from the framework
As mentioned before, usually the ASGI frameworks like **Esmerald** come with a default background
task option but let us assume you want to use **backgrounder** instead how it would look like.
```python
from esmerald.responses import Response, get
from backgrounder.tasks import Task, Tasks
def set_values(values_to_add) -> None:
for value in values_to_add:
values.add(value)
tasks = Tasks(
[
Task(set_values, ["a", "b", "c", "h"]),
Task(set_values, values_to_add=["d", "e", "f", "g"]),
],
as_group=True,
)
@get(background=tasks)
async def home() -> Response:
return Response("Task started", media_type="text/plain")
```
Simple, right? Internally Esmerald or any other framework will handle the process of the background
tasks for you and instead of using the native library, we simply pass the `Tasks` object from
the **backgrounder** and it should be it.
### Using as independent async object in any application
Well, here it is where the things become interesting. What if you want to run the tasks outside
of the response of a framework? Or if you want to run without a framework at all?
Well you can use the [Task](./tasks.md#task) directly. Something like this
```python
from backgrounder import Task
async def send_notification(email: str):
"""
Sends an email notification to a given email
"""
...
task = Task(send_notification, "user@example.com")
await task()
```
This will make sure your task will always run in `async` mode and therefore, not blocking and
taking advantage of the asynchronous functionality from Python.
You can also define `blocking` functions. **Backgrounder** will make sure it will always run them
in `async` for you.
```python
from backgrounder import Task
def send_notification(email: str):
"""
Sends an email notification to a given email
"""
...
task = Task(send_notification, "user@example.com")
await task()
```
This can be particularly useful if you want to implement some asynchronous functionality in your
applications without using a whole ASGI framework for it, for example, using **Django**, although
now also supporting `async` natively, you might want to run some background tasks there that basically
do not exist natively (by the time of the writting).
### The decorator
**Backgrounder** also offers a decorator for you to use which can be extremely useful if you don't
want to use the [Task](./tasks.md#task) object directly, providing a cleaner version out of the box.
```python
from backgrounder import background
@background
def send_notification(email: str):
"""
Sends an email notification to a given email
"""
...
send_notification("user@example.com")
```
As simple as this, this will automatically execute the task in the background for you with all
the `async` magic being provided.
[starlette]: https://www.starlette.io
[esmerald]: https://esmerald.dev
[fastapi]: https://fastapi.tiangolo.com
Raw data
{
"_id": null,
"home_page": "",
"name": "backgrounder",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "backgrounder",
"author": "",
"author_email": "Tiago Silva <tiago.silva@dymmond.com>",
"download_url": "https://files.pythonhosted.org/packages/e6/0d/76dfac31426d3923f21d8b5823895885749244bcc1c55edacbca67db159d/backgrounder-0.2.0.tar.gz",
"platform": null,
"description": "# Backgrounder\n\n<p align=\"center\">\n <a href=\"https://backgrounder.dymmond.com\"><img src=\"https://res.cloudinary.com/dymmond/image/upload/v1704377775/backgrounder/logo-ext_iwwiw1.png\" alt='Backgrounder'></a>\n</p>\n\n<p align=\"center\">\n <em>\ud83d\ude80 Run background tasks in async mode in any application. \ud83d\ude80</em>\n</p>\n\n<p align=\"center\">\n<a href=\"https://github.com/dymmond/backgrounder/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main\" target=\"_blank\">\n <img src=\"https://github.com/dymmond/backgrounder/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main\" alt=\"Test Suite\">\n</a>\n\n<a href=\"https://pypi.org/project/backgrounder\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/backgrounder?color=%2334D058&label=pypi%20package\" alt=\"Package version\">\n</a>\n\n<a href=\"https://pypi.org/project/backgrounder\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/pyversions/backgrounder.svg?color=%2334D058\" alt=\"Supported Python versions\">\n</a>\n</p>\n\n---\n\n**Documentation**: [https://backgrounder.dymmond.com](https://backgrounder.dymmond.com) \ud83d\udcda\n\n**Source Code**: [https://github.com/dymmond/backgrounder](https://github.com/dymmond/backgrounder)\n\n**The official supported version is always the latest released**.\n\n---\n\n## Motivation\n\nRunning background tasks nowadays is a must and not a nice to have and some of the the greatest\nframeworks out there implement this functionality as part of the ASGI reference.\n\n[Esmerald][esmerald], [FastAPI][fastapi] and [Starlette][starlette] by design implement the background\ntasks for you and those are great functionailties to have but what if you want to use background\ntasks without any of these frameworks? What if you simply want to have something that simply\nruns background tasks regardless of the framework you are using *if you are using one at all**?\n\nWell, this is where **backgrounder** comes to play and help you.\n\n## Compatibility\n\nThis package is 100% compatible with any ASGI framework that implements or wants to implement\nbackground tasks, which means you can even use it with [Esmerald][esmerald], [FastAPI][fastapi] or [Starlette][starlette]\nwithout using the native version of each framework but **also allows** to run this inside anything else\nlike **Django** for example.\n\n**Due to the nature of the package, this is only available from Python 3.10+.**\n\n## How to use it\n\nThis package is actually very simple to use it, really, there is no rocket science since the\nlibrary handles a lot of the magic for you.\n\nFor the purposes of these examples, we will be using [Esmerald][esmerald] since it belongs to the\nsame ecosystem but feel free to use with anything you want.\n\n### Using the backgrounder instead of default from the framework\n\nAs mentioned before, usually the ASGI frameworks like **Esmerald** come with a default background\ntask option but let us assume you want to use **backgrounder** instead how it would look like.\n\n```python\nfrom esmerald.responses import Response, get\n\nfrom backgrounder.tasks import Task, Tasks\n\n\ndef set_values(values_to_add) -> None:\n for value in values_to_add:\n values.add(value)\n\n\ntasks = Tasks(\n [\n Task(set_values, [\"a\", \"b\", \"c\", \"h\"]),\n Task(set_values, values_to_add=[\"d\", \"e\", \"f\", \"g\"]),\n ],\n as_group=True,\n)\n\n\n@get(background=tasks)\nasync def home() -> Response:\n return Response(\"Task started\", media_type=\"text/plain\")\n```\n\nSimple, right? Internally Esmerald or any other framework will handle the process of the background\ntasks for you and instead of using the native library, we simply pass the `Tasks` object from\nthe **backgrounder** and it should be it.\n\n### Using as independent async object in any application\n\nWell, here it is where the things become interesting. What if you want to run the tasks outside\nof the response of a framework? Or if you want to run without a framework at all?\n\nWell you can use the [Task](./tasks.md#task) directly. Something like this\n\n```python\nfrom backgrounder import Task\n\nasync def send_notification(email: str):\n \"\"\"\n Sends an email notification to a given email\n \"\"\"\n ...\n\n\ntask = Task(send_notification, \"user@example.com\")\nawait task()\n```\n\nThis will make sure your task will always run in `async` mode and therefore, not blocking and\ntaking advantage of the asynchronous functionality from Python.\n\nYou can also define `blocking` functions. **Backgrounder** will make sure it will always run them\nin `async` for you.\n\n```python\nfrom backgrounder import Task\n\ndef send_notification(email: str):\n \"\"\"\n Sends an email notification to a given email\n \"\"\"\n ...\n\n\ntask = Task(send_notification, \"user@example.com\")\nawait task()\n```\n\nThis can be particularly useful if you want to implement some asynchronous functionality in your\napplications without using a whole ASGI framework for it, for example, using **Django**, although\nnow also supporting `async` natively, you might want to run some background tasks there that basically\ndo not exist natively (by the time of the writting).\n\n### The decorator\n\n**Backgrounder** also offers a decorator for you to use which can be extremely useful if you don't\nwant to use the [Task](./tasks.md#task) object directly, providing a cleaner version out of the box.\n\n```python\nfrom backgrounder import background\n\n@background\ndef send_notification(email: str):\n \"\"\"\n Sends an email notification to a given email\n \"\"\"\n ...\n\n\nsend_notification(\"user@example.com\")\n```\n\nAs simple as this, this will automatically execute the task in the background for you with all\nthe `async` magic being provided.\n\n[starlette]: https://www.starlette.io\n[esmerald]: https://esmerald.dev\n[fastapi]: https://fastapi.tiangolo.com\n",
"bugtrack_url": null,
"license": "",
"summary": "Run background tasks in asynchronous mode at all times",
"version": "0.2.0",
"project_urls": {
"Changelog": "https://backgrounder.dymmond.com/release-notes/",
"Documentation": "https://backgrounder.dymmond.com",
"Funding": "https://github.com/sponsors/tarsil",
"Homepage": "https://github.com/dymmond/backgrounder",
"Source": "https://github.com/dymmond/backgrounder"
},
"split_keywords": [
"backgrounder"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4ece216530ff9f986c2e2f57106dab9d3cb24aeeb4380703b464d0866ad4ab56",
"md5": "a59e27e5e3eddb93b69aa8630d7cae3e",
"sha256": "15f560faec7eb26426c873a9c08d3a46272272793e4243bb435ad0c0228e204a"
},
"downloads": -1,
"filename": "backgrounder-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a59e27e5e3eddb93b69aa8630d7cae3e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9720,
"upload_time": "2024-01-05T15:13:43",
"upload_time_iso_8601": "2024-01-05T15:13:43.895455Z",
"url": "https://files.pythonhosted.org/packages/4e/ce/216530ff9f986c2e2f57106dab9d3cb24aeeb4380703b464d0866ad4ab56/backgrounder-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e60d76dfac31426d3923f21d8b5823895885749244bcc1c55edacbca67db159d",
"md5": "cd1171fff9523969ad0b3fb9b10bd604",
"sha256": "c8ea25b305e29181ec99a54e38fbaade35f07a0b4f320f9ffe8e0e4657537bc5"
},
"downloads": -1,
"filename": "backgrounder-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "cd1171fff9523969ad0b3fb9b10bd604",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8440,
"upload_time": "2024-01-05T15:13:45",
"upload_time_iso_8601": "2024-01-05T15:13:45.549850Z",
"url": "https://files.pythonhosted.org/packages/e6/0d/76dfac31426d3923f21d8b5823895885749244bcc1c55edacbca67db159d/backgrounder-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-05 15:13:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sponsors",
"github_project": "tarsil",
"github_not_found": true,
"lcname": "backgrounder"
}
