youpdated 0.1.0__py3-none-any.whl

youpdated/__init__.py

@@ -0,0 +1,3 @@
+"""Youpdated, a simple update tracker."""
+
+__version__ = "0.1.0"

youpdated/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

youpdated/cleanup.py

@@ -0,0 +1,117 @@
+"""Finds and removes everything from Youpdated."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import (
+    DEFAULT_CONFIG_NAME,
+    config_dir,
+    data_dir,
+    default_config_path,
+    default_state_path,
+)
+
+APP_DIR_NAME = "youpdated"
+
+
+@dataclass
+class Trace:
+    """Something Youpdated-based."""
+
+    path: Path
+    kind: str  # "config" | "state" | "directory"
+    note: str
+
+    @property
+    def exists(self) -> bool:
+        return self.path.exists()
+
+
+def find_traces(
+    config_override: str | Path | None = None,
+    state_override: str | Path | None = None,
+    *,
+    keep_config: bool = False,
+) -> list[Trace]:
+    """Every file and directory this tool may have created, existing now."""
+    traces: list[Trace] = []
+    seen: set[Path] = set()
+
+    def add(path: Path | None, kind: str, note: str) -> None:
+        if path is None:
+            return
+        resolved = Path(path).expanduser()
+        if resolved in seen or not resolved.exists():
+            return
+        seen.add(resolved)
+        traces.append(Trace(resolved, kind, note))
+
+    if not keep_config:
+        add(config_override, "config", "config file (--config)")
+        add(Path.cwd() / "youpdated.yaml", "config", "project config file")
+        add(Path.cwd() / "youpdated.yml", "config", "project config file")
+        add(default_config_path(), "config", "config file")
+
+    add(state_override, "state", "history database (--state)")
+    add(default_state_path(), "state", "history database")
+
+    # Dirs last
+    for directory in (config_dir(), data_dir()):
+        add(directory, "directory", "application directory (only if empty)")
+
+    return traces
+
+
+def remove_traces(traces: list[Trace]) -> tuple[list[Trace], list[tuple[Trace, str]]]:
+    """Delete the given traces. Returns ``(removed, failed)``.
+
+    Files first, then directories, any additions to dirs that are unexpected donn't let them delete
+    """
+    removed: list[Trace] = []
+    failed: list[tuple[Trace, str]] = []
+
+    files = [t for t in traces if t.kind != "directory"]
+    directories = [t for t in traces if t.kind == "directory"]
+
+    for trace in files:
+        try:
+            if trace.path.is_file():
+                trace.path.unlink()
+                removed.append(trace)
+        except OSError as exc:
+            failed.append((trace, str(exc)))
+
+    for trace in directories:
+        path = trace.path
+        # it must be a youpdated directory and empty.
+        if path.name != APP_DIR_NAME:
+            failed.append((trace, "not a youpdated directory, aborted"))
+            continue
+        try:
+            if not path.is_dir():
+                continue
+            leftovers = list(path.iterdir())
+            if leftovers:
+                failed.append(
+                    (trace, f"not empty ({len(leftovers)} other file(s)), aborted")
+                )
+                continue
+            path.rmdir()
+            removed.append(trace)
+        except OSError as exc:
+            failed.append((trace, str(exc)))
+
+    return removed, failed
+
+
+def package_removal_command() -> str:
+    """Command to remove the package."""
+    
+    return f"{sys.executable} -m pip uninstall youpdated"
+
+
+def config_filename() -> str:
+    return DEFAULT_CONFIG_NAME

youpdated/cli.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from rich.console import Console
+from rich.markup import escape
+
+from . import __version__
+from .cleanup import find_traces, package_removal_command, remove_traces
+from .config import (
+    EXAMPLE_CONFIG,
+    Config,
+    ConfigError,
+    default_config_path,
+    default_state_path,
+    load_config,
+)
+from .http import Client
+from .registry import all_sources
+from .render import json_out, rss_out, terminal
+from .runner import parse_since, run
+from .state import State
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="youpdated",
+        description="Collect updates for the games, apps, and packages you follow.",
+    )
+    parser.add_argument("--version", action="version", version=f"youpdated {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    check = sub.add_parser("check", help="fetch sources and report what's new (default)")
+    check.add_argument("-c", "--config", help="path to a config file")
+    check.add_argument(
+        "-s", "--source", action="append", dest="sources",
+        help="only check this source (repeatable)",
+    )
+    check.add_argument("--all", action="store_true", help="report everything, not just new items")
+    check.add_argument("--since", help="only items newer than a window. (Eg: 7d, 12h)")
+    check.add_argument("--json", action="store_true", help="emit JSON to stdout")
+    check.add_argument("--rss", metavar="FILE", help="write an aggregated Atom feed")
+    check.add_argument(
+        "--no-save", action="store_true",
+        help="do not record anything as seen (state untouched)",
+    )
+    check.add_argument(
+        "--test", action="store_true",
+        help="show what would have been requested",
+    )
+    check.add_argument("--state", help="path to the state database")
+    check.add_argument("-v", "--verbose", action="store_true", help="show request detail and bodies")
+    check.add_argument(
+        "--fail-on-error", action="store_true",
+        help="exit non-zero if any source failed",
+    )
+
+    sub.add_parser("sources", help="list available sources")
+
+    init = sub.add_parser("init", help="write a starter config file")
+    init.add_argument("-c", "--config", help="where to write it")
+    init.add_argument("-f", "--force", action="store_true", help="overwrite an existing file")
+
+    uninstall = sub.add_parser(
+        "uninstall",
+        help="remove all Youpdated files",
+    )
+    uninstall.add_argument("-c", "--config", help="also remove this config file")
+    uninstall.add_argument("--state", help="also remove this state database")
+    uninstall.add_argument(
+        "--keep-config", action="store_true", help="delete history but keep config files"
+    )
+    uninstall.add_argument(
+        "--test", action="store_true", help="list removals without deleting"
+    )
+    uninstall.add_argument(
+        "-y", "--yes", action="store_true", help="skip confirmation"
+    )
+
+    return parser
+
+
+def cmd_sources(console: Console) -> int:
+    console.print("[bold]Available sources[/]\n")
+    for name, source in sorted(all_sources().items()):
+        console.print(f"  [cyan]{name:<10}[/] {getattr(source, 'summary', '')}")
+    console.print("\n[dim]Add entries under `sources:` in your config.[/]")
+    return 0
+
+
+def cmd_init(args: argparse.Namespace, console: Console) -> int:
+    path = Path(args.config).expanduser() if args.config else default_config_path()
+    if path.exists() and not args.force:
+        console.print(f"[yellow]{path} already exists.[/] Use --force to overwrite.")
+        return 1
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(EXAMPLE_CONFIG, encoding="utf-8")
+    console.print(f"Wrote starter config to [bold]{path}[/]")
+    console.print("[dim]Edit, then run `youpdated check`.[/]")
+    return 0
+
+
+def cmd_uninstall(args: argparse.Namespace, console: Console) -> int:
+    traces = find_traces(args.config, args.state, keep_config=args.keep_config)
+
+    if not traces:
+        console.print("[dim]No Youpdated files found.[/]")
+        console.print(f"\nTo remove the package itself:\n  [bold]{package_removal_command()}[/]")
+        return 0
+
+    console.print("[bold]This will permanently delete:[/]\n")
+    for trace in traces:
+        console.print(f"  [yellow]{escape(str(trace.path))}[/]")
+        console.print(f"    [dim]{trace.note}[/]")
+    console.print()
+
+    if args.test:
+        console.print("[dim]--test: nothing was deleted.[/]")
+        return 0
+
+    if not args.yes:
+        if not sys.stdin.isatty():
+            console.print(
+                "[red]Refusing to delete without confirmation.[/] "
+                "Re-run with [bold]--yes[/] (or [bold]--test[/] to preview)."
+            )
+            return 1
+        try:
+            answer = input("Delete these? Type 'yes' to confirm: ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            answer = ""
+        if answer not in ("yes", "y"):
+            console.print("[dim]Cancelled. Nothing deleted.[/]")
+            return 1
+
+    removed, failed = remove_traces(traces)
+
+    for trace in removed:
+        console.print(f"[green]removed[/] {escape(str(trace.path))}")
+    for trace, reason in failed:
+        console.print(f"[yellow]kept[/]    {escape(str(trace.path))} — {escape(reason)}")
+
+    console.print(
+        f"\n[bold]{len(removed)}[/] item(s) removed"
+        + (f", [bold]{len(failed)}[/] left in place." if failed else ".")
+    )
+    console.print(
+        "\nRemoved all written files. To remove the package itself:\n"
+        f"  [bold]{package_removal_command()}[/]"
+    )
+    return 0
+
+
+def cmd_check(args: argparse.Namespace, console: Console) -> int:
+    # JSON goes to stdout, status chatter to stderr.
+    status = Console(stderr=True) if args.json else console
+
+    config: Config = load_config(args.config)
+
+    since = None
+    if args.since:
+        try:
+            since = parse_since(args.since)
+        except ValueError as exc:
+            raise ConfigError(str(exc)) from exc
+
+    unknown = set(args.sources or []) - set(all_sources())
+    if unknown:
+        raise ConfigError(
+            f"unknown source(s): {', '.join(sorted(unknown))}. "
+            "Run `youpdated sources` to see the list."
+        )
+
+    state_path = Path(args.state).expanduser() if args.state else default_state_path()
+
+    with State(state_path) as state:
+        with Client(
+            config.privacy,
+            state,
+            test=args.test,
+            verbose=args.verbose or args.test,
+            use_conditional=not args.all,
+            logger=lambda msg: status.print(escape(msg), style="dim", highlight=False),
+        ) as client:
+            if args.verbose or args.test:
+                status.print(f"[dim]config: {config.path}[/]")
+                status.print(f"[dim]state:  {state_path}[/]")
+                status.print(f"[dim]client: {client.describe()}[/]")
+
+            result = run(
+                config,
+                state,
+                client,
+                only_sources=args.sources,
+                show_all=args.all,
+                since=since,
+                save=not (args.no_save or args.test),
+            )
+
+            if args.test:
+                status.print(
+                    f"\n[dim]{len(client.requested_urls)} request(s) planned; "
+                    "none sent.[/]"
+                )
+                return 0
+
+    if args.json:
+        print(json_out.render(result))
+    else:
+        terminal.render(result, console=console, verbose=args.verbose)
+
+    if args.rss:
+        rss_path = Path(args.rss).expanduser()
+        rss_path.parent.mkdir(parents=True, exist_ok=True)
+        rss_path.write_text(rss_out.render(result), encoding="utf-8")
+        status.print(f"[dim]Wrote {len(result.updates)} entries to {rss_path}[/]")
+
+    if args.fail_on_error and result.errors:
+        return 2
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    parser = build_parser()
+
+    # `youpdated` and `youpdated --json` = `check`.
+    if not argv or argv[0].startswith("-") and argv[0] not in ("-h", "--help", "--version"):
+        argv.insert(0, "check")
+
+    args = parser.parse_args(argv)
+    if args.command is None:
+        args = parser.parse_args(["check"])
+
+    console = Console()
+    try:
+        if args.command == "sources":
+            return cmd_sources(console)
+        if args.command == "init":
+            return cmd_init(args, console)
+        if args.command == "uninstall":
+            return cmd_uninstall(args, console)
+        return cmd_check(args, console)
+    except ConfigError as exc:
+        console.print(f"[red]Config error:[/] {exc}")
+        return 1
+    except KeyboardInterrupt:
+        console.print("\n[dim]interrupted[/]")
+        return 130

youpdated/config.py

@@ -0,0 +1,214 @@
+"""Config load validation.
+
+A source entry either bare scalar or a mapping
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+from platformdirs import PlatformDirs
+
+# appauthor=False for Windows: left unset, platformdirs falls back to app name as the author and nests everything under
+# AppData\Local\youpdated\youpdated. macOS and Linux are unaffected.
+_DIRS = PlatformDirs("youpdated", appauthor=False)
+
+DEFAULT_CONFIG_NAME = "config.yaml"
+
+
+class ConfigError(Exception):
+    """Raised with a message meant to be shown to the user."""
+
+
+@dataclass
+class PrivacyConfig:
+    proxy: str | None = None
+    user_agent: str = "rotate"
+    jitter: tuple[float, float] = (0.5, 3.0)
+    concurrency: int = 4
+    timeout: float = 20.0
+
+
+@dataclass
+class Config:
+    privacy: PrivacyConfig = field(default_factory=PrivacyConfig)
+    sources: dict[str, list[Any]] = field(default_factory=dict)
+    path: Path | None = None
+
+
+def config_dir() -> Path:
+    return Path(_DIRS.user_config_dir)
+
+
+def data_dir() -> Path:
+    return Path(_DIRS.user_data_dir)
+
+
+def default_config_path() -> Path:
+    return config_dir() / DEFAULT_CONFIG_NAME
+
+
+def default_state_path() -> Path:
+    return data_dir() / "state.sqlite3"
+
+
+def find_config(explicit: str | Path | None = None) -> Path | None:
+    """Resolve the config file to use: --config, then ./youpdated.yaml, then XDG."""
+    if explicit:
+        path = Path(explicit).expanduser()
+        if not path.is_file():
+            raise ConfigError(f"config file not found: {path}")
+        return path
+    for candidate in (
+        Path.cwd() / "youpdated.yaml",
+        Path.cwd() / "youpdated.yml",
+        default_config_path(),
+    ):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load_config(explicit: str | Path | None = None) -> Config:
+    path = find_config(explicit)
+    if path is None:
+        raise ConfigError(
+            "no config file found. Run `youpdated init` to create one at "
+            f"{default_config_path()}"
+        )
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"{path}: invalid YAML: {exc}") from exc
+    return parse_config(raw, path=path)
+
+
+def parse_config(raw: Any, path: Path | None = None) -> Config:
+    where = f"{path}: " if path else ""
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{where}top level must be a mapping")
+
+    privacy = _parse_privacy(raw.get("privacy") or {}, where)
+
+    sources_raw = raw.get("sources")
+    if sources_raw is None:
+        raise ConfigError(f"{where}missing required `sources:` section")
+    if not isinstance(sources_raw, dict):
+        raise ConfigError(f"{where}`sources` must be a mapping of source name -> list")
+
+    sources: dict[str, list[Any]] = {}
+    for name, entries in sources_raw.items():
+        if entries is None:
+            continue
+        if not isinstance(entries, list):
+            raise ConfigError(f"{where}`sources.{name}` must be a list")
+        if entries:
+            sources[str(name)] = entries
+
+    if not sources:
+        raise ConfigError(f"{where}`sources` has no entries — nothing to check")
+
+    return Config(privacy=privacy, sources=sources, path=path)
+
+
+def _parse_privacy(raw: Any, where: str) -> PrivacyConfig:
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{where}`privacy` must be a mapping")
+
+    privacy = PrivacyConfig()
+
+    proxy = raw.get("proxy")
+    if proxy is not None:
+        if not isinstance(proxy, str) or "://" not in proxy:
+            raise ConfigError(
+                f"{where}`privacy.proxy` must be a URL like socks5://127.0.0.1:9050"
+                # tor as example across project btw
+            )
+        privacy.proxy = proxy
+
+    ua = raw.get("user_agent")
+    if ua is not None:
+        if not isinstance(ua, str) or not ua.strip():
+            raise ConfigError(f"{where}`privacy.user_agent` must be 'rotate' or a UA string")
+        privacy.user_agent = ua
+
+    jitter = raw.get("jitter")
+    if jitter is not None:
+        if (
+            not isinstance(jitter, (list, tuple))
+            or len(jitter) != 2
+            or not all(isinstance(v, (int, float)) and v >= 0 for v in jitter)
+        ):
+            raise ConfigError(f"{where}`privacy.jitter` must be [min, max] non-negative seconds")
+        low, high = float(jitter[0]), float(jitter[1])
+        if low > high:
+            raise ConfigError(f"{where}`privacy.jitter` min must not exceed max")
+        privacy.jitter = (low, high)
+
+    for name, cast, check in (
+        ("concurrency", int, lambda v: v >= 1),
+        ("timeout", float, lambda v: v > 0),
+    ):
+        value = raw.get(name)
+        if value is None:
+            continue
+        if not isinstance(value, (int, float)) or isinstance(value, bool) or not check(cast(value)):
+            raise ConfigError(f"{where}`privacy.{name}` must be a positive number")
+        setattr(privacy, name, cast(value))
+
+    return privacy
+
+
+EXAMPLE_CONFIG = """\
+# youpdated config: every source entry is a bare value or a mapping.
+
+privacy:
+  # Route every request through a proxy. Works with Tor's default SOCKS port.
+  # proxy: socks5://127.0.0.1:9050
+  user_agent: rotate       # 'rotate' or a fixed UA string
+  jitter: [0.5, 3.0]       # random delay, in seconds, between hits on one host
+  concurrency: 4
+  timeout: 20
+
+sources:
+  github:
+    - python/cpython
+    - repo: astral-sh/uv
+      watch: [releases, commits]
+
+  npm:
+    - express
+    - "@types/node"
+
+  steam:
+    - 440
+    - appid: 730
+      name: Counter-Strike 2
+
+  itch:
+    # Watches devlog posts and new builds; most games have one.
+    - https://hempuli.itch.io/baba-is-you
+    - url: https://aak581.itch.io/engineering-marvels-from-hell
+      watch: [devlog, releases]
+
+  youtube:
+    - "@NASA"
+    # - playlist: PLxxxxxxxxxxxxxxxx
+
+  browser:
+    - chrome
+    - brave
+    - firefox
+    - browser: edge
+      platform: windows
+      channel: beta
+
+  # Anything else with a RSS/Atom feed
+  feed:
+    - https://blog.rust-lang.org/feed.xml
+    - url: https://github.com/obsidianmd/obsidian-releases/releases.atom
+      name: Obsidian
+"""