readwright 0.3.0__py3-none-any.whl

readwright/images.py

@@ -0,0 +1,217 @@
+"""Screenshot discovery and image tag helpers."""
+
+from __future__ import annotations
+
+import html
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from readwright.config import Config
+
+EXTENSIONS = ("png", "jpg", "jpeg", "gif", "webp", "svg")
+VARIANTS = ("dark", "light")
+
+
+class MissingImageError(FileNotFoundError):
+    pass
+
+
+def titleize(stem: str) -> str:
+    stem = stem.rsplit("/", 1)[-1]
+    return " ".join(part.capitalize() for part in stem.replace("_", "-").split("-") if part)
+
+
+def img_tag(src: str, alt: str, width: int | None) -> str:
+    width_attr = f' width="{width}"' if width else ""
+    return f'<img src="{src}" alt="{html.escape(alt, quote=True)}"{width_attr}>'
+
+
+def md_image(src: str, alt: str) -> str:
+    return f"![{alt}]({src})"
+
+
+def md_pair(dark: str, light: str, alt: str) -> str:
+    """GitHub-only trick: image fragments select light/dark variants in pure markdown."""
+    return f"![{alt}]({light}#gh-light-mode-only)![{alt}]({dark}#gh-dark-mode-only)"
+
+
+def picture_tag(dark: str, light: str, alt: str, width: int | None) -> str:
+    return (
+        "<picture>\n"
+        f'  <source media="(prefers-color-scheme: dark)" srcset="{dark}">\n'
+        f'  <source media="(prefers-color-scheme: light)" srcset="{light}">\n'
+        f"  {img_tag(light, alt, width)}\n"
+        "</picture>"
+    )
+
+
+@dataclass
+class Shot:
+    name: str
+    single: Path | None = None
+    dark: Path | None = None
+    light: Path | None = None
+
+    @property
+    def is_pair(self) -> bool:
+        return self.dark is not None and self.light is not None
+
+
+class ImageHelper:
+    def __init__(
+        self, root: Path, config: Config, warn: Callable[[str], None] | None = None
+    ) -> None:
+        self.root = Path(root)
+        self.config = config
+        self.warn = warn or (lambda message: None)
+
+    @property
+    def shots_dir(self) -> Path:
+        return self.root / self.config.screenshots.dir
+
+    def _rel(self, path: Path) -> str:
+        return path.relative_to(self.root).as_posix()
+
+    def _find(self, stem: str) -> Path | None:
+        for ext in EXTENSIONS:
+            candidate = self.shots_dir / f"{stem}.{ext}"
+            if candidate.is_file():
+                return candidate
+        return None
+
+    def _lookup(self, name: str) -> Shot:
+        return Shot(
+            name=name,
+            single=self._find(name),
+            dark=self._find(f"{name}-dark"),
+            light=self._find(f"{name}-light"),
+        )
+
+    def _render_shot(self, shot: Shot, alt: str, width: int | None, force_html: bool) -> str:
+        html_mode = force_html or bool(width) or self.config.screenshots.style == "html"
+        if shot.is_pair:
+            dark, light = self._rel(shot.dark), self._rel(shot.light)
+            return picture_tag(dark, light, alt, width) if html_mode else md_pair(dark, light, alt)
+        src = shot.single or shot.light or shot.dark
+        assert src is not None
+        return img_tag(self._rel(src), alt, width) if html_mode else md_image(self._rel(src), alt)
+
+    def _missing(self, message: str) -> str:
+        if self.config.strict:
+            raise MissingImageError(message)
+        self.warn(message)
+        return ""
+
+    def screenshot(self, name: str, alt: str | None = None, width: int | None = None) -> str:
+        shot = self._lookup(name)
+        if not (shot.single or shot.dark or shot.light):
+            return self._missing(
+                f"screenshot '{name}' not found in {self.config.screenshots.dir} "
+                f"(tried extensions {', '.join(EXTENSIONS)})"
+            )
+        force_html = width is not None
+        width = width if width is not None else self._style_width()
+        return self._render_shot(shot, alt or titleize(name), width, force_html)
+
+    def _style_width(self) -> int | None:
+        return self.config.screenshots.width if self.config.screenshots.style == "html" else None
+
+    def image(self, path: str, alt: str = "", width: int | None = None) -> str:
+        if "://" not in path and not (self.root / path).is_file():
+            self.warn(f"image '{path}' not found")
+        return img_tag(path, alt, width) if width else md_image(path, alt)
+
+    def _captions(self, directory: Path) -> dict[str, str]:
+        path = directory / "captions.yaml"
+        if not path.is_file():
+            return {}
+        data = yaml.safe_load(path.read_text()) or {}
+        return {str(k): str(v) for k, v in data.items()} if isinstance(data, dict) else {}
+
+    def _discover(self, directory: Path) -> list[Shot]:
+        if not directory.is_dir():
+            self.warn(f"screenshots dir '{self._rel(directory)}' does not exist")
+            return []
+        files = sorted(p for p in directory.iterdir() if p.suffix.lstrip(".").lower() in EXTENSIONS)
+        shots: dict[str, Shot] = {}
+        for path in files:
+            stem, variant = path.stem, None
+            for candidate in VARIANTS:
+                if stem.endswith(f"-{candidate}"):
+                    stem, variant = stem[: -len(candidate) - 1], candidate
+                    break
+            shot = shots.setdefault(stem, Shot(name=stem))
+            if variant is None:
+                shot.single = shot.single or path
+            else:
+                setattr(shot, variant, getattr(shot, variant) or path)
+        return list(shots.values())
+
+    def has_screenshots(self) -> bool:
+        return self.shots_dir.is_dir() and any(
+            p.suffix.lstrip(".").lower() in EXTENSIONS for p in self.shots_dir.iterdir()
+        )
+
+    def screenshots(
+        self,
+        columns: int = 2,
+        subdir: str | None = None,
+        order: list[str] | None = None,
+        captions: dict[str, str] | None = None,
+        show_captions: bool = True,
+    ) -> str:
+        directory = self.shots_dir / subdir if subdir else self.shots_dir
+        shots = self._discover(directory)
+        if not shots:
+            if directory.is_dir():
+                self.warn(f"no screenshots found in {self._rel(directory)}")
+            return ""
+        all_captions = {**self._captions(directory), **(captions or {})}
+        if order:
+            by_name = {shot.name: shot for shot in shots}
+            missing = [name for name in order if name not in by_name]
+            if missing:
+                self.warn(f"screenshots order lists unknown names: {', '.join(missing)}")
+            ordered = [by_name[n] for n in order if n in by_name]
+            shots = ordered + [s for s in shots if s.name not in order]
+        columns = max(columns, 1)
+        captioned = [(shot, all_captions.get(shot.name, titleize(shot.name))) for shot in shots]
+        if self.config.screenshots.style == "html":
+            return self._html_gallery(captioned, columns, show_captions)
+        return self._markdown_gallery(captioned, columns, show_captions)
+
+    def _markdown_gallery(
+        self, shots: list[tuple[Shot, str]], columns: int, show_captions: bool
+    ) -> str:
+        def row(cells: list[str]) -> str:
+            padded = cells + [""] * (columns - len(cells))
+            return "| " + " | ".join(padded) + " |"
+
+        lines: list[str] = []
+        for i in range(0, len(shots), columns):
+            chunk = shots[i : i + columns]
+            lines.append(row([self._render_shot(s, c, None, False) for s, c in chunk]))
+            if i == 0:
+                lines.append(row([":---:"] * columns))
+            if show_captions:
+                lines.append(row([c.replace("|", "\\|") for _, c in chunk]))
+        return "\n".join(lines)
+
+    def _html_gallery(
+        self, shots: list[tuple[Shot, str]], columns: int, show_captions: bool
+    ) -> str:
+        width = self.config.screenshots.width
+        cells = []
+        for shot, caption in shots:
+            cell = self._render_shot(shot, caption, width, force_html=True)
+            if show_captions:
+                cell += f"<br><sub>{html.escape(caption)}</sub>"
+            cells.append(f'<td align="center">{cell}</td>')
+        rows = [
+            "<tr>\n" + "\n".join(cells[i : i + columns]) + "\n</tr>"
+            for i in range(0, len(cells), columns)
+        ]
+        return "<table>\n" + "\n".join(rows) + "\n</table>"

readwright/metadata.py

@@ -0,0 +1,292 @@
+"""Autodetect repository metadata from git and common project manifests."""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from xml.etree import ElementTree
+
+GITHUB_REMOTE = re.compile(
+    r"^(?:git@github\.com:|(?:https?|ssh)://(?:[\w.-]+@)?github\.com/)"
+    r"(?P<owner>[^/]+)/(?P<repo>[^/]+?)(?:\.git)?/?$"
+)
+
+LICENSE_SIGNATURES: list[tuple[str, str]] = [
+    ("MIT License", "MIT"),
+    ("Apache License", "Apache-2.0"),
+    ("GNU General Public License", "GPL-3.0"),
+    ("GNU LESSER GENERAL PUBLIC LICENSE", "LGPL-3.0"),
+    ("GNU AFFERO GENERAL PUBLIC LICENSE", "AGPL-3.0"),
+    ("BSD 3-Clause", "BSD-3-Clause"),
+    ("BSD 2-Clause", "BSD-2-Clause"),
+    ("Mozilla Public License", "MPL-2.0"),
+    ("ISC License", "ISC"),
+    ("The Unlicense", "Unlicense"),
+]
+
+PYTHON_CLASSIFIER = re.compile(r"Programming Language :: Python :: (\d+\.\d+)$")
+GO_MODULE = re.compile(r"^module\s+(\S+)", re.MULTILINE)
+GRADLE_ROOT_NAME = re.compile(r"""rootProject\.name\s*=\s*['"]([^'"]+)['"]""")
+
+
+@dataclass
+class Metadata:
+    name: str | None = None
+    owner: str | None = None
+    repo: str | None = None
+    tagline: str | None = None
+    version: str | None = None
+    license: str | None = None
+    pypi: str | None = None
+    npm: str | None = None
+    crate: str | None = None
+    go_module: str | None = None
+    nuget: str | None = None
+    mod_id: str | None = None
+    minecraft_version: str | None = None
+    ha_min_version: str | None = None
+    flow_plugin: str | None = None
+    python_versions: list[str] = field(default_factory=list)
+    project_type: str = "generic"
+
+    @property
+    def url(self) -> str | None:
+        if self.owner and self.repo:
+            return f"https://github.com/{self.owner}/{self.repo}"
+        return None
+
+
+def parse_github_remote(url: str) -> tuple[str, str] | None:
+    match = GITHUB_REMOTE.match(url.strip())
+    if not match:
+        return None
+    return match["owner"], match["repo"]
+
+
+def git_remote_url(root: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(root), "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        return None
+    return result.stdout.strip() or None
+
+
+def license_from_file(root: Path) -> str | None:
+    for candidate in ("LICENSE", "LICENSE.md", "LICENSE.txt", "LICENCE", "COPYING"):
+        path = root / candidate
+        if path.is_file():
+            text = path.read_text(errors="replace").lower()
+            for signature, spdx in LICENSE_SIGNATURES:
+                if signature.lower() in text:
+                    return spdx
+    return None
+
+
+def _license_field(value: object) -> str | None:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        text = value.get("text")
+        return text if isinstance(text, str) and len(text) < 40 else None
+    return None
+
+
+def _set(meta: Metadata, **values: object) -> None:
+    for key, value in values.items():
+        if value:
+            setattr(meta, key, value)
+
+
+def _apply_pyproject(meta: Metadata, root: Path) -> bool:
+    path = root / "pyproject.toml"
+    if not path.is_file():
+        return False
+    project = tomllib.loads(path.read_text()).get("project", {})
+    meta.project_type = "python"
+    _set(
+        meta,
+        name=project.get("name"),
+        pypi=project.get("name"),
+        version=project.get("version"),
+        tagline=project.get("description"),
+        license=_license_field(project.get("license")),
+        python_versions=[
+            m.group(1) for c in project.get("classifiers", []) if (m := PYTHON_CLASSIFIER.search(c))
+        ],
+    )
+    return True
+
+
+def _apply_package_json(meta: Metadata, root: Path) -> bool:
+    path = root / "package.json"
+    if not path.is_file():
+        return False
+    data = json.loads(path.read_text())
+    meta.project_type = "node"
+    _set(
+        meta,
+        name=data.get("name"),
+        npm=data.get("name"),
+        version=data.get("version"),
+        tagline=data.get("description"),
+        license=_license_field(data.get("license")),
+    )
+    return True
+
+
+def _apply_cargo(meta: Metadata, root: Path) -> bool:
+    path = root / "Cargo.toml"
+    if not path.is_file():
+        return False
+    package = tomllib.loads(path.read_text()).get("package", {})
+    meta.project_type = "rust"
+    _set(
+        meta,
+        name=package.get("name"),
+        crate=package.get("name"),
+        version=package.get("version"),
+        tagline=package.get("description"),
+        license=package.get("license"),
+    )
+    return True
+
+
+def _apply_go(meta: Metadata, root: Path) -> bool:
+    path = root / "go.mod"
+    if not path.is_file():
+        return False
+    match = GO_MODULE.search(path.read_text())
+    meta.project_type = "go"
+    if match:
+        module = match.group(1)
+        _set(meta, go_module=module, name=module.rsplit("/", 1)[-1])
+    return True
+
+
+def _apply_dotnet(meta: Metadata, root: Path) -> bool:
+    projects = sorted(root.glob("*.csproj")) or sorted(root.glob("*/*.csproj"))
+    if not projects:
+        return False
+    path = projects[0]
+    meta.project_type = "dotnet"
+    try:
+        tree = ElementTree.parse(path)
+    except ElementTree.ParseError:
+        _set(meta, name=path.stem)
+        return True
+    props = {el.tag: (el.text or "").strip() for pg in tree.iter("PropertyGroup") for el in pg}
+    package_id = props.get("PackageId") or props.get("AssemblyName") or path.stem
+    _set(
+        meta,
+        name=package_id,
+        nuget=package_id if props.get("PackAsTool") or props.get("PackageId") else None,
+        version=props.get("Version") or props.get("PackageVersion"),
+        tagline=props.get("Description"),
+        license=props.get("PackageLicenseExpression"),
+    )
+    return True
+
+
+def _gradle_properties(root: Path) -> dict[str, str]:
+    path = root / "gradle.properties"
+    if not path.is_file():
+        return {}
+    props: dict[str, str] = {}
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if line and not line.startswith(("#", "!")) and "=" in line:
+            key, value = line.split("=", 1)
+            props[key.strip()] = value.strip()
+    return props
+
+
+def _apply_gradle(meta: Metadata, root: Path) -> bool:
+    build = next(
+        (root / n for n in ("build.gradle", "build.gradle.kts") if (root / n).is_file()), None
+    )
+    if build is None:
+        return False
+    props = _gradle_properties(root)
+    if props.get("mod_id") or props.get("mod_name") or props.get("minecraft_version"):
+        meta.project_type = "minecraft-mod"
+        _set(
+            meta,
+            name=props.get("mod_name") or props.get("mod_id"),
+            mod_id=props.get("mod_id"),
+            version=props.get("mod_version") or props.get("version"),
+            tagline=props.get("mod_description"),
+            minecraft_version=props.get("minecraft_version"),
+            license=props.get("mod_license"),
+        )
+        return True
+    meta.project_type = "gradle"
+    for settings in ("settings.gradle", "settings.gradle.kts"):
+        path = root / settings
+        if path.is_file() and (m := GRADLE_ROOT_NAME.search(path.read_text())):
+            _set(meta, name=m.group(1))
+    _set(meta, version=props.get("version"))
+    return True
+
+
+def _apply_hacs(meta: Metadata, root: Path) -> bool:
+    path = root / "hacs.json"
+    if not path.is_file():
+        return False
+    data = json.loads(path.read_text())
+    _apply_package_json(meta, root)
+    meta.project_type = "hacs"
+    _set(meta, name=data.get("name"), ha_min_version=data.get("homeassistant"))
+    return True
+
+
+def _apply_flow_plugin(meta: Metadata, root: Path) -> bool:
+    path = root / "plugin.json"
+    if not path.is_file():
+        return False
+    data = json.loads(path.read_text())
+    if "ActionKeyword" not in data and "ExecuteFileName" not in data:
+        return False
+    meta.project_type = "flow-plugin"
+    _set(
+        meta,
+        name=data.get("Name"),
+        flow_plugin=data.get("Name"),
+        version=data.get("Version"),
+        tagline=data.get("Description"),
+    )
+    return True
+
+
+DETECTORS = (
+    _apply_hacs,
+    _apply_flow_plugin,
+    _apply_pyproject,
+    _apply_package_json,
+    _apply_cargo,
+    _apply_go,
+    _apply_dotnet,
+    _apply_gradle,
+)
+
+
+def detect(root: Path) -> Metadata:
+    root = Path(root)
+    meta = Metadata(name=root.resolve().name)
+    remote = git_remote_url(root)
+    if remote and (parsed := parse_github_remote(remote)):
+        meta.owner, meta.repo = parsed
+    for detector in DETECTORS:
+        if detector(meta, root):
+            break
+    if not meta.license:
+        meta.license = license_from_file(root)
+    return meta

readwright/renderer.py

@@ -0,0 +1,183 @@
+"""Jinja environment construction and README rendering."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from jinja2 import (
+    BaseLoader,
+    ChoiceLoader,
+    Environment,
+    FileSystemLoader,
+    PackageLoader,
+    StrictUndefined,
+    TemplateNotFound,
+)
+
+from readwright.badges import BadgeRegistry, apply_style, shield
+from readwright.changelog import latest_entries
+from readwright.config import DEFAULT_TEMPLATE, Config, user_templates_dir
+from readwright.helpers import Helpers
+from readwright.images import ImageHelper
+from readwright.toc import FENCE, insert_toc, toc_token
+
+BASE_TEMPLATE = "base.md.j2"
+MARKER_PREFIX = "<!-- generated by readwright"
+
+
+def collapse_blank_lines(text: str) -> str:
+    """Squeeze runs of blank lines down to one, leaving fenced code blocks untouched."""
+    lines: list[str] = []
+    in_fence = False
+    previous_blank = False
+    for line in text.splitlines():
+        if FENCE.match(line):
+            in_fence = not in_fence
+        blank = not in_fence and line.strip() == ""
+        if blank and previous_blank:
+            continue
+        lines.append(line)
+        previous_blank = blank
+    result = "\n".join(lines)
+    return result.strip("\n") + "\n"
+
+
+def marker(template_name: str) -> str:
+    return f"{MARKER_PREFIX} from {template_name}; edit the template, not this file -->\n"
+
+
+class TrackingLoader(BaseLoader):
+    """Delegates to another loader and records which template names it served."""
+
+    def __init__(self, label: str, inner: BaseLoader) -> None:
+        self.label = label
+        self.inner = inner
+        self.served: list[str] = []
+
+    def get_source(self, environment: Environment, template: str):  # type: ignore[override]
+        source = self.inner.get_source(environment, template)
+        self.served.append(template)
+        return source
+
+    def list_templates(self) -> list[str]:
+        return self.inner.list_templates()
+
+
+@dataclass
+class RenderResult:
+    text: str
+    template_name: str
+    warnings: list[str] = field(default_factory=list)
+    user_templates: list[str] = field(default_factory=list)
+    sources: dict[str, str] = field(default_factory=dict)
+
+
+def loader_for(spec: str, root: Path) -> BaseLoader:
+    """Build a loader from a config `templates:` entry: a path or `pkg:<package>[/subdir]`."""
+    if spec.startswith("pkg:"):
+        package, _, subdir = spec[4:].partition("/")
+        return PackageLoader(package, subdir or "templates")
+    path = Path(spec)
+    return FileSystemLoader(str(path if path.is_absolute() else root / path))
+
+
+class Renderer:
+    def __init__(
+        self,
+        root: Path,
+        config: Config,
+        warn: Callable[[str], None] | None = None,
+        user_templates: Path | None = None,
+    ) -> None:
+        self.root = Path(root)
+        self.config = config
+        self.warnings: list[str] = []
+        self._external_warn = warn
+        self.badges = BadgeRegistry(config)
+        self.images = ImageHelper(self.root, config, warn=self._warn)
+        self.helpers = Helpers(self.root, config, warn=self._warn)
+        self.loaders: list[TrackingLoader] = [
+            TrackingLoader(
+                "repo", FileSystemLoader([str(self.root / "templates"), str(self.root)])
+            ),
+            *[TrackingLoader(spec, loader_for(spec, self.root)) for spec in config.templates],
+            TrackingLoader(
+                "user",
+                FileSystemLoader(str(user_templates if user_templates else user_templates_dir())),
+            ),
+            TrackingLoader("readwright", PackageLoader("readwright", "templates")),
+        ]
+        self.user_loader = next(ld for ld in self.loaders if ld.label == "user")
+        self.env = self._build_env()
+
+    def _warn(self, message: str) -> None:
+        self.warnings.append(message)
+        if self._external_warn:
+            self._external_warn(message)
+
+    def _build_env(self) -> Environment:
+        env = Environment(
+            loader=ChoiceLoader(list(self.loaders)),
+            undefined=StrictUndefined,
+            trim_blocks=True,
+            lstrip_blocks=True,
+            keep_trailing_newline=True,
+            autoescape=False,
+        )
+        env.globals.update(
+            badge=self.badges.render,
+            badges=self.badges.render_all,
+            donate_badges=self.badges.render_donate,
+            shield=self._styled_shield,
+            screenshot=self.images.screenshot,
+            screenshots=self.images.screenshots,
+            image=self.images.image,
+            has_screenshots=self.images.has_screenshots,
+            toc=toc_token,
+            changelog=lambda n=1, path=None, level=3: latest_entries(self.root, n, path, level),
+            project=self.config.project,
+            vars=self.config.vars,
+            config=self.config,
+            **self.helpers.as_globals(),
+        )
+        return env
+
+    def _styled_shield(self, *args, **kwargs) -> str:
+        style = kwargs.pop("style", None) or self.config.badges_style
+        return apply_style(shield(*args, **kwargs), style)
+
+    def source_label(self, name: str) -> str:
+        for loader in self.loaders:
+            try:
+                loader.inner.get_source(self.env, name)
+            except TemplateNotFound:
+                continue
+            return loader.label
+        raise TemplateNotFound(name)
+
+    def resolve_template_name(self) -> str:
+        name = self.config.template
+        try:
+            self.env.get_template(name)
+        except TemplateNotFound:
+            if name != DEFAULT_TEMPLATE:
+                raise
+            return BASE_TEMPLATE
+        return name
+
+    def render(self) -> RenderResult:
+        self.warnings.clear()
+        for loader in self.loaders:
+            loader.served.clear()
+        name = self.resolve_template_name()
+        body = self.env.get_template(name).render()
+        text = marker(name) + collapse_blank_lines(insert_toc(body))
+        return RenderResult(
+            text=text,
+            template_name=name,
+            warnings=list(self.warnings),
+            user_templates=list(self.user_loader.served),
+            sources={name: ld.label for ld in self.loaders for name in ld.served},
+        )