Metadata-Version: 2.4
Name: simplesyntax
Version: 0.1.4
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.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

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.

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