cli-web-pexels 0.1.0__tar.gz

cli_web_pexels-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: cli-web-pexels
+Version: 0.1.0
+Summary: CLI for Pexels free stock photos and videos
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: curl_cffi>=0.5
+Requires-Dist: prompt_toolkit>=3.0
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

cli_web_pexels-0.1.0/cli_web/pexels/README.md

@@ -0,0 +1,83 @@
+# cli-web-pexels
+
+CLI for [Pexels](https://www.pexels.com/) — free stock photos and videos from the command line.
+
+## Installation
+
+```bash
+cd pexels/agent-harness
+pip install -e .
+```
+
+## Usage
+
+### Search Photos
+
+```bash
+cli-web-pexels photos search "nature"
+cli-web-pexels photos search "sunset" --orientation landscape --size large --json
+```
+
+### Get Photo Details
+
+```bash
+cli-web-pexels photos get green-leaves-1072179
+cli-web-pexels photos get green-leaves-1072179 --json
+```
+
+### Download Photos
+
+```bash
+cli-web-pexels photos download green-leaves-1072179
+cli-web-pexels photos download green-leaves-1072179 --size large --output photo.jpg
+```
+
+### Search Videos
+
+```bash
+cli-web-pexels videos search "ocean"
+cli-web-pexels videos search "nature" --orientation landscape --json
+```
+
+### Download Videos
+
+```bash
+cli-web-pexels videos download long-narrow-road-856479 --quality hd
+```
+
+### User Profiles
+
+```bash
+cli-web-pexels users get pixabay
+cli-web-pexels users media pixabay --json
+```
+
+### Collections
+
+```bash
+cli-web-pexels collections discover
+cli-web-pexels collections get spring-aesthetic-fvku5ng --json
+```
+
+### REPL Mode
+
+```bash
+cli-web-pexels        # enters interactive REPL
+cli-web-pexels --json # REPL with JSON output
+```
+
+## Search Filters
+
+| Filter | Options | Example |
+|--------|---------|---------|
+| `--orientation` | landscape, portrait, square | `--orientation landscape` |
+| `--size` | large, medium, small | `--size large` |
+| `--color` | hex or named color | `--color orange` |
+| `--page` | page number (1-based) | `--page 2` |
+
+## Running Tests
+
+```bash
+cd pexels/agent-harness
+python -m pytest cli_web/pexels/tests/ -v
+```

cli_web_pexels-0.1.0/cli_web/pexels/__init__.py

@@ -0,0 +1,3 @@
+"""cli-web-pexels — CLI for Pexels free stock photos and videos."""
+
+__version__ = "0.1.0"

cli_web_pexels-0.1.0/cli_web/pexels/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m cli_web.pexels."""
+
+from cli_web.pexels.pexels_cli import main
+
+if __name__ == "__main__":
+    main()

cli_web_pexels-0.1.0/cli_web/pexels/commands/collections.py

@@ -0,0 +1,63 @@
+"""Collections commands for cli-web-pexels."""
+
+import click
+
+from ..core.client import PexelsClient
+from ..utils.helpers import handle_errors
+from ..utils.output import (
+    print_collection_detail,
+    print_collections_table,
+    print_json,
+    print_pagination,
+    print_photos_table,
+)
+
+
+@click.group("collections")
+@click.pass_context
+def collections(ctx):
+    """Browse and explore Pexels collections."""
+    pass
+
+
+@collections.command()
+@click.argument("slug")
+@click.option("--page", type=int, default=1, help="Page number.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def get(ctx, slug, page, json_mode):
+    """Get collection detail and media by slug."""
+    json_mode = json_mode or ctx.obj.get("json", False)
+    with handle_errors(json_mode):
+        client = PexelsClient()
+        result = client.get_collection(slug, page=page)
+        if json_mode:
+            print_json(result)
+        else:
+            print_collection_detail(result["collection"])
+            media = result.get("media", {})
+            if media.get("data"):
+                print_photos_table(media["data"])
+                print_pagination(media.get("pagination", {}))
+
+
+@collections.command()
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def discover(ctx, json_mode):
+    """Show popular and curated collections from the discover page."""
+    json_mode = json_mode or ctx.obj.get("json", False)
+    with handle_errors(json_mode):
+        client = PexelsClient()
+        result = client.discover()
+        if json_mode:
+            print_json(result)
+        else:
+            if result.get("popular"):
+                click.echo("\n  Popular Collections")
+                click.echo(f"  {'─' * 40}")
+                print_collections_table(result["popular"])
+            if result.get("collections"):
+                click.echo("\n  Curated Collections")
+                click.echo(f"  {'─' * 40}")
+                print_collections_table(result["collections"])

cli_web_pexels-0.1.0/cli_web/pexels/commands/photos.py

@@ -0,0 +1,116 @@
+"""Photos commands for cli-web-pexels."""
+
+import os
+
+import click
+
+from ..core.client import PexelsClient
+from ..core.exceptions import NotFoundError
+from ..utils.helpers import handle_errors, sanitize_filename
+from ..utils.output import (
+    print_json,
+    print_pagination,
+    print_photo_detail,
+    print_photos_table,
+)
+
+
+@click.group("photos")
+@click.pass_context
+def photos(ctx):
+    """Browse and download Pexels photos."""
+    pass
+
+
+@photos.command()
+@click.argument("query")
+@click.option(
+    "--orientation",
+    type=click.Choice(["landscape", "portrait", "square"]),
+    default=None,
+    help="Filter by orientation.",
+)
+@click.option(
+    "--size",
+    type=click.Choice(["large", "medium", "small"]),
+    default=None,
+    help="Filter by minimum size.",
+)
+@click.option("--color", default=None, help="Filter by color (hex or named color).")
+@click.option("--page", type=int, default=1, help="Page number.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def search(ctx, query, orientation, size, color, page, json_mode):
+    """Search photos by keyword."""
+    json_mode = json_mode or ctx.obj.get("json", False)
+    with handle_errors(json_mode):
+        client = PexelsClient()
+        result = client.search_photos(
+            query=query,
+            orientation=orientation,
+            size=size,
+            color=color,
+            page=page,
+        )
+        if json_mode:
+            print_json(result)
+        else:
+            print_photos_table(result["data"])
+            print_pagination(result.get("pagination", {}))
+
+
+@photos.command()
+@click.argument("slug")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def get(ctx, slug, json_mode):
+    """Get photo details by slug or ID."""
+    json_mode = json_mode or ctx.obj.get("json", False)
+    with handle_errors(json_mode):
+        client = PexelsClient()
+        photo = client.get_photo(slug)
+        if json_mode:
+            print_json(photo)
+        else:
+            print_photo_detail(photo)
+
+
+@photos.command()
+@click.argument("slug")
+@click.option("--output", "-o", default=None, help="Output file path.")
+@click.option(
+    "--size",
+    type=click.Choice(["small", "medium", "large", "original"]),
+    default="original",
+    help="Download size.",
+)
+@click.pass_context
+def download(ctx, slug, output, size):
+    """Download a photo by slug or ID."""
+    json_mode = ctx.obj.get("json", False)
+    with handle_errors(json_mode):
+        client = PexelsClient()
+        photo = client.get_photo(slug)
+
+        image = photo.get("image", {})
+        size_map = {
+            "original": "download",
+            "large": "large",
+            "medium": "medium",
+            "small": "small",
+        }
+        url = image.get(size_map[size]) or image.get("download") or image.get("large")
+        if not url:
+            raise NotFoundError("No download URL available")
+
+        if output is None:
+            title = photo.get("title") or photo.get("alt") or "photo"
+            ext = os.path.splitext(url.split("?")[0])[1] or ".jpeg"
+            output = sanitize_filename(title) + ext
+
+        client.download_file(url, output)
+
+        if json_mode:
+            print_json({"downloaded": True, "path": output, "size": size})
+        else:
+            click.echo(f"Downloaded: {output}")

cli_web_pexels-0.1.0/cli_web/pexels/commands/users.py

@@ -0,0 +1,62 @@
+"""Users commands for cli-web-pexels."""
+
+import click
+
+from ..core.client import PexelsClient
+from ..utils.helpers import handle_errors
+from ..utils.output import print_json, print_pagination, print_user_detail
+
+
+@click.group("users")
+@click.pass_context
+def users(ctx):
+    """Browse user profiles and their media."""
+    pass
+
+
+@users.command("get")
+@click.argument("username")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def get(ctx, username, json_mode):
+    """Get a user's profile information."""
+    json_mode = json_mode or ctx.obj.get("json", False)
+    with handle_errors(json_mode):
+        client = PexelsClient()
+        result = client.get_user(username)
+        if json_mode:
+            print_json(result)
+        else:
+            print_user_detail(result["user"])
+
+
+@users.command("media")
+@click.argument("username")
+@click.option("--page", type=int, default=1, help="Page number.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def media(ctx, username, page, json_mode):
+    """List a user's uploaded photos and videos."""
+    json_mode = json_mode or ctx.obj.get("json", False)
+    with handle_errors(json_mode):
+        client = PexelsClient()
+        result = client.get_user_media(username, page=page)
+        if json_mode:
+            print_json(result)
+        else:
+            items = result.get("data", [])
+            if not items:
+                click.echo(f"  No media found for @{username}.")
+                return
+
+            click.echo(f"\n  Media by @{username}")
+            click.echo(f"  {'ID':<12} {'Type':<8} {'Title':<35} {'Size':<12}")
+            click.echo(f"  {'─' * 12} {'─' * 8} {'─' * 35} {'─' * 12}")
+            for item in items:
+                title = (item.get("title") or "Untitled")[:34]
+                size = f"{item.get('width', '?')}x{item.get('height', '?')}"
+                click.echo(
+                    f"  {item.get('id', ''):<12} {item.get('type', 'photo'):<8} "
+                    f"{title:<35} {size:<12}"
+                )
+            print_pagination(result.get("pagination", {}))

cli_web_pexels-0.1.0/cli_web/pexels/commands/videos.py

@@ -0,0 +1,162 @@
+"""Video commands for cli-web-pexels."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ..core.client import PexelsClient
+from ..core.exceptions import NotFoundError
+from ..utils.helpers import handle_errors, sanitize_filename
+from ..utils.output import print_json, print_pagination, print_video_detail, print_videos_table
+
+QUALITY_ORDER = {"sd": 0, "hd": 1, "uhd": 2}
+
+
+@click.group("videos")
+def videos():
+    """Search, view, and download videos."""
+
+
+@videos.command("search")
+@click.argument("query")
+@click.option(
+    "--orientation",
+    type=click.Choice(["landscape", "portrait", "square"]),
+    help="Filter by orientation.",
+)
+@click.option("--page", type=int, default=1, help="Page number.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def search(ctx, query, orientation, page, json_mode):
+    """Search videos by keyword."""
+    json_mode = json_mode or ctx.obj.get("json", False)
+    with handle_errors(json_mode):
+        client = PexelsClient()
+        result = client.search_videos(query, page=page, orientation=orientation)
+        videos_list = result.get("data", [])
+        pagination = result.get("pagination", {})
+
+        if json_mode:
+            print_json(
+                {
+                    "query": query,
+                    "page": page,
+                    "total_results": pagination.get("total_results", 0),
+                    "total_pages": pagination.get("total_pages", 0),
+                    "results": videos_list,
+                }
+            )
+        else:
+            total = pagination.get("total_results", 0)
+            click.echo(f"\n  Found {total:,} videos for '{query}'")
+            print_videos_table(videos_list)
+            print_pagination(pagination)
+
+
+@videos.command("get")
+@click.argument("slug")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def get(ctx, slug, json_mode):
+    """Get video details by slug or ID (e.g., 'long-narrow-road-856479' or '856479')."""
+    json_mode = json_mode or ctx.obj.get("json", False)
+    with handle_errors(json_mode):
+        client = PexelsClient()
+        video = client.get_video(slug)
+
+        if json_mode:
+            print_json(video)
+        else:
+            print_video_detail(video)
+
+
+@videos.command("download")
+@click.argument("slug")
+@click.option(
+    "--quality",
+    type=click.Choice(["sd", "hd", "uhd"]),
+    default="hd",
+    help="Video quality (default: hd).",
+)
+@click.option("--output", "-o", type=click.Path(), help="Output file path.")
+@click.pass_context
+def download(ctx, slug, quality, output):
+    """Download a video by slug or ID."""
+    json_mode = ctx.obj.get("json", False)
+    with handle_errors(json_mode):
+        client = PexelsClient()
+        video = client.get_video(slug)
+
+        video_files = video.get("video_files", [])
+        if not video_files:
+            raise NotFoundError(f"No video files available for '{slug}'")
+
+        # Find best matching file by quality
+        best = _select_video_file(video_files, quality)
+        if not best:
+            raise NotFoundError(f"No downloadable video file found for '{slug}'")
+
+        download_url = best.get("link")
+        if not download_url:
+            raise NotFoundError(f"No download link for selected quality ({best.get('quality')})")
+
+        # Determine output filename
+        if not output:
+            title = video.get("title") or slug
+            safe_name = sanitize_filename(title)
+            output = f"{safe_name}.mp4"
+
+        out_path = Path(output)
+        client.download_file(download_url, str(out_path))
+
+        file_size = out_path.stat().st_size
+        if json_mode:
+            print_json(
+                {
+                    "video_id": video.get("id"),
+                    "slug": slug,
+                    "quality": best.get("quality"),
+                    "resolution": f"{best.get('width')}x{best.get('height')}",
+                    "file": str(out_path),
+                    "bytes": file_size,
+                }
+            )
+        else:
+            click.echo(f"  Downloaded: {out_path} ({file_size:,} bytes)")
+            click.echo(
+                f"  Quality: {best.get('quality')} "
+                f"({best.get('width')}x{best.get('height')}, "
+                f"{best.get('fps', '?')}fps)"
+            )
+            click.echo(f"  Video: {video.get('title') or slug}")
+
+
+def _select_video_file(video_files: list[dict], target_quality: str) -> dict | None:
+    """Select the best video file matching the requested quality.
+
+    Picks the highest-resolution file at the target quality level.
+    Falls back to the closest available quality if no exact match.
+    """
+    target_rank = QUALITY_ORDER.get(target_quality, 1)
+
+    # Filter exact matches and pick highest resolution
+    exact = [f for f in video_files if f.get("quality") == target_quality]
+    if exact:
+        return max(exact, key=lambda f: f.get("width", 0) * f.get("height", 0))
+
+    # No exact match — find closest quality
+    # Sort candidates by distance to target rank, then by resolution descending
+    candidates = [f for f in video_files if f.get("link")]
+    if not candidates:
+        return None
+
+    def sort_key(f):
+        f_rank = QUALITY_ORDER.get(f.get("quality", ""), 1)
+        distance = abs(f_rank - target_rank)
+        resolution = f.get("width", 0) * f.get("height", 0)
+        return (distance, -resolution)
+
+    candidates.sort(key=sort_key)
+    return candidates[0]