Metadata-Version: 2.4
Name: simplesyntax
Version: 0.1.3
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 media tasks with automatic cookie fallback, metadata extraction, playlist handling, and image fallback support.

## Current Version

**0.1.3**

## What's Fixed / Improved in 0.1.3

- Fixed caller-scope variable assignment so values returned by `rz()` are available directly in the user's Python scope.
- Improved cookie fallback handling with cookie ranking based on the target site's hostname and cookie filename.
- Added a 40% cookie-match threshold so unrelated cookie files are skipped.
- Added ordered cookie fallback attempts for matching cookie files.
- Added successful URL/cookie history support through the helper file.
- Preserved the `ReiZyuki` cookie-list API for user-supplied cookie files.
- Improved media fallback flow between video downloading and image downloading.
- Kept the CSS-inspired selector API and existing `rz({...}, url)` syntax unchanged.
- Metadata selectors continue to support title, creator, URL, views, likes, comments, duration, thumbnail, date, and live status.
- Playlist selector support remains available through `QUALITY:SKIP:COUNT` syntax.

## 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

```bash
pip install simplesyntax
```

The package installs its Python dependencies automatically. `ffmpeg` should be available separately when media merging is required.

## Basic Usage

The library provides a single entry point, `rz`, using a CSS-inspired selector syntax.

```python
from simplesyntax import rz

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

rz({
    "video[3]": "my_video",
    "title": "video_title"
}, url)

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

## Selector Syntax

### Media Selectors

Media selectors support a quality index from `0` to `6`:

- `video[N]`: Downloads video/audio media.
- `media[N]`: Attempts video downloading first and 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

The following metadata selectors are supported:

- `title`
- `creator`
- `url`
- `views`
- `likes`
- `comments`
- `duration`
- `thumbnail`
- `date` (YYYY/MM/DD)
- `live`

## Cookie & Fallback System

SimpleSyntax supports optional cookie files through a variable named `ReiZyuki` in the caller's scope:

```python
ReiZyuki = [
    "/path/to/youtube.txt",
    "/path/to/instagram.txt",
    "/path/to/reddit.txt"
]
```

The fallback system:

1. Matches the target site's hostname against supplied cookie filenames.
2. Calculates a cookie match score.
3. Skips cookies below the **40% match threshold**.
4. Tries the best matching cookie first.
5. Falls back to a no-cookie attempt when the matching cookie fails.
6. Continues with the next matching cookie when necessary.
7. Records successful URL/cookie associations in the helper history file.

No cookie files are scanned automatically; only paths supplied through `ReiZyuki` are used.

## Playlist Handling

Playlist downloads use the existing `QUALITY:SKIP:COUNT` syntax:

```python
rz({"playlist": "3:0:5"}, url)
```

This downloads 5 items starting from index 0 using quality index 3 (720p).

## Notes

Some platforms may still require valid cookies or may restrict automated access. A platform-side HTTP/API restriction does not necessarily indicate a SimpleSyntax selector or fallback error.

---

*Author: ReiZyuki*  
*SimpleSyntax 0.1.3*
