Metadata-Version: 2.4
Name: xtream-api-client
Version: 0.1.0
Summary: A small Python client for Xtream-style IPTV API endpoints using only the standard library.
Author: XtreamTech
License-Expression: MIT
Project-URL: Homepage, https://xtreamtech.net
Project-URL: Documentation, https://xtreamtech.net
Keywords: xtream,iptv,api,client,player_api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# xtream-api-client

A small Python client for working with Xtream-style IPTV API endpoints (`player_api.php`). It is built entirely on the Python standard library — no third-party runtime dependencies — and returns plain dictionaries, lists, and optional lightweight dataclass models.

The library handles URL validation/normalization, query construction, JSON parsing, and error mapping so you can work with an Xtream-compatible server from a few lines of Python.

## What the package does

- Configures and validates an Xtream-compatible server base URL
- Authenticates with a username/password pair that you supply
- Retrieves account information
- Retrieves live, VOD, and series categories
- Retrieves basic live, VOD, and series stream lists
- Maps HTTP, connection, timeout, and authentication failures to dedicated exception classes
- Exports any result as JSON (to a string or a file)

This client only calls documented read-style endpoints (`player_api.php` actions). It does not implement stream playback, does not bypass authentication, and does not attempt to circumvent any provider restriction.

## Installation

```bash
pip install xtream-api-client
```

Requires Python 3.9 or newer.

Or from source:

```bash
git clone <your-repo-url>
cd xtreamtech
py -m pip install -e .
```

## Quick-start example

```python
from xtream_api_client import XtreamClient

client = XtreamClient(
    server_url="http://example.com:8080",
    username="your-username",
    password="your-password",
)

account = client.get_account_info()
print(account["user_info"]["status"])

for category in client.get_live_categories():
    print(category["category_id"], category["category_name"])
```

## Configuration

`XtreamClient` accepts:

| Parameter | Type | Default | Description |
|---|---|---|---|
| `server_url` | `str` | required | Base URL, with or without a scheme (`http://` is assumed). Trailing slashes and whitespace are stripped. |
| `username` | `str` | required | Your account username. |
| `password` | `str` | required | Your account password. |
| `timeout` | `float` | `10.0` | Per-request timeout in seconds. |
| `verify_input` | `bool` | `True` | Validate/normalize the URL on construction. |

## Authentication

Credentials are sent as query parameters on every `player_api.php` request, matching the Xtream API convention. If the server reports `user_info.auth` as falsy, an `XtreamAuthenticationError` is raised.

There are no hard-coded credentials or servers — supply your own.

## Retrieving account information

```python
info = client.get_account_info()          # raw dict with user_info / server_info
parsed = client.get_account_info_parsed() # AccountInfo dataclass
print(parsed.username, parsed.status, parsed.max_connections)
```

## Retrieving categories and streams

```python
client.get_live_categories()    # list[dict]
client.get_vod_categories()     # list[dict]
client.get_series_categories()  # list[dict]

client.get_live_streams(category_id="1")  # optional category filter
client.get_vod_streams(category_id="2")
client.get_series(category_id="3")
```

Model-based equivalents:

```python
cats = client.list_live_categories()   # list[Category]
streams = client.list_live_streams()   # list[Channel]
```

## Error handling

All exceptions derive from `XtreamAPIError`:

| Exception | Raised when |
|---|---|
| `XtreamURLValidationError` | The server URL is empty, malformed, or uses an unsupported scheme. |
| `XtreamAuthenticationError` | Credentials are missing or the server rejects them. |
| `XtreamTimeoutError` | A request exceeds the configured timeout. |
| `XtreamConnectionError` | The server cannot be reached (DNS failure, connection refused, etc.). |
| `XtreamHTTPError` | The server returns a non-200 status (`status_code` and `url` attributes). |
| `XtreamAPIError` | Base class; also raised for non-JSON or unexpected responses. |

```python
from xtream_api_client.exceptions import XtreamAPIError, XtreamTimeoutError

try:
    categories = client.get_live_categories()
except XtreamTimeoutError:
    ...
except XtreamAPIError as exc:
    ...
```

## Timeout configuration

```python
client = XtreamClient(url, user, password, timeout=5.0)  # seconds
```

The timeout applies per request to both connection establishment and reading.

## Exporting results as JSON

```python
text = client.export_json(client.get_live_categories())      # returns str
client.export_json(data, path="categories.json")             # writes a file
```

## Testing

Tests use mocked HTTP responses only — no real servers are contacted.

```bash
py -m pip install -e ".[test]"
py -m pytest
```

## Limitations

- Read-style `player_api.php` actions only; no episode/stream URL building or playback.
- Error detection relies on the server returning well-formed JSON; behavior varies between server implementations and versions.
- Credentials appear in query strings, matching the API convention; avoid logging full request URLs.
- Synchronous `urllib` based I/O only; no async support or connection pooling.

## License

MIT — see [LICENSE](LICENSE).

## Additional Xtream/IPTV technical resources

- Project documentation and resources: [https://xtreamtech.net](https://xtreamtech.net)
- Python `urllib.request` documentation: https://docs.python.org/3/library/urllib.request.html
