youpdated 0.1.0__tar.gz

youpdated-0.1.0/ADDING_SOURCES.md

@@ -0,0 +1,333 @@
+# Adding your own source
+
+A source is one class with two methods. This guide builds a complete, working one: a `pypi` source that reports new releases of a Python package.
+
+- [The contract](#the-contract)
+- [Two ways to add one](#two-ways-to-add-one)
+- [Step 1: normalize config into targets](#step-1-normalize-config-into-targets)
+- [Step 2: fetch updates](#step-2-fetch-updates)
+- [The complete source](#the-complete-source)
+- [Notes](#notes)
+- [Testing it](#testing-it)
+- [Shipping it as a package](#shipping-it-as-a-package)
+- [Checklist](#checklist)
+
+## The contract
+
+From [youpdated/sources/base.py](youpdated/sources/base.py):
+
+```python
+class Source(Protocol):
+    name: ClassVar[str]      # the key users write under `sources:` in config
+    summary: ClassVar[str]   # one line shown by `youpdated sources`
+
+    def targets(self, entries: list[Any]) -> list[Target]:
+        """Normalize raw config entries into targets."""
+
+    def fetch(self, target: Target, client: Client) -> Iterable[Update]:
+        """Fetch current items for one target."""
+```
+
+The split matters: `targets()` is pure config parsing and never touches the network, so `youpdated check --test` can validate a config without sending a request. `fetch()` does the network work and is called once per target, possibly on several threads at once.
+
+## Two ways to add one
+
+**In-tree** for a source you want in the project itself:
+
+1. Create `youpdated/sources/yourname.py`
+2. Decorate the class with `@register`
+3. Import it in [youpdated/sources/\_\_init\_\_.py](youpdated/sources/__init__.py)
+
+**As a separate package**: for a source you want to distribute without forking. Declare a
+`youpdated.sources` entry point and Youpdated finds it automatically; see
+[Shipping it as a package](#shipping-it-as-a-package).
+
+## Step 1: normalize config into targets
+
+Every source accepts two config shapes: a bare value and a mapping:
+
+```yaml
+sources:
+  pypi:
+    - httpx                    # bare
+    - package: rich            # mapping
+      name: Rich
+```
+
+`entry_fields()` collapses both into a dict, so you never branch on the shape yourself:
+
+```python
+from youpdated.models import Target
+from youpdated.sources.base import ConfigEntryError, entry_fields, require
+
+
+def targets(self, entries: list[Any]) -> list[Target]:
+    targets = []
+    for entry in entries:
+        # "httpx" becomes {"package": "httpx"}; a mapping passes through.
+        fields = entry_fields(entry, "package", self.name)
+        package = str(require(fields, "package", self.name)).strip()
+        if "/" in package or not package:
+            raise ConfigEntryError(f"sources.{self.name}: `{package}` is not a package name")
+        targets.append(
+            Target(source=self.name, key=package, label=fields.get("name"), params={})
+        )
+    return targets
+```
+
+A `Target` has four fields:
+
+| Field | Purpose |
+| --- | --- |
+| `source` | Your source's `name`. |
+| `key` | **Stable identity.** Scopes deduplication and appears in reports. Never let it vary between runs for the same thing. |
+| `label` | Optional friendly name. Falls back to `key`. May be filled in during `fetch()` once you learn it. |
+| `params` | Anything `fetch()` needs (resolved URLs, watch lists, channel names) |
+
+Raise `ConfigEntryError` for anything you can't parse. The message is shown to the user verbatim,
+so name the offending value and say what was expected.
+
+## Step 2: fetch updates
+
+`fetch()` gets one target and the shared `Client`. **Always use that client** never `httpx` or `requests` directly. It applies the user's proxy, rotates user agents, paces requests per host, and clears cookies.
+
+```python
+def fetch(self, target: Target, client: Client) -> Iterable[Update]:
+    fetched = client.get(f"https://pypi.org/pypi/{target.key}/json", conditional=True)
+    if fetched is None:          # 304 Not Modified, or --test mode
+        return []
+    doc = fetched.json()
+    ...
+```
+
+`client.get()` returns a `Fetched` (with `.content`, `.text`, `.json()`, `.status`) or `None`.
+Useful arguments:
+
+| Argument | Use for |
+| --- | --- |
+| `conditional=True` | Send ETag/Last-Modified and get `None` on a 304. Use it for anything polled repeatedly. |
+| `soft_statuses=(404,)` | Return the response instead of raising, when a status is expected. itch answers 404 for a game with no devlog. |
+| `headers={...}` | Extra request headers. The user agent is added for you. |
+| `retries=0` | Skip retries when you're probing a fallback and want to fail fast. |
+
+Any other non-200 raises `FetchError`, which the runner catches and reports without killing.
+
+If the feed is RSS or Atom, don't parse it yourself:
+
+```python
+from youpdated.sources.feed import parse_feed
+
+return parse_feed(fetched.content, source=self.name, target=target.key, tags=("release",))
+```
+
+## The complete source
+
+```python
+"""A example Youpdated source for PyPI package releases."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, ClassVar, Iterable
+
+from youpdated.http import Client
+from youpdated.models import Target, Update
+from youpdated.registry import register
+from youpdated.sources.base import ConfigEntryError, entry_fields, require
+
+MAX_VERSIONS = 10
+
+
+@register
+class PyPISource:
+    name: ClassVar[str] = "pypi"
+    summary: ClassVar[str] = "New releases of a PyPI package"
+
+    def targets(self, entries: list[Any]) -> list[Target]:
+        targets = []
+        for entry in entries:
+            fields = entry_fields(entry, "package", self.name)
+            package = str(require(fields, "package", self.name)).strip()
+            if "/" in package or not package:
+                raise ConfigEntryError(f"sources.{self.name}: `{package}` is not a package name")
+            targets.append(
+                Target(source=self.name, key=package, label=fields.get("name"), params={})
+            )
+        return targets
+
+    def fetch(self, target: Target, client: Client) -> Iterable[Update]:
+        fetched = client.get(f"https://pypi.org/pypi/{target.key}/json", conditional=True)
+        if fetched is None:
+            return []
+
+        doc = fetched.json()
+        latest = doc["info"]["version"]
+
+        dated = []
+        for version, files in (doc.get("releases") or {}).items():
+            if not files or all(f.get("yanked") for f in files):
+                continue
+            dated.append((version, _parse_iso(files[0].get("upload_time_iso_8601"))))
+        dated.sort(
+            key=lambda pair: pair[1] or datetime.min.replace(tzinfo=timezone.utc), reverse=True
+        )
+
+        return [
+            Update(
+                source=self.name,
+                target=target.key,
+                uid=f"version:{version}",
+                title=f"{target.key} {version}",
+                url=f"https://pypi.org/project/{target.key}/{version}/",
+                published=published,
+                version=version,
+                body=doc["info"].get("summary"),
+                tags=("release",) + (("latest",) if version == latest else ()),
+            )
+            for version, published in dated[:MAX_VERSIONS]
+        ]
+
+
+def _parse_iso(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+```
+
+## Notes
+
+### The uid is the deduplication system
+
+`uid` decides whether an item is "new".
+
+- **Stable** across runs for the same item. Derive it from an upstream id, version, or permalink.
+- **Don't** derive it from anything that changes on its own: a timestamp, a position in a list, a relative date, a view count, `hash()` (randomized per process).
+- Unique **within a target** only. Deduplication is scoped to `(source, target, uid)`, so two packages can both use `version:1.0`.
+
+```python
+uid=f"version:{version}"        # good: stable, tied to the item
+uid=f"{datetime.now()}"         # broken: new every run, reports forever
+uid=str(index)                  # broken: shifts as items are added
+```
+
+When an upstream gives you no id at all, fingerprint the content: hash the fields that define the item. [itch.py](youpdated/sources/itch.py) does this for game builds: filenames, sizes, and the update timestamp hash into one uid.
+
+### Filling in a label during fetch
+
+Sometimes the friendly name is only available from the response. Assign it to `target.label`; the renderers pick it up:
+
+```python
+if not target.label:
+    target.label = doc["info"].get("name")
+```
+
+### Caching a resolved value
+
+`client.state` is a small key-value store for things that are expensive to resolve and never change: the Steam source caches appid→name there, so it looks it up once ever:
+
+```python
+cached = client.state.cache_get("my_namespace", key) if client.state else None
+if cached is None:
+    cached = expensive_lookup()
+    if client.state:
+        client.state.cache_set("my_namespace", key, cached)
+```
+
+`client.state` may be `None`
+
+### Thread
+
+Targets are fetched concurrently. Keep everything in local variables or on the `Target`; don't mutate shared state on the source instance.
+
+## Testing it
+
+The suite is offline. `respx` intercepts requests and fails on anything unmocked.
+
+Save a real payload as a fixture:
+
+```sh
+curl -s https://pypi.org/pypi/httpx/json -o tests/fixtures/pypi_httpx.json
+```
+
+Then test against it. The `client` fixture from [tests/conftest.py](tests/conftest.py) gives you a zero-jitter client with in-memory state:
+
+```python
+import httpx
+import respx
+
+from youpdated.registry import get_source
+from .conftest import fixture
+
+
+@respx.mock
+def test_pypi_releases(client):
+    respx.get("https://pypi.org/pypi/httpx/json").mock(
+        return_value=httpx.Response(200, content=fixture("pypi_httpx.json"))
+    )
+    source = get_source("pypi")
+    (target,) = source.targets(["httpx"])
+    updates = list(source.fetch(target, client))
+
+    assert updates
+    assert all(u.uid == f"version:{u.version}" for u in updates)
+    assert sum("latest" in u.tags for u in updates) == 1
+    dated = [u.published for u in updates if u.published]
+    assert dated == sorted(dated, reverse=True)      # newest first
+```
+
+Worth covering explicitly:
+
+- Both config shapes normalize to the same `key`
+- Bad entries raise `ConfigEntryError`
+- Uids are stable: fetch the same payload twice, compare uids
+- Any expected-error path (a soft 404 returning `[]` rather than raising)
+
+Run with `PYTHONPATH=$PWD .venv/bin/python -m pytest` (on Windows,
+`$env:PYTHONPATH=$PWD; .venv\Scripts\python -m pytest`).
+
+## Shipping it as a package
+
+Youpdated discovers sources through the `youpdated.sources` entry point group, so a plugin needs
+no changes to this repo:
+
+```toml
+# pyproject.toml of your plugin package
+[project]
+name = "youpdated-pypi"
+version = "0.1.0"
+dependencies = ["youpdated"]
+
+[project.entry-points."youpdated.sources"]
+pypi = "youpdated_pypi:PyPISource"
+```
+
+Install it alongside Youpdated and it appears immediately:
+
+```console
+$ pip install youpdated-pypi
+$ youpdated sources
+  ...
+  pypi       New releases of a PyPI package
+```
+
+Users then configure it like any built-in source. A plugin that fails to import is skipped.
+
+## Checklist
+
+- [ ] `name` and `summary` set as `ClassVar`s
+- [ ] `targets()` does no network I/O
+- [ ] Both config shapes accepted via `entry_fields()`
+- [ ] Bad config raises `ConfigEntryError` naming the bad value
+- [ ] `key` is stable across runs
+- [ ] `uid` is stable and derived from the item, never from the clock or list position
+- [ ] All requests go through `client.get()`
+- [ ] `conditional=True` on anything polled repeatedly
+- [ ] Expected non-200s handled with `soft_statuses`; real failures left to raise
+- [ ] Returns `[]` rather than inventing an update
+- [ ] `published` is timezone-aware UTC (or `None`)
+- [ ] Tests cover parsing, both config shapes, and uid stability
+- [ ] Registered — `@register` plus an import, or an entry point

youpdated-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-08-18
+
+First release.
+
+### Added
+
+- **Seven sources**, all working without accounts or API keys:
+  - `github` — releases, tags, and commits via `.atom` feeds
+  - `npm` — newly published versions from public registry
+  - `steam` — patch notes and news; resolves the store name from a bare appid
+  - `itch` — devlog posts and new builds, fingerprinted from the game page
+  - `youtube` — channels and playlists, with Invidious and Data API fallback
+  - `browser` — Chrome, Brave, Firefox, and Edge releases across platforms and channels
+  - `feed` — any RSS/Atom URL, for apps without a dedicated source
+- **Plugin architecture**: sources register in-tree with `@register` or ship from a third-party package through a `youpdated.sources` entry point.
+- **Config**: every source entry takes a bare value for the common case or a
+  mapping for advanced options
+- **Incremental reporting**: a SQLite history so each run reports what changed. First run records a baseline.
+- **Three output formats**: terminal report, `--json`, and `--rss`
+- **Privacy controls**: optional SOCKS/HTTP proxy covering every request, user-agent rotation, per-host request pacing with jitter, per-request cookie clearing, and conditional GETs. `--test` prints URLs without sending
+- **`youpdated uninstall`** to remove every file from the tool. Refuses directories it didn't create or have other files.
+
+### Known issues
+
+- YouTube's RSS endpoint throttles occassionaly and 404s valid URLs; fallback covers, but a run can still fail all three. Retry or set `privacy.proxy`.
+- Some itch games publish no "Updated" timestamp, so build updates are reported undated.
+- Firefox publishes current versions, so it reports one item per channel.
+- Edge exposes release notes only for the stable and beta channels. (But like, it's Edge, why do you want to know when it updates?)
+
+[0.1.0]: https://github.com/Void1-1/youpdated/releases/tag/v0.1.0

youpdated-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+Thanks for looking. This is a small project with a few constraints.
+
+## The constraints
+
+These are the reasons the tool exists, so a change that breaks one needs a strong argument:
+
+1. **No accounts, no required API keys.** Every source works unauthenticated. Keys are read from the environment when present, only to raise rate limits, and are never written to disk.
+2. **Nothing leaves the machine** except requests to the sources the user configured. No telemetry, no crash reporting, no update checks for Youpdated itself.
+3. **One HTTP path.** Every request goes through `client.get()` in [youpdated/http.py](youpdated/http.py).
+4. **Files stay in the platform's config and data directories.** Nowhere else.
+
+## Setting up
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install ".[dev]"
+PYTHONPATH=$PWD .venv/bin/python -m pytest
+```
+
+`PYTHONPATH=$PWD` makes your working tree take effect without reinstalling. On Windows:
+`$env:PYTHONPATH=$PWD; .venv\Scripts\python -m pytest`.
+
+## Sending a change
+
+`main` requires a pull request with passing CI:
+
+```sh
+git switch -c my-change
+# work, commit
+git push -u origin my-change
+gh pr create --fill
+```
+
+CI runs the suite on Linux, macOS, and Windows across Python 3.11–3.14. All 13 jobs must be green, and the branch must be up to date with `main`. No review approvals are required.
+
+## Tests
+
+The suite is **fully offline**. `respx` intercepts HTTP and fails on any unmocked request, so a green run proves the parsers work rather than that the network happened to be up. Keep it that way: capture a real payload into [tests/fixtures/](tests/fixtures/) and test against that.
+
+```sh
+curl -s https://example.com/api/thing -o tests/fixtures/thing.json
+```
+
+Trim large fixtures to the part that matters.
+
+## Adding a source
+
+Read [ADDING_SOURCES.md](ADDING_SOURCES.md), it builds a complete working source.
+
+## Style
+
+Match the surrounding code rather than a style guide. Concretely:
+
+- Type annotations throughout, with `from __future__ import annotations`
+- Comments should explain why, especially where the code looks odd because an upstream service is odd.
+  The Brave source reads the REST API instead of the atom feed for a reason and that reason is a comment.
+- Errors that reach the user name the offending value and say what was expected
+- A source raises on genuine failure: the runner catches it and reports without killing the run and returns `[]` when it's working but has nothing to report
+
+## Reporting things
+
+Issue templates cover bugs, feature requests, and new-source requests. For security, see
+[SECURITY.md](SECURITY.md) and use private vulnerability reporting rather than a public issue.
+
+## Use of AI
+
+If you want to use AI to code for you or aid in your coding when contributing here, that's fine, just actually read it's output before submitting anything. No bloat or bad code is a goal you need to try to keep to.
+
+Also, if you could acknowledge what AI did, that would be great!

youpdated-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Void1-1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

youpdated-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include SECURITY.md
+include CONTRIBUTING.md
+include ADDING_SOURCES.md
+include youpdated/py.typed
+
+prune tests
+prune .venv
+global-exclude __pycache__ *.py[cod] *.sqlite3