mirror of
https://github.com/kennethreitz/kennethreitz.org.git
synced 2026-06-05 22:50:17 +00:00
kennethreitz
47305360c7
Added documentation links, expanded code examples, personal context, and related essay links across all 11 software pages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
74 lines
2.8 KiB
Markdown
74 lines
2.8 KiB
Markdown
# Background: Simple Background Tasks
|
|
|
|
Background lets you run Python functions in background threads with a single decorator. No task queue. No message broker. No configuration. Just `@background.task` and you're done.
|
|
|
|
$ uv pip install background
|
|
|
|
## What It Looks Like
|
|
|
|
```python
|
|
import time
|
|
import background
|
|
|
|
@background.task
|
|
def send_email(to, subject, body):
|
|
# This runs in a background thread.
|
|
time.sleep(2) # Simulate sending.
|
|
print(f"Sent '{subject}' to {to}")
|
|
|
|
# These all return immediately.
|
|
send_email("alice@example.com", "Hello", "How are you?")
|
|
send_email("bob@example.com", "Update", "Project shipped.")
|
|
send_email("charlie@example.com", "Reminder", "Meeting at 3.")
|
|
|
|
# Main thread keeps running while emails send in the background.
|
|
print("All emails queued.")
|
|
```
|
|
|
|
Under the hood, Background uses a `ThreadPoolExecutor`. The default thread count matches your CPU cores. You can configure it if you need to:
|
|
|
|
```python
|
|
import background
|
|
|
|
# Set the number of background threads.
|
|
background.n = 8
|
|
|
|
@background.task
|
|
def process_image(path):
|
|
# Up to 8 of these will run concurrently.
|
|
resize_and_compress(path)
|
|
|
|
# Returns a Future you can inspect if needed.
|
|
future = process_image("/uploads/photo.jpg")
|
|
future.result() # Block until complete, if you want.
|
|
```
|
|
|
|
The decorated function returns a `concurrent.futures.Future`, so you get the simplicity of fire-and-forget with the option to wait for results when you need them.
|
|
|
|
## The Philosophy
|
|
|
|
Sometimes you need Celery. Sometimes you need Redis and a message broker and dead-letter queues and retry policies. And sometimes you just need a function to run without blocking the main thread. Background is for that third case.
|
|
|
|
Not everything needs infrastructure. Not every background task needs to survive a server restart. Sometimes a thread pool and a decorator are exactly enough. The gap between "I need this to run in the background" and "I need a distributed task queue" is enormous, and Background lives in that gap.
|
|
|
|
I use it on this very website for trivial background tasks outside the main event loop. It's the kind of tool that would be embarrassing to over-engineer and satisfying to keep simple.
|
|
|
|
The project was gifted to [Parth Shandilya](https://github.com/ParthS007), who now maintains it.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
$ uv pip install background
|
|
```
|
|
|
|
## Resources
|
|
|
|
- [Source Code on GitHub](https://github.com/ParthS007/background)
|
|
- [Python Package Index](https://pypi.org/project/background/)
|
|
|
|
## Related
|
|
|
|
- [**Delegator**](/software/delegator) — Another small, focused utility for common Python tasks.
|
|
- [**Requests**](/software/requests) — The philosophy that simple tools should stay simple.
|
|
- [**Programming as Spiritual Practice**](/essays/2025-08-26-programming_as_spiritual_practice) — Knowing when not to over-engineer is its own discipline.
|