Metadata-Version: 2.4
Name: python-stremio
Version: 0.1.0
Summary: An asynchronous Python library for building Stremio addons with ease
Project-URL: Homepage, https://github.com/craftypythondeveloper/python-stremio
Project-URL: Repository, https://github.com/craftypythondeveloper/python-stremio
Project-URL: Tracker, https://github.com/craftypythondeveloper/python-stremio/issues
Author-email: Amit Yadav <amityadav4664@gmail.com>
License-File: LICENSE
Requires-Python: >=3.14
Requires-Dist: blacksheep>=2.0.0
Requires-Dist: packaging>=23.0
Requires-Dist: uvicorn>=0.20.0
Description-Content-Type: text/markdown

# Python-Stremio

A fully modernized, asynchronous Python framework for building awesome [Stremio](https://www.stremio.com/) 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 `blacksheep` under the hood. High-performance async/await native.
- **Auto-Optimized JSON**: Automatically prefers and leverages high-speed `orjson` or `ujson` environments when available!
- **Deep Schema Validation**: Validates your manifest heavily using standard `ExceptionGroup` and 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).

```bash
uv pip install python-stremio
```

Alternatively using standard `pip`:

```bash
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!

```python
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:**
```python
@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:**
```python
@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!

```python
@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!
```python
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.
```python
@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.
```python
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.
```python
# To be run asynchronously:
await app.publish_to_registry(manifest_remote_url="https://api.mycustomaddon.com/manifest.json")
```
