simplesyntax 0.1.0__tar.gz

simplesyntax-0.1.0/PKG-INFO

@@ -0,0 +1,870 @@
+Metadata-Version: 2.4
+Name: simplesyntax
+Version: 0.1.0
+Summary: Simple CSS-inspired Python media task library
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: yt-dlp
+Requires-Dist: gallery-dl
+
+# EasyTasks
+
+EasyTasks is a simple CSS-inspired Python media library built around:
+
+- yt-dlp
+- FFmpeg
+- gallery-dl
+
+Its main goal is to provide a simple API for downloading media and extracting metadata without requiring complicated downloader classes or configuration objects.
+
+## Installation
+
+```bash
+pip install easytasks
+
+EasyTasks uses:
+
+yt-dlp for video and supported metadata operations
+
+gallery-dl for images and galleries
+
+FFmpeg when media streams need to be merged
+
+
+
+---
+
+Main API
+
+The main API is:
+
+from easytasks import rz
+
+rz({...}, url)
+
+The value on the right side of every selector is a user-defined Python variable name.
+
+Example:
+
+from easytasks import rz
+
+rz({
+    "media[4]": "M"
+}, "https://example.com/media")
+
+print(M)
+
+Here:
+
+"media[4]" → M
+
+means the downloaded media is made available through the variable M.
+
+Another example:
+
+from easytasks import rz
+
+rz({
+    "media[4]": "V",
+    "title": "T",
+    "creator": "C"
+}, url)
+
+print(V)
+print(T)
+print(C)
+
+The user chooses the variable names.
+
+EasyTasks does not force names such as:
+
+video
+title
+creator
+views
+
+The right-side names can be different valid Python variable names.
+
+
+---
+
+Dictionary Order
+
+The order of selectors inside the dictionary does not matter.
+
+These are equivalent:
+
+rz({
+    "media[4]": "M",
+    "title": "T",
+    "creator": "C"
+}, url)
+
+and:
+
+rz({
+    "creator": "C",
+    "media[4]": "M",
+    "title": "T"
+}, url)
+
+EasyTasks identifies each operation from its selector.
+
+
+---
+
+Variable Assignment
+
+EasyTasks uses the right side of each selector as the variable name exposed to the caller.
+
+For example:
+
+rz({
+    "media[4]": "M"
+}, url)
+
+print(M)
+
+The selector:
+
+media[4]
+
+defines what EasyTasks should retrieve.
+
+The value:
+
+M
+
+defines the variable name that the user will use.
+
+Multiple values can be requested together:
+
+rz({
+    "media[4]": "VIDEO",
+    "title": "TITLE",
+    "creator": "AUTHOR",
+    "views": "VIEW_COUNT"
+}, url)
+
+print(VIDEO)
+print(TITLE)
+print(AUTHOR)
+print(VIEW_COUNT)
+
+No separate result dictionary is required for normal usage.
+
+
+---
+
+Video Selectors
+
+video[N] explicitly selects a video/yt-dlp operation.
+
+The quality mapping is fixed:
+
+Selector	Meaning
+
+video[0]	Best available audio
+video[1]	360p
+video[2]	480p
+video[3]	720p
+video[4]	1080p
+video[5]	1440p
+video[6]	Best available
+
+
+Example:
+
+from easytasks import rz
+
+rz({
+    "video[4]": "V"
+}, url)
+
+print(V)
+
+video without [N] is invalid.
+
+
+---
+
+Video Quality Fallback
+
+If the requested quality is unavailable, EasyTasks automatically tries the next lower available quality.
+
+For example:
+
+1080p
+  ↓
+720p
+  ↓
+480p
+  ↓
+360p
+
+The operation should not fail merely because the requested quality is unavailable.
+
+
+---
+
+Media Selectors
+
+media[N] automatically determines which media downloader should be used.
+
+media[N]
+   ↓
+detect media type
+   ├── VIDEO → yt-dlp
+   └── IMAGE → gallery-dl
+
+The quality mapping is:
+
+Selector	Meaning
+
+media[0]	Best available audio
+media[1]	360p
+media[2]	480p
+media[3]	720p
+media[4]	1080p
+media[5]	1440p
+media[6]	Best available
+
+
+Example:
+
+from easytasks import rz
+
+rz({
+    "media[4]": "M"
+}, "https://example.com/media")
+
+print(M)
+
+For a video, [N] controls the requested video quality.
+
+For an image, [N] does not resize or convert the image. gallery-dl downloads the original/available image quality.
+
+media[N] does not mean downloading both a video and an image.
+
+
+---
+
+Media Fallback
+
+media[N] uses automatic media detection.
+
+The video path is attempted through yt-dlp first.
+
+If the video operation fails, EasyTasks attempts the image/gallery operation through gallery-dl.
+
+media[N]
+   ↓
+yt-dlp
+   ↓
+success?
+ ├── YES → done
+ └── NO
+      ↓
+gallery-dl
+      ↓
+success?
+ ├── YES → done
+ └── NO → failure
+
+Cookie fallback is applied to both downloader types.
+
+
+---
+
+Image Selector
+
+For direct image operations, use:
+
+from easytasks import rz
+
+rz({
+    "image": "IMG"
+}, "https://example.com/image")
+
+print(IMG)
+
+The image selector uses gallery-dl directly.
+
+image[N] is invalid.
+
+
+---
+
+Metadata
+
+EasyTasks supports the following metadata selectors:
+
+Selector	Meaning
+
+title	Title
+creator	Creator/uploader/author
+url	Page/video URL
+views	View count
+likes	Like count
+comments	Comment count
+duration	Duration
+thumbnail	Thumbnail URL
+
+
+Example:
+
+from easytasks import rz
+
+rz({
+    "title": "T",
+    "creator": "C",
+    "url": "U",
+    "views": "V",
+    "likes": "L",
+    "comments": "CM",
+    "duration": "D",
+    "thumbnail": "TH"
+}, url)
+
+print(T)
+print(C)
+print(U)
+print(V)
+print(L)
+print(CM)
+print(D)
+print(TH)
+
+The right-side names are completely user-defined.
+
+
+---
+
+Media and Metadata Together
+
+Media and metadata can be requested in the same rz() call.
+
+from easytasks import rz
+
+rz({
+    "media[4]": "M",
+    "title": "T",
+    "creator": "C",
+    "url": "U",
+    "views": "V",
+    "likes": "L",
+    "comments": "CM",
+    "duration": "D",
+    "thumbnail": "TH"
+}, url)
+
+print(M)
+print(T)
+print(C)
+print(U)
+print(V)
+print(L)
+print(CM)
+print(D)
+print(TH)
+
+
+---
+
+Cookies
+
+EasyTasks uses the variable:
+
+ReiZyuki
+
+Example:
+
+ReiZyuki = [
+    "/storage/emulated/0/Download/youtube.txt",
+    "/storage/emulated/0/Download/instagram.txt",
+    "/storage/emulated/0/Download/reddit.txt"
+]
+
+The user does not pass cookies as an argument to rz().
+
+Correct:
+
+from easytasks import rz
+
+ReiZyuki = [
+    "/storage/emulated/0/Download/instagram.txt"
+]
+
+rz({
+    "image": "IMG"
+}, url)
+
+print(IMG)
+
+There is no need for:
+
+rz({...}, url, cookies=ReiZyuki)
+
+
+---
+
+Cookie Fallback
+
+EasyTasks always attempts the operation without cookies first.
+
+Request
+   ↓
+No-cookie attempt
+   ↓
+Success?
+ ┌───────┴───────┐
+ YES             NO
+ ↓                ↓
+DONE          ReiZyuki
+                  ↓
+             cookie #1
+                  ↓
+               works?
+              /     \
+            YES      NO
+             ↓       ↓
+           DONE   cookie #2
+                    ↓
+                  ...
+
+Rules:
+
+1. Try without cookies first.
+
+
+2. If successful, stop immediately.
+
+
+3. If it fails, use the supplied ReiZyuki paths.
+
+
+4. Test cookie files one-by-one.
+
+
+5. The first working cookie is selected.
+
+
+6. If all cookies fail, raise the original no-cookie error.
+
+
+
+This applies to:
+
+video downloads
+
+image downloads
+
+media operations
+
+playlists
+
+metadata extraction
+
+supported yt-dlp operations
+
+supported gallery-dl operations
+
+
+EasyTasks does not:
+
+scan random directories
+
+invent cookie files
+
+require specific cookie filenames
+
+automatically search for cookies
+
+hardcode website-specific cookie filenames
+
+
+Only paths supplied by the user through ReiZyuki are candidates.
+
+
+---
+
+Observer
+
+EasyTasks includes an Observer for ranking supplied cookie paths.
+
+Observer can consider:
+
+URL relevance
+
+cookie filename relevance
+
+previous successful cookie history
+
+
+The Observer score is a ranking/relevance score.
+
+It does not mean that a cookie is partially valid.
+
+A cookie must still be tested by the actual downloader.
+
+Example:
+
+[Observer]
+
+instagram.txt -> 78.85% match
+youtube.txt   -> 21.25% match
+reddit.txt    -> 20.00% match
+
+Selected order:
+
+1. instagram.txt
+2. youtube.txt
+3. reddit.txt
+
+The highest-ranked cookie is tested first.
+
+
+---
+
+Playlist
+
+Playlist syntax is fixed:
+
+from easytasks import rz
+
+rz({
+    "playlist": "QUALITY:SKIP:COUNT"
+}, playlist_url)
+
+The quality mapping is:
+
+Value	Meaning
+
+0	Best available audio
+1	360p
+2	480p
+3	720p
+4	1080p
+5	1440p
+6	Best available
+
+
+Example:
+
+rz({
+    "playlist": "4:5:10"
+}, playlist_url)
+
+This means:
+
+4  → 1080p
+5  → skip first 5 items
+10 → download next 10 items
+
+Therefore:
+
+Items 1–5   → skipped
+Items 6–15  → downloaded
+
+Quality fallback also applies to playlist downloads.
+
+
+---
+
+Playlist + Media + Metadata
+
+Playlist processing can be combined with media and metadata selectors.
+
+from easytasks import rz
+
+rz({
+    "playlist": "4:5:10",
+    "media[4]": "M",
+    "title": "T",
+    "creator": "C",
+    "url": "U",
+    "views": "V",
+    "likes": "L",
+    "comments": "CM",
+    "duration": "D",
+    "thumbnail": "TH"
+}, playlist_url)
+
+print(M)
+print(T)
+print(C)
+
+
+---
+
+FFmpeg
+
+FFmpeg is used when required to merge separate video and audio streams.
+
+EasyTasks avoids unnecessary re-encoding.
+
+When compatible source streams are available, the downloader prefers:
+
+H.264 / AVC video
+AAC / M4A audio
+
+and produces MP4 output when merging is required.
+
+The goal is to preserve source quality while producing compatible media.
+
+
+---
+
+yt-dlp
+
+yt-dlp handles video-based operations such as:
+
+video[N]
+
+video detection through media[N]
+
+playlist downloads
+
+supported metadata extraction
+
+
+
+---
+
+gallery-dl
+
+gallery-dl handles:
+
+image
+
+image/gallery detection through media[N]
+
+
+The user does not need to manually call gallery-dl when using media[N].
+
+
+---
+
+Default Download Directory
+
+Downloaded media is stored by default in:
+
+/storage/emulated/0/Download/ReiDownloader/
+
+
+---
+
+Complete Examples
+
+Video Download
+
+from easytasks import rz
+
+rz({
+    "video[4]": "V"
+}, "https://example.com/video")
+
+print(V)
+
+Audio
+
+from easytasks import rz
+
+rz({
+    "video[0]": "A"
+}, "https://example.com/video")
+
+print(A)
+
+Automatic Media
+
+from easytasks import rz
+
+rz({
+    "media[4]": "M"
+}, "https://example.com/media")
+
+print(M)
+
+Image
+
+from easytasks import rz
+
+rz({
+    "image": "IMG"
+}, "https://example.com/image")
+
+print(IMG)
+
+Metadata
+
+from easytasks import rz
+
+rz({
+    "title": "T",
+    "creator": "C",
+    "views": "V"
+}, url)
+
+print(T)
+print(C)
+print(V)
+
+Cookies
+
+from easytasks import rz
+
+ReiZyuki = [
+    "/storage/emulated/0/Download/instagram.txt"
+]
+
+rz({
+    "image": "IMG"
+}, "https://www.instagram.com/example/")
+
+print(IMG)
+
+Playlist
+
+from easytasks import rz
+
+rz({
+    "playlist": "4:5:10"
+}, "https://example.com/playlist")
+
+
+---
+
+Invalid Syntax
+
+Invalid Video Selector
+
+This is invalid:
+
+rz({
+    "video": "V"
+}, url)
+
+Use a quality selector:
+
+rz({
+    "video[4]": "V"
+}, url)
+
+
+---
+
+Invalid Image Quality Selector
+
+This is invalid:
+
+rz({
+    "image[4]": "IMG"
+}, url)
+
+Use:
+
+rz({
+    "image": "IMG"
+}, url)
+
+
+---
+
+Invalid Quality
+
+Quality values outside 0–6 are invalid.
+
+For example:
+
+rz({
+    "video[10]": "V"
+}, url)
+
+is invalid.
+
+
+---
+
+Invalid Playlist Format
+
+This is invalid:
+
+rz({
+    "playlist": "1080p:5:10"
+}, url)
+
+Use the numeric quality format:
+
+rz({
+    "playlist": "4:5:10"
+}, url)
+
+
+---
+
+Quick Reference
+
+Main API
+
+from easytasks import rz
+
+rz({...}, url)
+
+Video
+
+video[0] → audio
+video[1] → 360p
+video[2] → 480p
+video[3] → 720p
+video[4] → 1080p
+video[5] → 1440p
+video[6] → best
+
+Media
+
+media[0] → audio
+media[1] → 360p
+media[2] → 480p
+media[3] → 720p
+media[4] → 1080p
+media[5] → 1440p
+media[6] → best
+
+Image
+
+image
+
+Metadata
+
+title
+creator
+url
+views
+likes
+comments
+duration
+thumbnail
+
+Playlist
+
+playlist = "QUALITY:SKIP:COUNT"
+
+Cookies
+
+ReiZyuki = [...]
+
+Default Directory
+
+/storage/emulated/0/Download/ReiDownloader/
+
+
+---
+
+Public API Principle
+
+EasyTasks is designed around a small CSS-inspired API:
+
+rz({...}, url)
+
+Selectors describe what EasyTasks should do, while the right-side values define the variable names through which the requested values are made available to the caller.