An asynchronous Python library for building Stremio addons with ease
Project description
Python-Stremio
A fully modernized, asynchronous Python framework for building awesome Stremio Addons with ease.
python-stremio drops confusing legacy architectures in favor of a sleek, type-safe, routing-based approach—feeling right at home if you've developed using frameworks like FastAPI or Starlette.
⚡ Features
- Modern Routing Architecture: Built with a decorator-based web hook event model (
@app.on_stream()). - Insanely Fast: Powered by
blacksheepunder the hood. High-performance async/await native. - Auto-Optimized JSON: Automatically prefers and leverages high-speed
orjsonorujsonenvironments when available! - Deep Schema Validation: Validates your manifest heavily using standard
ExceptionGroupand Python structural pattern matching to surface all configuration errors simultaneously instead of failing silently or repetitively. - Fail-Safe execution: Wraps plugin executions so unhandled tracebacks map gracefully to HTTP 500 responses without crashing the Addon socket!
- Forward-Compatible Typing: Leverages PEP 695 Type Aliasing to give you brilliant IDE autocomplete on payload types.
🚀 Installation
Because the framework targets cutting edge functionalities, Python 3.14+ is expected to be utilized alongside uv (or pip).
uv pip install python-stremio
Alternatively using standard pip:
pip install python-stremio
📖 Quickstart Guide
Building an addon requires two main things: defining a manifest, and mapping routes to those resources!
1. Initialize the Application
Start by declaring your Stremio manifest dictionary. StremioApplication will aggressively validate this configuration on boot, letting you know instantly if you've violated the Stremio schema requirements!
from python_stremio import StremioApplication
addon_manifest = {
"id": "org.example.hello_world",
"version": "1.0.0",
"name": "Hello World Addon",
"description": "My incredibly fast python-stremio addon!",
"resources": ["catalog", "stream", "meta"],
"types": ["movie", "series"],
"catalogs": [
{"id": "my_top_catalog", "type": "movie"}
]
}
# Creates the internal API and validates the manifest configuration
app = StremioApplication(
app_manifest=addon_manifest,
bind_port=7000, # The port to run the web application on
server_log_level="info" # Logging outputs (info, debug, error etc.)
)
2. Register Framework Routes
You can seamlessly bind handlers for Stremio concepts using routing decorators. Each function receives a context dictionary mapping the request id, type, and parsed extraArgs.
Handling Catalogs:
@app.on_catalog()
async def serve_catalog_content(req: dict):
# Returns the list of content presented when opening the addon!
return {
"metas": [
{
"id": "tt1254207",
"type": "movie",
"name": "Big Buck Bunny",
"poster": "https://upload.wikimedia.org/wikipedia/commons/c/c5/Big_buck_bunny_poster_big.jpg"
}
]
}
Handling Video Streams:
@app.on_stream()
async def serve_video_stream(req: dict):
# Check if the requested video matches our catalog
if req["id"] == "tt1254207":
return {
"streams": [
{
"title": "1080p HD Direct",
"url": "http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_30fps_normal.mp4"
}
]
}
# Returning an empty streams array tells Stremio we don't have sources for the title
return {"streams": []}
Custom Landing Pages: If a user goes to the Addon url directly, you can serve them custom installation prompts or visual content!
@app.serve_landing_page()
async def show_presentation_page(req):
return """
<html>
<body>
<h1>Welcome to the Hello World Addon!</h1>
<a href="/manifest.json">Click here to install manually in Stremio</a>
</body>
</html>
"""
3. Run the application
Block and ignite the uvicorn network layer!
if __name__ == "__main__":
app.run()
🛠 Advanced Features
Dynamic Extra Parameters
When reading catalog tags (e.g. searching, genre filtering), Stremio sends them in the req["extraArgs"] mapping! python-stremio parses query strings automatically.
@app.on_catalog()
async def filter_catalog(req):
extras = req.get("extraArgs")
if extras and "search" in extras:
return search_database(query=extras["search"])
...
Dealing with Errors
You can safely rely on the internal framework exception classes to diagnose complex issues.
from python_stremio import ManifestValidationError, StremioBaseError
try:
StremioApplication(broken_manifest)
except ManifestValidationError as e:
# Use standard Python ExceptionGroup unrolling
for validation_failure in e.exceptions:
print(validation_failure)
Publishing the Addon Remotely
You can easily register your deployed Stremio webhook remotely to standard Stremio catalog pipelines.
# To be run asynchronously:
await app.publish_to_registry(manifest_remote_url="https://api.mycustomaddon.com/manifest.json")
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file python_stremio-0.1.0.tar.gz.
File metadata
- Download URL: python_stremio-0.1.0.tar.gz
- Upload date:
- Size: 8.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.7.15
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2e596d74bf21c2fb65bed46efe81f06099b23352b15c0f17069f1117ef90c2ff
|
|
| MD5 |
48213c8bd07acc3c2dcb5aa70b363d58
|
|
| BLAKE2b-256 |
007052e7725c772a4472207bc43714073054a3ea85e5c01aa59fc1576f2fddae
|
File details
Details for the file python_stremio-0.1.0-py3-none-any.whl.
File metadata
- Download URL: python_stremio-0.1.0-py3-none-any.whl
- Upload date:
- Size: 9.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.7.15
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3950742db1cd3d284330cc70fb1055fc79437eb4defd29f05a407154b81948a4
|
|
| MD5 |
50577d454ec8d200698089af4993a8dd
|
|
| BLAKE2b-256 |
c541458a20ab46796eeb9f3a3f098777b75dc29d360c53a9de09187b47cb0d41
|
