pagequiet 0.1.0__tar.gz

pagequiet-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 User0856
+
+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.

pagequiet-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: pagequiet
+Version: 0.1.0
+Summary: Website change detection that stays quiet until something real changes.
+Author: User0856
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/User0856/pagequiet
+Project-URL: Issues, https://github.com/User0856/pagequiet/issues
+Keywords: website monitoring,change detection,web page diff,playwright,screenshot,visualping alternative
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management :: Link Checking
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.40; extra == "playwright"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# pagequiet
+
+Website change detection that stays quiet until something real changes.
+
+Most change monitors compare HTML, so they alert on every rotating ad slot, CSRF token and "updated 3 minutes ago". After a week nobody reads the alerts. `pagequiet` compares what a reader sees instead: the rendered text of one element on the page, with relative times, counters and whitespace stripped. When that changes, you get the changed lines and a full-page screenshot of the new version.
+
+```
+$ pagequiet check
+CHANGED example-com-pricing https://example.com/pricing
+  - Pro $49 / month
+  + Pro $59 / month
+  screenshot: .pagequiet/captures/example-com-pricing-20261005T080012Z.png
+1 changed, 11 unchanged, 0 new, 0 errors
+```
+
+It is a single command with a TOML file, built for cron and CI: exit code 1 means something changed.
+
+## Install
+
+```bash
+pip install "pagequiet[playwright]"
+playwright install chromium
+```
+
+Python 3.11 or later. The Playwright extra renders pages with a local Chromium and costs nothing. If you would rather not run a browser (CI runners, small servers), see [Renderers](#renderers).
+
+## Quick start
+
+```bash
+pagequiet init        # writes pagequiet.toml
+# edit the [[page]] entries
+pagequiet check       # first run records a baseline
+pagequiet check       # later runs report changes
+```
+
+## Configuration
+
+```toml
+[settings]
+renderer = "playwright"           # or "snaprender"
+state = ".pagequiet/state.json"   # last text and fingerprint per page
+captures = ".pagequiet/captures"  # full-page screenshot of each new version
+notify = ["stdout", "slack"]      # stdout, slack, webhook
+timeout = 45                      # seconds per page
+use_default_noise = true          # strip relative times, timestamps, view counters
+
+[[page]]
+url = "https://example.com/pricing"
+selector = "main"                          # watch one element, not the whole page
+ignore = ['Offer ends in \d+ days']        # extra regex patterns removed before comparing
+hide = [".testimonial-carousel"]           # hidden before text and screenshot
+
+[[page]]
+url = "https://example.com/legal/terms"
+selector = "article"
+screenshot = false                         # text only
+```
+
+Notifiers read their targets from the environment:
+
+| Notifier | Variable | Sends |
+|---|---|---|
+| `stdout` | none | the changed lines and screenshot path |
+| `slack` | `PAGEQUIET_SLACK_WEBHOOK` | a message to a Slack incoming webhook |
+| `webhook` | `PAGEQUIET_WEBHOOK_URL` | JSON: `{"event": "page.changed", "name", "url", "changes", "screenshot"}` |
+
+Exit codes: `0` nothing changed, `1` at least one page changed, `2` errors and no changes.
+
+## What counts as a change
+
+1. Render the page and take the visible text of `selector` (default `body`).
+2. Remove noise: relative times ("5 minutes ago", "just now"), ISO timestamps and clock times, view and visitor counters, extra whitespace, plus your `ignore` patterns.
+3. Hash the result. Same hash as last run: quiet. Different: report the changed lines and take a screenshot.
+
+The defaults are deliberately few. Every pattern you strip is a kind of change you will never be told about, so add `ignore` patterns only after you have seen one cause a false alarm. If timestamps on a page are meaningful to you, set `use_default_noise = false`.
+
+The biggest single improvement is `selector`. Watching `main` or the pricing table instead of the whole page ignores navigation, footers and "latest posts" widgets that change for reasons you do not care about.
+
+A failed render or an empty selector is reported as an error and never as a change, and the previous text is kept, so a flaky site does not produce a false alarm the next time it loads.
+
+## Renderers
+
+**`playwright`** (default) runs Chromium locally through Playwright. Free, private, and fine for most pages. Cookie consent banners are part of the page, so if one varies between visits, scope `selector` to the content or add the banner to `hide`.
+
+**`snaprender`** uses the hosted [SnapRender](https://snap-render.com) API to render pages, so no browser runs on your machine. Cookie banners and ads are removed before the text and screenshot are taken. It needs `SNAPRENDER_API_KEY`; the free plan covers 200 renders a month. Each check is one render, plus one when a page changed. Disclosure: I build SnapRender. `pagequiet` works fully without it and always will.
+
+## Run it on a schedule
+
+Cron, every six hours:
+
+```bash
+0 */6 * * * cd /opt/watch && pagequiet check -q >> pagequiet.log 2>&1
+```
+
+GitHub Actions, keeping state in the repository: see [`examples/github-actions.yml`](examples/github-actions.yml). Scheduled workflows run at most every five minutes, can start late at busy times, and are paused in public repositories after 60 days without activity; committing the state file each run counts as activity.
+
+## Limits
+
+- Pages behind a login are not supported.
+- Text comparison misses purely visual changes (a new image, a broken layout). Compare the screenshots in `captures/` for those, or keep `screenshot = true` and review them when text changes.
+- `hide` applies to the SnapRender renderer's screenshots only; scope its text with `selector`.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev,playwright]"
+pytest
+```
+
+MIT licensed.

pagequiet-0.1.0/README.md

@@ -0,0 +1,111 @@
+# pagequiet
+
+Website change detection that stays quiet until something real changes.
+
+Most change monitors compare HTML, so they alert on every rotating ad slot, CSRF token and "updated 3 minutes ago". After a week nobody reads the alerts. `pagequiet` compares what a reader sees instead: the rendered text of one element on the page, with relative times, counters and whitespace stripped. When that changes, you get the changed lines and a full-page screenshot of the new version.
+
+```
+$ pagequiet check
+CHANGED example-com-pricing https://example.com/pricing
+  - Pro $49 / month
+  + Pro $59 / month
+  screenshot: .pagequiet/captures/example-com-pricing-20261005T080012Z.png
+1 changed, 11 unchanged, 0 new, 0 errors
+```
+
+It is a single command with a TOML file, built for cron and CI: exit code 1 means something changed.
+
+## Install
+
+```bash
+pip install "pagequiet[playwright]"
+playwright install chromium
+```
+
+Python 3.11 or later. The Playwright extra renders pages with a local Chromium and costs nothing. If you would rather not run a browser (CI runners, small servers), see [Renderers](#renderers).
+
+## Quick start
+
+```bash
+pagequiet init        # writes pagequiet.toml
+# edit the [[page]] entries
+pagequiet check       # first run records a baseline
+pagequiet check       # later runs report changes
+```
+
+## Configuration
+
+```toml
+[settings]
+renderer = "playwright"           # or "snaprender"
+state = ".pagequiet/state.json"   # last text and fingerprint per page
+captures = ".pagequiet/captures"  # full-page screenshot of each new version
+notify = ["stdout", "slack"]      # stdout, slack, webhook
+timeout = 45                      # seconds per page
+use_default_noise = true          # strip relative times, timestamps, view counters
+
+[[page]]
+url = "https://example.com/pricing"
+selector = "main"                          # watch one element, not the whole page
+ignore = ['Offer ends in \d+ days']        # extra regex patterns removed before comparing
+hide = [".testimonial-carousel"]           # hidden before text and screenshot
+
+[[page]]
+url = "https://example.com/legal/terms"
+selector = "article"
+screenshot = false                         # text only
+```
+
+Notifiers read their targets from the environment:
+
+| Notifier | Variable | Sends |
+|---|---|---|
+| `stdout` | none | the changed lines and screenshot path |
+| `slack` | `PAGEQUIET_SLACK_WEBHOOK` | a message to a Slack incoming webhook |
+| `webhook` | `PAGEQUIET_WEBHOOK_URL` | JSON: `{"event": "page.changed", "name", "url", "changes", "screenshot"}` |
+
+Exit codes: `0` nothing changed, `1` at least one page changed, `2` errors and no changes.
+
+## What counts as a change
+
+1. Render the page and take the visible text of `selector` (default `body`).
+2. Remove noise: relative times ("5 minutes ago", "just now"), ISO timestamps and clock times, view and visitor counters, extra whitespace, plus your `ignore` patterns.
+3. Hash the result. Same hash as last run: quiet. Different: report the changed lines and take a screenshot.
+
+The defaults are deliberately few. Every pattern you strip is a kind of change you will never be told about, so add `ignore` patterns only after you have seen one cause a false alarm. If timestamps on a page are meaningful to you, set `use_default_noise = false`.
+
+The biggest single improvement is `selector`. Watching `main` or the pricing table instead of the whole page ignores navigation, footers and "latest posts" widgets that change for reasons you do not care about.
+
+A failed render or an empty selector is reported as an error and never as a change, and the previous text is kept, so a flaky site does not produce a false alarm the next time it loads.
+
+## Renderers
+
+**`playwright`** (default) runs Chromium locally through Playwright. Free, private, and fine for most pages. Cookie consent banners are part of the page, so if one varies between visits, scope `selector` to the content or add the banner to `hide`.
+
+**`snaprender`** uses the hosted [SnapRender](https://snap-render.com) API to render pages, so no browser runs on your machine. Cookie banners and ads are removed before the text and screenshot are taken. It needs `SNAPRENDER_API_KEY`; the free plan covers 200 renders a month. Each check is one render, plus one when a page changed. Disclosure: I build SnapRender. `pagequiet` works fully without it and always will.
+
+## Run it on a schedule
+
+Cron, every six hours:
+
+```bash
+0 */6 * * * cd /opt/watch && pagequiet check -q >> pagequiet.log 2>&1
+```
+
+GitHub Actions, keeping state in the repository: see [`examples/github-actions.yml`](examples/github-actions.yml). Scheduled workflows run at most every five minutes, can start late at busy times, and are paused in public repositories after 60 days without activity; committing the state file each run counts as activity.
+
+## Limits
+
+- Pages behind a login are not supported.
+- Text comparison misses purely visual changes (a new image, a broken layout). Compare the screenshots in `captures/` for those, or keep `screenshot = true` and review them when text changes.
+- `hide` applies to the SnapRender renderer's screenshots only; scope its text with `selector`.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev,playwright]"
+pytest
+```
+
+MIT licensed.

pagequiet-0.1.0/pagequiet/__init__.py

@@ -0,0 +1,3 @@
+"""pagequiet: website change detection that stays quiet until something real changes."""
+
+__version__ = "0.1.0"

pagequiet-0.1.0/pagequiet/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

pagequiet-0.1.0/pagequiet/check.py

@@ -0,0 +1,86 @@
+"""One monitoring run: render each page, compare with the stored state, report changes."""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import Config
+from .normalize import fingerprint, normalize, summarize
+from .notify import Change
+from .renderers import Renderer
+
+
+@dataclass
+class Result:
+    changed: list[Change] = field(default_factory=list)
+    baselined: list[str] = field(default_factory=list)
+    unchanged: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+def _now() -> str:
+    return dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def load_state(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except ValueError:
+        return {}
+
+
+def save_state(path: Path, state: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(state, indent=2, sort_keys=True), encoding="utf-8")
+    tmp.replace(path)  # atomic: a crash never leaves half-written state
+
+
+def run(config: Config, renderer: Renderer) -> Result:
+    s = config.settings
+    state = load_state(s.state)
+    result = Result()
+
+    for page in config.pages:
+        try:
+            raw = renderer.text(page)
+        except Exception as e:
+            result.errors.append(f"{page.name}: {e}")
+            continue  # keep the old fingerprint; an error is not a change
+
+        text = normalize(raw, page.ignore, s.use_default_noise)
+        if not text:
+            result.errors.append(f"{page.name}: rendered text is empty (check the selector {page.selector!r})")
+            continue
+        fp = fingerprint(text)
+        prev = state.get(page.url)
+
+        if prev and prev.get("fingerprint") == fp:
+            prev["checked_at"] = _now()
+            result.unchanged.append(page.name)
+            continue
+
+        shot_path = None
+        if page.screenshot:
+            s.captures.mkdir(parents=True, exist_ok=True)
+            stamp = dt.datetime.now(dt.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+            dest = s.captures / f"{page.name}-{stamp}.png"
+            try:
+                renderer.screenshot(page, dest)
+                shot_path = str(dest)
+            except Exception as e:
+                result.errors.append(f"{page.name}: screenshot failed: {e}")
+
+        if prev:
+            result.changed.append(Change(page.name, page.url, summarize(prev.get("text", ""), text), shot_path))
+        else:
+            result.baselined.append(page.name)
+        state[page.url] = {"fingerprint": fp, "text": text, "checked_at": _now(), "changed_at": _now()}
+
+    save_state(s.state, state)
+    return result

pagequiet-0.1.0/pagequiet/cli.py

@@ -0,0 +1,71 @@
+"""Command line: `pagequiet init` and `pagequiet check`.
+
+Exit codes for `check`: 0 nothing changed, 1 at least one page changed, 2 configuration
+or rendering errors and no changes. Changes win over errors so CI jobs still alert.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .check import run
+from .config import SAMPLE, ConfigError, load
+from .notify import send
+from .renderers import RenderError, make_renderer
+
+
+def _init(path: Path) -> int:
+    if path.exists():
+        print(f"{path} already exists; leaving it alone.", file=sys.stderr)
+        return 2
+    path.write_text(SAMPLE, encoding="utf-8")
+    print(f"wrote {path}. Edit the [[page]] entries, then run: pagequiet check")
+    return 0
+
+
+def _check(path: Path, quiet: bool) -> int:
+    try:
+        config = load(path)
+        renderer = make_renderer(config.settings)
+    except (ConfigError, RenderError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    try:
+        result = run(config, renderer)
+    finally:
+        renderer.close()
+
+    errors = list(result.errors)
+    errors += send(config.settings.notify, result.changed)
+    if not quiet:
+        for name in result.baselined:
+            print(f"baseline recorded: {name}")
+        print(f"{len(result.changed)} changed, {len(result.unchanged)} unchanged, "
+              f"{len(result.baselined)} new, {len(result.errors)} errors")
+    for e in errors:
+        print(f"error: {e}", file=sys.stderr)
+    if result.changed:
+        return 1
+    return 2 if result.errors else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="pagequiet", description="Website change detection that stays quiet until something real changes.")
+    parser.add_argument("--version", action="version", version=f"pagequiet {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    p_init = sub.add_parser("init", help="write a sample pagequiet.toml")
+    p_init.add_argument("-c", "--config", default="pagequiet.toml")
+    p_check = sub.add_parser("check", help="render every page and report changes")
+    p_check.add_argument("-c", "--config", default="pagequiet.toml")
+    p_check.add_argument("-q", "--quiet", action="store_true", help="print only changes and errors")
+    args = parser.parse_args(argv)
+    if args.command == "init":
+        return _init(Path(args.config))
+    return _check(Path(args.config), args.quiet)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

pagequiet-0.1.0/pagequiet/config.py

@@ -0,0 +1,127 @@
+"""Load and validate pagequiet.toml."""
+
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class ConfigError(ValueError):
+    pass
+
+
+@dataclass
+class Page:
+    url: str
+    name: str
+    selector: str = "body"
+    ignore: list[str] = field(default_factory=list)
+    hide: list[str] = field(default_factory=list)
+    screenshot: bool = True
+
+
+@dataclass
+class Settings:
+    renderer: str = "playwright"
+    state: Path = Path(".pagequiet/state.json")
+    captures: Path = Path(".pagequiet/captures")
+    notify: list[str] = field(default_factory=lambda: ["stdout"])
+    timeout: int = 45
+    use_default_noise: bool = True
+    width: int = 1280
+    height: int = 800
+
+
+@dataclass
+class Config:
+    settings: Settings
+    pages: list[Page]
+
+
+RENDERERS = {"playwright", "snaprender"}
+NOTIFIERS = {"stdout", "slack", "webhook"}
+
+
+def _slug(url: str) -> str:
+    s = re.sub(r"^https?://", "", url)
+    s = re.sub(r"[^A-Za-z0-9]+", "-", s).strip("-").lower()
+    return s[:80] or "page"
+
+
+def load(path: str | os.PathLike[str]) -> Config:
+    p = Path(path)
+    if not p.exists():
+        raise ConfigError(f"config not found: {p} (run `pagequiet init` to create one)")
+    try:
+        raw = tomllib.loads(p.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError(f"{p}: {e}") from e
+
+    s = raw.get("settings", {})
+    settings = Settings(
+        renderer=s.get("renderer", "playwright"),
+        state=Path(s.get("state", ".pagequiet/state.json")),
+        captures=Path(s.get("captures", ".pagequiet/captures")),
+        notify=list(s.get("notify", ["stdout"])),
+        timeout=int(s.get("timeout", 45)),
+        use_default_noise=bool(s.get("use_default_noise", True)),
+        width=int(s.get("width", 1280)),
+        height=int(s.get("height", 800)),
+    )
+    if settings.renderer not in RENDERERS:
+        raise ConfigError(f"settings.renderer must be one of {sorted(RENDERERS)}, got {settings.renderer!r}")
+    unknown = [n for n in settings.notify if n not in NOTIFIERS]
+    if unknown:
+        raise ConfigError(f"settings.notify: unknown notifier(s) {unknown}; use {sorted(NOTIFIERS)}")
+
+    pages_raw = raw.get("page", [])
+    if not pages_raw:
+        raise ConfigError("no [[page]] entries in config")
+    pages: list[Page] = []
+    seen: set[str] = set()
+    for i, item in enumerate(pages_raw):
+        url = item.get("url")
+        if not url or not re.match(r"^https?://", url):
+            raise ConfigError(f"page #{i + 1}: url must start with http:// or https://")
+        for pattern in item.get("ignore", []):
+            try:
+                re.compile(pattern)
+            except re.error as e:
+                raise ConfigError(f"page {url}: bad ignore pattern {pattern!r}: {e}") from e
+        name = item.get("name") or _slug(url)
+        if name in seen:
+            name = f"{name}-{i + 1}"
+        seen.add(name)
+        pages.append(Page(
+            url=url,
+            name=name,
+            selector=item.get("selector", "body"),
+            ignore=list(item.get("ignore", [])),
+            hide=list(item.get("hide", [])),
+            screenshot=bool(item.get("screenshot", True)),
+        ))
+    return Config(settings=settings, pages=pages)
+
+
+SAMPLE = """\
+# pagequiet: website change detection that stays quiet until something real changes.
+
+[settings]
+renderer = "playwright"          # free, runs Chromium locally. Or "snaprender" (needs SNAPRENDER_API_KEY)
+state = ".pagequiet/state.json"  # last fingerprint and text per page
+captures = ".pagequiet/captures" # full-page screenshots of each changed version
+notify = ["stdout"]              # add "slack" (PAGEQUIET_SLACK_WEBHOOK) or "webhook" (PAGEQUIET_WEBHOOK_URL)
+
+[[page]]
+url = "https://example.com/"
+selector = "body"                # watch only the element that holds the content you care about
+
+# [[page]]
+# url = "https://example.com/pricing"
+# selector = "main"
+# ignore = ['Offer ends in \\d+ days']   # extra regex patterns to strip before comparing
+# hide = [".testimonial-carousel"]       # CSS selectors hidden before text and screenshot
+"""

pagequiet-0.1.0/pagequiet/normalize.py

@@ -0,0 +1,54 @@
+"""Turn rendered page text into a stable fingerprint and a readable diff.
+
+Most false alarms in change monitoring come from content that changes on every
+visit: relative times, view counters, dates, whitespace. These are stripped
+before hashing. User patterns from the config are applied on top.
+"""
+
+from __future__ import annotations
+
+import difflib
+import hashlib
+import re
+from collections.abc import Iterable
+
+# Noise that changes on every visit without the page meaningfully changing.
+# Kept deliberately short: every pattern is a kind of change you will never hear about.
+DEFAULT_NOISE: tuple[str, ...] = (
+    r"\b\d+\s+(?:seconds?|secs?|minutes?|mins?|hours?|hrs?|days?|weeks?)\s+ago\b",
+    r"\b(?:just now|a moment ago|yesterday|today)\b",
+    r"\b(?:19|20)\d{2}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?\b",
+    r"\b\d{1,2}:\d{2}(?::\d{2})?\s?(?:AM|PM|am|pm)?\b",
+    r"\b\d[\d,.]*\s+(?:views|visitors|people (?:are )?(?:viewing|watching)|online now)\b",
+)
+
+
+def normalize(text: str, ignore: Iterable[str] = (), use_defaults: bool = True) -> str:
+    """Remove noise patterns and collapse whitespace, line by line."""
+    patterns = [*(DEFAULT_NOISE if use_defaults else ()), *ignore]
+    compiled = [re.compile(p, re.IGNORECASE) for p in patterns]
+    lines = []
+    for line in text.splitlines():
+        for rx in compiled:
+            line = rx.sub("", line)
+        line = re.sub(r"\s+", " ", line).strip()
+        if line:
+            lines.append(line)
+    return "\n".join(lines)
+
+
+def fingerprint(normalized: str) -> str:
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+
+
+def summarize(old: str, new: str, limit: int = 8) -> list[str]:
+    """Changed lines as '- removed' / '+ added', at most `limit` of them."""
+    out: list[str] = []
+    for line in difflib.unified_diff(old.splitlines(), new.splitlines(), lineterm="", n=0):
+        if line.startswith(("+++", "---", "@@")):
+            continue
+        if line.startswith(("+", "-")):
+            out.append(f"{line[0]} {line[1:].strip()}")
+        if len(out) >= limit:
+            break
+    return out

pagequiet-0.1.0/pagequiet/notify.py

@@ -0,0 +1,58 @@
+"""Send change notices: stdout, a Slack incoming webhook, or any JSON webhook."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.request
+from dataclasses import dataclass
+
+
+@dataclass
+class Change:
+    name: str
+    url: str
+    lines: list[str]
+    screenshot: str | None
+
+
+def _post(url: str, payload: dict) -> None:
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json", "User-Agent": "pagequiet"},
+    )
+    with urllib.request.urlopen(req, timeout=15):
+        pass
+
+
+def to_text(c: Change) -> str:
+    body = "\n".join(f"  {line}" for line in c.lines) or "  (layout or wording changed; see screenshot)"
+    shot = f"\n  screenshot: {c.screenshot}" if c.screenshot else ""
+    return f"CHANGED {c.name} {c.url}\n{body}{shot}"
+
+
+def send(channels: list[str], changes: list[Change]) -> list[str]:
+    """Deliver each change to each channel. Returns error messages instead of raising."""
+    errors: list[str] = []
+    for c in changes:
+        for channel in channels:
+            try:
+                if channel == "stdout":
+                    print(to_text(c), file=sys.stdout)
+                elif channel == "slack":
+                    hook = os.environ.get("PAGEQUIET_SLACK_WEBHOOK")
+                    if not hook:
+                        errors.append("slack: PAGEQUIET_SLACK_WEBHOOK is not set")
+                        continue
+                    _post(hook, {"text": f"*Changed:* <{c.url}|{c.name}>\n```" + ("\n".join(c.lines) or "layout or wording changed") + "```"})
+                elif channel == "webhook":
+                    hook = os.environ.get("PAGEQUIET_WEBHOOK_URL")
+                    if not hook:
+                        errors.append("webhook: PAGEQUIET_WEBHOOK_URL is not set")
+                        continue
+                    _post(hook, {"event": "page.changed", "name": c.name, "url": c.url, "changes": c.lines, "screenshot": c.screenshot})
+            except Exception as e:  # a failed notice must never stop the run
+                errors.append(f"{channel}: {e}")
+    return errors

pagequiet-0.1.0/pagequiet/renderers.py

@@ -0,0 +1,128 @@
+"""Renderers turn a URL into visible text and, on change, a full-page screenshot.
+
+PlaywrightRenderer runs Chromium locally and costs nothing. SnapRenderRenderer calls
+the hosted SnapRender API, which removes cookie banners and ads before rendering
+and needs no browser on the machine. Both implement the same two methods.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Protocol
+
+from .config import Page, Settings
+
+
+class RenderError(RuntimeError):
+    pass
+
+
+class Renderer(Protocol):
+    def text(self, page: Page) -> str: ...
+    def screenshot(self, page: Page, dest: Path) -> None: ...
+    def close(self) -> None: ...
+
+
+class PlaywrightRenderer:
+    """Local Chromium through Playwright. Install with: pip install "pagequiet[playwright]"."""
+
+    def __init__(self, settings: Settings):
+        try:
+            from playwright.sync_api import sync_playwright
+        except ImportError as e:  # pragma: no cover - depends on optional install
+            raise RenderError(
+                'Playwright is not installed. Run: pip install "pagequiet[playwright]" && playwright install chromium'
+            ) from e
+        self._settings = settings
+        self._pw = sync_playwright().start()
+        self._browser = self._pw.chromium.launch()
+
+    def _open(self, page: Page):
+        ctx = self._browser.new_context(viewport={"width": self._settings.width, "height": self._settings.height})
+        tab = ctx.new_page()
+        try:
+            tab.goto(page.url, wait_until="networkidle", timeout=self._settings.timeout * 1000)
+        except Exception:
+            # Some pages never reach network idle (long polling, analytics); the DOM is usually ready anyway.
+            tab.wait_for_load_state("domcontentloaded", timeout=self._settings.timeout * 1000)
+        if page.hide:
+            css = ",".join(page.hide) + "{display:none!important}"
+            tab.add_style_tag(content=css)
+        return ctx, tab
+
+    def text(self, page: Page) -> str:
+        ctx, tab = self._open(page)
+        try:
+            loc = tab.locator(page.selector).first
+            if loc.count() == 0:
+                raise RenderError(f"selector {page.selector!r} not found on {page.url}")
+            return loc.inner_text(timeout=self._settings.timeout * 1000)
+        finally:
+            ctx.close()
+
+    def screenshot(self, page: Page, dest: Path) -> None:
+        ctx, tab = self._open(page)
+        try:
+            tab.screenshot(path=str(dest), full_page=True)
+        finally:
+            ctx.close()
+
+    def close(self) -> None:
+        self._browser.close()
+        self._pw.stop()
+
+
+class SnapRenderRenderer:
+    """Hosted rendering through the SnapRender API (https://snap-render.com).
+
+    Cookie banners and ads are removed before text and screenshots are taken. Text comes
+    from GET /v1/extract?type=text scoped by selector; screenshots from GET /v1/screenshot.
+    Note: `hide` applies to screenshots only; scope the text with `selector` instead.
+    """
+
+    API = "https://app.snap-render.com"
+
+    def __init__(self, settings: Settings, api_key: str | None = None):
+        self._settings = settings
+        self._key = api_key or os.environ.get("SNAPRENDER_API_KEY", "")
+        if not self._key:
+            raise RenderError("SNAPRENDER_API_KEY is not set (get a free key at https://snap-render.com)")
+
+    def _get(self, path: str, params: dict[str, str]) -> bytes:
+        url = f"{self.API}{path}?{urllib.parse.urlencode(params)}"
+        req = urllib.request.Request(url, headers={"X-API-Key": self._key, "User-Agent": "pagequiet"})
+        try:
+            with urllib.request.urlopen(req, timeout=self._settings.timeout + 30) as resp:
+                return resp.read()
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")[:300]
+            raise RenderError(f"SnapRender {path} returned {e.code}: {detail}") from e
+        except urllib.error.URLError as e:
+            raise RenderError(f"SnapRender {path} unreachable: {e.reason}") from e
+
+    def text(self, page: Page) -> str:
+        body = self._get("/v1/extract", {"url": page.url, "type": "text", "selector": page.selector})
+        try:
+            return json.loads(body)["content"]
+        except (ValueError, KeyError) as e:
+            raise RenderError(f"unexpected extract response for {page.url}") from e
+
+    def screenshot(self, page: Page, dest: Path) -> None:
+        params = {"url": page.url, "format": "png", "full_page": "true", "width": str(self._settings.width)}
+        if page.hide:
+            params["hide_selectors"] = ",".join(page.hide)
+        dest.write_bytes(self._get("/v1/screenshot", params))
+
+    def close(self) -> None:
+        pass
+
+
+def make_renderer(settings: Settings) -> Renderer:
+    if settings.renderer == "snaprender":
+        return SnapRenderRenderer(settings)
+    return PlaywrightRenderer(settings)

pagequiet-0.1.0/pagequiet.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: pagequiet
+Version: 0.1.0
+Summary: Website change detection that stays quiet until something real changes.
+Author: User0856
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/User0856/pagequiet
+Project-URL: Issues, https://github.com/User0856/pagequiet/issues
+Keywords: website monitoring,change detection,web page diff,playwright,screenshot,visualping alternative
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management :: Link Checking
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.40; extra == "playwright"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# pagequiet
+
+Website change detection that stays quiet until something real changes.
+
+Most change monitors compare HTML, so they alert on every rotating ad slot, CSRF token and "updated 3 minutes ago". After a week nobody reads the alerts. `pagequiet` compares what a reader sees instead: the rendered text of one element on the page, with relative times, counters and whitespace stripped. When that changes, you get the changed lines and a full-page screenshot of the new version.
+
+```
+$ pagequiet check
+CHANGED example-com-pricing https://example.com/pricing
+  - Pro $49 / month
+  + Pro $59 / month
+  screenshot: .pagequiet/captures/example-com-pricing-20261005T080012Z.png
+1 changed, 11 unchanged, 0 new, 0 errors
+```
+
+It is a single command with a TOML file, built for cron and CI: exit code 1 means something changed.
+
+## Install
+
+```bash
+pip install "pagequiet[playwright]"
+playwright install chromium
+```
+
+Python 3.11 or later. The Playwright extra renders pages with a local Chromium and costs nothing. If you would rather not run a browser (CI runners, small servers), see [Renderers](#renderers).
+
+## Quick start
+
+```bash
+pagequiet init        # writes pagequiet.toml
+# edit the [[page]] entries
+pagequiet check       # first run records a baseline
+pagequiet check       # later runs report changes
+```
+
+## Configuration
+
+```toml
+[settings]
+renderer = "playwright"           # or "snaprender"
+state = ".pagequiet/state.json"   # last text and fingerprint per page
+captures = ".pagequiet/captures"  # full-page screenshot of each new version
+notify = ["stdout", "slack"]      # stdout, slack, webhook
+timeout = 45                      # seconds per page
+use_default_noise = true          # strip relative times, timestamps, view counters
+
+[[page]]
+url = "https://example.com/pricing"
+selector = "main"                          # watch one element, not the whole page
+ignore = ['Offer ends in \d+ days']        # extra regex patterns removed before comparing
+hide = [".testimonial-carousel"]           # hidden before text and screenshot
+
+[[page]]
+url = "https://example.com/legal/terms"
+selector = "article"
+screenshot = false                         # text only
+```
+
+Notifiers read their targets from the environment:
+
+| Notifier | Variable | Sends |
+|---|---|---|
+| `stdout` | none | the changed lines and screenshot path |
+| `slack` | `PAGEQUIET_SLACK_WEBHOOK` | a message to a Slack incoming webhook |
+| `webhook` | `PAGEQUIET_WEBHOOK_URL` | JSON: `{"event": "page.changed", "name", "url", "changes", "screenshot"}` |
+
+Exit codes: `0` nothing changed, `1` at least one page changed, `2` errors and no changes.
+
+## What counts as a change
+
+1. Render the page and take the visible text of `selector` (default `body`).
+2. Remove noise: relative times ("5 minutes ago", "just now"), ISO timestamps and clock times, view and visitor counters, extra whitespace, plus your `ignore` patterns.
+3. Hash the result. Same hash as last run: quiet. Different: report the changed lines and take a screenshot.
+
+The defaults are deliberately few. Every pattern you strip is a kind of change you will never be told about, so add `ignore` patterns only after you have seen one cause a false alarm. If timestamps on a page are meaningful to you, set `use_default_noise = false`.
+
+The biggest single improvement is `selector`. Watching `main` or the pricing table instead of the whole page ignores navigation, footers and "latest posts" widgets that change for reasons you do not care about.
+
+A failed render or an empty selector is reported as an error and never as a change, and the previous text is kept, so a flaky site does not produce a false alarm the next time it loads.
+
+## Renderers
+
+**`playwright`** (default) runs Chromium locally through Playwright. Free, private, and fine for most pages. Cookie consent banners are part of the page, so if one varies between visits, scope `selector` to the content or add the banner to `hide`.
+
+**`snaprender`** uses the hosted [SnapRender](https://snap-render.com) API to render pages, so no browser runs on your machine. Cookie banners and ads are removed before the text and screenshot are taken. It needs `SNAPRENDER_API_KEY`; the free plan covers 200 renders a month. Each check is one render, plus one when a page changed. Disclosure: I build SnapRender. `pagequiet` works fully without it and always will.
+
+## Run it on a schedule
+
+Cron, every six hours:
+
+```bash
+0 */6 * * * cd /opt/watch && pagequiet check -q >> pagequiet.log 2>&1
+```
+
+GitHub Actions, keeping state in the repository: see [`examples/github-actions.yml`](examples/github-actions.yml). Scheduled workflows run at most every five minutes, can start late at busy times, and are paused in public repositories after 60 days without activity; committing the state file each run counts as activity.
+
+## Limits
+
+- Pages behind a login are not supported.
+- Text comparison misses purely visual changes (a new image, a broken layout). Compare the screenshots in `captures/` for those, or keep `screenshot = true` and review them when text changes.
+- `hide` applies to the SnapRender renderer's screenshots only; scope its text with `selector`.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev,playwright]"
+pytest
+```
+
+MIT licensed.

pagequiet-0.1.0/pagequiet.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+pagequiet/__init__.py
+pagequiet/__main__.py
+pagequiet/check.py
+pagequiet/cli.py
+pagequiet/config.py
+pagequiet/normalize.py
+pagequiet/notify.py
+pagequiet/renderers.py
+pagequiet.egg-info/PKG-INFO
+pagequiet.egg-info/SOURCES.txt
+pagequiet.egg-info/dependency_links.txt
+pagequiet.egg-info/entry_points.txt
+pagequiet.egg-info/requires.txt
+pagequiet.egg-info/top_level.txt
+tests/test_pagequiet.py

pagequiet-0.1.0/pagequiet.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pagequiet-0.1.0/pagequiet.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pagequiet = pagequiet.cli:main

pagequiet-0.1.0/pagequiet.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest>=8
+
+[playwright]
+playwright>=1.40

pagequiet-0.1.0/pagequiet.egg-info/top_level.txt

@@ -0,0 +1 @@
+pagequiet

pagequiet-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pagequiet"
+version = "0.1.0"
+description = "Website change detection that stays quiet until something real changes."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "User0856" }]
+keywords = ["website monitoring", "change detection", "web page diff", "playwright", "screenshot", "visualping alternative"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Topic :: Internet :: WWW/HTTP :: Site Management :: Link Checking",
+  "Topic :: Software Development :: Testing",
+]
+dependencies = []
+
+[project.optional-dependencies]
+playwright = ["playwright>=1.40"]
+dev = ["pytest>=8"]
+
+[project.scripts]
+pagequiet = "pagequiet.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/User0856/pagequiet"
+Issues = "https://github.com/User0856/pagequiet/issues"
+
+[tool.setuptools]
+packages = ["pagequiet"]

pagequiet-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pagequiet-0.1.0/tests/test_pagequiet.py

@@ -0,0 +1,157 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from pagequiet.check import run
+from pagequiet.cli import main
+from pagequiet.config import ConfigError, Page, load
+from pagequiet.normalize import fingerprint, normalize, summarize
+
+
+# ---------- normalize ----------
+
+def test_relative_times_counters_and_whitespace_do_not_change_the_fingerprint():
+    a = "Pricing\nPro   $49 / month\nUpdated 3 minutes ago\n1,204 people viewing"
+    b = "Pricing\n  Pro $49 / month  \nUpdated 2 hours ago\n987 people viewing\n\n"
+    assert fingerprint(normalize(a)) == fingerprint(normalize(b))
+
+
+def test_a_real_change_changes_the_fingerprint():
+    a = "Pro $49 / month"
+    b = "Pro $59 / month"
+    assert fingerprint(normalize(a)) != fingerprint(normalize(b))
+
+
+def test_iso_timestamps_are_ignored_by_default_but_can_be_kept():
+    a, b = "Build 2026-10-05T08:00:00Z ok", "Build 2026-10-06T09:30:00Z ok"
+    assert normalize(a) == normalize(b)
+    assert normalize(a, use_defaults=False) != normalize(b, use_defaults=False)
+
+
+def test_user_ignore_patterns_apply():
+    a, b = "Offer ends in 3 days\nPlan A", "Offer ends in 2 days\nPlan A"
+    assert normalize(a) != normalize(b)
+    assert normalize(a, [r"Offer ends in \d+ days"]) == normalize(b, [r"Offer ends in \d+ days"])
+
+
+def test_summary_lists_removed_and_added_lines():
+    lines = summarize("Plan A\nPro $49\nFooter", "Plan A\nPro $59\nFooter")
+    assert lines == ["- Pro $49", "+ Pro $59"]
+
+
+def test_summary_is_capped():
+    old = "\n".join(f"line {i}" for i in range(50))
+    new = "\n".join(f"LINE {i}" for i in range(50))
+    assert len(summarize(old, new, limit=5)) == 5
+
+
+# ---------- config ----------
+
+def write(tmp_path: Path, body: str) -> Path:
+    p = tmp_path / "pagequiet.toml"
+    p.write_text(body, encoding="utf-8")
+    return p
+
+
+def test_config_defaults_and_names(tmp_path):
+    cfg = load(write(tmp_path, '[[page]]\nurl = "https://example.com/pricing"\n'))
+    assert cfg.settings.renderer == "playwright"
+    assert cfg.pages[0].name == "example-com-pricing"
+    assert cfg.pages[0].selector == "body"
+
+
+@pytest.mark.parametrize("body,needle", [
+    ('[settings]\nrenderer = "selenium"\n[[page]]\nurl = "https://x.y"\n', "renderer"),
+    ('[[page]]\nurl = "ftp://x.y"\n', "http"),
+    ('[settings]\nnotify = ["email"]\n[[page]]\nurl = "https://x.y"\n', "notifier"),
+    ('[[page]]\nurl = "https://x.y"\nignore = ["(unclosed"]\n', "ignore pattern"),
+    ('[settings]\nrenderer = "playwright"\n', r"no \[\[page\]\] entries"),
+])
+def test_config_errors_are_explicit(tmp_path, body, needle):
+    with pytest.raises(ConfigError, match=needle):
+        load(write(tmp_path, body))
+
+
+def test_missing_config_suggests_init(tmp_path):
+    with pytest.raises(ConfigError, match="pagequiet init"):
+        load(tmp_path / "nope.toml")
+
+
+# ---------- run ----------
+
+class FakeRenderer:
+    def __init__(self, texts):
+        self.texts = texts
+        self.shots = []
+
+    def text(self, page: Page) -> str:
+        value = self.texts[page.url]
+        if isinstance(value, Exception):
+            raise value
+        return value
+
+    def screenshot(self, page: Page, dest: Path) -> None:
+        dest.write_bytes(b"\x89PNG fake")
+        self.shots.append(dest)
+
+    def close(self):
+        pass
+
+
+def cfg_for(tmp_path, urls):
+    pages = "\n".join(f'[[page]]\nurl = "{u}"\n' for u in urls)
+    return load(write(tmp_path, f'[settings]\nstate = "{tmp_path}/state.json"\ncaptures = "{tmp_path}/shots"\n{pages}'))
+
+
+def test_first_run_baselines_then_quiet_then_alerts(tmp_path):
+    cfg = cfg_for(tmp_path, ["https://a.test/"])
+    r1 = run(cfg, FakeRenderer({"https://a.test/": "Hello\nPrice $10\nUpdated 1 minute ago"}))
+    assert r1.baselined == ["a-test"] and not r1.changed
+
+    r2 = run(cfg, FakeRenderer({"https://a.test/": "Hello\nPrice $10\nUpdated 5 minutes ago"}))
+    assert r2.unchanged == ["a-test"] and not r2.changed
+
+    fake = FakeRenderer({"https://a.test/": "Hello\nPrice $12\nUpdated just now"})
+    r3 = run(cfg, fake)
+    assert len(r3.changed) == 1
+    assert r3.changed[0].lines == ["- Price $10", "+ Price $12"]
+    assert r3.changed[0].screenshot and Path(r3.changed[0].screenshot).exists()
+
+
+def test_render_errors_keep_the_previous_fingerprint(tmp_path):
+    cfg = cfg_for(tmp_path, ["https://a.test/"])
+    run(cfg, FakeRenderer({"https://a.test/": "v1"}))
+    r = run(cfg, FakeRenderer({"https://a.test/": RuntimeError("timeout")}))
+    assert r.errors and not r.changed
+    state = json.loads((tmp_path / "state.json").read_text())
+    assert state["https://a.test/"]["text"] == "v1"
+
+
+def test_empty_text_is_an_error_not_a_change(tmp_path):
+    cfg = cfg_for(tmp_path, ["https://a.test/"])
+    run(cfg, FakeRenderer({"https://a.test/": "v1"}))
+    r = run(cfg, FakeRenderer({"https://a.test/": "   \n  "}))
+    assert r.errors and not r.changed
+
+
+# ---------- cli ----------
+
+def test_init_writes_a_loadable_sample(tmp_path, capsys):
+    target = tmp_path / "pagequiet.toml"
+    assert main(["init", "-c", str(target)]) == 0
+    assert load(target).pages[0].url == "https://example.com/"
+    assert main(["init", "-c", str(target)]) == 2  # never overwrites
+
+
+def test_check_exit_codes(tmp_path, monkeypatch, capsys):
+    cfg_path = write(tmp_path, f'[settings]\nstate = "{tmp_path}/s.json"\ncaptures = "{tmp_path}/c"\n[[page]]\nurl = "https://a.test/"\n')
+    texts = {"https://a.test/": "v1"}
+    monkeypatch.setattr("pagequiet.cli.make_renderer", lambda settings: FakeRenderer(texts))
+    assert main(["check", "-c", str(cfg_path)]) == 0  # baseline
+    assert main(["check", "-c", str(cfg_path)]) == 0  # unchanged
+    texts["https://a.test/"] = "v2"
+    assert main(["check", "-c", str(cfg_path)]) == 1  # changed
+    out = capsys.readouterr().out
+    assert "CHANGED a-test https://a.test/" in out and "+ v2" in out
+    assert main(["check", "-c", str(tmp_path / "missing.toml")]) == 2