### Install HdRezkaApi with pip

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Install the HdRezkaApi library using pip. This is the first step to using the library.

```bash
pip install HdRezkaApi
```

--------------------------------

### HdRezkaStream Usage Example

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Demonstrates how to get a stream object and access its video URLs by resolution. The `stream` object can be called with a resolution string or integer to get the video URL.

```python
stream = rezka.getStream(1, 5)

print( stream('720p') )
print( stream('720') )
print( stream(1080) )
print( stream('Ultra') )
print( stream('1080p Ultra') )
print( stream.videos )
```

--------------------------------

### HdRezkaStreamSubtitles Usage Example

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Shows how to access subtitle information from a stream object, including available languages, subtitle details, and fetching subtitle URLs by language code, name, or index.

```python
stream = rezka.getStream(1, 5)

print( stream.subtitles.subtitles )  # { 'en': {'title': 'English', 'link': 'https:/'}, ...  }
print( stream.subtitles.keys )       # ['en', 'ru']
print( stream.subtitles('en') )      # 'https:/'
print( stream.subtitles('English') ) # 'https:/'
print( stream.subtitles(0) )         # 'https:/'
#                       ^ index
```

--------------------------------

### Get Series Info and Episode Listing

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Use `rezka.seriesInfo` for per-translator season/episode data and `rezka.episodesInfo` for a flat unified structure. Both are only available for `TVSeries` types. Access `rezka.otherParts` for sequels.

```python
from HdRezkaApi import HdRezkaApi
from HdRezkaApi.types import TVSeries

rezka = HdRezkaApi("https://hdrezka.ag/series/drama/99999-some-series.html")
assert rezka.type == TVSeries

# seriesInfo: keyed by translator_id
info = rezka.seriesInfo
for tr_id, data in info.items():
    print(tr_id, data['translator_name'], data['seasons'])
    # e.g. 56 'Дубляж' {1: 'Season 1', 2: 'Season 2'}

# episodesInfo: flat list for all seasons/episodes
for season in rezka.episodesInfo:
    print(f"Season {season['season']}: {season['season_text']}")
    for ep in season['episodes']:
        print(f"  Episode {ep['episode']}: {ep['episode_text']}")
        for tr in ep['translations']:
            print(f"    Translator: {tr['translator_name']} (id={tr['translator_id']})")

# Other parts / sequels
print(rezka.otherParts)
# [{'Film Part 1': 'https://hdrezka.ag/...'}, {'Film Part 2': 'https://hdrezka.ag/...'}]
```

--------------------------------

### Get Season Streams with Options

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Retrieves streams for a given season, with options to specify translation, ignore errors, and track progress. The `progress` callback function can be used to monitor download status.

```python
getSeasonStreams(season, translation=None, ignore=False, progress=None, priority=None, non_priority=None)
```

```python
getSeasonStreams(
	translation='Дубляж' or translation='56'
)
```

```python
def progress(current, all):
	percent = round(current * 100 / all)
	print(f"{percent}%: {current}/{all}", end="\r")

print( dict(rezka.getSeasonStreams(1, ignore=True, progress=progress)) )
```

```python
for i, stream in rezka.getSeasonStreams('1'):
	print(stream)
```

--------------------------------

### Initialize HdRezkaSession without Origin

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Initialize HdRezkaSession without specifying an origin. Requests will be made to the URL provided directly in the get() method. Note that login() cannot be used in this mode.

```python
with HdRezkaSession() as session:
	rezka = session.get("https://hdrezka.ag/__URL_PATH__.html")
```

--------------------------------

### Fetch a Single Stream for Movies and TV Episodes

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Use `getStream` to fetch an `HdRezkaStream` object. Omit season/episode for movies. Pass `translation` as a name or ID string to select a specific dub. You can then access video URLs by resolution or get the full `stream.videos` dictionary.

```python
from HdRezkaApi import HdRezkaApi

# --- Movie ---
rezka = HdRezkaApi("https://hdrezka.ag/films/action/11111-film.html")
stream = rezka.getStream()                        # auto-selects best translator
stream = rezka.getStream(translation='Дубляж')    # by name
stream = rezka.getStream(translation='56')        # by ID string

# --- TV Series episode ---
rezka = HdRezkaApi("https://hdrezka.ag/series/drama/99999-series.html")
stream = rezka.getStream('2', '5')                # season 2, episode 5
stream = rezka.getStream('2', '5', translation='Дубляж')

# Get direct video URL by resolution
print(stream('720p'))       # ['https://cdn.../720.mp4', ...]
print(stream('720'))        # same — partial match works
print(stream(1080))         # int also works
print(stream('Ultra'))      # 4K Ultra HD
print(stream('1080p Ultra'))

# Full videos dict
print(stream.videos)
# {'360p': ['https://...mp4'], '480p': ['https://...mp4'], '720p': ['https://...mp4']}

# Stream metadata
print(stream.name)           # Film/series name
print(stream.translator_id)  # e.g. 56
print(stream.season)         # e.g. 2 (None for movies)
print(stream.episode)        # e.g. 5 (None for movies)
print(repr(stream))          # <HdRezkaStream(season:2, episode:5)>
```

--------------------------------

### Get Stream URL with Translation Preference

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Fetch a stream URL by specifying a translation name or ID, and optionally quality. This allows for targeted stream retrieval.

```python
getStream(
	translation='Дубляж' or translation='56'
)
```

--------------------------------

### Get Specific Page

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Retrieve a specific page's data by its page number or index. This is useful for accessing content from a particular page in a paginated result set.

```python
print(results.get_page(2)) # page number
# or
print(results[1]) # index
```

--------------------------------

### Get Stream URL for Movies

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Retrieve the stream URL for a movie by specifying the desired quality. Season and episode are not required for movies.

```python
stream = rezka.getStream() # if movie
```

--------------------------------

### HdRezkaApi Initialization with Proxy

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Initializes the HdRezkaApi with a specified proxy server.

```APIDOC
## HdRezkaApi Initialization with Proxy

### Description
Initializes the HdRezkaApi with a specified proxy server to route requests through.

### Method
```python
HdRezkaApi(url, proxy={'http': 'http://192.168.0.1:80'})
```

### Parameters
- **url** (str) - The base URL of the HRezka website.
- **proxy** (dict) - A dictionary specifying the proxy settings. Example: `{'http': 'http://user:password@host:port'}`.
```

--------------------------------

### Initialize HdRezkaApi and Check Status

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Initialize the HdRezkaApi with a URL and check if the request was successful using the `.ok` property. Access basic metadata like ID, name, description, and release year.

```python
from HdRezkaApi import HdRezkaApi

url = "https://hdrezka.ag/films/comedy/12345-some-film-2023.html"
rezka = HdRezkaApi(url)

if not rezka.ok:
    print("Error:", str(rezka.exception))
    raise rezka.exception

# Basic metadata
print(rezka.id)           # e.g. 12345
print(rezka.name)         # e.g. "Some Film"
print(rezka.names)        # e.g. ["Some Film", "Некий Фильм"]
print(rezka.origName)     # e.g. "Some Film"
print(rezka.description)  # Full plot description text
print(rezka.thumbnail)    # "https://...jpg"  (standard quality)
print(rezka.thumbnailHQ)  # "https://...jpg"  (high quality)
print(rezka.releaseYear)  # e.g. 2023
```

--------------------------------

### HdRezkaSession Initialization and Usage

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Demonstrates how to initialize HdRezkaSession, log in, and make requests. Supports specifying an origin URL and handling authentication.

```APIDOC
## HdRezkaSession Initialization

### Description
Initializes a session for interacting with the HdRezka API. Supports specifying an origin URL for requests and optional authentication.

### Method
```python
with HdRezkaSession(origin_url, translators_priority=None, translators_non_priority=None, cookies=None, headers=None, proxy=None) as session:
    ...
```

### Parameters
- **origin_url** (str) - Optional - The base URL for requests. If not provided, requests are made to the URL specified in `session.get()`.
- **translators_priority** (list) - Optional - A list of preferred translator IDs.
- **translators_non_priority** (list) - Optional - A list of non-preferred translator IDs.
- **cookies** (dict) - Optional - Custom cookies to use for the session.
- **headers** (dict) - Optional - Custom headers to use for the session.
- **proxy** (str) - Optional - A proxy server to use for requests.

### Usage Examples
```python
# With origin URL and login
with HdRezkaSession("https://rezka_mirror.com/") as session:
    session.login("email@gmail.com", "password")
    rezka = session.get("https://hdrezka.ag/__URL_PATH__.html")

# With origin URL and only URL path
with HdRezkaSession("https://rezka_mirror.com/") as session:
    rezka = session.get("__URL_PATH__.html")

# Without origin URL
with HdRezkaSession() as session:
    rezka = session.get("https://hdrezka.ag/__URL_PATH__.html")

# With custom cookies, headers, and proxy
with HdRezkaSession(cookies=cookies, headers=headers, proxy=proxy) as session:
    # or inline setting up
    session.cookies = cookies
    session.headers = headers
    session.proxy = proxy

# Setting translator priorities
with HdRezkaSession(translators_priority, translators_non_priority) as session:
    session.translators_priority = new_value
    session.translators_non_priority = new_value
```
```

--------------------------------

### Manual Login for HdRezkaApi

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Demonstrates how to manually log in to the HdRezkaApi service using email and password.

```python
rezka = HdRezkaApi(url)
rezka.login("your_email@gmail.com", "your_password1234")
```

--------------------------------

### HdRezkaApi Initialization and Status Check

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Initialize HdRezkaApi with a URL and optional parameters like proxy, headers, and cookies. Check the status of the loaded data using the `.ok` property and access any exceptions via the `.exception` attribute.

```APIDOC
## HdRezkaApi Initialization and Status Check

`HdRezkaApi(url, proxy={}, headers={}, cookies={}, translators_priority=None, translators_non_priority=None)` fetches and parses a film or TV series page from its HDRezka URL. Results are lazily loaded and cached via `@cached_property`. The `.ok` property and `.exception` attribute allow safe status checking before accessing data.

```python
from HdRezkaApi import HdRezkaApi

url = "https://hdrezka.ag/films/comedy/12345-some-film-2023.html"
rezka = HdRezkaApi(url)

if not rezka.ok:
    print("Error:", str(rezka.exception))
    raise rezka.exception

# Basic metadata
print(rezka.id)           # e.g. 12345
print(rezka.name)         # e.g. "Some Film"
print(rezka.names)        # e.g. ["Some Film", "Некий Фильм"]
print(rezka.origName)     # e.g. "Some Film"
print(rezka.description)  # Full plot description text
print(rezka.thumbnail)    # "https://...jpg"  (standard quality)
print(rezka.thumbnailHQ)  # "https://...jpg"  (high quality)
print(rezka.releaseYear)  # e.g. 2023
```
```

--------------------------------

### Authentication - Login and Cookies

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Demonstrates how to authenticate with the API using `HdRezkaApi.login()` or by providing cookies directly. Includes error handling for login failures.

```APIDOC
## Authentication — Login and Cookies

`HdRezkaApi.login()` authenticates a session and updates internal cookies. `make_cookies()` is a static helper to build cookie dicts from stored credentials.

```python
from HdRezkaApi import HdRezkaApi

# Method 1: Login after construction
rezka = HdRezkaApi("https://hdrezka.ag/films/drama/22222-premium-film.html")
rezka.login("user@example.com", "password1234")

# Method 2: Pass cookies directly (from stored session)
cookies = {"dle_user_id": "98765", "dle_password": "abc123hashvalue"}
rezka = HdRezkaApi("https://hdrezka.ag/films/drama/22222-film.html", cookies=cookies)

# Method 3: Use the static helper
cookies = HdRezkaApi.make_cookies("98765", "abc123hashvalue")
rezka = HdRezkaApi("https://hdrezka.ag/films/drama/22222-film.html", cookies=cookies)

# Error handling for login failures
from HdRezkaApi.errors import LoginFailed, LoginRequiredError

try:
    rezka.login("wrong@example.com", "badpassword")
except LoginFailed as e:
    print(f"Login failed: {e}")

try:
    stream = rezka.getStream()
except LoginRequiredError:
    print("This content requires login")
```
```

--------------------------------

### Proxy Support

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Explains how to route all API requests through a proxy server by providing a `requests`-style proxy dictionary during initialization.

```APIDOC
## Proxy Support

Pass a standard `requests`-style proxy dict to route all requests through a proxy server.

```python
from HdRezkaApi import HdRezkaApi

proxy = {
    'http':  'http://192.168.0.1:8080',
    'https': 'http://192.168.0.1:8080',
}
rezka = HdRezkaApi("https://hdrezka.ag/films/action/11111-film.html", proxy=proxy)

if rezka.ok:
    stream = rezka.getStream()
    print(stream('720p'))
```
```

--------------------------------

### Initialize HdRezkaApi with Proxy

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Configures the HdRezkaApi instance to use a specified proxy for network requests.

```python
rezka = HdRezkaApi(url, proxy={'http': 'http://192.168.0.1:80'})
```

--------------------------------

### Initialize HdRezkaApi with Cookies

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Initializes the HdRezkaApi with provided cookies or uses a helper method to create them from user ID and password hash.

```python
rezka = HdRezkaApi(url, cookies={"dle_user_id": user_id, "dle_password": password_hash})
```

```python
rezka = HdRezkaApi(url, cookies=HdRezkaApi.make_cookies(user_id, password_hash))
```

--------------------------------

### Initialize HdRezkaSession with Custom Options

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Initialize HdRezkaSession with custom cookies, headers, and proxy settings. These can be set during initialization or assigned directly to session attributes.

```python
with HdRezkaSession(cookies=cookies, headers=headers, proxy=proxy) as session:
	# or inline seting up
	session.cookies = cookies
	session.headers = headers
	session.proxy = proxy
```

--------------------------------

### Initialize HdRezkaSession with Origin URL Path

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Initialize HdRezkaSession with an origin URL and specify only the URL path for requests. This is a shorthand when the origin is already set.

```python
with HdRezkaSession("https://rezka_mirror.com/") as session:
	rezka = session.get("__URL_PATH__.html")
```

--------------------------------

### Initialize HdRezkaSession with Origin

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Initialize HdRezkaSession with a specific origin URL. This ensures all subsequent requests are made to the specified mirror, ignoring the origin in full URLs. Login functionality is available.

```python
from HdRezkaApi import HdRezkaSession
```

```python
with HdRezkaSession("https://rezka_mirror.com/") as session:
	session.login("email@gmail.com", "password")
	rezka = session.get("https://hdrezka.ag/__URL_PATH__.html")
```

--------------------------------

### HdRezkaApi Initialization with Cookies

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Initializes the HdRezkaApi with custom cookies, which can be useful for authentication or session management.

```APIDOC
## HdRezkaApi Initialization with Cookies

### Description
Initializes the HdRezkaApi with custom cookies, which can be useful for authentication or session management.

### Method
```python
HdRezkaApi(url, cookies={"dle_user_id": user_id, "dle_password": password_hash})
HdRezkaApi(url, cookies=HdRezkaApi.make_cookies(user_id, password_hash))
```

### Parameters
- **url** (str) - The base URL of the HRezka website.
- **cookies** (dict or None) - A dictionary of cookies to be used for requests. Can also be generated using `HdRezkaApi.make_cookies()`.
```

--------------------------------

### Print All Pages Results

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Use this to print the structure of all pages retrieved. The output is a list of lists, where each inner list contains dictionaries representing a page's content.

```python
print(results.all_pages)
```

```text
[
	[ {'title', 'url', 'image', 'category'}, ...],
	[ {'title', 'url', 'image', 'category'}, ...],
	...
]
```

--------------------------------

### Basic Usage of HdRezkaApi

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Initialize HdRezkaApi with a URL and access film details like name, thumbnail, rating, and type. Handles potential initialization errors.

```python
from HdRezkaApi import HdRezkaApi
from HdRezkaApi.types import TVSeries, Movie
from HdRezkaApi.types import Film, Series, Cartoon, Anime

url = "https://hdrezka.ag/   __YOUR_URL__   .html"

rezka = HdRezkaApi(url)
if not rezka.ok:
	print("Error:", str(rezka.exception))
	raise rezka.exception

print(rezka.name)
print(rezka.thumbnail)
print( rezka.rating.value )
print( rezka.rating.votes )
print( rezka.translators )
print( rezka.otherParts )
print( rezka.seriesInfo )

print(rezka.type)
print(rezka.type == TVSeries == TVSeries() == "tv_series")

print(rezka.category)
print(rezka.category == Anime == Anime() == "anime")

print( rezka.getStream()('720p') ) # if movie
print( rezka.getStream('1', '1')('720p') )
print( dict(rezka.getSeasonStreams('1')) )
```

--------------------------------

### Print Flattened Results

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Use this to print a flattened list of all results. Each item in the list is a dictionary containing details like title, URL, image, and category.

```python
print(results.all)
```

```text
[
	{'title', 'url', 'image', 'category'},
	{'title', 'url', 'image', 'category'},
	...
]
```

--------------------------------

### Proxy Support for Requests

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Routes all API requests through a specified proxy server. Requires a standard requests-style proxy dictionary.

```python
from HdRezkaApi import HdRezkaApi

proxy = {
    'http':  'http://192.168.0.1:8080',
    'https': 'http://192.168.0.1:8080',
}
rezka = HdRezkaApi("https://hdrezka.ag/films/action/11111-film.html", proxy=proxy)

if rezka.ok:
    stream = rezka.getStream()
    print(stream('720p'))
```

--------------------------------

### Reusable Authenticated Sessions with HdRezkaSession

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Manages reusable authenticated sessions as a context manager. Supports mirror domains, proxies, and translator priorities.

```python
from HdRezkaApi import HdRezkaSession

# --- Basic session with login ---
with HdRezkaSession("https://hdrezka.ag/") as session:
    session.login("user@example.com", "password1234")

    # Fetch any title (origin is automatically prepended)
    rezka = session.get("https://hdrezka.ag/films/action/11111-film.html")
    print(rezka.name)
    stream = rezka.getStream()
    print(stream('1080p'))
```

```python
# --- Mirror domain: requests are transparently redirected ---
with HdRezkaSession("https://rezka-mirror.com/") as session:
    rezka = session.get("series/drama/99999-series.html")  # relative path OK
    for ep, stream in rezka.getSeasonStreams('1'):
        print(ep, stream('720p'))
```

```python
# --- Session with proxy, cookies, and translator priority ---
with HdRezkaSession(
    "https://hdrezka.ag/",
    proxy={'https': 'http://10.0.0.1:3128'},
    translators_priority=[56, 111],
    translators_non_priority=[238]
) as session:
    session.login("user@example.com", "pass")
    results = session.search("Dune", find_all=True)
    for item in results.all:
        print(item['title'], item['url'])
```

```python
# --- Search within a session ---
with HdRezkaSession("https://hdrezka.ag/") as session:
    results = session.search("Breaking Bad")       # fast search
    results = session.search("Breaking Bad", find_all=True)  # advanced search
    for page in results:
        for r in page:
            print(r['title'])
```

--------------------------------

### Login and Cookie Management

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Authenticates a session using login credentials or pre-existing cookies. Handles login failures and checks for required login for content.

```python
from HdRezkaApi import HdRezkaApi

# Method 1: Login after construction
rezka = HdRezkaApi("https://hdrezka.ag/films/drama/22222-film.html")
rezka.login("user@example.com", "password1234")

# Method 2: Pass cookies directly (from stored session)
cookies = {"dle_user_id": "98765", "dle_password": "abc123hashvalue"}
rezka = HdRezkaApi("https://hdrezka.ag/films/drama/22222-film.html", cookies=cookies)

# Method 3: Use the static helper
cookies = HdRezkaApi.make_cookies("98765", "abc123hashvalue")
rezka = HdRezkaApi("https://hdrezka.ag/films/drama/22222-film.html", cookies=cookies)
```

```python
# Error handling for login failures
from HdRezkaApi.errors import LoginFailed, LoginRequiredError

try:
    rezka.login("wrong@example.com", "badpassword")
except LoginFailed as e:
    print(f"Login failed: {e}")

try:
    stream = rezka.getStream()
except LoginRequiredError:
    print("This content requires login")
```

--------------------------------

### Advanced Search with Session

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Perform an advanced search with the HdRezkaSession, including login and the find_all option. This retrieves all pages of search results, allowing for detailed iteration.

```python
with HdRezkaSession("https://rezka_mirror.com/") as session:
	session.login("email@gmail.com", "password")
	results = session.search("film name", find_all=True)
	for page in results:
		for result in page:
			print(result)
```

--------------------------------

### Batch Fetch a Full Season's Streams

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Use `getSeasonStreams` as a generator to yield `(episode_number, HdRezkaStream)` pairs for a season. Use `ignore=True` to retry indefinitely on errors. Streams are fetched on demand. The result can be collected into a dictionary.

```python
from HdRezkaApi import HdRezkaApi

rezka = HdRezkaApi("https://hdrezka.ag/series/drama/99999-series.html")

# Progress callback
def on_progress(current, total):
    pct = round(current * 100 / total)
    print(f"\r{pct}% ({current}/{total})", end="", flush=True)

# Iterate lazily — each stream is fetched on demand
for episode_num, stream in rezka.getSeasonStreams('1', ignore=True, progress=on_progress):
    if stream:
        urls = stream('720p')
        print(f"\nEp {episode_num}: {urls[0]}")
    else:
        print(f"\nEp {episode_num}: failed")

# Collect to dict all at once
season_dict = dict(rezka.getSeasonStreams('1', translation='Дубляж'))
# {1: <HdRezkaStream(season:1, episode:1)>, 2: <HdRezkaStream(...)>, ...}

# Specific translation by ID
season_dict = dict(rezka.getSeasonStreams('2', translation='56'))
```

--------------------------------

### HdRezkaApi Manual Login

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Performs a manual login to the HRezka website using provided credentials.

```APIDOC
## HdRezkaApi Manual Login

### Description
Performs a manual login to the HRezka website using provided credentials.

### Method
```python
rezka.login(email, password)
```

### Parameters
- **email** (str) - The user's email address.
- **password** (str) - The user's password.
```

--------------------------------

### Handle HdRezkaApi Errors Gracefully

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Import custom exceptions from HdRezkaApi.errors for precise error management. Check the .ok attribute before accessing properties and use try-except blocks for stream fetching to handle potential issues like FetchFailed or ValueError.

```python
from HdRezkaApi import HdRezkaApi
from HdRezkaApi.errors import (
    LoginRequiredError,  # page requires authentication
    LoginFailed,         # wrong credentials
    FetchFailed,         # stream URL could not be fetched
    CaptchaError,        # site is showing a CAPTCHA
    HTTP,                # non-200 HTTP response (wraps status code)
)

url = "https://hdrezka.ag/films/action/11111-film.html"
rezka = HdRezkaApi(url)

# Check via .ok / .exception before touching any property
if not rezka.ok:
    exc = rezka.exception
    if isinstance(exc, LoginRequiredError):
        rezka.login("user@example.com", "pass")
    elif isinstance(exc, CaptchaError):
        print("Manual captcha solving required")
    elif isinstance(exc, HTTP):
        print(f"HTTP error: {exc}")
    else:
        raise exc

# Wrap stream fetching
try:
    stream = rezka.getStream('1', '1')
    print(stream('720p'))
except FetchFailed:
    print("Could not retrieve stream — try again later")
except ValueError as e:
    print(f"Bad argument: {e}")  # invalid season/episode/resolution
```

--------------------------------

### HdRezkaSession - Reusable Authenticated Sessions

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Introduces `HdRezkaSession` as a context manager for managing authenticated sessions, sharing cookies and configuration, and handling mirror domains.

```APIDOC
## HdRezkaSession — Reusable Authenticated Sessions

`HdRezkaSession` acts as a context manager that shares authentication cookies and configuration across multiple `get()` and `search()` calls. Specifying an `origin` redirects all requests to a mirror domain.

```python
from HdRezkaApi import HdRezkaSession

# --- Basic session with login ---
with HdRezkaSession("https://hdrezka.ag/") as session:
    session.login("user@example.com", "password1234")

    # Fetch any title (origin is automatically prepended)
    rezka = session.get("https://hdrezka.ag/films/action/11111-film.html")
    print(rezka.name)
    stream = rezka.getStream()
    print(stream('1080p'))

# --- Mirror domain: requests are transparently redirected ---
with HdRezkaSession("https://rezka-mirror.com/") as session:
    rezka = session.get("series/drama/99999-series.html")  # relative path OK
    for ep, stream in rezka.getSeasonStreams('1'):
        print(ep, stream('720p'))

# --- Session with proxy, cookies, and translator priority ---
with HdRezkaSession(
    "https://hdrezka.ag/",
    proxy={'https': 'http://10.0.0.1:3128'},
    translators_priority=[56, 111],
    translators_non_priority=[238]
) as session:
    session.login("user@example.com", "pass")
    results = session.search("Dune", find_all=True)
    for item in results.all:
        print(item['title'], item['url'])

# --- Search within a session ---
with HdRezkaSession("https://hdrezka.ag/") as session:
    results = session.search("Breaking Bad")       # fast search
    results = session.search("Breaking Bad", find_all=True)  # advanced search
    for page in results:
        for r in page:
            print(r['title'])
```
```

--------------------------------

### Series and Episodes Information

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Describes the structure for series and episodes information.

```APIDOC
#### `seriesInfo`
```
{
	Translator_id: {
		translator_name,
		seasons: {1, 2},
		episodes: {
			1: {1, 2, 3},
			2: {1, 2, 3}
		}
	}
}
```
#### `episodesInfo`
```
[
	{
		season: 1, season_text,
		episodes: [
			{
				episode: 1, episode_text,
				translations: [
					{translator_id, translator_name, premium}
				]
			}
	]
	}
]
```
```

--------------------------------

### Series Info and Episode Listing

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Retrieve detailed season and episode data for TV series, organized by translator or as a flat list.

```APIDOC
## Series Info and Episode Listing

`rezka.seriesInfo` returns per-translator season/episode data. `rezka.episodesInfo` provides a flat unified structure grouping episodes across all translators — both are only available for `TVSeries`.

```python
from HdRezkaApi import HdRezkaApi
from HdRezkaApi.types import TVSeries

rezka = HdRezkaApi("https://hdrezka.ag/series/drama/99999-some-series.html")
assert rezka.type == TVSeries

# seriesInfo: keyed by translator_id
info = rezka.seriesInfo
for tr_id, data in info.items():
    print(tr_id, data['translator_name'], data['seasons'])
    # e.g. 56 'Дубляж' {1: 'Season 1', 2: 'Season 2'}

# episodesInfo: flat list for all seasons/episodes
for season in rezka.episodesInfo:
    print(f"Season {season['season']}: {season['season_text']}")
    for ep in season['episodes']:
        print(f"  Episode {ep['episode']}: {ep['episode_text']}")
        for tr in ep['translations']:
            print(f"    Translator: {tr['translator_name']} (id={tr['translator_id']})")

# Other parts / sequels
print(rezka.otherParts)
# [{'Film Part 1': 'https://hdrezka.ag/...'}, {'Film Part 2': 'https://hdrezka.ag/...'}]
```
```

--------------------------------

### Fast Search with Session

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Perform a fast search for a film using the HdRezkaSession. This method is suitable for quick lookups when advanced options are not needed.

```python
with HdRezkaSession("https://rezka_mirror.com/") as session:
	results = session.search("film name")
```

--------------------------------

### Configure Translator Priority

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Initialize HdRezkaApi with specific translator priorities and non-priorities. You can inspect available translators and their IDs, or override priorities after initialization. The `sort_translators` method can be used to manually sort translators.

```python
from HdRezkaApi import HdRezkaApi

rezka = HdRezkaApi(
    "https://hdrezka.ag/films/action/11111-film.html",
    translators_priority=[56, 111],       # prefer IDs 56 (Дубляж) then 111
    translators_non_priority=[238]        # deprioritize ID 238 (Оригинал + субтитры)
)

# Inspect available translators
print(rezka.translators)
# {56: {'name': 'Дубляж', 'premium': False}, 238: {'name': 'Оригинал + субтитры', 'premium': False}}

print(rezka.translators_names)
# {'Дубляж': {'id': 56, 'premium': False}, ...}

# Override priority after construction
rezka.translators_priority = [105, 56]
rezka.translators_non_priority = [238]

# Manually sort translators dict
sorted_tr = rezka.sort_translators(
    translators=rezka.translators,
    priority=[56],
    non_priority=[238]
)
print(sorted_tr)
```

--------------------------------

### Set Translators Priority

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Initialize HdRezkaSession with specific translator priorities or set them inline after initialization. This allows control over which translators are preferred.

```python
with HdRezkaSession(translators_priority, translators_non_priority) as session:
	# or inline seting up
	session.translators_priority = new_value
	session.translators_non_priority = new_value
```

--------------------------------

### Translators and Dubbing

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Manage translator and dubbing preferences. Inspect available translators, their IDs, and premium status. Override priority for automatic dub selection.

```APIDOC
## Translators and Dubbing

`rezka.translators` is a dict keyed by translator ID containing name and premium flag. `rezka.translators_names` provides the inverse lookup by name. Translator priority can be set at construction or overridden later to control which dub is selected automatically.

```python
from HdRezkaApi import HdRezkaApi

rezka = HdRezkaApi(
    "https://hdrezka.ag/films/action/11111-film.html",
    translators_priority=[56, 111],       # prefer IDs 56 (Дубляж) then 111
    translators_non_priority=[238]        # deprioritize ID 238 (Оригинал + субтитры)
)

# Inspect available translators
print(rezka.translators)
# {56: {'name': 'Дубляж', 'premium': False}, 238: {'name': 'Оригинал + субтитры', 'premium': False}}

print(rezka.translators_names)
# {'Дубляж': {'id': 56, 'premium': False}, ...}

# Override priority after construction
rezka.translators_priority = [105, 56]
rezka.translators_non_priority = [238]

# Manually sort translators dict
sorted_tr = rezka.sort_translators(
    translators=rezka.translators,
    priority=[56],
    non_priority=[238]
)
print(sorted_tr)
```
```

--------------------------------

### HdRezkaStreamSubtitles Object

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Provides access to subtitle information for a given stream, including available languages and subtitle URLs.

```APIDOC
## HdRezkaStreamSubtitles Object

### Description
Provides access to subtitle information for a given stream, including available languages and subtitle URLs.

### Attributes
- **`self.subtitles`** (dict) - Dictionary of subtitles where the key is the language code and the value is the subtitle information (e.g., title and link).
- **`self.keys`** (list) - List of available subtitle language codes.

### Methods
- **`self(id)`** - Call object with an argument (language code, language name, or index) to get the URL of the subtitles.

### Usage Examples
```python
stream = rezka.getStream(1, 5) # Assuming getStream is a method to get a specific stream

print( stream.subtitles.subtitles )  # Access the dictionary of all available subtitles
print( stream.subtitles.keys )       # Get a list of available language codes
print( stream.subtitles('en') )      # Get the URL for English subtitles
print( stream.subtitles(0) )         # Get the URL for subtitles using their index
```

### Response Example for `stream.subtitles.subtitles`
```json
{
  "en": {"title": "English", "link": "https://example.com/en.srt"},
  "ru": {"title": "Russian", "link": "https://example.com/ru.srt"}
}
```
```

--------------------------------

### getSeasonStreams

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Retrieves streaming links for a given season. Supports translation filtering, error ignoring, and progress callbacks. If an error occurs, it attempts to retry or returns None for that specific stream.

```APIDOC
## getSeasonStreams

### Description
Retrieves streaming links for a given season. Supports translation filtering, error ignoring, and progress callbacks. If an error occurs, it attempts to retry or returns None for that specific stream.

### Method
```python
getSeasonStreams(season, translation=None, ignore=False, progress=None, priority=None, non_priority=None)
```

### Parameters
#### Path Parameters
- **season** (int or str) - Required - The season number.
- **translation** (str, optional) - Filter streams by translation (e.g., 'Дубляж' or a translation ID).
- **ignore** (bool, optional) - If True, ignore errors and retry requests until a response is received.
- **progress** (function, optional) - A callback function to report download progress.
- **priority** (list, optional) - List of translator IDs to prioritize.
- **non_priority** (list, optional) - List of translator IDs to de-prioritize.

### Request Example
```python
rezka.getSeasonStreams(1, ignore=True, progress=progress)
rezka.getSeasonStreams(season='1')
rezka.getSeasonStreams(translation='Дубляж')
```

### Response
#### Success Response (dict)
- Returns a dictionary where keys are episode numbers and values are HdRezkaStream objects.

### Response Example
```json
{
  "1": "<HdRezkaStream(season:1, episode:1)>",
  "2": "<HdRezkaStream(season:1, episode:2)>"
}
```

### Error Handling
If an error occurs, an attempt will be made to repeat the request. If the error persists, `None` will be added to the final dictionary for that stream. Specify `ignore=True` to retry requests until a response is received.
```

--------------------------------

### HdRezkaFormat

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Information about the HdRezkaFormat class, parent of TVSeries and Movie.

```APIDOC
### HdRezkaFormat

Parent of classes: `TVSeries` and `Movie`
```python
from HdRezkaApi.types import TVSeries, Movie
rezka.type == TVSeries == TVSeries() == "tv_series"
```
```

--------------------------------

### Check Film Type with HdRezkaFormat

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Compare the film's type attribute against HdRezkaFormat classes like TVSeries or Movie. Ensures correct type checking.

```python
from HdRezkaApi.types import TVSeries, Movie
rezka.type == TVSeries == TVSeries() == "tv_series"
```

--------------------------------

### Translators Priority

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Configure translator priorities for stream selection.

```APIDOC
### Translators priority
```python
rezka = HdRezkaApi(url, translators_priority:list, translators_non_priority:list)
# or
rezka.translators_priority = new_value
rezka.translators_non_priority = new_value
```
#### `translators_priority`
Priority of translators IDs, where the further to the left, the more desirable the translation.

#### `translators_non_priority`
Priority of unwanted translator identifiers, where the further to the right, the less desirable the translation.
```

--------------------------------

### getStream Method

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Retrieves the stream URL for a movie or a specific episode of a series.

```APIDOC
### getStream
```python
getStream(season, episode, translation=None, priority=None, non_priority=None)
```
```python
getStream(
	translation='Дубляж' or translation='56'
)
```
If type is movie then there is no need to specify season and episode.
```python
stream = rezka.getStream() # if movie
```
```

--------------------------------

### Compare Film Type and Category

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Check the type (Movie/TVSeries) and category (Film/Series/Cartoon/Anime) of a title. Comparisons can be made against class instances, raw strings, or class objects.

```python
from HdRezkaApi import HdRezkaApi
from HdRezkaApi.types import TVSeries, Movie, Film, Series, Cartoon, Anime

rezka = HdRezkaApi("https://hdrezka.ag/series/drama/99999-some-series.html")

# Type comparison — all three forms are equivalent
print(rezka.type == TVSeries)      # True
print(rezka.type == TVSeries())    # True
print(rezka.type == "tv_series")   # True

# Category comparison
print(rezka.category == Series)    # True
print(rezka.category == "series")  # True

# Branching on type
if rezka.type == Movie:
    stream = rezka.getStream()
elif rezka.type == TVSeries:
    stream = rezka.getStream('1', '1')
```

--------------------------------

### getStream - Fetch a Single Stream

Source: https://context7.com/superzombi/hdrezkaapi/llms.txt

Fetches an `HdRezkaStream` object for a movie or a specific TV episode. Allows selection of a specific translator by name or ID.

```APIDOC
## getStream — Fetch a Single Stream

`getStream(season=None, episode=None, translation=None, priority=None, non_priority=None)` returns an `HdRezkaStream` object for a movie or a specific TV episode. Omit season/episode for movies. Pass `translation` as a translator name string or numeric ID string to select a specific dub.

```python
from HdRezkaApi import HdRezkaApi

# --- Movie ---
rezka = HdRezkaApi("https://hdrezka.ag/films/action/11111-film.html")
stream = rezka.getStream()                        # auto-selects best translator
stream = rezka.getStream(translation='Дубляж')    # by name
stream = rezka.getStream(translation='56')        # by ID string

# --- TV Series episode ---
rezka = HdRezkaApi("https://hdrezka.ag/series/drama/99999-series.html")
stream = rezka.getStream('2', '5')                # season 2, episode 5
stream = rezka.getStream('2', '5', translation='Дубляж')

# Get direct video URL by resolution
print(stream('720p'))       # ['https://cdn.../720.mp4', ...]
print(stream('720'))        # same — partial match works
print(stream(1080))         # int also works
print(stream('Ultra'))      # 4K Ultra HD
print(stream('1080p Ultra'))

# Full videos dict
print(stream.videos)
# {'360p': ['https://...mp4'], '480p': ['https://...mp4'], '720p': ['https://...mp4']}

# Stream metadata
print(stream.name)           # Film/series name
print(stream.translator_id)  # e.g. 56
print(stream.season)         # e.g. 2 (None for movies)
print(stream.episode)        # e.g. 5 (None for movies)
print(repr(stream))          # <HdRezkaStream(season:2, episode:5)>
```
```

--------------------------------

### Set Translator Priorities

Source: https://github.com/superzombi/hdrezkaapi/blob/main/README.md

Configure preferred and unwanted translators using `translators_priority` and `translators_non_priority` lists. This affects the order in which translations are selected.

```python
rezka = HdRezkaApi(url, translators_priority:list, translators_non_priority:list)
# or
rezka.translators_priority = new_value
rezka.translators_non_priority = new_value
```