pasteup 0.1.0__py3-none-any.whl

pasteup/__init__.py

@@ -0,0 +1,3 @@
+"""Pasteup: turn a folder of clip art into listing images."""
+
+__version__ = "0.1.0"

pasteup/__main__.py

@@ -0,0 +1,4 @@
+from pasteup.cli import main
+
+if __name__ == "__main__":
+    main()

pasteup/cli.py

@@ -0,0 +1,171 @@
+"""The `pasteup` command: start the app and open it in the browser."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import socket
+import sys
+import threading
+import time
+import urllib.request
+import webbrowser
+
+from pasteup import __version__
+
+LOCAL_HOSTS = ("127.0.0.1", "localhost", "::1")
+WILDCARD_HOSTS = {"0.0.0.0": "127.0.0.1", "::": "::1"}
+DEFAULT_PORT = 8000
+# Ports tried after the default when another program holds it.
+FALLBACK_PORTS = 10
+BROWSER_WAIT_SECONDS = 20
+
+# Asking the local server must not go through a proxy set in the environment.
+_local_opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="pasteup",
+        description="Turn a folder of clip art into listing images. Starts the app and opens it in your browser.",
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="address to listen on (default: 127.0.0.1)")
+    parser.add_argument(
+        "--port", type=_port_number, help=f"port to listen on (default: {DEFAULT_PORT}, or the next free one)"
+    )
+    parser.add_argument("--no-browser", action="store_true", help="don't open the app in a browser")
+    parser.add_argument(
+        "--shortcut", action="store_true", help="put a Pasteup launcher on your desktop, then exit"
+    )
+    parser.add_argument("--reload", action="store_true", help="restart on code changes, for development")
+    parser.add_argument("--version", action="version", version=f"pasteup {__version__}")
+    args = parser.parse_args(argv)
+
+    if args.shortcut:
+        from pasteup.shortcut import create_shortcut
+
+        print(create_shortcut())
+        return
+
+    if args.host not in LOCAL_HOSTS:
+        print(
+            f"Warning: listening on {args.host} lets other machines reach an app that reads and "
+            "writes your files, with no login. See SECURITY.md before doing this.",
+            file=sys.stderr,
+        )
+
+    visit_host = WILDCARD_HOSTS.get(args.host, args.host)
+    open_browser = not args.no_browser and _can_open_browser(visit_host)
+    port, state = _choose_port(visit_host, args.port)
+    url = _base_url(visit_host, port)
+
+    if state == "pasteup":
+        print(f"Pasteup is already running at {url}")
+        if open_browser:
+            webbrowser.open(url)
+        return
+
+    if port != (args.port or DEFAULT_PORT):
+        print(f"Port {DEFAULT_PORT} is taken by another program, so Pasteup is using {port}.")
+    print(f"Pasteup is running at {url}")
+    if open_browser:
+        print("Opening it in your browser...")
+        _open_when_ready(url)
+    else:
+        print("Open that address in your browser.")
+    print("Keep this window open while you use Pasteup; press Ctrl+C to stop it.")
+    if shutil.which("ffmpeg") is None:
+        print(
+            "Note: preview videos need ffmpeg (https://ffmpeg.org), which isn't installed. "
+            "Everything else works."
+        )
+    sys.stdout.flush()
+
+    # Imported here so `pasteup --help` and `--version` stay instant.
+    import uvicorn
+
+    uvicorn.run(
+        "pasteup.main:app",
+        host=args.host,
+        port=port,
+        reload=args.reload,
+        # Errors only, unless developing: request logs mean nothing to a user.
+        log_level="info" if args.reload else "warning",
+    )
+    print("Pasteup has stopped.")
+
+
+def _port_number(value: str) -> int:
+    port = int(value)
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError("must be between 1 and 65535")
+    return port
+
+
+def _choose_port(host: str, requested_port: int | None) -> tuple[int, str]:
+    """Return the port to use, and "pasteup" when Pasteup already runs there."""
+    if requested_port is not None:
+        state = _probe(host, requested_port)
+        if state == "busy":
+            sys.exit(f"Port {requested_port} is in use by another program. Choose a different one with --port.")
+        return requested_port, state
+
+    for port in range(DEFAULT_PORT, DEFAULT_PORT + FALLBACK_PORTS + 1):
+        state = _probe(host, port)
+        if state != "busy":
+            return port, state
+    sys.exit(
+        f"Ports {DEFAULT_PORT} to {DEFAULT_PORT + FALLBACK_PORTS} are all in use by other programs. "
+        "Choose a free one with --port."
+    )
+
+
+def _probe(host: str, port: int) -> str:
+    """Say whether a port is "free", has Pasteup on it ("pasteup") or another program ("busy")."""
+    try:
+        with socket.create_connection((host, port), timeout=0.5):
+            pass
+    except OSError:
+        return "free"
+    return "pasteup" if _answers_as_pasteup(_base_url(host, port)) else "busy"
+
+
+def _answers_as_pasteup(url: str) -> bool:
+    try:
+        with _local_opener.open(f"{url}api/jobs/health", timeout=2) as response:
+            return json.load(response).get("app") == "pasteup"
+    except (OSError, ValueError, AttributeError):
+        return False
+
+
+def _open_when_ready(url: str) -> None:
+    """Open the browser once the server answers, without holding up its start."""
+    threading.Thread(target=_wait_then_open, args=(url,), daemon=True).start()
+
+
+def _wait_then_open(url: str, timeout: float = BROWSER_WAIT_SECONDS) -> None:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if _answers_as_pasteup(url):
+            webbrowser.open(url)
+            return
+        time.sleep(0.25)
+
+
+def _can_open_browser(host: str) -> bool:
+    # A browser on this machine can reach only a server listening on it.
+    if host not in LOCAL_HOSTS:
+        return False
+    if os.environ.get("BROWSER"):
+        return True
+    # Without a display, Python falls back to text browsers such as lynx, which
+    # would take over this terminal.
+    if sys.platform.startswith(("linux", "freebsd", "openbsd", "netbsd")):
+        return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+    return True
+
+
+def _base_url(host: str, port: int) -> str:
+    return f"http://[{host}]:{port}/" if ":" in host else f"http://{host}:{port}/"

pasteup/main.py

@@ -0,0 +1,34 @@
+import os
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.trustedhost import TrustedHostMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from pasteup import __version__
+from pasteup.routes.jobs import router as jobs_router
+from pasteup.routes.ui import router as ui_router
+
+APP_DIR = Path(__file__).resolve().parent
+
+# The app reads and writes local paths and has no authentication, so it answers
+# only requests addressed to this machine. Checking Host stops a web page whose
+# domain has been re-pointed at 127.0.0.1 (DNS rebinding) from driving the app
+# through the user's browser. Extra names, comma-separated, are for serving the
+# app deliberately under another host.
+ALLOWED_HOSTS_ENV_VAR = "PASTEUP_ALLOWED_HOSTS"
+DEFAULT_ALLOWED_HOSTS = ("localhost", "127.0.0.1", "[::1]")
+
+
+def allowed_hosts() -> list[str]:
+    extra_hosts = os.environ.get(ALLOWED_HOSTS_ENV_VAR, "").split(",")
+    return [*DEFAULT_ALLOWED_HOSTS, *(host.strip() for host in extra_hosts if host.strip())]
+
+
+app = FastAPI(title="Pasteup", version=__version__)
+
+app.add_middleware(TrustedHostMiddleware, allowed_hosts=allowed_hosts())
+app.mount("/static", StaticFiles(directory=APP_DIR / "static"), name="static")
+
+app.include_router(ui_router)
+app.include_router(jobs_router, prefix="/api")

pasteup/models/schemas.py

@@ -0,0 +1,410 @@
+from pathlib import Path
+from typing import Literal
+
+from mullion import DEFAULT_TOLERANCE, BackgroundCleanMode
+from pasteup.services.cover_collage import CoverCollageFittingMode, CoverCollageTemplate
+from mullion import DEFAULT_DPI
+
+from pydantic import AliasChoices, BaseModel, Field, field_validator
+
+# The preview is encoded at a real frame rate, so its length sets the encoding
+# work. Two minutes is well past any listing site's limit (Etsy's is 15 s).
+MAX_VIDEO_DURATION_SECONDS = 120
+
+
+def _normalize_optional_string_list(value: object, *, field_name: str) -> list[str] | None:
+    if value is None:
+        return None
+    if not isinstance(value, list):
+        raise ValueError(f"{field_name} must be a list of strings.")
+
+    normalized_values: list[str] = []
+    seen_values: set[str] = set()
+    for item in value:
+        if not isinstance(item, str):
+            raise ValueError(f"{field_name} must contain only strings.")
+        normalized_item = item.strip()
+        if not normalized_item or normalized_item in seen_values:
+            continue
+        seen_values.add(normalized_item)
+        normalized_values.append(normalized_item)
+
+    return normalized_values
+
+
+def _validate_video_filename(value: str) -> str:
+    """Keep the preview video inside the output folder.
+
+    The name is joined onto the output folder and ffmpeg overwrites whatever is
+    already there, so a path in it would let a request replace any file the user
+    can write — ``/Users/me/notes.txt`` or ``../../anything.mp4`` alike.
+    """
+    name = value.strip()
+    if name in {"", ".", ".."} or "\\" in name or Path(name).name != name:
+        raise ValueError("video_filename must be a plain file name, without folders.")
+    if Path(name).suffix.lower() != ".mp4":
+        raise ValueError("video_filename must end in .mp4.")
+    return name
+
+
+class OutputQualityOptions(BaseModel):
+    """Print-resolution and background-cleaning options.
+
+    Shared by every request that produces a page, so the four builders cannot
+    drift into supporting different subsets of the same feature.
+    """
+
+    dpi: int = Field(
+        default=DEFAULT_DPI,
+        gt=0,
+        le=1200,
+        description=(
+            "Resolution stamped into exported files. Without it a 3000x4000 page "
+            "reads as 41.7x55.6in at the 72 DPI default rather than 10x13.3in."
+        ),
+    )
+    page_unit: Literal["px", "in", "mm"] = Field(
+        default="px",
+        description="Unit for page_width/page_height. Converted to pixels at dpi.",
+    )
+    background_clean_mode: BackgroundCleanMode = Field(
+        default=BackgroundCleanMode.OFF,
+        description=(
+            "'flatten' turns an edge-connected near-white background pure white; "
+            "'transparent' makes it transparent; 'off' leaves images untouched."
+        ),
+    )
+    background_tolerance: int = Field(
+        default=DEFAULT_TOLERANCE,
+        ge=0,
+        le=255,
+        description="Minimum channel value counted as background. Higher is stricter.",
+    )
+    background_feather: int = Field(
+        default=1,
+        ge=0,
+        le=25,
+        description="Mask softening in pixels; removes halos on anti-aliased edges.",
+    )
+
+    @field_validator("background_clean_mode", mode="before")
+    @classmethod
+    def normalize_background_clean_mode(cls, value: object) -> object:
+        if isinstance(value, str):
+            return value.strip().lower()
+        return value
+
+
+class JobStatus(BaseModel):
+    status: str
+
+
+class ScanRequest(BaseModel):
+    folder_path: str
+
+
+class ScanSubfolder(BaseModel):
+    display_name: str
+    full_path: str
+
+
+class ScanResponse(BaseModel):
+    valid: bool
+    image_count: int
+    sample_files: list[str]
+    estimated_pages: int
+    available_subfolders: list[ScanSubfolder] = Field(default_factory=list)
+    message: str
+
+
+class SelectedBatchFolderValidationRequest(BaseModel):
+    parent_folder_path: str
+    selected_subfolders: list[str] = Field(
+        validation_alias=AliasChoices("selected_subfolders", "selected_subfolder_paths"),
+    )
+
+    @field_validator("selected_subfolders", mode="before")
+    @classmethod
+    def normalize_selected_subfolders(cls, value: object) -> list[str]:
+        if not isinstance(value, list):
+            raise ValueError("selected_subfolders must be a list of paths.")
+
+        normalized_paths: list[str] = []
+        seen_paths: set[str] = set()
+        for item in value:
+            if not isinstance(item, str):
+                raise ValueError("selected_subfolders must contain only strings.")
+            normalized_item = item.strip()
+            if not normalized_item or normalized_item in seen_paths:
+                continue
+            seen_paths.add(normalized_item)
+            normalized_paths.append(normalized_item)
+
+        return normalized_paths
+
+
+class SelectedBatchFolderScanResult(BaseModel):
+    display_name: str
+    full_path: str
+    valid: bool
+    image_count: int
+    sample_files: list[str]
+    estimated_pages: int
+    message: str
+
+
+class SelectedBatchFolderValidationResponse(BaseModel):
+    parent_folder_path: str
+    selected_folders: int
+    valid_selected_folders: int
+    invalid_selected_folders: int
+    scanned_folders: list[SelectedBatchFolderScanResult]
+    skipped_folders: list[SelectedBatchFolderScanResult]
+    message: str
+
+
+class GenerationRequest(OutputQualityOptions):
+    folder_path: str
+    output_path: str
+    page_width: float = Field(gt=0)
+    page_height: float = Field(gt=0)
+    gap: float = Field(ge=0)
+    margin: float = Field(ge=0)
+    format: Literal["PNG", "JPG"]
+    include_partial_page: bool = Field(
+        default=False,
+        description=(
+            "Render a final page whose cells are not all filled. Off preserves the "
+            "existing behaviour of leaving trailing images out; either way the count "
+            "is reported rather than dropped silently."
+        ),
+    )
+    create_video: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("create_video", "create_preview_video"),
+    )
+    video_duration_seconds: float = Field(
+        default=15.0,
+        gt=0,
+        le=MAX_VIDEO_DURATION_SECONDS,
+        validation_alias=AliasChoices("video_duration_seconds", "duration_seconds"),
+    )
+    video_transition: Literal["none", "crossfade", "flip"] = Field(
+        default="none",
+        validation_alias=AliasChoices("video_transition", "transition"),
+    )
+    video_filename: str = "preview.mp4"
+
+    @field_validator("format", mode="before")
+    @classmethod
+    def normalize_format(cls, value: str) -> str:
+        if isinstance(value, str):
+            return value.upper()
+        return value
+
+    @field_validator("video_filename")
+    @classmethod
+    def validate_video_filename(cls, value: str) -> str:
+        return _validate_video_filename(value)
+
+
+class GenerationResponse(BaseModel):
+    success: bool
+    total_images: int
+    pages_generated: int
+    output_files: list[str]
+    output_path: str
+    video_file: str | None = None
+    video_created: bool = False
+    images_dropped: int = 0
+    images_skipped: int = 0
+    backgrounds_cleaned: int = 0
+    page_geometry: str | None = None
+    message: str
+
+
+class CoverCollageGenerationRequest(OutputQualityOptions):
+    folder_path: str
+    output_path: str
+    page_width: float = Field(gt=0)
+    page_height: float = Field(gt=0)
+    format: Literal["PNG", "JPG"]
+    collage_template: CoverCollageTemplate = CoverCollageTemplate.RANDOMIZED_GRID
+    image_fit: CoverCollageFittingMode = CoverCollageFittingMode.COVER
+    selected_cover_images: list[str] | None = None
+
+    @field_validator("format", mode="before")
+    @classmethod
+    def normalize_format(cls, value: str) -> str:
+        if isinstance(value, str):
+            return value.upper()
+        return value
+
+    @field_validator("selected_cover_images", mode="before")
+    @classmethod
+    def normalize_selected_cover_images(cls, value: object) -> list[str] | None:
+        return _normalize_optional_string_list(value, field_name="selected_cover_images")
+
+
+class CoverCollageResponse(BaseModel):
+    success: bool
+    total_images: int
+    pages_generated: int
+    output_files: list[str]
+    output_path: str
+    page_geometry: str | None = None
+    message: str
+
+
+class BatchCoverCollageGenerationRequest(OutputQualityOptions):
+    parent_folder_path: str
+    created_output_root_path: str = Field(
+        validation_alias=AliasChoices("created_output_root_path", "output_root_path"),
+    )
+    selected_subfolders: list[str] = Field(
+        validation_alias=AliasChoices("selected_subfolders", "selected_subfolder_paths"),
+    )
+    page_width: float = Field(gt=0)
+    page_height: float = Field(gt=0)
+    format: Literal["PNG", "JPG"]
+    collage_template: CoverCollageTemplate = CoverCollageTemplate.RANDOMIZED_GRID
+    image_fit: CoverCollageFittingMode = CoverCollageFittingMode.COVER
+
+    @field_validator("selected_subfolders", mode="before")
+    @classmethod
+    def normalize_selected_subfolders(cls, value: object) -> list[str]:
+        if not isinstance(value, list):
+            raise ValueError("selected_subfolders must be a list of paths.")
+
+        normalized_paths: list[str] = []
+        seen_paths: set[str] = set()
+        for item in value:
+            if not isinstance(item, str):
+                raise ValueError("selected_subfolders must contain only strings.")
+            normalized_item = item.strip()
+            if not normalized_item or normalized_item in seen_paths:
+                continue
+            seen_paths.add(normalized_item)
+            normalized_paths.append(normalized_item)
+
+        return normalized_paths
+
+    @field_validator("format", mode="before")
+    @classmethod
+    def normalize_format(cls, value: str) -> str:
+        if isinstance(value, str):
+            return value.upper()
+        return value
+
+
+class BatchCoverCollageResult(BaseModel):
+    folder_name: str
+    success: bool
+    pages_generated: int
+    total_images: int
+    output_path: str
+    output_files: list[str] = Field(default_factory=list)
+    message: str
+
+
+class BatchCoverCollageGenerationResponse(BaseModel):
+    success: bool
+    processed_folders: int
+    generated_folders: int
+    total_detected_folders: int
+    selected_folders: int
+    bundle_results: list[BatchCoverCollageResult]
+    created_output_root_path: str
+    message: str
+
+
+class BatchGenerationRequest(OutputQualityOptions):
+    parent_folder_path: str
+    created_output_root_path: str
+    selected_subfolders: list[str] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("selected_subfolders", "selected_subfolder_paths"),
+    )
+    page_width: float = Field(gt=0)
+    page_height: float = Field(gt=0)
+    gap: float = Field(ge=0)
+    margin: float = Field(ge=0)
+    format: Literal["PNG", "JPG"]
+    include_partial_page: bool = Field(
+        default=False,
+        description=(
+            "Render a final page whose cells are not all filled. Off preserves the "
+            "existing behaviour of leaving trailing images out; either way the count "
+            "is reported rather than dropped silently."
+        ),
+    )
+    create_video: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("create_video", "create_preview_video"),
+    )
+    video_duration_seconds: float = Field(
+        default=15.0,
+        gt=0,
+        le=MAX_VIDEO_DURATION_SECONDS,
+        validation_alias=AliasChoices("video_duration_seconds", "duration_seconds"),
+    )
+    video_transition: Literal["none", "crossfade", "flip"] = Field(
+        default="none",
+        validation_alias=AliasChoices("video_transition", "transition"),
+    )
+    video_filename: str = "preview.mp4"
+
+    @field_validator("selected_subfolders", mode="before")
+    @classmethod
+    def normalize_selected_subfolders(cls, value: object) -> list[str] | None:
+        if value is None:
+            return None
+        if not isinstance(value, list):
+            raise ValueError("selected_subfolders must be a list of paths.")
+
+        normalized_paths: list[str] = []
+        seen_paths: set[str] = set()
+        for item in value:
+            if not isinstance(item, str):
+                raise ValueError("selected_subfolders must contain only strings.")
+            normalized_item = item.strip()
+            if not normalized_item or normalized_item in seen_paths:
+                continue
+            seen_paths.add(normalized_item)
+            normalized_paths.append(normalized_item)
+
+        return normalized_paths
+
+    @field_validator("format", mode="before")
+    @classmethod
+    def normalize_format(cls, value: str) -> str:
+        if isinstance(value, str):
+            return value.upper()
+        return value
+
+    @field_validator("video_filename")
+    @classmethod
+    def validate_video_filename(cls, value: str) -> str:
+        return _validate_video_filename(value)
+
+
+class BatchBundleResult(BaseModel):
+    folder_name: str
+    success: bool
+    pages_generated: int
+    total_images: int
+    output_path: str
+    video_file: str | None = None
+    video_created: bool = False
+    message: str
+
+
+class BatchGenerationResponse(BaseModel):
+    success: bool
+    processed_folders: int
+    generated_folders: int
+    total_detected_folders: int
+    selected_folders: int
+    bundle_results: list[BatchBundleResult]
+    created_output_root_path: str
+    message: str