yaffo 0.0.11__py3-none-any.whl

yaffo/__main__.py

@@ -0,0 +1,144 @@
+"""Entry point for `python -m yaffo` and the packaged (PyInstaller) app.
+
+One frozen binary plays three roles, selected by the YAFFO_ROLE env var, because a
+PyInstaller app's `sys.executable` is the app itself and its bootloader ignores
+`-m`/`-c` — so a child process is started by re-executing this same entry with a
+role set, not by invoking a module path:
+
+- (unset) "web": serve the Flask app via waitress (a production WSGI server, not
+  the Flask dev server), run migrations, and supervise the host + watcher children.
+- "host":    run the task-queue host (which itself spawns workers via multiprocessing).
+- "watcher": run the filesystem watcher.
+
+`multiprocessing.freeze_support()` must run first: in a spawned task worker the
+bootloader/freeze_support intercept startup and run the worker, never reaching main().
+"""
+from __future__ import annotations
+
+import atexit
+import multiprocessing
+import os
+import subprocess
+import sys
+import threading
+import webbrowser
+
+HOST = "127.0.0.1"
+PORT = 5001
+WEB_THREADS = 8
+WORKERS = max(2, (os.cpu_count() or 4) - 1)
+RECYCLE = 100
+
+
+def _child_cmd() -> list[str]:
+    """Command to re-launch this entry for a child role. Frozen: just the app
+    binary (args ignored; role travels via env). Dev: `python -m yaffo`."""
+    if getattr(sys, "frozen", False):
+        return [sys.executable]
+    return [sys.executable, "-m", "yaffo"]
+
+
+def _start_background() -> list[subprocess.Popen]:
+    from yaffo.logging_config import get_logger
+
+    logger = get_logger(__name__, "webapp")
+    procs: list[subprocess.Popen] = []
+    for role in ("host", "watcher"):
+        try:
+            procs.append(subprocess.Popen(_child_cmd(), env={**os.environ, "YAFFO_ROLE": role}))
+            logger.info(f"started {role}")
+        except Exception:
+            logger.exception(f"failed to start {role}")
+    return procs
+
+
+def _stop_background(procs: list[subprocess.Popen]) -> None:
+    for proc in procs:
+        if proc.poll() is None:
+            proc.terminate()
+
+
+def _run_menubar(procs: list[subprocess.Popen], url: str) -> None:
+    """Run a macOS menu-bar item on the main thread (the AppKit run loop that gives
+    the app a face and keeps it alive). 'Quit' tears down the host/watcher children
+    so nothing is orphaned — the failure mode of the headless, faceless build."""
+    import rumps
+
+    from yaffo.common import RESOURCES_DIR
+
+    icon = RESOURCES_DIR / "branding" / "menubar.png"
+    icon_kwargs = {"icon": str(icon), "template": False} if icon.exists() else {"title": "📷"}
+
+    class YaffoApp(rumps.App):
+        def __init__(self) -> None:
+            super().__init__("Yaffo", quit_button=None, **icon_kwargs)
+            self.menu = [
+                rumps.MenuItem("Open Yaffo", callback=lambda _: webbrowser.open(url)),
+                None,
+                rumps.MenuItem("Quit Yaffo", callback=self._quit),
+            ]
+
+        def _quit(self, _) -> None:
+            _stop_background(procs)
+            rumps.quit_application()
+
+    YaffoApp().run()
+
+
+def _run_web() -> None:
+    from waitress import serve
+    from yaffo.app import create_app
+    from yaffo.logging_config import get_logger
+    from yaffo.scripts.db.migrate import run_migrations
+
+    logger = get_logger(__name__, "webapp")
+    run_migrations()
+    procs = _start_background()
+    atexit.register(_stop_background, procs)
+
+    app = create_app()
+    url = f"http://{HOST}:{PORT}"
+    threading.Timer(1.5, lambda: webbrowser.open(url)).start()
+
+    try:
+        import rumps  # noqa: F401  (probe: present in the bundle, absent in plain dev)
+    except Exception:
+        # No menu bar (e.g. Linux / a bare dev run): serve on the main thread.
+        logger.info(f"serving Yaffo at {url} (no menu bar)")
+        serve(app, host=HOST, port=PORT, threads=WEB_THREADS)
+        return
+
+    logger.info(f"serving Yaffo at {url} (menu bar)")
+    threading.Thread(
+        target=serve, args=(app,),
+        kwargs={"host": HOST, "port": PORT, "threads": WEB_THREADS},
+        daemon=True,
+    ).start()
+    _run_menubar(procs, url)
+
+
+def _run_host() -> None:
+    from yaffo.taskq.host import main as host_main
+
+    host_main()
+
+
+def _run_watcher() -> None:
+    from yaffo.background_tasks.watcher import main as watcher_main
+
+    watcher_main()
+
+
+def main() -> None:
+    role = os.environ.get("YAFFO_ROLE", "web")
+    if role == "host":
+        _run_host()
+    elif role == "watcher":
+        _run_watcher()
+    else:
+        _run_web()
+
+
+if __name__ == "__main__":
+    multiprocessing.freeze_support()
+    main()

yaffo/app.py

@@ -0,0 +1,79 @@
+import os
+import logging
+from pathlib import Path
+from typing import Optional
+
+from flask import Flask
+from yaffo import themes
+from yaffo.db import db
+from yaffo.common import DB_PATH
+from yaffo.distance_units import supported_distance_unit_options
+from yaffo.i18n import init_i18n, select_locale, supported_locale_options, text_direction
+from yaffo.logging_config import get_logger
+from yaffo.template_filters import init_template_filters
+from yaffo.routes.init_routes import init_routes
+
+logger = get_logger(__name__, 'webapp')
+
+def create_app(db_path: Path = DB_PATH, config: Optional[dict] = None):
+    app = Flask(__name__)
+
+    # Configure werkzeug logger to use our logging system
+    werkzeug_logger = logging.getLogger('werkzeug')
+    werkzeug_logger.setLevel(logging.ERROR)
+
+    # Set Flask app logger to use our webapp logger
+    app.logger.handlers = logger.handlers
+    app.logger.setLevel(logger.level)
+
+    logger.info("Starting Photo Organizer application")
+    app.config["SQLALCHEMY_DATABASE_URI"] = f"sqlite:///{db_path}"
+    app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+    app.config["SQLALCHEMY_ECHO"] = os.environ.get("SQLALCHEMY_ECHO", "").lower() == "true"
+    app.config["SESSION_COOKIE_SAMESITE"] = "Lax"
+    app.config["SESSION_COOKIE_SECURE"] = False
+    app.config["SESSION_COOKIE_HTTPONLY"] = True
+
+    app.secret_key = os.environ.get('SECRET_KEY', 'dev-secret-key-change-in-production')
+    app.config['SESSION_TYPE'] = 'filesystem'  # or 'redis', 'memcached', etc.
+    app.config['SESSION_PERMANENT'] = True
+    #app.config['SESSION_USE_SIGNER'] = True
+
+    # Caller overrides (e.g. tests) win over the defaults above.
+    if config:
+        app.config.update(config)
+
+    db.init_app(app)
+    init_i18n(app)
+
+    # Make url_map available in all templates
+    @app.context_processor
+    def inject_url_map():
+        return {'url_map': app.url_map}
+
+    @app.context_processor
+    def inject_theme():
+        return {'theme': themes.get_theme()}
+
+    @app.context_processor
+    def inject_i18n():
+        locale = select_locale()
+        return {
+            "current_locale": locale,
+            "distance_unit_options": supported_distance_unit_options(),
+            "supported_locales": supported_locale_options(),
+            "text_direction": text_direction(locale),
+        }
+
+    # Register template filters
+
+    init_template_filters(app)
+    init_routes(app)
+    return app
+
+if __name__ == "__main__":
+    app = create_app()
+    # threaded so a long streaming response (e.g. the index-photos scan) doesn't block
+    # the page's other requests on the single-user dev server. Port 5001, not 5000 —
+    # macOS AirPlay Receiver (Control Center) binds *:5000 and answers with a 403.
+    app.run(debug=True, threaded=True, port=5001)

yaffo/common.py

@@ -0,0 +1,69 @@
+import sys
+from pathlib import Path
+from platformdirs import user_cache_dir, user_data_dir
+import os
+
+app_author = "Jason Turan"
+version = "0.0.1"
+app_name = "yaffo"
+
+# Media-type discriminator values. Defined here (a dependency-free leaf module) so
+# both yaffo.common and yaffo.db.models can expose them without an import cycle;
+# models re-exports these, so `from yaffo.db.models import MEDIA_TYPE_*` still works.
+MEDIA_TYPE_PHOTO = "photo"
+MEDIA_TYPE_VIDEO = "video"
+
+# Containers that play inline in the browser's <video> (H.264/HEVC in MP4/MOV/M4V).
+PLAYABLE_VIDEO_EXTENSIONS = {".mp4", ".mov", ".m4v"}
+# All cataloged video. The non-playable containers (avi/mkv/wmv/flv) are still
+# indexed for metadata + poster + faces (exiftool/ffmpeg handle them); the detail
+# view offers "open externally" instead of an inline player. See docs/development/video.md.
+VIDEO_EXTENSIONS = PLAYABLE_VIDEO_EXTENSIONS | {".avi", ".mkv", ".wmv", ".flv"}
+PHOTO_EXTENSIONS = {".jpg", ".jpeg", ".png", ".heic"}
+MEDIA_EXTENSIONS = PHOTO_EXTENSIONS | VIDEO_EXTENSIONS
+
+
+def media_type_for_path(path: Path) -> str:
+    """The MEDIA_TYPE_* a file belongs to, from its suffix. Defaults to photo for
+    anything that isn't a known video extension (the import path only ever sees
+    files already filtered to MEDIA_EXTENSIONS)."""
+    return MEDIA_TYPE_VIDEO if path.suffix.lower() in VIDEO_EXTENSIONS else MEDIA_TYPE_PHOTO
+
+
+def is_browser_playable_video(path: "Path | str") -> bool:
+    """Whether a video plays inline in an HTML5 <video> (a container-level check).
+    Non-playable containers are cataloged but opened in an external player."""
+    return Path(path).suffix.lower() in PLAYABLE_VIDEO_EXTENSIONS
+
+# Where the DB, thumbnails, temp/trash, and logs live. Set YAFFO_DATA_DIR to
+# override (invoke sets it to ~/Pictures for dev). Otherwise default to the OS
+# per-user data dir, so an installed app gets its own home (the photo library
+# itself is configured in-app, independent of this).
+if os.environ.get("YAFFO_DATA_DIR"):
+    data_dir = Path(os.environ["YAFFO_DATA_DIR"])
+else:
+    data_dir = Path(user_data_dir(app_name, app_author))
+
+ROOT_DIR = Path(data_dir)
+# Ensure the DB/log home exists before anything writes into it (logging opens a
+# file here at import time, ahead of any migration step).
+ROOT_DIR.mkdir(parents=True, exist_ok=True)
+
+DB_PATH = ROOT_DIR / f"{app_name}.db"
+QUEUE_DB_PATH = ROOT_DIR / f"{app_name}-queue.db"
+
+# Downloaded vision models (CLIP ONNX encoders) cache here on first use, like
+# InsightFace's ~/.insightface — kept out of the photo library / data dir.
+MODEL_CACHE_DIR = Path(user_cache_dir(app_name, app_author))
+
+# Read-only assets shipped with the source tree and bundled into the app. When
+# frozen by PyInstaller they live under sys._MEIPASS (the spec adds `resources`
+# there); in dev `parents[1]` is the repo root, where `resources/` sits beside the
+# `yaffo/` package. Models, when pre-bundled by the build script, live under
+# BUNDLED_MODELS_DIR; loaders prefer them and fall back to a network download.
+if getattr(sys, "frozen", False):
+    BUNDLE_ROOT = Path(sys._MEIPASS)  # type: ignore[attr-defined]
+else:
+    BUNDLE_ROOT = Path(__file__).resolve().parents[1]
+RESOURCES_DIR = BUNDLE_ROOT / "resources"
+BUNDLED_MODELS_DIR = RESOURCES_DIR / "models"

yaffo/config.py

@@ -0,0 +1,154 @@
+"""Optional user config, read once at startup from ``<data dir>/config.toml``.
+
+TOML (not YAML/JSON) because it's the Python-conventional config format: the stdlib
+``tomllib`` reads it with no dependency, it supports comments, and the project
+already uses TOML (pyproject.toml). Edit the file and restart the app to apply.
+
+On startup the file is migrated to the current template: new sections/keys (and their
+documentation comments) are added while the user's set values are preserved. The
+template is the source of truth for structure + comments + defaults, so we re-render
+it with the user's overrides substituted in rather than round-tripping through a dict
+(``tomllib`` can read but not write TOML, and would drop every comment).
+"""
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from typing import Any
+
+from yaffo.common import ROOT_DIR
+
+CONFIG_PATH = ROOT_DIR / "config.toml"
+
+_TEMPLATE = """\
+# Yaffo configuration. Edit a value and restart the app to apply it.
+
+[logging]
+# Verbosity of the log files (yaffo.log, background_tasks.log).
+# One of: DEBUG, INFO, WARNING, ERROR
+level = "INFO"
+# Max size (MB) of each rolling log file before it rotates, and how many old files
+# to keep.
+max_file_mb = 5
+backup_count = 3
+# How many recent page/theme/automation generation runs to keep under model_logs/.
+max_model_log_runs = 50
+
+[database]
+# SQLite durability vs. write speed (PRAGMA synchronous), paired with WAL.
+#   NORMAL = fast; the last transaction can be lost on an OS/power/disk failure
+#            (never corruption). The default — best for bulk photo indexing.
+#   FULL   = fsync on every commit; survives OS/power/disk failures with no lost
+#            writes, at a write-throughput cost.
+# One of: NORMAL, FULL
+synchronous = "NORMAL"
+
+[tasks]
+# Background worker processes: more = more parallel indexing, more CPU/RAM. Defaults
+# to the CPU count when unset; a `--workers` CLI flag still overrides this.
+# workers = 4
+# Recycle (restart) a worker after this many tasks, to bound slow leaks.
+recycle = 100
+
+[ai]
+# Caps per AI generation run (page/theme/automation builder), to bound cost.
+# max_iterations: tool-use loop steps before the run stops.
+# max_output_tokens: tokens per model call — shared with the thinking budget, so
+#   setting it too low risks responses getting cut off mid-generation.
+max_iterations = 25
+max_output_tokens = 64000
+"""
+
+
+_SECTION_RE = re.compile(r"^\s*\[([A-Za-z0-9_.-]+)\]\s*$")
+# A `key = value` line, optionally commented (e.g. the `# workers = 4` default).
+_KEY_RE = re.compile(r"^(\s*)#?\s*([A-Za-z_][\w-]*)\s*=\s*(.*)$")
+
+
+def _toml_value(value: Any) -> str:
+    """Render a Python scalar as a TOML literal (covers the value types this config
+    uses: str, int, float, bool)."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    escaped = str(value).replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _render(user: dict[str, Any]) -> str:
+    """Render _TEMPLATE (the canonical structure + comments + defaults), substituting
+    any value the user has set so their overrides survive the migration. A commented
+    default (e.g. `# workers = 4`) is activated when the user has set that key. Pure
+    doc-comment lines and unknown user keys are left untouched / dropped."""
+    section: str | None = None
+    out: list[str] = []
+    for line in _TEMPLATE.splitlines():
+        sm = _SECTION_RE.match(line)
+        if sm:
+            section = sm.group(1)
+            out.append(line)
+            continue
+        km = _KEY_RE.match(line)
+        if km and section and section in user and km.group(2) in user[section]:
+            indent, key = km.group(1), km.group(2)
+            out.append(f"{indent}{key} = {_toml_value(user[section][key])}")
+            continue
+        out.append(line)
+    return "\n".join(out) + "\n"
+
+
+def _atomic_write(text: str) -> None:
+    """Write config.toml via a temp file + rename so concurrently-starting processes
+    (flask, watcher, host, spawn workers all import this) never see a torn file."""
+    tmp = CONFIG_PATH.with_suffix(".toml.tmp")
+    tmp.write_text(text)
+    os.replace(tmp, CONFIG_PATH)
+
+
+def _load() -> dict[str, Any]:
+    if not CONFIG_PATH.exists():
+        try:
+            _atomic_write(_TEMPLATE)  # seed a documented default on first run
+        except OSError:
+            pass
+        return tomllib.loads(_TEMPLATE)
+
+    try:
+        existing = CONFIG_PATH.read_text()
+        user = tomllib.loads(existing)
+    except (OSError, tomllib.TOMLDecodeError):
+        # Leave an unreadable/corrupt file alone (don't clobber something the user
+        # could still fix); fall back to code defaults via get()/get_int().
+        return {}
+
+    # Migrate: re-render the template with the user's values, rewriting only when the
+    # result actually differs (so a settled config doesn't get rewritten every launch).
+    merged_text = _render(user)
+    if merged_text != existing:
+        try:
+            _atomic_write(merged_text)
+        except OSError:
+            pass
+    return tomllib.loads(merged_text)
+
+
+_config = _load()
+
+
+def get(section: str, key: str, default: Any = None) -> Any:
+    """Read config[section][key], falling back to default if absent."""
+    return _config.get(section, {}).get(key, default)
+
+
+def get_int(section: str, key: str, default: int, minimum: int = 1) -> int:
+    """Read an integer config value, falling back to `default` when absent, the wrong
+    type, or below `minimum` — so a typo in config.toml can't feed a nonsensical value
+    (e.g. 0 workers, a negative retention) into the system."""
+    raw = get(section, key, default)
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return default
+    return value if value >= minimum else default

yaffo/distance_units.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from flask_babel import lazy_gettext
+from sqlalchemy.exc import OperationalError
+
+from yaffo.db import db
+from yaffo.db.models import ApplicationSettings
+
+DISTANCE_UNIT_SETTING = "distance_unit"
+DISTANCE_UNIT_MILES = "mi"
+DISTANCE_UNIT_KILOMETERS = "km"
+DEFAULT_DISTANCE_UNIT = DISTANCE_UNIT_MILES
+KILOMETERS_PER_MILE = 1.609344
+
+
+@dataclass(frozen=True)
+class DistanceUnitOption:
+    code: str
+    label: str
+
+
+def supported_distance_unit_options() -> list[DistanceUnitOption]:
+    return [
+        DistanceUnitOption(code=DISTANCE_UNIT_MILES, label=lazy_gettext("Miles")),
+        DistanceUnitOption(code=DISTANCE_UNIT_KILOMETERS, label=lazy_gettext("Kilometers")),
+    ]
+
+
+def normalize_distance_unit(unit: str | None) -> str | None:
+    if not unit:
+        return None
+    normalized = unit.strip().lower()
+    return normalized if normalized in {DISTANCE_UNIT_MILES, DISTANCE_UNIT_KILOMETERS} else None
+
+
+def get_saved_distance_unit(session=None) -> str:
+    session = session or db.session
+    try:
+        row = session.query(ApplicationSettings).filter_by(name=DISTANCE_UNIT_SETTING).first()
+    except OperationalError:
+        return DEFAULT_DISTANCE_UNIT
+    return normalize_distance_unit(row.value if row else None) or DEFAULT_DISTANCE_UNIT
+
+
+def set_distance_unit(unit: str) -> bool:
+    normalized = normalize_distance_unit(unit)
+    if normalized is None:
+        return False
+    row = db.session.query(ApplicationSettings).filter_by(name=DISTANCE_UNIT_SETTING).first()
+    if row is None:
+        db.session.add(ApplicationSettings(name=DISTANCE_UNIT_SETTING, type="string", value=normalized))
+    else:
+        row.value = normalized
+    db.session.commit()
+    return True
+
+
+def kilometers_per_unit(unit: str) -> float:
+    return {
+        DISTANCE_UNIT_MILES: KILOMETERS_PER_MILE,
+        DISTANCE_UNIT_KILOMETERS: 1.0,
+    }[normalize_distance_unit(unit) or DEFAULT_DISTANCE_UNIT]
+
+
+def distance_to_kilometers(value: float, unit: str) -> float:
+    return value * kilometers_per_unit(unit)
+
+
+def kilometers_to_distance(value_kilometers: float, unit: str) -> float:
+    return value_kilometers / kilometers_per_unit(unit)