Metadata-Version: 2.4
Name: simplesyntax
Version: 0.1.5
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 media tasks with:

- 🎯 CSS-inspired selectors
- 🍪 Automatic cookie matching and fallback
- 📥 Video and media downloading
- 🖼️ Image fallback through `gallery-dl`
- 🧾 Metadata extraction
- 📋 Playlist downloading
- 🔄 Successful URL/cookie history
- 🐍 A simple Python API through `rz()`

## Current Version

**0.1.5**

## What's Fixed / Improved in 0.1.5

- Fixed caller-scope variable assignment so values returned by `rz()` are available directly in the user's Python scope.
- Fixed playlist request validation so `QUALITY:SKIP:COUNT` values such as `"0:0:150"` are correctly recognized as playlist configuration instead of being incorrectly validated as Python variable names.
- Fixed playlist downloads using the existing `QUALITY:SKIP:COUNT` syntax and verified playlist requests can reach the downloader correctly.
- Fixed metadata handling so extraction errors are printed as safe error messages instead of crashing the program with an unhandled exception.
- Improved metadata failure handling so a failed metadata extraction returns safely without breaking a successful media fallback operation.
- 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.

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

SimpleSyntax uses a single entry point, `rz`, with 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 cannot download the media.

### Quality Index

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

Example:

```python
rz({"media[3]": "downloaded_media"}, url)
print(downloaded_media)
```

### Metadata Selectors

The following metadata selectors are supported:

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

Example:

```python
rz({
    "title": "title",
    "creator": "creator",
    "views": "views"
}, url)

print(title)
print(creator)
print(views)
```

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

## Cookie File Naming

For reliable cookie matching, keep each cookie filename based on the target website's domain name. SimpleSyntax compares the target URL hostname with the cookie filename using similarity matching.

Recommended examples:

```text
https://www.youtube.com/...      → youtube.txt
https://www.instagram.com/...    → instagram.txt
https://www.reddit.com/...       → reddit.txt
https://www.tiktok.com/...       → tiktok.txt
```

Avoid unrelated or generic names such as `cookies.txt`, `mycookie.txt`, `login.txt`, or `account1.txt` when possible.

For best results, use the website/domain name as the filename followed by `.txt`.

## Media Fallback

`media[N]` is designed for URLs where the normal video downloader may not be able to retrieve a video.

The flow is:

```text
media[N]
   │
   ├── Try video download (yt-dlp)
   │
   └── If video download fails
           │
           └── Try image download (gallery-dl)
```

This means a platform response such as **"No video formats found"** from yt-dlp does not necessarily mean the overall `media[N]` operation cannot succeed. If `gallery-dl` can retrieve an image, the media fallback can still complete successfully.

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

## Project & Creator

**Project:** SimpleSyntax  
**Creator / YouTube:** **ReiZyuki**

SimpleSyntax is developed under the **ReiZyuki** name.

## Bug Reports & Help

If you find a bug, need help using SimpleSyntax, or have a problem with a selector or downloader, contact:

**Email:** `Azadofficial2026@gmail.com`

When reporting an issue, it helps to include:

- Python version
- SimpleSyntax version
- Platform/URL type
- The selector you used
- The relevant error or terminal output

Please avoid sharing private cookie contents in bug reports.

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

Cookie files are user-supplied and should be kept private. Never publish or share your cookie file contents.

---

**Author / YouTube:** ReiZyuki  
**Contact:** Azadofficial2026@gmail.com  
**SimpleSyntax 0.1.5**
