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

pip install xtream-api-client

Requires Python 3.9 or newer.

Or from source:

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

Quick-start example

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

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

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:

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.

from xtream_api_client.exceptions import XtreamAPIError, XtreamTimeoutError

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

Timeout configuration

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

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

Exporting results as JSON

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.

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.

Additional Xtream/IPTV technical resources

• Project documentation and resources: https://xtreamtech.net
• Python urllib.request documentation: https://docs.python.org/3/library/urllib.request.html