### Install Py1337x

Source: https://context7.com/hemantapkh/1337x/llms.txt

Install the library using pip, either from PyPI or directly from the source repository.

```bash
pip install 1337x
# or from source
pip install git+https://github.com/hemantapkh/1337x
```

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

### Install 1337x Python Package

Source: https://github.com/hemantapkh/1337x/blob/main/README.md

Install the 1337x Python package using pip. You can install from PyPi or directly from the source repository.

```bash
pip install 1337x
```

```bash
pip install git+https://github.com/hemantapkh/1337x
```

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

### Search Torrents with 1337x API

Source: https://github.com/hemantapkh/1337x/blob/main/README.md

Demonstrates how to search for torrents using the Py1337x library. It's recommended to specify a category due to recent website changes. Examples include basic search, search with sorting, and fetching trending torrents.

```python
import py1337x

torrents = py1337x.Py1337x()

# Basic search
results = torrents.search(
    'ubuntu',
    page=1,
    category=py1337x.category.APPS
)
for result in results.items:
  print(f"Title={result.name} Seeders={result.seeders}")

# Search with sorting by seeders
results = torrents.search('vlc', sort_by=py1337x.sort.SEEDERS, category=py1337x.category.APPS)
print(results)

# Get today's trending torrents
results = torrents.trending()
print(results)
```

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

### info() - Get Detailed Torrent Information

Source: https://context7.com/hemantapkh/1337x/llms.txt

Retrieves full metadata for a single torrent, including its magnet link, info hash, description, genres, and images.

```APIDOC
## info()

### Description
Retrieves full metadata for a single torrent, including its magnet link, info hash, description, genres, images, and upload details. Accepts either a direct torrent URL (`link`) or a `torrent_id` extracted from search results. Exactly one of the two must be provided.

### Parameters

- **link** (str) - Optional - The direct URL of the torrent page.
- **torrent_id** (str) - Optional - The unique ID of the torrent.

### Request Body

Exactly one of `link` or `torrent_id` must be provided.

### Usage Examples

```python
import py1337x
from py1337x.types import category

torrents = py1337x.Py1337x()

# Retrieve torrent_id from a search result
results = torrents.search("ubuntu 22.04", category=category.APPS)
torrent_id = results.items[0].torrent_id

# Fetch full info using torrent_id
info = torrents.info(torrent_id=torrent_id)
print(f"Name:        {info.name}")
print(f"Category:    {info.category}")
print(f"Size:        {info.size}")
print(f"Seeders:     {info.seeders}")
print(f"Leechers:    {info.leechers}")
print(f"Uploaded:    {info.date_uploaded}")
print(f"Magnet Link: {info.magnet_link}")
print(f"Info Hash:   {info.info_hash}")

# Fetch using a direct URL instead
info = torrents.info(link="https://www.1337x.to/torrent/123456/ubuntu-22-04/")

# Serialize to a plain dictionary
info_dict = info.to_dict()
print(info_dict)
# {
#   'name': 'Ubuntu 22.04.3 LTS',
#   'size': '1.4 GB',
#   'magnet_link': 'magnet:?xt=urn:btih:...',
#   'seeders': '312',
#   'leechers': '45',
#   ...
# }

# TypeError raised if both or neither are provided:
# torrents.info()                              # raises TypeError
# torrents.info(link="...", torrent_id="...") # raises TypeError
```
```

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

### Get Torrent Info and Magnet Link

Source: https://context7.com/hemantapkh/1337x/llms.txt

Fetches detailed information about a specific torrent using its ID, including name, magnet link, and size. The `genre` and `images` fields are optional.

```python
info = torrents.info(torrent_id="5961735")
print(info.name)         # "Ubuntu 22.04 LTS"
print(info.magnet_link)  # "magnet:?xt=urn:btih:..."
print(info.info_hash)    # "abc123..."
print(info.size)         # "3.6 GB"
print(info.genre)        # ["Linux", "OS"]
print(info.images)       # ["https://...screenshot1.jpg"]
print(info.to_dict())    # Full dict representation
```

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

### Get Detailed Torrent Information

Source: https://context7.com/hemantapkh/1337x/llms.txt

Retrieve comprehensive details for a specific torrent, including magnet link, info hash, description, and upload information. This can be done using either a torrent ID or a direct URL. The result can be serialized to a dictionary.

```python
import py1337x
from py1337x.types import category

torrents = py1337x.Py1337x()

# Retrieve torrent_id from a search result
results = torrents.search("ubuntu 22.04", category=category.APPS)
torrent_id = results.items[0].torrent_id

# Fetch full info using torrent_id
info = torrents.info(torrent_id=torrent_id)
print(f"Name:        {info.name}")
print(f"Category:    {info.category}")
print(f"Size:        {info.size}")
print(f"Seeders:     {info.seeders}")
print(f"Leechers:    {info.leechers}")
print(f"Uploaded:    {info.date_uploaded}")
print(f"Magnet Link: {info.magnet_link}")
print(f"Info Hash:   {info.info_hash}")

# Fetch using a direct URL instead
info = torrents.info(link="https://www.1337x.to/torrent/123456/ubuntu-22-04/")

# Serialize to a plain dictionary
info_dict = info.to_dict()
print(info_dict)
# {
#   'name': 'Ubuntu 22.04.3 LTS',
#   'size': '1.4 GB',
#   'magnet_link': 'magnet:?xt=urn:btih:...',
#   'seeders': '312',
#   'leechers': '45',
#   ...
# }

# TypeError raised if both or neither are provided:
# torrents.info()                              # raises TypeError
# torrents.info(link="...", torrent_id="...") # raises TypeError
```

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

### Retrieve Top 100 Torrents with py1337x

Source: https://context7.com/hemantapkh/1337x/llms.txt

Get the global top 100 torrents or the top 100 within a specific category. Requires importing `py1337x` and `category` from `py1337x.types`.

```python
import py1337x
from py1337x.types import category

torrents = py1337x.Py1337x()

# Global top 100
top_all = torrents.top()
print(f"Total: {top_all.item_count}")

# Top 100 movies
top_movies = torrents.top(category=category.MOVIES)
for item in top_movies.items[:3]:
    print(f"{item.name} | Seeders: {item.seeders} | Size: {item.size}")

# Top 100 games
top_games = torrents.top(category=category.GAMES)
print(top_games.items[0].name)
```

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

### Get Torrent Information with 1337x API

Source: https://github.com/hemantapkh/1337x/blob/main/README.md

Retrieves detailed information for a specific torrent, including its magnet link. The result can be converted to a dictionary.

```python
# Getting info the the first result of the above search
torrent_id = results.items[0].torrent_id
info = torrents.info(torrent_id=torrent_id)
print(info)

# Convert the result to dictionary
info_dict = info.to_dict()
print(info_dict)
```

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

### Initialize Synchronous Py1337x Client

Source: https://context7.com/hemantapkh/1337x/llms.txt

Create a synchronous client instance. Default initialization connects to the standard 1337x URL. Customization options include overriding the base URL, configuring cloudscraper, and setting request timeouts or proxies.

```python
from py1337x import Py1337x

# Default initialization — connects to https://www.1337x.to
torrents = Py1337x()

# Custom base URL with a proxy and a timeout on every request
torrents = Py1337x(
    base_url="https://www.1337x.to",
    cloudscraper_kwargs={"browser": {"browser": "chrome", "platform": "windows"}},
    requests_kwargs={"timeout": 10, "proxies": {"https": "https://proxy.example.com:8080"}},
)
```

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

### Py1337x() - Synchronous Client Initialization

Source: https://context7.com/hemantapkh/1337x/llms.txt

Initializes a synchronous client for interacting with 1337x. Supports custom base URLs and request configurations.

```APIDOC
## Py1337x()

### Description
Creates a synchronous client backed by a `cloudscraper` session. Accepts an optional `base_url` override (useful if the default domain is unreachable), `cloudscraper_kwargs` for tuning the scraper, and `requests_kwargs` forwarded to every HTTP call.

### Initialization Examples

```python
from py1337x import Py1337x

# Default initialization — connects to https://www.1337x.to
torrents = Py1337x()

# Custom base URL with a proxy and a timeout on every request
torrents = Py1337x(
    base_url="https://www.1337x.to",
    cloudscraper_kwargs={"browser": {"browser": "chrome", "platform": "windows"}},
    requests_kwargs={"timeout": 10, "proxies": {"https": "https://proxy.example.com:8080"}},
)
```
```

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

### browse() — Browse Torrents by Category

Source: https://context7.com/hemantapkh/1337x/llms.txt

Browses all torrents in a given category with support for pagination.

```APIDOC
## `browse()` — Browse Torrents by Category

Browses all torrents in a given category with pagination support.

### Method Signature
`browse(category: Category, page: int = 1) -> TorrentResult`

### Parameters
- **category** (Category): The category to browse (e.g., `category.APPS`, `category.ANIME`). This parameter is required.
- **page** (int, optional): The page number to retrieve. Defaults to `1`.

### Returns
- `TorrentResult`: An object containing a list of `TorrentItem` and pagination information.
```

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

### Browse Torrents by Category with py1337x

Source: https://context7.com/hemantapkh/1337x/llms.txt

Browse all torrents in a given category with pagination support. Requires importing `py1337x` and `category` from `py1337x.types`.

```python
import py1337x
from py1337x.types import category

torrents = py1337x.Py1337x()

# Browse page 1 of Applications
apps_page1 = torrents.browse(category=category.APPS, page=1)
print(f"Page {apps_page1.current_page} of {apps_page1.page_count}")
for item in apps_page1.items:
    print(f"  {item.name} — uploaded by {item.uploader}")

# Browse page 3 of Anime
anime = torrents.browse(category=category.ANIME, page=3)
print(anime.items[0].url)
```

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

### Search for Torrents with Py1337x

Source: https://context7.com/hemantapkh/1337x/llms.txt

Search for torrents using a query string, optionally filtering by category, sorting by various fields (seeders, size, time), and ordering the results. Specifying a category is recommended for better results. Supports pagination.

```python
import py1337x
from py1337x.types import category, sort, order

torrents = py1337x.Py1337x()

# Basic search within a category
results = torrents.search("ubuntu", category=category.APPS)
print(f"Total items: {results.item_count}, Pages: {results.page_count}")
for item in results.items:
    print(f"  [{item.seeders}S/{item.leechers}L] {item.name} — {item.size} — {item.url}")

# Search sorted by seeders descending
results = torrents.search(
    "vlc media player",
    category=category.APPS,
    sort_by=sort.SEEDERS,
    order=order.DESCENDING,
)
print(results.items[0].name)  # Top-seeded result

# Paginated search — fetch page 2, ascending order
results = torrents.search(
    "python tutorial",
    category=category.OTHER,
    page=2,
    sort_by=sort.TIME,
    order=order.ASCENDING,
)
print(f"Page {results.current_page} of {results.page_count}")

# Available categories:
# category.MOVIES | category.TV | category.GAMES | category.MUSIC
# category.APPS   | category.ANIME | category.DOCUMENTARIES | category.OTHER

# Available sort fields:  sort.TIME | sort.SIZE | sort.SEEDERS | sort.LEECHERS
# Available orders:       order.ASCENDING ("asc") | order.DESCENDING ("desc")
```

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

### Py1337x Synchronous Client

Source: https://github.com/hemantapkh/1337x/blob/main/docs/sync_client.md

The Py1337x class provides a synchronous interface for interacting with 1337x. It allows users to perform various operations like searching for torrents, retrieving magnet links, and accessing torrent details.

```APIDOC
## Class: Py1337x

### Description
Provides a synchronous interface for interacting with 1337x.

### Methods

#### `__init__`

Initializes the Py1337x client.

#### `search(query, category='all', page=1)`

Searches for torrents based on a query.

- **query** (str): The search term.
- **category** (str, optional): The category to search within. Defaults to 'all'.
- **page** (int, optional): The page number for search results. Defaults to 1.

#### `info(torrent_id)`

Retrieves detailed information about a specific torrent.

- **torrent_id** (str): The unique identifier of the torrent.

#### `download(torrent_id)`

Retrieves the download magnet link for a specific torrent.

- **torrent_id** (str): The unique identifier of the torrent.

#### `trending()`

Retrieves a list of currently trending torrents.

#### `latest()`

Retrieves a list of the latest uploaded torrents.

#### `categories()`

Retrieves a list of available categories.

### Example Usage

```python
from py1337x import Py1337x

sync_client = Py1337x()

# Search for torrents
results = sync_client.search('python tutorial')
print(results)

# Get trending torrents
trending_torrents = sync_client.trending()
print(trending_torrents)

# Get torrent details
torrent_details = sync_client.info('some_torrent_id')
print(torrent_details)

# Get download magnet link
magnet_link = sync_client.download('some_torrent_id')
print(magnet_link)

# Get available categories
all_categories = sync_client.categories()
print(all_categories)
```
```

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

### Retrieve Trending Torrents with py1337x

Source: https://context7.com/hemantapkh/1337x/llms.txt

Fetch today's or this week's trending torrents, optionally filtered by category. Requires importing `py1337x` and `category` from `py1337x.types`.

```python
import py1337x
from py1337x.types import category

torrents = py1337x.Py1337x()

# Today's global trending torrents
trending_today = torrents.trending()
for item in trending_today.items[:5]:
    print(f"{item.name} — {item.seeders} seeders")

# Weekly trending in Movies
trending_movies_weekly = torrents.trending(category=category.MOVIES, weekly=True)
print(f"Top weekly movie: {trending_movies_weekly.items[0].name}")

# Daily trending in Anime
trending_anime = torrents.trending(category=category.ANIME, weekly=False)
print(trending_anime.items[0].to_dict())
```

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

### Retrieve Popular Torrents with py1337x

Source: https://context7.com/hemantapkh/1337x/llms.txt

Fetch popular torrents in a given category, either for today or this week. A category is required for this method. Requires importing `py1337x` and `category` from `py1337x.types`.

```python
import py1337x
from py1337x.types import category

torrents = py1337x.Py1337x()

# Popular games today
popular_games = torrents.popular(category=category.GAMES)
for item in popular_games.items:
    print(f"{item.name} ({item.size})")

# Popular apps this week
popular_apps_weekly = torrents.popular(category=category.APPS, weekly=True)
print(popular_apps_weekly.items[0].name)

# Popular music this week
popular_music = torrents.popular(category=category.MUSIC, weekly=True)
print(popular_music.to_dict())
```

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

### Asynchronous Torrent Operations with AsyncPy1337x

Source: https://context7.com/hemantapkh/1337x/llms.txt

Utilize `AsyncPy1337x` for asynchronous torrent operations, including concurrent searches and trending fetches, and awaiting individual torrent info. Requires importing `asyncio`, `AsyncPy1337x`, and types from `py1337x.types`.

```python
import asyncio
from py1337x import AsyncPy1337x
from py1337x.types import category, sort

async def main():
    torrents = AsyncPy1337x()

    # Concurrent search and trending fetch
    search_task = torrents.search("linux mint", category=category.APPS, sort_by=sort.SEEDERS)
    trending_task = torrents.trending(category=category.MOVIES, weekly=True)
    results, trending = await asyncio.gather(search_task, trending_task)

    print(f"Search results: {results.item_count}")
    for item in results.items[:3]:
        print(f"  {item.name} — {item.seeders} seeders")

    print(f"\nTop trending movie: {trending.items[0].name}")

    # Get detailed info asynchronously
    torrent_id = results.items[0].torrent_id
    info = await torrents.info(torrent_id=torrent_id)
    print(f"\nMagnet: {info.magnet_link}")

asyncio.run(main())
```

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

### AsyncPy1337x Class

Source: https://github.com/hemantapkh/1337x/blob/main/docs/async_client.md

The AsyncPy1337x class provides an asynchronous interface for interacting with the 1337x website. It allows for non-blocking operations, making it suitable for applications that require high concurrency.

```APIDOC
## Class: AsyncPy1337x

### Description
Provides an asynchronous interface for interacting with the 1337x website.

### Methods
(Details of methods would be listed here if available in the source)
```

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

### AsyncPy1337x — Asynchronous Client

Source: https://context7.com/hemantapkh/1337x/llms.txt

An asynchronous client that mirrors the synchronous `Py1337x` methods. All methods must be awaited and are identical in signature and return type.

```APIDOC
## `AsyncPy1337x` — Asynchronous Client

`AsyncPy1337x` is a drop-in async replacement for `Py1337x`. All methods are identical in signature and return type but must be awaited. Internally, synchronous calls are offloaded to a thread pool via `asyncer.asyncify`.

### Methods
All methods from the synchronous `Py1337x` client are available and must be `await`ed. Examples include:
- `search(query: str, category: Optional[Category] = None, sort_by: Optional[Sort] = None) -> TorrentResult`
- `trending(category: Optional[Category] = None, weekly: bool = False) -> TorrentResult`
- `top(category: Optional[Category] = None) -> TorrentResult`
- `popular(category: Category, weekly: bool = False) -> TorrentResult`
- `browse(category: Category, page: int = 1) -> TorrentResult`
- `info(torrent_id: int) -> TorrentInfo`

### Usage Example
```python
import asyncio
from py1337x import AsyncPy1337x
from py1337x.types import category, sort

async def main():
    torrents = AsyncPy1337x()
    # ... await calls to torrents methods ...

asyncio.run(main())
```
```

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

### Asynchronous Torrent Search with 1337x API

Source: https://github.com/hemantapkh/1337x/blob/main/README.md

Shows how to perform asynchronous torrent searches using the AsyncPy1337x class. This is useful for non-blocking operations in async applications.

```python
import asyncio
from py1337x import AsyncPy1337x

async def main():
    torrents = AsyncPy1337x()
    results = await torrents.search('vlc media player')
    print(results)

asyncio.run(main())
```

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

### top() — Retrieve Top 100 Torrents

Source: https://context7.com/hemantapkh/1337x/llms.txt

Retrieves the global top 100 torrents or the top 100 within a specific category.

```APIDOC
## `top()` — Retrieve Top 100 Torrents

Returns the global top 100 torrents or the top 100 within a specific category.

### Method Signature
`top(category: Optional[Category] = None) -> TorrentResult`

### Parameters
- **category** (Category, optional): Filter torrents by a specific category (e.g., `category.MOVIES`, `category.GAMES`). Defaults to `None` for global top 100.

### Returns
- `TorrentResult`: An object containing a list of `TorrentItem` and pagination information.
```

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

### trending() — Retrieve Trending Torrents

Source: https://context7.com/hemantapkh/1337x/llms.txt

Retrieves today's or this week's trending torrents. It can be optionally filtered by category and time period (daily/weekly).

```APIDOC
## `trending()` — Retrieve Trending Torrents

Returns today's or this week's trending torrents, optionally filtered by category.

### Method Signature
`trending(category: Optional[Category] = None, weekly: bool = False) -> TorrentResult`

### Parameters
- **category** (Category, optional): Filter torrents by a specific category (e.g., `category.MOVIES`, `category.ANIME`). Defaults to `None` for global trending.
- **weekly** (bool, optional): If `True`, retrieves weekly trending torrents; otherwise, retrieves daily trending torrents. Defaults to `False`.

### Returns
- `TorrentResult`: An object containing a list of `TorrentItem` and pagination information.
```

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

### search() - Search for Torrents

Source: https://context7.com/hemantapkh/1337x/llms.txt

Searches 1337x for torrents matching a query string. Supports optional category filtering, result sorting, ordering, and pagination.

```APIDOC
## search()

### Description
Searches 1337x for torrents matching a query string. Supports optional category filtering, result sorting, ordering, and pagination. Due to a recent website change, specifying a `category` is strongly recommended to avoid empty results.

### Parameters

- **query** (str) - Required - The search term for torrents.
- **category** (py1337x.types.category) - Optional - Filters results by category. Recommended to avoid empty results.
- **sort_by** (py1337x.types.sort) - Optional - Field to sort results by (e.g., SEEDERS, TIME).
- **order** (py1337x.types.order) - Optional - Order of sorting (ASCENDING or DESCENDING).
- **page** (int) - Optional - The page number of search results to retrieve.

### Usage Examples

```python
import py1337x
from py1337x.types import category, sort, order

torrents = py1337x.Py1337x()

# Basic search within a category
results = torrents.search("ubuntu", category=category.APPS)
print(f"Total items: {results.item_count}, Pages: {results.page_count}")
for item in results.items:
    print(f"  [{item.seeders}S/{item.leechers}L] {item.name} — {item.size} — {item.url}")

# Search sorted by seeders descending
results = torrents.search(
    "vlc media player",
    category=category.APPS,
    sort_by=sort.SEEDERS,
    order=order.DESCENDING,
)
print(results.items[0].name)  # Top-seeded result

# Paginated search — fetch page 2, ascending order
results = torrents.search(
    "python tutorial",
    category=category.OTHER,
    page=2,
    sort_by=sort.TIME,
    order=order.ASCENDING,
)
print(f"Page {results.current_page} of {results.page_count}")

# Available categories:
# category.MOVIES | category.TV | category.GAMES | category.MUSIC
# category.APPS   | category.ANIME | category.DOCUMENTARIES | category.OTHER

# Available sort fields:  sort.TIME | sort.SIZE | sort.SEEDERS | sort.LEECHERS
# Available orders:       order.ASCENDING ("asc") | order.DESCENDING ("desc")
```
```

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

### popular() — Retrieve Popular Torrents

Source: https://context7.com/hemantapkh/1337x/llms.txt

Returns popular torrents in a given category, either for today or this week. A category is required for this method.

```APIDOC
## `popular()` — Retrieve Popular Torrents

Returns popular torrents in a given category — either today's or this week's. Unlike `top()`, a category is required.

### Method Signature
`popular(category: Category, weekly: bool = False) -> TorrentResult`

### Parameters
- **category** (Category): The category to retrieve popular torrents from (e.g., `category.GAMES`, `category.APPS`). This parameter is required.
- **weekly** (bool, optional): If `True`, retrieves weekly popular torrents; otherwise, retrieves daily popular torrents. Defaults to `False`.

### Returns
- `TorrentResult`: An object containing a list of `TorrentItem` and pagination information.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.