parla 0.0.1__py3-none-any.whl

parla/__init__.py

@@ -0,0 +1,3 @@
+"""parla."""
+
+__version__ = "0.0.1"

parla/assets/fonts/LICENSE-Latin-Modern.txt

@@ -0,0 +1,171 @@
+This package was debianized by Florent Rougon <f.rougon@free.fr> on
+Tue, 27 Jan 2004 20:12:21 +0100.
+
+The following TeX Live packages were downloaded from 
+    http://www.ctan.org/tex-archive/systems/texlive/tlnet/archive/
+and merged into one orig.tar.gz file:
+    lm.tar.xz
+    lm.doc.tar.xz
+    lm-math.tar.xz
+    lm-math.doc.tar.xz
+
+
+Upstream work
+-------------
+
+The upstream README-Latin-Modern.txt file says:
+
+  Font: The Latin Modern Family of Fonts
+  Designer (Computer Modern Family of Fonts): Donald E. Knuth
+  Author: Bogus\l{}aw Jackowski and Janusz M. Nowacki
+  Version: 2.005
+  Date: 21 III 2021
+  Downloads: http://www.gust.org.pl/projects/e-foundry/latin-modern/
+  License: 
+    % Copyright 2003--2021 by B. Jackowski and J.M. Nowacki
+    % (on behalf of TeX Users Groups).
+    % This work is released under the GUST Font License
+    %   -- see GUST-FONT-LICENSE.txt.
+    % This work has the LPPL maintenance status "maintained".
+    % The Current Maintainer of this work is Bogus\l{}aw Jackowski
+    % This work consists of the files listed in the MANIFEST.txt file.
+
+  [...]
+
+  The current LM package contains the most recent version
+  of the Latin Modern family of fonts in the PostScript Type 1 and
+  OpenType format. The fonts are based on Donald E. Knuth's Computer Modern
+  fonts in the PostScript Type 1 format, released into public domain by the
+  American Mathematical Society (for the history of the outline version of
+  the CM fonts see, e.g., http://www.math.utah.edu/~beebe/fonts/bluesky.html ).
+  The project is supported by TeX users groups: CSTUG, DANTE eV, GUST,
+  GUTenberg, NTG, and TUG.
+
+
+The current README-Latin-Modern-Math.txt says
+License:
+  % Copyright 2012--2014 for the Latin Modern math extensions by B. Jackowski,
+  % P. Strzelczyk and P. Pianowski (on behalf of TeX Users Groups).
+  %
+  % This work can be freely used and distributed under
+  % the GUST Font License (GFL -- see GUST-FONT-LICENSE.txt)
+  % which is actually an instance of the LaTeX Project Public License
+  % (LPPL -- see http://www.latex-project.org/lppl.txt).
+  %
+  % This work has the maintenance status "maintained". The Current Maintainer
+  % of this work is Bogus\l{}aw Jackowski, Piotr Strzelczyk and Piotr Pianowski.
+  %
+  % This work consists of the files listed
+  % in the MANIFEST-Latin-Modern-Math.txt file.
+
+
+See the appendix B for the GUST Font License.
+
+Please read the appendix A below if you want to examine the licensing terms 
+for the Computer Modern fonts in Type 1 format on which the Latin Modern fonts
+are based.
+
+
+Debian packaging
+----------------
+
+Copyright (c) 2004-2007 Florent Rougon
+Copyright (c) 2005-2019 Norbert Preining
+Copyright (c) 2021-2022 Hilmar Preusse
+
+   This program is free software; you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; version 2 dated June, 1991.
+
+   This program is distributed in the hope that it will be useful, but
+   WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+   General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; see the file COPYING. If not, write to the
+   Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+   Boston, MA  02110-1301 USA.
+
+On Debian systems, the complete text of the GNU General Public License version
+2 can be found in `/usr/share/common-licenses/GPL-2'.
+
+
+Appendix A -- Licensing terms for the Computer Modern fonts in Type 1 format
+              on which the Latin Modern fonts are based.
+-----------------------------------------------------------------------------
+
+Running t1disasm (from the t1utils package) on
+/usr/share/texmf/fonts/type1/bluesky/cm/*.pfb and
+/usr/share/texmf/fonts/type1/bluesky/cmextra/*.pfb yields:
+
+  Copyright (C) 1997 American Mathematical Society.  All Rights Reserved
+
+  [ Florent Rougon's note: well, for
+    /usr/share/texmf/fonts/type1/bluesky/cm/cmb{,sy}10.pfb, you will only get
+    one space between "Society." and "All" (with tetex-extra 2.0.2-5.1). ;-) ]
+
+The precise distribution conditions for these fonts can be found in
+/usr/share/doc/texmf/fonts/bluesky/README from the tetex-doc package. I will
+duplicate here the relevant excerpt for your convenience:
+
+  The PostScript Type 1 implementation of the Computer Modern fonts produced
+  by and previously distributed by Blue Sky Research and Y&Y, Inc. are now
+  freely available for general use. This has been accomplished through the
+  cooperation of a consortium of scientific publishers with Blue Sky Research
+  and Y&Y. Members of this consortium include:
+
+        Elsevier Science
+        IBM Corporation
+        Society for Industrial and Applied Mathematics (SIAM)
+        Springer-Verlag
+        American Mathematical Society (AMS)
+
+  In order to assure the authenticity of these fonts, copyright will be held
+  by the American Mathematical Society. This is not meant to restrict in any
+  way the legitimate use of the fonts, such as (but not limited to) electronic
+  distribution of documents containing these fonts, inclusion of these fonts
+  into other public domain or commercial font collections or computer
+  applications, use of the outline data to create derivative fonts and/or
+  faces, etc. However, the AMS does require that the AMS copyright notice be
+  removed from any derivative versions of the fonts which have been altered in
+  any way. In addition, to ensure the fidelity of TeX documents using Computer
+  Modern fonts, Professor Donald Knuth, creator of the Computer Modern faces,
+  has requested that any alterations which yield different font metrics be
+  given a different name.
+
+
+Appendix B -- GUST Font License
+-------------------------------
+
+What follows is the exact contents of GUST-FONT-LICENSE.txt from the
+upstream distribution of the Latin Modern fonts.
+
+% This is version 1.0, dated 22 June 2009, of the GUST Font License.
+% (GUST is the Polish TeX Users Group, http://www.gust.org.pl)
+%
+% For the most recent version of this license see
+% http://www.gust.org.pl/fonts/licenses/GUST-FONT-LICENSE.txt
+% or
+% http://tug.org/fonts/licenses/GUST-FONT-LICENSE.txt
+%
+% This work may be distributed and/or modified under the conditions
+% of the LaTeX Project Public License, either version 1.3c of this
+% license or (at your option) any later version.
+%
+% Please also observe the following clause:
+% 1) it is requested, but not legally required, that derived works be
+%    distributed only after changing the names of the fonts comprising this
+%    work and given in an accompanying "manifest", and that the
+%    files comprising the Work, as listed in the manifest, also be given
+%    new names. Any exceptions to this request are also given in the
+%    manifest.
+%
+%    We recommend the manifest be given in a separate file named
+%    MANIFEST-<fontid>.txt, where <fontid> is some unique identification
+%    of the font family. If a separate "readme" file accompanies the Work,
+%    we recommend a name of the form README-<fontid>.txt.
+%
+% The latest version of the LaTeX Project Public License is in
+% http://www.latex-project.org/lppl.txt and version 1.3c or later
+% is part of all distributions of LaTeX version 2006/05/20 or later.

parla/casebook.py

@@ -0,0 +1,180 @@
+"""The casebook: approved corrections as an append-only JSON-lines store. See `specs/casebook.md`."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, date, datetime, timedelta
+from pathlib import Path
+
+from . import config as config_mod
+from .checks import Finding
+from .checks.ids import finding
+
+STATUSES = ("active", "distilled", "contradicted", "pruned")
+REQUIRED = ("artifact", "part", "topics", "hook", "problem", "before", "after", "lesson")
+CASES_FILE = "cases.jsonl"
+USE_FILE = "cases.use.jsonl"
+
+
+class CaseError(Exception):
+    """A case command cannot proceed."""
+
+
+def _path(name: str) -> Path:
+    return config_mod.guides_private() / name
+
+
+def _lines(name: str) -> list[dict]:
+    path = _path(name)
+    if not path.is_file():
+        return []
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+def _append(name: str, entry: dict) -> None:
+    path = _path(name)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+
+def load() -> dict[str, dict]:
+    """The current state of every case: its lines folded in order. Insertion order is first-seen."""
+    cases: dict[str, dict] = {}
+    for entry in _lines(CASES_FILE):
+        cases.setdefault(entry["id"], {}).update(entry)
+    return cases
+
+
+def add(root: Path, payload: dict, known_topics: set[str], *, today: date | None = None) -> str:
+    missing = [k for k in REQUIRED if not payload.get(k)]
+    if missing:
+        raise CaseError(f"missing field(s): {', '.join(missing)}")
+    if not isinstance(payload["topics"], list):
+        raise CaseError("topics must be a list")
+    unknown = [t for t in payload["topics"] if t not in known_topics]
+    if unknown:
+        raise CaseError(f"unknown topic(s): {', '.join(unknown)} (have: {', '.join(sorted(known_topics))})")
+    for key in ("hook", "lesson"):
+        if "\n" in payload[key].strip():
+            raise CaseError(f"the {key} must be one line")
+    card = config_mod.load_card(root, payload["artifact"])
+    cases = load()
+    number = max((int(i.removeprefix("c-")) for i in cases), default=0) + 1
+    entry = {
+        "id": f"c-{number:04d}",
+        "date": (today or datetime.now(UTC).date()).isoformat(),
+        **{k: payload[k] for k in REQUIRED},
+        "modality": card.modality,
+        "audience": card.audience,
+        "contradicts": payload.get("contradicts", []),
+        "status": "active",
+    }
+    _append(CASES_FILE, entry)
+    return entry["id"]
+
+
+EDITABLE = ("hook", "lesson", "problem", "topics")
+
+
+def edit(case_id: str, fields: dict, known_topics: set[str]) -> None:
+    """Appends an update to a case. Only the hook, lesson, problem and topics can change; the before
+    and after stay as the author left them."""
+    if case_id not in load():
+        raise CaseError(f"unknown case '{case_id}'")
+    bad = set(fields) - set(EDITABLE)
+    if bad or not fields:
+        raise CaseError(f"edit takes {', '.join(EDITABLE)}; got {', '.join(sorted(bad)) or 'nothing'}")
+    for key in ("hook", "lesson"):
+        if key in fields and ("\n" in str(fields[key]).strip() or not str(fields[key]).strip()):
+            raise CaseError(f"the {key} must be one non-empty line")
+    unknown = [t for t in fields.get("topics", []) if t not in known_topics]
+    if unknown:
+        raise CaseError(f"unknown topic(s): {', '.join(unknown)} (have: {', '.join(sorted(known_topics))})")
+    _append(CASES_FILE, {"id": case_id, **fields})
+
+
+def mark(case_id: str, status: str) -> None:
+    if status not in STATUSES:
+        raise CaseError(f"unknown status '{status}' (have: {', '.join(STATUSES)})")
+    if case_id not in load():
+        raise CaseError(f"unknown case '{case_id}'")
+    _append(CASES_FILE, {"id": case_id, "status": status})
+
+
+def list_lines(topic: str | None = None, status: str | None = None) -> list[str]:
+    return [
+        f"{c['id']} {c['status']} {','.join(c['topics'])} {c['audience']} {c.get('hook', '-')} | {c['lesson']}"
+        for c in load().values()
+        if (topic is None or topic in c["topics"]) and (status is None or c["status"] == status)
+    ]
+
+
+def retrieve(
+    *, topics: set[str], modality: str, audience: str | None, artifact: str, max_cases: int
+) -> list[dict]:
+    """Active or distilled cases on the loaded topics whose audience and modality match or are
+    absent, best first: same artifact, same audience, same modality, most recent."""
+    hits = [
+        c for c in load().values()
+        if c["status"] in ("active", "distilled")
+        and topics & set(c["topics"])
+        and (not c.get("audience") or c["audience"] == audience)
+        and (not c.get("modality") or c["modality"] == modality)
+    ]
+    hits.sort(
+        key=lambda c: (c["artifact"] == artifact, c.get("audience") == audience, c.get("modality") == modality, c["date"], c["id"]),
+        reverse=True,
+    )
+    return hits[:max_cases]
+
+
+def show(case_ids: list[str], artifact: str) -> str:
+    """The cases in full as XML, in the order asked; logs one use per case."""
+    cases = load()
+    unknown = [i for i in case_ids if i not in cases]
+    if unknown:
+        raise CaseError(f"unknown case(s): {', '.join(unknown)}")
+    log_use(case_ids, artifact)
+    return "\n\n".join(
+        f'<case id="{i}">\n'
+        + "\n".join(f"<{k}>{cases[i][k]}</{k}>" for k in ("problem", "after", "lesson"))
+        + "\n</case>"
+        for i in case_ids
+    )
+
+
+def log_use(case_ids: list[str], artifact: str, *, today: date | None = None) -> None:
+    stamp = (today or datetime.now(UTC).date()).isoformat()
+    for case_id in case_ids:
+        _append(USE_FILE, {"case": case_id, "date": stamp, "artifact": artifact})
+
+
+def lint(*, distill_min: int, stale_days: int | None, today: date | None = None) -> list[Finding]:
+    today = today or datetime.now(UTC).date()
+    cases = load()
+    first_line: dict[str, int] = {}
+    for number, entry in enumerate(_lines(CASES_FILE), 1):
+        first_line.setdefault(entry["id"], number)
+    active = [c for c in cases.values() if c["status"] == "active"]
+    findings: list[Finding] = []
+    groups: dict[tuple[str, str], list[str]] = {}
+    for c in active:
+        for topic in c["topics"]:
+            groups.setdefault((topic, c.get("audience", "")), []).append(c["id"])
+    for (topic, audience), ids in sorted(groups.items()):
+        if len(ids) >= distill_min:
+            findings.append(finding(
+                "case-distill", CASES_FILE, first_line[ids[0]],
+                f"{len(ids)} active cases on '{topic}' for '{audience}' ({', '.join(ids)}): propose a principle",
+            ))
+    if stale_days is not None:
+        last_use: dict[str, str] = {}
+        for use in _lines(USE_FILE):
+            last_use[use["case"]] = max(last_use.get(use["case"], ""), use["date"])
+        cutoff = today - timedelta(days=stale_days)
+        for c in active:
+            seen = date.fromisoformat(last_use.get(c["id"], c["date"]))
+            if seen < cutoff:
+                findings.append(finding("case-stale", CASES_FILE, first_line[c["id"]], f"{c['id']} was not retrieved since {seen}"))
+    return findings

parla/checks/__init__.py

@@ -0,0 +1,3 @@
+from .finding import CheckFailed, Finding, Severity
+
+__all__ = ["CheckFailed", "Finding", "Severity"]

parla/checks/finding.py

@@ -0,0 +1,28 @@
+"""One reported problem. See `specs/checks.md#finding`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Severity = Literal["error", "warning", "probe", "resolved"]
+
+
+@dataclass(frozen=True)
+class Finding:
+    file: str  # relative to parla/
+    line: int
+    severity: Severity
+    id: str
+    message: str
+
+    def format(self) -> str:
+        return f"{self.file}:{self.line}: {self.severity} {self.id}: {self.message}"
+
+
+class CheckFailed(Exception):
+    """A check reported an error finding; nothing was built."""
+
+    def __init__(self, findings: list[Finding]):
+        self.findings = findings
+        super().__init__("\n".join(f.format() for f in findings if f.severity == "error"))

parla/checks/ids.py

@@ -0,0 +1,59 @@
+"""Every check id and its severity. Ids are stable: projects list them in `[checks].ignore`."""
+
+from __future__ import annotations
+
+from .finding import Finding, Severity
+
+SEVERITY: dict[str, Severity] = {
+    "card-invalid": "error",
+    "source-missing": "error",
+    "cite-unresolved": "error",
+    "figure-missing": "error",
+    "bib-name-syntax": "error",
+    "unescaped-char": "error",
+    "brace-unbalanced": "error",
+    "macro-missing": "error",
+    "translation-parity": "error",
+    "ref-dangling": "warning",
+    "float-unreferenced": "warning",
+    "float-order": "warning",
+    "figure-duplicate": "warning",
+    "abbreviation-repeated": "warning",
+    "cite-style": "warning",
+    "todo-marker": "warning",
+    "appendix-structure": "warning",
+    "svg-overflow": "error",
+    "svg-collision": "error",
+    "svg-arrow-crossing": "error",
+    "svg-glyph-missing": "error",
+    "svg-href-missing": "error",
+    "svg-malformed": "error",
+    "svg-math-in-text": "error",
+    "svg-unsupported": "warning",
+    "rule-malformed": "error",
+    "rule-origin-missing": "error",
+    "rule-duplicate": "error",
+    "rule-overrides-missing": "error",
+    "public-rule": "error",
+    "brief-missing": "error",
+    "link-broken": "error",
+    "guide-over-budget": "warning",
+    "guide-page-over-cap": "warning",
+    "hook-missing": "error",
+    "topic-applicable-unknown": "error",
+    "constraint-example-failed": "error",
+    "constraint-refine": "warning",
+    "frame-overflow": "error",
+    "overfull-line": "warning",
+    "rule-contradicted": "warning",
+    "case-distill": "warning",
+    "case-stale": "warning",
+}
+
+
+def finding(check_id: str, file: str, line: int, message: str) -> Finding:
+    return Finding(file, line, SEVERITY[check_id], check_id, message)
+
+
+def is_constraint(f: Finding) -> bool:
+    return f.id.startswith("constraint/")

parla/checks/shared.py

@@ -0,0 +1,57 @@
+"""Checks every engine shares. See `specs/checks.md#ids`."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .. import config as config_mod
+from ..names import PROJECT_DIR
+from .finding import Finding
+from .ids import finding
+
+TEXT_SUFFIXES = {".tex", ".md", ".svg", ".txt"}
+SKIPPED_FILES = {"card.md", "references.bib"}
+_FIGURE_EXTENSIONS = (".pdf", ".png", ".jpg", ".jpeg", ".eps", ".svg", ".tex")
+_COMMENT_RE = re.compile(r"(?<!\\)%.*")
+_SOURCE_PATH_RE = re.compile(r"(?<![\w/.\-])sources/[^\s{}()\[\],\"'<>]+")
+
+
+def card_invalid(root: Path, artifact: str) -> Finding | None:
+    """A finding when the artifact has a card that does not validate; `None` when there is no
+    card file (the caller fails on that) or the card is valid."""
+    if not config_mod.card_path(root, artifact).is_file():
+        return None
+    try:
+        config_mod.load_card(root, artifact)
+    except config_mod.ConfigError as exc:
+        return finding("card-invalid", f"artifacts/{artifact}/card.md", 1, str(exc))
+    return None
+
+
+def artifact_files(root: Path, artifact: str) -> list[Path]:
+    base = root / PROJECT_DIR / "artifacts" / artifact
+    return [
+        p for p in sorted(base.rglob("*"))
+        if p.is_file() and p.suffix in TEXT_SUFFIXES and p.name not in SKIPPED_FILES
+    ]
+
+
+def _exists(base: Path, rel: str) -> bool:
+    path = base / rel
+    return path.exists() or any(path.with_name(path.name + ext).exists() for ext in _FIGURE_EXTENSIONS)
+
+
+def source_missing(root: Path, artifact: str) -> list[Finding]:
+    """Every `sources/...` path an artifact file names that does not exist under `parla/`."""
+    base = root / PROJECT_DIR
+    findings: list[Finding] = []
+    for path in artifact_files(root, artifact):
+        rel_file = path.relative_to(base).as_posix()
+        for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+            text = _COMMENT_RE.sub("", line) if path.suffix == ".tex" else line
+            for match in _SOURCE_PATH_RE.finditer(text):
+                target = match.group(0).rstrip(".:;")
+                if not _exists(base, target):
+                    findings.append(finding("source-missing", rel_file, number, f"{target} does not exist"))
+    return findings