fxcss 0.6.1__py3-none-any.whl

fxcss/fetch.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""Fetch a theme from GitHub so it can be test-driven.
+
+`fxcss try owner/repo` downloads a theme, installs it into a throwaway profile
+and opens it, so someone can see what a theme actually looks like before putting
+it anywhere near their real Firefox profile.
+
+**Nothing from the downloaded repository is ever executed.** A theme's install
+script is, in practice, `cp -r chrome/ <profile>/` plus flipping a pref -- which
+is precisely what fxcss already does itself. So this locates and *reports* the
+install script and any options it documents, and then does the installation by
+copying files. Running a shell script fetched from a URL to preview a stylesheet
+would be a poor trade.
+
+That leaves the theme's own contents, which are CSS, SVG and occasionally a .js
+file. Firefox does not execute a .js file sitting in a profile's chrome folder --
+that needs an autoconfig hook in the *application* directory, which fxcss does
+not create.
+"""
+
+import io
+import json
+import os
+import re
+import shutil
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+API = "https://api.github.com"
+USER_AGENT = "fxcss (+https://github.com/AdamXweb/fxcss)"
+
+# A theme is small. Anything wildly bigger than this is not one, and unpacking it
+# blindly would be careless.
+MAX_ARCHIVE_BYTES = 80 * 1024 * 1024
+MAX_UNPACKED_BYTES = 200 * 1024 * 1024
+
+REPO_SPEC = re.compile(
+    r"^(?:https?://)?(?:www\.)?(?:github\.com/)?([\w.-]+)/([\w.-]+?)(?:\.git)?/?$")
+
+INSTALL_SCRIPTS = [
+    "install.sh", "install.bat", "install.ps1", "install.py",
+    "setup.sh", "Makefile", "makefile", "justfile",
+]
+
+# Themes commonly keep optional tweaks in one of these.
+VARIANT_DIRS = ["custom", "optional", "options", "extras", "variants"]
+
+# "- `-c` Left hand side tab close button" and similar list items.
+FLAG_LINE = re.compile(r"^\s*[-*+]\s*`?(-{1,2}[\w-]+)`?\s*[—:-]?\s+(.{4,120}?)\s*$")
+
+
+def parse_repo(spec: str):
+    match = REPO_SPEC.match(spec.strip())
+    if not match:
+        raise ValueError(
+            f"could not read {spec!r} as a GitHub repo. "
+            "Use owner/name or a github.com URL.")
+    return match.group(1), match.group(2)
+
+
+def _request(url, accept="application/vnd.github+json"):
+    headers = {"User-Agent": USER_AGENT, "Accept": accept}
+    # Only raises the anonymous rate limit; never required.
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return urllib.request.Request(url, headers=headers)
+
+
+def _api(path):
+    try:
+        with urllib.request.urlopen(_request(API + path), timeout=45) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            return None
+        if exc.code == 403:
+            raise RuntimeError(
+                "GitHub refused the request (rate limit). Set GITHUB_TOKEN to "
+                "raise it, or pass --ref to skip the lookups.") from exc
+        raise
+
+
+def resolve(owner, name):
+    """Report what is available: the default branch tip and the latest release."""
+    repo = _api(f"/repos/{owner}/{name}")
+    if repo is None:
+        raise RuntimeError(f"no such repository: {owner}/{name}")
+
+    branch = repo.get("default_branch", "main")
+    commit = _api(f"/repos/{owner}/{name}/commits/{branch}") or {}
+    release = _api(f"/repos/{owner}/{name}/releases/latest")
+
+    info = {
+        "owner": owner, "name": name,
+        "description": repo.get("description") or "",
+        "stars": repo.get("stargazers_count", 0),
+        "licence": (repo.get("license") or {}).get("spdx_id"),
+        "default_branch": branch,
+        "commit": {
+            "sha": (commit.get("sha") or "")[:7],
+            "date": (commit.get("commit", {}).get("author", {}) or {}).get("date", ""),
+            "message": (commit.get("commit", {}).get("message") or "").splitlines()[0][:72],
+        } if commit else None,
+        "release": {
+            "tag": release.get("tag_name"),
+            "name": release.get("name") or release.get("tag_name"),
+            "date": release.get("published_at", ""),
+        } if release else None,
+    }
+    return info
+
+
+def choose_ref(info, prefer):
+    """Pick what to download. Releases are what a theme's author blessed."""
+    if prefer == "commit":
+        return info["default_branch"], "latest commit"
+    if info["release"]:
+        return info["release"]["tag"], f"release {info['release']['tag']}"
+    return info["default_branch"], f"latest commit on {info['default_branch']}"
+
+
+def _safe_members(archive, destination: Path):
+    """Yield members that stay inside the destination, refusing anything else."""
+    total = 0
+    root = destination.resolve()
+    for member in archive:
+        if member.issym() or member.islnk():
+            continue  # a link could point anywhere; a theme does not need them
+        if not (member.isfile() or member.isdir()):
+            continue
+        target = (root / member.name).resolve()
+        if not str(target).startswith(str(root) + os.sep):
+            raise RuntimeError(f"archive tried to write outside the target: {member.name}")
+        total += max(member.size, 0)
+        if total > MAX_UNPACKED_BYTES:
+            raise RuntimeError("archive unpacks to more than 200 MB; refusing")
+        yield member
+
+
+def download(owner, name, ref, into: Path):
+    """Download and unpack a repository at a ref. Returns the unpacked root."""
+    url = f"https://codeload.github.com/{owner}/{name}/tar.gz/{ref}"
+    try:
+        with urllib.request.urlopen(_request(url, accept="*/*"), timeout=180) as response:
+            payload = response.read(MAX_ARCHIVE_BYTES + 1)
+    except urllib.error.HTTPError as exc:
+        raise RuntimeError(f"could not download {owner}/{name}@{ref}: {exc}") from exc
+    if len(payload) > MAX_ARCHIVE_BYTES:
+        raise RuntimeError("archive is larger than 80 MB; refusing")
+
+    into.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(fileobj=io.BytesIO(payload), mode="r:gz") as archive:
+        archive.extractall(into, members=_safe_members(archive, into))
+
+    entries = [p for p in into.iterdir() if p.is_dir()]
+    if len(entries) == 1:
+        return entries[0]  # GitHub wraps everything in one directory
+    return into
+
+
+def find_theme_root(unpacked: Path):
+    """Locate the folder that holds chrome/userChrome.css.
+
+    Not always the repository root: plenty of themes keep sources under src/ or
+    ship several variants side by side.
+    """
+    candidates = sorted(unpacked.rglob("userChrome.css"),
+                        key=lambda p: len(p.relative_to(unpacked).parts))
+    for sheet in candidates:
+        if sheet.parent.name == "chrome":
+            return sheet.parent.parent
+    if candidates:
+        # userChrome.css not inside a folder called chrome; treat its parent as
+        # the chrome folder anyway.
+        return candidates[0].parent.parent
+    return None
+
+
+def describe(repo_root: Path, theme_root: Path):
+    """What this theme offers, and how its author says to install it."""
+    scripts = [name for name in INSTALL_SCRIPTS if (repo_root / name).is_file()]
+
+    variants = []
+    for folder in VARIANT_DIRS:
+        directory = repo_root / folder
+        if directory.is_dir():
+            for sheet in sorted(directory.glob("*.css")):
+                variants.append(sheet)
+
+    flags = []
+    for readme in ("README.md", "readme.md", "README", "README.rst"):
+        path = repo_root / readme
+        if not path.is_file():
+            continue
+        for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+            match = FLAG_LINE.match(line)
+            if match:
+                flags.append({"flag": match.group(1), "text": match.group(2)})
+        break
+
+    sheets = list(theme_root.rglob("*.css")) if theme_root else []
+    return {
+        "scripts": scripts,
+        "variants": variants,
+        "flags": flags[:14],
+        "stylesheets": len(sheets),
+        "bytes": sum(p.stat().st_size for p in sheets),
+        "has_configuration": (theme_root / "configuration").is_dir() if theme_root else False,
+    }
+
+
+def apply_variants(profile: Path, chosen):
+    """Layer optional stylesheets on top, by import rather than by copying.
+
+    Themes disagree about where an optional sheet belongs -- some expect it
+    inside their own folder, some rely on their installer editing an import
+    list. Appending an absolute @import to the profile's userChrome.css works
+    for all of them, and relative url()s inside the sheet still resolve because
+    the file stays where it was unpacked.
+    """
+    user_chrome = profile / "chrome" / "userChrome.css"
+    if not user_chrome.exists() or not chosen:
+        return []
+    lines = ["", "/* optional sheets layered on by fxcss try --with */"]
+    for sheet in chosen:
+        lines.append(f'@import url("{sheet.resolve().as_uri()}");')
+    with user_chrome.open("a", encoding="utf-8") as handle:
+        handle.write("\n".join(lines) + "\n")
+    return chosen
+
+
+def humanise(info):
+    """Lines describing what was found upstream."""
+    out = []
+    header = f"{info['owner']}/{info['name']}"
+    if info["stars"]:
+        header += f"  ★{info['stars']}"
+    if info["licence"] and info["licence"] != "NOASSERTION":
+        header += f"  {info['licence']}"
+    out.append(header)
+    if info["description"]:
+        out.append(f"  {info['description'][:96]}")
+    if info["release"]:
+        out.append(f"  latest release   {info['release']['tag']}"
+                   f"  ({info['release']['date'][:10]})")
+    else:
+        out.append("  latest release   none published")
+    if info["commit"]:
+        out.append(f"  latest commit    {info['commit']['sha']}"
+                   f"  ({info['commit']['date'][:10]})  {info['commit']['message']}")
+    return out

fxcss/probe.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""Identify browser UI elements and the rules that style them.
+
+Two ways in:
+
+* `pick` overlays a highlighter on the running browser -- hover any part of the
+  UI and click to get a selector you can paste into your theme.
+* `inspect` takes a selector you already have and reports what it matches.
+
+Both finish by grepping the theme for rules that target the element, so the
+answer is not just "what is this" but "where do I edit it".
+
+Named probe.py rather than inspect.py so it cannot shadow the standard
+library's inspect module for the sibling imports.
+"""
+
+import time
+
+# Builds a selector from an element. Prefers an id, because userChrome rules
+# overwhelmingly key off ids, then falls back to tag + classes, then to a short
+# ancestor path so a nameless element is still addressable.
+SELECTOR_HELPERS = """
+const esc = (s) => (typeof CSS !== "undefined" && CSS.escape) ? CSS.escape(s) : s;
+function classListOf(el) {
+  const c = el.getAttribute && el.getAttribute("class");
+  return c ? c.trim().split(/\\s+/).filter(Boolean) : [];
+}
+function selOf(el) {
+  if (!el || el.nodeType !== 1) return "";
+  if (el.id) return "#" + esc(el.id);
+  let s = el.localName;
+  const cls = classListOf(el);
+  if (cls.length) s += "." + cls.map(esc).join(".");
+  return s;
+}
+function pathOf(el) {
+  const parts = [];
+  let e = el;
+  while (e && e.nodeType === 1 && parts.length < 6) {
+    parts.unshift(selOf(e));
+    if (e.id) break;
+    e = e.parentElement;
+  }
+  return parts.join(" ");
+}
+function describe(el) {
+  const r = el.getBoundingClientRect();
+  const win = Services.wm.getMostRecentWindow("navigator:browser");
+  const cs = win.getComputedStyle(el);
+  const styles = {};
+  for (const p of ["background-color","color","border-radius","box-shadow",
+                   "list-style-image","font-size","padding","margin","opacity",
+                   "height","width","display"]) {
+    const v = cs.getPropertyValue(p);
+    if (v && !["none","normal","auto","0px","rgba(0, 0, 0, 0)","1"].includes(v)) {
+      styles[p] = v;
+    }
+  }
+  return {
+    selector: selOf(el), path: pathOf(el),
+    tag: el.localName, id: el.id || null,
+    classes: classListOf(el),
+    attrs: [...el.attributes].map(a => a.name).filter(n => n !== "class" && n !== "id"),
+    rect: {x: Math.round(r.x), y: Math.round(r.y),
+           w: Math.round(r.width), h: Math.round(r.height)},
+    styles,
+  };
+}
+"""
+
+START_PICKER = SELECTOR_HELPERS + """
+const win = Services.wm.getMostRecentWindow("navigator:browser");
+const doc = win.document;
+if (win._fxcssStopPicker) { win._fxcssStopPicker(); }
+win._fxcssPicked = null;
+
+const HTML = "http://www.w3.org/1999/xhtml";
+const box = doc.createElementNS(HTML, "div");
+box.style.cssText = "position:fixed;z-index:2147483647;pointer-events:none;" +
+  "border:2px solid #ff0080;background:rgba(255,0,128,.14);box-sizing:border-box;" +
+  "border-radius:3px;display:none;";
+const tag = doc.createElementNS(HTML, "div");
+tag.style.cssText = "position:fixed;z-index:2147483647;pointer-events:none;" +
+  "background:#ff0080;color:#fff;padding:2px 6px;border-radius:3px;display:none;" +
+  "font:11px ui-monospace,Menlo,monospace;white-space:nowrap;";
+doc.documentElement.appendChild(box);
+doc.documentElement.appendChild(tag);
+
+let current = null;
+function onMove(ev) {
+  const el = ev.originalTarget || ev.target;
+  if (!el || el.nodeType !== 1 || el === box || el === tag) return;
+  current = el;
+  const r = el.getBoundingClientRect();
+  box.style.display = "block";
+  box.style.left = r.left + "px"; box.style.top = r.top + "px";
+  box.style.width = r.width + "px"; box.style.height = r.height + "px";
+  tag.style.display = "block";
+  tag.textContent = selOf(el);
+  tag.style.left = Math.max(0, r.left) + "px";
+  tag.style.top = Math.max(0, r.top - 19) + "px";
+}
+function onPick(ev) {
+  if (!current) return;
+  ev.preventDefault(); ev.stopPropagation();
+  win._fxcssPicked = describe(current);
+}
+function onKey(ev) {
+  if (ev.key === "Escape") { ev.preventDefault(); win._fxcssStopPicker(); }
+}
+
+// Capture phase so a click lands on the highlighter rather than activating the
+// button underneath it.
+doc.addEventListener("mousemove", onMove, true);
+doc.addEventListener("mousedown", onPick, true);
+doc.addEventListener("click", onPick, true);
+doc.addEventListener("keydown", onKey, true);
+
+win._fxcssStopPicker = function () {
+  doc.removeEventListener("mousemove", onMove, true);
+  doc.removeEventListener("mousedown", onPick, true);
+  doc.removeEventListener("click", onPick, true);
+  doc.removeEventListener("keydown", onKey, true);
+  box.remove(); tag.remove();
+  win._fxcssStopPicker = null;
+  win._fxcssPickerStopped = true;
+};
+win._fxcssPickerStopped = false;
+return true;
+"""
+
+READ_PICK = """
+const win = Services.wm.getMostRecentWindow("navigator:browser");
+const p = win._fxcssPicked;
+win._fxcssPicked = null;
+return {picked: p, stopped: !!win._fxcssPickerStopped};
+"""
+
+STOP_PICKER = """
+const win = Services.wm.getMostRecentWindow("navigator:browser");
+if (win._fxcssStopPicker) { win._fxcssStopPicker(); }
+return true;
+"""
+
+QUERY = SELECTOR_HELPERS + """
+const win = Services.wm.getMostRecentWindow("navigator:browser");
+const doc = win.document;
+let nodes = [];
+try { nodes = [...doc.querySelectorAll(arguments[0])]; }
+catch (e) { return {error: String(e)}; }
+return {count: nodes.length, matches: nodes.slice(0, 8).map(describe)};
+"""
+
+
+def _print_element(info, repo, references):
+    print(f"\n  {info['tag']}  →  {info['selector']}")
+    if info["path"] and info["path"] != info["selector"]:
+        print(f"  path      {info['path']}")
+    if info["classes"]:
+        print(f"  classes   {' '.join(info['classes'])}")
+    if info["attrs"]:
+        print(f"  attrs     {' '.join(info['attrs'][:10])}")
+    r = info["rect"]
+    print(f"  box       {r['w']}×{r['h']} at ({r['x']}, {r['y']})"
+          + ("   (not visible in this layout)" if not r["w"] or not r["h"] else ""))
+    if info["styles"]:
+        print("  styles")
+        for k, v in info["styles"].items():
+            print(f"    {k}: {v}")
+
+    hits = references(repo, info["selector"])
+    if hits:
+        print(f"  styled by {len(hits)} rule{'s' if len(hits) != 1 else ''} in this theme")
+        for h in hits[:8]:
+            print(f"    {h['file']}:{h['line']}  {h['text'][:88]}")
+        if len(hits) > 8:
+            print(f"    … and {len(hits) - 8} more")
+    else:
+        print("  styled by no rules in this theme (Firefox defaults only)")
+
+
+def inspect_selector(session, selector, repo, references):
+    result = session.m.script(QUERY, [selector])
+    if isinstance(result, dict) and result.get("error"):
+        print(f"invalid selector: {result['error']}")
+        return 2
+    count = result["count"]
+    if not count:
+        print(f"no elements match {selector!r} in this Firefox")
+        return 1
+    print(f"{count} element{'s' if count != 1 else ''} match {selector!r}"
+          + ("  (showing first 8)" if count > 8 else ""))
+    for info in result["matches"]:
+        _print_element(info, repo, references)
+    return 0
+
+
+def pick(session, repo, references):
+    session.m.script(START_PICKER)
+    print("\n  Move the mouse over the browser window; the element under the")
+    print("  cursor is outlined. Click to capture it. Esc in the browser, or")
+    print("  Ctrl-C here, to stop.\n")
+    picked = 0
+    try:
+        while True:
+            time.sleep(0.35)
+            state = session.m.script(READ_PICK)
+            if state.get("picked"):
+                picked += 1
+                _print_element(state["picked"], repo, references)
+            if state.get("stopped"):
+                print("\n  picker stopped.")
+                break
+    except KeyboardInterrupt:
+        print("\n  stopping.")
+        try:
+            session.m.script(STOP_PICKER)
+        except Exception:
+            pass
+    return 0 if picked else 0