### Install tpblite

Source: https://github.com/mlyon-other/tpb-lite/blob/master/README.md

Install the tpblite library using pip. Ensure you have lxml installed as a dependency.

```sh
pip install tpblite
```

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

### Automate Torrent Download with aria2c

Source: https://github.com/mlyon-other/tpb-lite/blob/master/README.md

Example workflow demonstrating how to search for a torrent, get the best match, and initiate a download using aria2c via subprocess.

```python
import subprocess
from tpblite import TPB

t = TPB()
torrents = t.search('GIMP 2.10.8')
torrent = torrents.getBestTorrent()
subprocess.call(['aria2c', torrent.magnetlink])
```

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

### Get Best Torrent with Filtering

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Filters search results by seed count and file size, returning the highest-seeded torrent matching the criteria. Default filters are 30 seeds and 1-4 GiB. Custom constraints can be specified.

```python
from tpblite import TPB, CATEGORIES, ORDERS

t = TPB('https://tpb.party')
torrents = t.search('debian', order=ORDERS.SEEDERS.DES, category=CATEGORIES.APPLICATIONS.ALL)

# Get best torrent with default filters (min 30 seeds, 1-4 GiB)
best = torrents.getBestTorrent()

# Get best torrent with custom size constraints
best = torrents.getBestTorrent(
    min_seeds=50,              # Minimum 50 seeders
    min_filesize='500 MiB',    # At least 500 MiB
    max_filesize='8 GiB'       # No larger than 8 GiB
)

if best:
    print(f'Best torrent: {best.title}')
    print(f'Seeds: {best.seeds}, Size: {best.filesize}')
    print(f'Magnet: {best.magnetlink}')
else:
    print('No torrents found matching criteria')
```

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

### Get Top Torrents

Source: https://github.com/mlyon-other/tpb-lite/blob/master/README.md

Retrieve the top recent torrents, optionally filtering by category and time (last 48 hours).

```python
from tpblite import TPB, CATEGORIES
t = TPB()

# Get the top recent torrents 
torrents = t.top(CATEGORIES.GAMES.ALL)
```

```python
# Customize with category and restriction to torrents from the last 48h
torrents = t.top(category=CATEGORIES.GAMES.ALL, last_48=True)
```

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

### Get Top Torrents

Source: https://github.com/mlyon-other/tpb-lite/blob/master/README.md

Retrieve the top torrents for a specific category.

```APIDOC
## Top

### Description
Fetches the top torrents for a given category, with an option to restrict results to the last 48 hours.

### Parameters
#### Query Parameters
- **category** (CATEGORIES) - Required - The category to fetch top torrents from.
- **last_48** (bool) - Optional - If True, restricts results to the last 48 hours.
```

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

### Get Top Torrents

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Retrieve the most popular torrents for a category. Optionally filter to show only torrents uploaded in the last 48 hours.

```python
from tpblite import TPB, CATEGORIES

t = TPB('https://tpb.party')

# Get overall top torrents for games
torrents = t.top(category=CATEGORIES.GAMES.ALL)

# Get top torrents from the last 48 hours for TV shows
torrents = t.top(
    category=CATEGORIES.VIDEO.TV_SHOWS,
    last_48=True
)

# Get overall top torrents across all categories
torrents = t.top(category=CATEGORIES.ALL)

print(f'Top {len(torrents)} torrents:')
for torrent in torrents[:10]:
    print(f'{torrent.title} - Seeds: {torrent.seeds}')
```

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

### TPB Class Initialization

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Initializes the main TPB client instance to connect to a specific Pirate Bay mirror.

```APIDOC
## TPB Class Initialization

### Description
Initializes the TPB client to interact with a specific Pirate Bay mirror URL.

### Parameters
#### Request Body
- **domain** (string) - Optional - The URL of the Pirate Bay mirror to connect to. Defaults to a fallback domain if not provided.
```

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

### Initialize TPB Class

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Instantiate the TPB class to connect to a Pirate Bay mirror. A default fallback domain is used if none is provided.

```python
from tpblite import TPB

# Create TPB instance with default domain
t = TPB()

# Create TPB instance with a specific mirror
t = TPB('https://tpb.party')

# Create TPB instance with another working mirror
t = TPB('https://thepiratebay.org')

print(t)
# Output: TPB Object, base URL: https://tpb.party
```

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

### Initialize TPB Object

Source: https://github.com/mlyon-other/tpb-lite/blob/master/README.md

Create a TPB object to interact with ThePirateBay. You can specify a working domain or use the default.

```python
from tpblite import TPB

# Create a TPB object with a domain name
t = TPB('https://tpb.party')
```

```python
# Or create a TPB object with default domain
t = TPB()
```

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

### Print All Categories

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Displays all available hierarchical category constants for filtering searches. Use this to understand the structure and available options.

```python
from tpblite import CATEGORIES

# Print all available categories
CATEGORIES.printOptions()
```

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

### List Available Categories and Sort Orders

Source: https://github.com/mlyon-other/tpb-lite/blob/master/README.md

Print all available categories or a subset, and list all available sort orders for searches and browsing.

```python
# To print all available categories, use the classmethod printOptions
CATEGORIES.printOptions()
```

```python
# Or just a subset of categories, like VIDEO
CATEGORIES.VIDEO.printOptions()
```

```python
# Similarly for the sort order
ORDERS.printOptions()
```

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

### Automated Download Workflow with CLI Client

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Searches for content, retrieves the best torrent matching specified criteria (seed count, file size), verifies trust status, and initiates download using a command-line torrent client like aria2c.

```python
import subprocess
from tpblite import TPB, CATEGORIES, ORDERS

t = TPB('https://tpb.party')

# Search for specific content
torrents = t.search(
    'GIMP 2.10',
    category=CATEGORIES.APPLICATIONS.ALL,
    order=ORDERS.SEEDERS.DES
)

# Get the best torrent matching criteria
torrent = torrents.getBestTorrent(
    min_seeds=10,
    min_filesize='50 MiB',
    max_filesize='500 MiB'
)

if torrent:
    # Verify it's from a trusted source
    if torrent.is_trusted or torrent.is_vip:
        print(f'Downloading: {torrent.title}')
        print(f'From: {torrent.uploader} ({"VIP" if torrent.is_vip else "Trusted"})')

        # Use aria2c or other CLI torrent client
        subprocess.call(['aria2c', torrent.magnetlink])
    else:
        print('Warning: Torrent is not from a trusted source')
else:
    print('No suitable torrent found')
```

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

### Print All Sort Orders

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Displays all available sorting options for search results, including ascending and descending variants for name, upload date, size, seeders, leechers, and uploader.

```python
from tpblite import ORDERS

# Print all available sort orders
ORDERS.printOptions()
```

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

### Search for Torrents

Source: https://github.com/mlyon-other/tpb-lite/blob/master/README.md

Perform a quick search for torrents. The results are returned as a Torrents object. You can customize search parameters like page number, order, and category.

```python
# Quick search for torrents, returns a Torrents object
torrents = t.search('public domain')
```

```python
# See how many torrents were found
print('There were {0} torrents found.'.format(len(torrents)))
```

```python
# Iterate through list of torrents and print info for Torrent object
for torrent in torrents:
    print(torrent)
```

```python
# Customize your search
from tpblite import CATEGORIES, ORDERS
torrents = t.search('public domain', page=2, order=ORDERS.NAME.DES, category=CATEGORIES.VIDEO.MOVIES)
```

```python
# Get the most seeded torrent based on a filter
torrent = torrents.getBestTorrent(min_seeds=30, min_filesize='500 MiB', max_filesize='4 GiB')
```

```python
# Or select a particular torrent by indexing
torrent = torrents[3]
```

```python
# Get the magnet link for a torrent
print(torrent.magnetlink)
```

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

### Print Video Subcategories

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Displays only the available subcategories within the VIDEO category. Useful for targeted video searches.

```python
from tpblite import CATEGORIES

# Print only video subcategories
CATEGORIES.VIDEO.printOptions()
```

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

### Browse Category

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Browses all torrents within a specific category, supporting pagination and custom sorting.

```APIDOC
## Browse Category

### Description
Retrieves a list of torrents within a specific category.

### Parameters
#### Request Body
- **category** (object) - Required - The category to browse.
- **page** (int) - Optional - Page number (0-indexed).
- **order** (object) - Optional - Sorting order.
```

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

### Browse Category

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Browse torrents within a specific category. Useful for content discovery without a search term. Supports pagination and custom sorting.

```python
from tpblite import TPB, CATEGORIES, ORDERS

t = TPB('https://tpb.party')

# Browse all video content
torrents = t.browse(category=CATEGORIES.VIDEO.ALL)

# Browse HD movies sorted by upload date (newest first)
torrents = t.browse(
    category=CATEGORIES.VIDEO.HD_MOVIES,
    page=0,
    order=ORDERS.UPLOADED.DES
)

# Browse PC games sorted by file size
torrents = t.browse(
    category=CATEGORIES.GAMES.PC,
    page=1,
    order=ORDERS.SIZE.DES
)

print(f'Found {len(torrents)} torrents in category')
for torrent in torrents[:5]:
    print(f'{torrent.title} - {torrent.filesize}')
```

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

### Search for Torrents

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Perform searches for torrents using keywords. Supports advanced options like pagination, custom ordering, and category filtering. Results are returned as a Torrents collection.

```python
from tpblite import TPB, CATEGORIES, ORDERS

t = TPB('https://tpb.party')

# Basic search
torrents = t.search('ubuntu')
print(f'Found {len(torrents)} torrents')

# Advanced search with pagination, ordering, and category filter
torrents = t.search(
    'ubuntu',
    page=0,                          # Page number (0-indexed)
    order=ORDERS.SEEDERS.DES,        # Sort by seeders descending
    category=CATEGORIES.APPLICATIONS.UNIX  # Unix applications only
)

# Iterate through results
for torrent in torrents:
    print(f'{torrent.title} - Seeds: {torrent.seeds}, Size: {torrent.filesize}')

# Output:
# Ubuntu 22.04 LTS Desktop - Seeds: 1523, Size: 3.6 GiB
# Ubuntu 20.04.4 Server - Seeds: 892, Size: 1.2 GiB
```

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

### Search Torrents

Source: https://github.com/mlyon-other/tpb-lite/blob/master/README.md

Search for torrents on ThePirateBay with optional filtering by category, page, and sort order.

```APIDOC
## Search

### Description
Searches for torrents based on a query string and returns a Torrents object containing multiple Torrent objects.

### Parameters
#### Query Parameters
- **query** (str) - Required - The search term.
- **page** (int) - Optional - The page number of results.
- **order** (ORDERS) - Optional - The sort order for results.
- **category** (CATEGORIES) - Optional - The category to filter by.

### Response
- **Torrents** (object) - A list-like collection of Torrent objects.
```

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

### Search for Torrents

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Searches for torrents based on a query string with support for pagination, sorting, and category filtering.

```APIDOC
## Search for Torrents

### Description
Searches The Pirate Bay for torrents matching a query string.

### Parameters
#### Request Body
- **query** (string) - Required - The search term.
- **page** (int) - Optional - Page number (0-indexed).
- **order** (object) - Optional - Sorting order (e.g., ORDERS.SEEDERS.DES).
- **category** (object) - Optional - Category filter (e.g., CATEGORIES.APPLICATIONS.UNIX).
```

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

### Browse Torrents

Source: https://github.com/mlyon-other/tpb-lite/blob/master/README.md

Browse torrents within a specific category. You can customize the page number and sort order for the browse results.

```python
# You can browse all of the torrents from a single category
torrents = t.browse(category=CATEGORIES.VIDEO)
```

```python
# Customize the page number and sort order
torrents = t.browse(category=CATEGORIES.VIDEO.MOVIES, page=1, order=ORDERS.UPLOADED.DES)
```

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

### Browse Torrents

Source: https://github.com/mlyon-other/tpb-lite/blob/master/README.md

Browse torrents within a specific category.

```APIDOC
## Browse

### Description
Retrieves a list of torrents from a specific category.

### Parameters
#### Query Parameters
- **category** (CATEGORIES) - Required - The category to browse.
- **page** (int) - Optional - The page number.
- **order** (ORDERS) - Optional - The sort order.
```

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

### Torrent Object Attributes

Source: https://context7.com/mlyon-other/tpb-lite/llms.txt

Access metadata for individual torrents, including title, peer counts, size, upload date, uploader, magnet link, and trust indicators.

```python
from tpblite import TPB

t = TPB('https://tpb.party')
torrents = t.search('linux mint')

# Access individual torrent by index
torrent = torrents[0]

# Available attributes
print(f'Title: {torrent.title}')           # Torrent name
print(f'Seeds: {torrent.seeds}')           # Number of seeders (int)
print(f'Leeches: {torrent.leeches}')       # Number of leechers (int)
print(f'Size: {torrent.filesize}')         # Human-readable size (e.g., "2.1 GiB")
print(f'Bytes: {torrent.byte_size}')       # Size in bytes (int)
print(f'Uploaded: {torrent.upload_date}')  # Upload date string
print(f'Uploader: {torrent.uploader}')     # Username of uploader
print(f'URL: {torrent.url}')               # Torrent page URL
print(f'Magnet: {torrent.magnetlink}')     # Magnet link for download
print(f'InfoHash: {torrent.infohash}')     # Torrent info hash
print(f'Category: {torrent.category}')     # Category (e.g., "Applications -> UNIX")
print(f'VIP: {torrent.is_vip}')            # Is VIP uploader (bool)
print(f'Trusted: {torrent.is_trusted}')    # Is trusted uploader (bool)

# String representation
print(torrent)
# Output: Linux Mint 21 Cinnamon, S: 456, L: 23, 2.1 GiB
```

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