youpdated 0.1.0__py3-none-any.whl

youpdated/sources/github.py

@@ -0,0 +1,158 @@
+"""GitHub releases, tags, and commits.
+
+``.atom`` endpoints don't need credentials and no rate-limit (default here)
+``GITHUB_TOKEN`` in the environment switches to the REST API, which has better release info
+
+COMMONLY RATE LIMITED!
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from datetime import datetime, timezone
+from typing import Any, ClassVar, Iterable
+
+from ..http import Client
+from ..models import Target, Update
+from ..registry import register
+from .base import ConfigEntryError, entry_fields, require
+from .feed import html_to_text, parse_feed
+
+REPO_RE = re.compile(r"^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$")
+VALID_WATCH = ("releases", "tags", "commits")
+
+
+def _normalize_repo(value: Any, source: str) -> str:
+    text = str(value).strip().rstrip("/")
+    # Accept a full URL as well as owner/repo.
+    match = re.search(r"github\.com/([A-Za-z0-9._-]+/[A-Za-z0-9._-]+)", text)
+    if match:
+        text = match.group(1)
+    if not REPO_RE.match(text):
+        raise ConfigEntryError(
+            f"sources.{source}: `{value}` is not an owner/repo or a github.com URL"
+        )
+    return text
+
+
+@register
+class GitHubSource:
+    name: ClassVar[str] = "github"
+    summary: ClassVar[str] = "Releases, tags, and commits for a repository"
+
+    def targets(self, entries: list[Any]) -> list[Target]:
+        targets = []
+        for entry in entries:
+            fields = entry_fields(entry, "repo", self.name)
+            repo = _normalize_repo(require(fields, "repo", self.name), self.name)
+
+            watch = fields.get("watch") or ["releases"]
+            if isinstance(watch, str):
+                watch = [watch]
+            unknown = [w for w in watch if w not in VALID_WATCH]
+            if unknown:
+                raise ConfigEntryError(
+                    f"sources.{self.name}: unknown watch {unknown} for {repo}; "
+                    f"valid options are {list(VALID_WATCH)}"
+                )
+
+            targets.append(
+                Target(
+                    source=self.name,
+                    key=repo,
+                    label=fields.get("name"),
+                    params={"watch": list(watch), "branch": fields.get("branch")},
+                )
+            )
+        return targets
+
+    def fetch(self, target: Target, client: Client) -> Iterable[Update]:
+        watch = target.params.get("watch") or ["releases"]
+        token = os.environ.get("GITHUB_TOKEN")
+        updates: list[Update] = []
+
+        for kind in watch:
+            if kind == "releases" and token:
+                updates.extend(self._releases_via_api(target, client, token))
+            elif kind == "releases":
+                updates.extend(self._atom(target, client, "releases.atom", "release"))
+            elif kind == "tags":
+                updates.extend(self._atom(target, client, "tags.atom", "tag"))
+            elif kind == "commits":
+                branch = target.params.get("branch")
+                path = f"commits/{branch}.atom" if branch else "commits.atom"
+                updates.extend(self._atom(target, client, path, "commit"))
+
+        return updates
+
+    # anon path
+
+    def _atom(self, target: Target, client: Client, path: str, tag: str) -> list[Update]:
+        url = f"https://github.com/{target.key}/{path}"
+        fetched = client.get(url, conditional=True)
+        if fetched is None:  # 304 Not Modified, or test run
+            return []
+        return parse_feed(
+            fetched.content,
+            source=self.name,
+            target=target.key,
+            version_of=_version_from_entry if tag != "commit" else None,
+            tags=(tag,),
+        )
+
+    # authed path
+
+    def _releases_via_api(self, target: Target, client: Client, token: str) -> list[Update]:
+        url = f"https://api.github.com/repos/{target.key}/releases?per_page=20"
+        fetched = client.get(
+            url,
+            conditional=True,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+        )
+        if fetched is None:
+            return []
+
+        updates = []
+        for release in fetched.json():
+            if release.get("draft"):
+                continue
+            published = release.get("published_at") or release.get("created_at")
+            updates.append(
+                Update(
+                    source=self.name,
+                    target=target.key,
+                    uid=f"release:{release['id']}",
+                    title=(release.get("name") or release.get("tag_name") or "").strip()
+                    or "(untitled)",
+                    url=release.get("html_url", ""),
+                    published=_parse_iso(published),
+                    version=release.get("tag_name"),
+                    body=html_to_text(release.get("body")),
+                    tags=("release",) + (("prerelease",) if release.get("prerelease") else ()),
+                )
+            )
+        return updates
+
+
+def _version_from_entry(entry: Any) -> str | None:
+    """Recover the tag from an atom entry id like ``tag:github.com,...:Repository/1/v3.13.0``."""
+    for candidate in (entry.get("id", ""), entry.get("link", "")):
+        match = re.search(r"[/:]([^/:]*\d[^/:]*)$", str(candidate))
+        if match:
+            return match.group(1)
+    return None
+
+
+def _parse_iso(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)

youpdated/sources/itch.py

@@ -0,0 +1,210 @@
+"""itch.io devlogs and builds.
+
+Two watched per game:
+- devlogs (``<game-url>/devlog.rss``): itch answers 404 when a game doesn't have one, which is normal and not an error
+- releases: many games ship new builds without a devlog, so 404 above moves here. The game page has "Updated" timestamps 
+  and the list of downloadable files; they fingerprint the current build, and a change means a new release.
+
+Both are on by default. ``watch: [devlog]`` or ``watch: [releases]`` to choose
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import datetime, timezone
+from typing import Any, ClassVar, Iterable
+
+from ..http import Client
+from ..models import Target, Update
+from ..registry import register
+from .base import ConfigEntryError, entry_fields, require
+from .feed import parse_feed
+
+GAME_URL_RE = re.compile(
+    r"^(?:https?://)?(?P<user>[A-Za-z0-9-]+)\.itch\.io/(?P<game>[A-Za-z0-9._-]+)/?$"
+)
+
+# info panel: <tr><td>Updated</td><td><abbr title="17 August 2026 @ 10:34 UTC">…
+INFO_ROW_RE = re.compile(r"<td>([^<]{1,30})</td><td>(.{0,400}?)</td>", re.S)
+ABBR_TITLE_RE = re.compile(r'<abbr title="([^"]+)"')
+UPLOAD_NAME_RE = re.compile(r'<strong title="([^"]*)" class="name">')
+UPLOAD_SIZE_RE = re.compile(r'class="file_size"><span>([^<]*)</span>')
+ITCH_DATE_RE = re.compile(
+    r"(\d{1,2})\s+([A-Za-z]+)\s+(\d{4})(?:\s*@\s*(\d{1,2}):(\d{2}))?", re.I
+)
+
+MONTHS = {
+    m.lower(): i
+    for i, m in enumerate(
+        [
+            "January", "February", "March", "April", "May", "June",
+            "July", "August", "September", "October", "November", "December",
+        ],
+        start=1,
+    )
+}
+
+VALID_WATCH = ("devlog", "releases")
+
+
+@register
+class ItchSource:
+    name: ClassVar[str] = "itch"
+    summary: ClassVar[str] = "Devlog posts and new builds for an itch.io game"
+
+    def targets(self, entries: list[Any]) -> list[Target]:
+        targets = []
+        for entry in entries:
+            fields = entry_fields(entry, "url", self.name)
+
+            if fields.get("user") and fields.get("game"):
+                user, game = str(fields["user"]).strip(), str(fields["game"]).strip()
+            else:
+                raw = str(require(fields, "url", self.name)).strip()
+                match = GAME_URL_RE.match(raw)
+                if not match:
+                    raise ConfigEntryError(
+                        f"sources.{self.name}: `{raw}` is not an itch.io game URL "
+                        "(expected https://user.itch.io/game)"
+                    )
+                user, game = match.group("user"), match.group("game")
+
+            watch = fields.get("watch") or list(VALID_WATCH)
+            if isinstance(watch, str):
+                watch = [watch]
+            unknown = [w for w in watch if w not in VALID_WATCH]
+            if unknown:
+                raise ConfigEntryError(
+                    f"sources.{self.name}: unknown watch {unknown} for {user}/{game}; "
+                    f"valid options are {list(VALID_WATCH)}"
+                )
+
+            targets.append(
+                Target(
+                    source=self.name,
+                    key=f"{user}/{game}",
+                    label=fields.get("name") or game.replace("-", " "),
+                    params={
+                        "page": f"https://{user}.itch.io/{game}",
+                        "watch": list(watch),
+                    },
+                )
+            )
+        return targets
+
+    def fetch(self, target: Target, client: Client) -> Iterable[Update]:
+        watch = target.params.get("watch") or list(VALID_WATCH)
+        updates: list[Update] = []
+        if "devlog" in watch:
+            updates.extend(self._devlog(target, client))
+        if "releases" in watch:
+            updates.extend(self._release(target, client))
+        return updates
+
+    # devlog feed
+
+    def _devlog(self, target: Target, client: Client) -> list[Update]:
+        url = f"{target.params['page']}/devlog.rss"
+        fetched = client.get(url, conditional=True, soft_statuses=(404,))
+        if fetched is None:
+            return []
+        if fetched.status == 404:
+            # No devlog has ever been posted for this game
+            return []
+
+        return parse_feed(
+            fetched.content,
+            source=self.name,
+            target=target.key,
+            tags=("devlog",),
+        )
+
+    # build fingerprint from the game page
+
+    def _release(self, target: Target, client: Client) -> list[Update]:
+        page = target.params["page"]
+        fetched = client.get(page, conditional=True, soft_statuses=(404,))
+        if fetched is None or fetched.status == 404:
+            return []
+
+        html = fetched.text
+        info = self._info_rows(html)
+        uploads = self._uploads(html)
+        updated = _parse_itch_date(info.get("Updated") or info.get("Published"))
+        version = info.get("Version")
+
+        # Nothing observable on page
+        if not uploads and updated is None and not version:
+            return []
+
+        # Any change to the build produces a different uid
+        fingerprint = "|".join(
+            [
+                updated.isoformat() if updated else "",
+                version or "",
+                *(f"{name}:{size}" for name, size in uploads),
+            ]
+        )
+        digest = hashlib.sha256(fingerprint.encode("utf-8")).hexdigest()[:16]
+
+        if version:
+            title = f"New build — {version}"
+        elif uploads:
+            title = f"New build — {len(uploads)} file(s)"
+        else:
+            title = "Game page updated"
+
+        body = ", ".join(f"{name} ({size})" for name, size in uploads) or None
+
+        return [
+            Update(
+                source=self.name,
+                target=target.key,
+                uid=f"build:{digest}",
+                title=title,
+                url=page,
+                published=updated,
+                version=version,
+                body=body,
+                tags=("release",),
+            )
+        ]
+
+    def _info_rows(self, html: str) -> dict[str, str]:
+        """Pull "More information" table into a plain dict.
+
+        Values keep their timestamp when supplied. (visible text is relative ("20 hours ago") fyi)
+        """
+        rows: dict[str, str] = {}
+        for key, cell in INFO_ROW_RE.findall(html):
+            key = key.strip()
+            if key in rows:
+                continue
+            abbr = ABBR_TITLE_RE.search(cell)
+            value = abbr.group(1) if abbr else re.sub(r"<[^>]+>", "", cell).strip()
+            if value:
+                rows[key] = value
+        return rows
+
+    def _uploads(self, html: str) -> list[tuple[str, str]]:
+        names = UPLOAD_NAME_RE.findall(html)
+        sizes = UPLOAD_SIZE_RE.findall(html)
+        # Sizes can be missing for some entries
+        return [(n, sizes[i] if i < len(sizes) else "") for i, n in enumerate(names)]
+
+
+def _parse_itch_date(value: str | None) -> datetime | None:
+    """Parse itch's "17 August 2026 @ 10:34 UTC" (time optional)."""
+    if not value:
+        return None
+    match = ITCH_DATE_RE.search(value)
+    if not match:
+        return None
+    day, month_name, year, hour, minute = match.groups()
+    month = MONTHS.get(month_name.lower())
+    if month is None:
+        return None
+    return datetime(
+        int(year), month, int(day), int(hour or 0), int(minute or 0), tzinfo=timezone.utc
+    )

youpdated/sources/npm.py

@@ -0,0 +1,88 @@
+"""npm package releases from the public registry."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, ClassVar, Iterable
+from urllib.parse import quote
+
+from ..http import Client
+from ..models import Target, Update
+from ..registry import register
+from .base import ConfigEntryError, entry_fields, require
+
+# keys alongside real versions in the registry `time` map
+_NON_VERSION_KEYS = {"created", "modified"}
+MAX_VERSIONS = 10
+
+
+@register
+class NpmSource:
+    name: ClassVar[str] = "npm"
+    summary: ClassVar[str] = "New published versions of a 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 not package or package.startswith("."):
+                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={"tag": fields.get("tag")},
+                )
+            )
+        return targets
+
+    def fetch(self, target: Target, client: Client) -> Iterable[Update]:
+        # name keeps @ but slash escaped
+        url = f"https://registry.npmjs.org/{quote(target.key, safe='@')}"
+        fetched = client.get(url, conditional=True)
+        if fetched is None:
+            return []
+
+        doc = fetched.json()
+        latest = (doc.get("dist-tags") or {}).get("latest")
+        only_tag = target.params.get("tag")
+        if only_tag:
+            wanted = (doc.get("dist-tags") or {}).get(only_tag)
+            versions = [wanted] if wanted else []
+        else:
+            versions = [v for v in (doc.get("time") or {}) if v not in _NON_VERSION_KEYS]
+
+        times = doc.get("time") or {}
+        dated = [(v, _parse_iso(times.get(v))) for v in versions if v]
+        dated.sort(key=lambda pair: pair[1] or datetime.min.replace(tzinfo=timezone.utc), reverse=True)
+
+        updates = []
+        for version, published in dated[:MAX_VERSIONS]:
+            meta = (doc.get("versions") or {}).get(version) or {}
+            tags = ("release",) if version == latest else ()
+            updates.append(
+                Update(
+                    source=self.name,
+                    target=target.key,
+                    uid=f"version:{version}",
+                    title=f"{target.key} {version}",
+                    url=f"https://www.npmjs.com/package/{target.key}/v/{version}",
+                    published=published,
+                    version=version,
+                    body=meta.get("description") or doc.get("description"),
+                    tags=tags + (("latest",) if version == latest else ()),
+                )
+            )
+        return updates
+
+
+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)

youpdated/sources/steam.py

@@ -0,0 +1,88 @@
+"""Steam patch notes and news for a game.
+
+Config can be an appid; the store name is resolved and cached locally so reports stay readable
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, ClassVar, Iterable
+
+from ..http import Client, FetchError
+from ..models import Target, Update
+from ..registry import register
+from .base import ConfigEntryError, entry_fields, require
+from .feed import parse_feed
+
+NAME_CACHE = "steam_app_names"
+
+
+@register
+class SteamSource:
+    name: ClassVar[str] = "steam"
+    summary: ClassVar[str] = "Patch notes and news for Steam games"
+
+    def targets(self, entries: list[Any]) -> list[Target]:
+        targets = []
+        for entry in entries:
+            fields = entry_fields(entry, "appid", self.name)
+            raw = str(require(fields, "appid", self.name)).strip()
+            # Accept store URL and id
+            match = re.search(r"(?:app/)?(\d+)", raw)
+            if not match:
+                raise ConfigEntryError(
+                    f"sources.{self.name}: `{raw}` is not an appid or a store URL"
+                )
+            appid = match.group(1)
+            targets.append(
+                Target(
+                    source=self.name,
+                    key=appid,
+                    label=fields.get("name"),
+                    params={},
+                )
+            )
+        return targets
+
+    def fetch(self, target: Target, client: Client) -> Iterable[Update]:
+        if not target.label:
+            target.label = self._app_name(target.key, client)
+
+        url = (
+            f"https://store.steampowered.com/feeds/news/app/{target.key}/"
+            "?cc=US&l=english"
+        )
+        fetched = client.get(url, conditional=True)
+        if fetched is None:
+            return []
+
+        return parse_feed(
+            fetched.content,
+            source=self.name,
+            target=target.key,
+            tags=("news",),
+        )
+
+    def _app_name(self, appid: str, client: Client) -> str | None:
+        """Resolve store name once then cache"""
+        state = client.state
+        if state is not None:
+            cached = state.cache_get(NAME_CACHE, appid)
+            if cached:
+                return cached
+        try:
+            fetched = client.get(
+                f"https://store.steampowered.com/api/appdetails?appids={appid}&l=english"
+            )
+        except FetchError:
+            return None
+        if fetched is None:
+            return None
+        try:
+            payload = fetched.json().get(appid) or {}
+            name = (payload.get("data") or {}).get("name")
+        except (ValueError, AttributeError):
+            return None
+        if name and state is not None:
+            state.cache_set(NAME_CACHE, appid, name)
+        return name