Metadata-Version: 2.4
Name: simplesyntax
Version: 0.1.2
Summary: Simple CSS-inspired Python media task library
Author: ReiZyuki
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: yt-dlp
Requires-Dist: gallery-dl

# SimpleSyntax

SimpleSyntax is a lightweight, CSS-selector-inspired Python library for downloading media and extracting metadata from various platforms. It provides a clean, declarative API for handling complex downloading tasks, including automatic fallback mechanisms, cookie management, and metadata extraction.

## Requirements
- Python >= 3.9
- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
- [gallery-dl](https://github.com/mikf/gallery-dl)
- `ffmpeg` (required for merging audio/video streams)

## Installation
SimpleSyntax is designed to be used as a drop-in library. Ensure you have the required dependencies installed:

```bash
pip install yt-dlp gallery-dl
```

## Basic Usage

The library provides a single entry point, `rz`, which allows you to define the operations you want to perform using a selector-based syntax.

```python
from SimpleSyntax import rz

url = "https://example.com/video"

# Perform operations and bind results to variables in your current scope
rz({
    "video[3]": "my_video",
    "title": "video_title"
}, url)

print(f"Downloaded: {my_video}")
print(f"Title: {video_title}")
```

## Selector Syntax

SimpleSyntax uses a CSS-inspired selector syntax to define tasks.

### Media Selectors
Media selectors support a quality index from `0` to `6`:
- `video[N]`: Downloads video content.
- `media[N]`: Attempts to download as video; falls back to image downloading if the video engine fails.

**Quality Index (`N`):**
- `0`: Audio only
- `1`: 360p
- `2`: 480p
- `3`: 720p
- `4`: 1080p
- `5`: 1440p
- `6`: Best quality

### Metadata Selectors
Extract information without downloading the media:
- `title`
- `creator`
- `url`
- `views` (formatted)
- `likes` (formatted)
- `comments` (formatted)
- `duration` (formatted)
- `thumbnail`
- `date` (YYYY/MM/DD)
- `live` (True/False)

## Fallback & Cookie Management

SimpleSyntax includes a resilient fallback system:
1. **No-Cookie Attempt:** Every operation is first attempted without cookies.
2. **Ranked Cookie Fallback:** If the first attempt fails, SimpleSyntax ranks user-supplied cookie files by calculating the similarity between the target URL and the cookie filename (using host/path matching).
3. **Automatic Retry:** It sequentially retries the operation using the ranked cookies, stopping at the first successful attempt.
4. **History:** Successful cookie-URL associations are cached to improve future ranking.

To enable cookie support, define a `ReiZyuki` list/tuple in your caller's scope containing paths to your cookie files:
```python
ReiZyuki = ["/path/to/cookies.txt"]
```

## Playlist Handling
SimpleSyntax supports downloading segments of playlists.
*Note: Usage requires providing a string value in the format `QUALITY:SKIP:COUNT`.*
- `rz({"playlist": "3:0:5"}, url)` - Download 5 videos starting from index 0, in 720p quality.

---
*Author: ReiZyuki*
