Metadata-Version: 2.4
Name: proxytv
Version: 1.1.0
Summary: Python library and CLI tool for parsing and filtering IPTV playlists from proxytv.ru
License-Expression: MIT
License-File: LICENSE
Keywords: IPTV,proxytv,parser,m3u8,m3u,playlist
Author: Nikita Denissov
Author-email: n.denissov@proton.me
Requires-Python: >=3.9
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/ndenissov/proxytv
Project-URL: Repository, https://github.com/ndenissov/proxytv
Description-Content-Type: text/markdown

# proxytv

[![PyPI version](https://img.shields.io/pypi/v/proxytv.svg)](https://pypi.org/project/proxytv/)
[![Downloads](https://static.pepy.tech/badge/proxytv)](https://pepy.tech/project/proxytv)
[![Python versions](https://img.shields.io/pypi/pyversions/proxytv.svg)](https://pypi.org/project/proxytv/)
[![License](https://img.shields.io/pypi/l/proxytv.svg)](https://github.com/ndenissov/proxytv/blob/main/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/ndenissov/proxytv)](https://github.com/ndenissov/proxytv/stargazers)

Python library and CLI tool for parsing, processing, and filtering IPTV playlists from proxytv.ru.

## Installation

```bash
pip install proxytv
```

Or using Poetry:

```bash
poetry add proxytv
```

## Command Line Interface

The package provides a `proxytv` executable command (also accessible via `python -m proxytv`).

### CLI Options

```text
usage: proxytv [-h] [-f] [-t] [-q QUERY] [-cd COOLDOWN] [-x PROXY] [-chf CHANNEL_FILTERS] [-pl [PL ...]] [-o OUTPUT]

options:
  -h, --help            Show help message and exit.
  -f, --forever         Run repeatedly every cooldown seconds.
  -t, --threading       Fetch and parse playlists concurrently in separate threads (default: True).
  -q, --query QUERY     Single search query (e.g. "ch: HD" or "pl: aist").
  -cd, --cooldown COOLDOWN
                        Interval between iterations in seconds (default: 30).
  -x, --proxy PROXY     Proxy server formatted as <protocol>://<ip>:<port>.
  -chf, --channel-filters CHANNEL_FILTERS
                        Path to channel filter file.
  -pl [PL ...]          Playlist names to download.
  -o, --output OUTPUT   Output .m3u(8) file path (default: stdout).
```

### Usage Examples

Collect all channels from all available playlists into a single file:

```bash
proxytv -o playlist.m3u8
```

Periodically update selected channels every 2 minutes:

```bash
proxytv -chf filters.txt -f -cd 120 -o tv.m3u8
```

Query a specific channel or playlist:

```bash
proxytv -q "ch: HD" -o hd_channels.m3u
```

## Channel Filtering Rules

The `--channel-filters` (`-chf`) flag specifies a text file containing filter rules. Each line defines a rule based on regular expressions.

A channel is included in the output playlist if it matches at least one defined rule.

### Rule Syntax

1. A leading `\` character is ignored.
2. A leading `:` character filters by IP address or stream URL instead of channel title.
3. A leading `#` character matches literal substrings without evaluating regular expression symbols.
4. Rules without special prefixes are evaluated as regular expressions against channel titles and metadata.
5. All rule matching is case-insensitive.

### Example Filter File (filters.txt)

```regexp
#NICKELODEON HD
#CARTOON NETWORK
#REN TV
#TNT HD
```

Run continuous parsing with filtering:

```bash
python -m proxytv -chf filters.txt -f -cd 120 -o tv.m3u8
```

## Python API

The library can be integrated directly into Python applications.

### Basic API Search

```python
from proxytv import SearchEngine

# List available playlists
playlists = SearchEngine.plist()

# Search for a specific playlist
extinf = SearchEngine.pl("aist")

# Save results to a file
with open("aist.m3u8", "w", encoding="utf-8") as f:
    f.write(str(extinf))
```

### Custom Robot Implementation

Extend the `Robot` or `RobotThreading` classes to customize processing loops or post-processing behavior:

```python
from proxytv import RobotThreading, SearchEngine

class CustomRobot(RobotThreading):
    def post_init(self):
        # Perform custom setup after initialization
        pass

    def upload(self, filename: str):
        # Called after output saving (e.g. upload file to remote host)
        print(f"Playlist saved to: {filename}")

# Instantiate and run
robot = CustomRobot(forever=False, search=SearchEngine, output="output.m3u8")
robot.run()
```

## License

MIT License. Developed by Nikita Denissov ([ndenissov](https://github.com/ndenissov)).
