cv-tools-cli 2.0.0__py3-none-any.whl

cv_tools/__init__.py

@@ -0,0 +1,7 @@
+"""cv-tools: generate a LaTeX CV from a YAML file."""
+
+__version__ = "2.0.0"
+
+from .api import build_pdf, load, migrate_text, render_html, render_tex  # noqa: E402
+
+__all__ = ["__version__", "build_pdf", "load", "migrate_text", "render_html", "render_tex"]

cv_tools/__main__.py

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

cv_tools/api.py

@@ -0,0 +1,123 @@
+"""The public API: load a CV, then render it to LaTeX, HTML or PDF."""
+
+from __future__ import annotations
+
+import datetime
+import sys
+import warnings
+from pathlib import Path
+from typing import Optional, Union
+
+from . import engine as _engine
+from . import charset, model, v1
+from .loader import CVError, Source, YamlPath, load_file, load_text
+from .migrate import migrate_text as _migrate
+from .model import Document
+from .render import html, latex
+from .render.html import HtmlResult
+from .render.latex import RenderResult
+from .validate import ValidationError, validate
+
+__all__ = [
+    "CVError", "Document", "HtmlResult", "RenderResult", "ValidationError",
+    "build_pdf", "load", "load_with_v1_warnings", "loads", "migrate_text", "render_html", "render_tex",
+    "split_path",
+]
+
+
+def load(path: Union[str, Path]) -> Document:
+    """Load a v1 or v2 CV file into the v2 model (a v1 file also warns on stderr)."""
+    return _document(load_file(path))[0]
+
+
+def load_with_v1_warnings(path: Union[str, Path]) -> tuple[Document, list[str]]:
+    """Like :func:`load`, and also return the v1 conversion warnings on their own."""
+    return _document(load_file(path))
+
+
+def loads(text: str, name: str = "<string>", base_dir: Optional[Path] = None) -> Document:
+    """Like :func:`load`, for YAML text. Relative .bib paths resolve against ``base_dir``."""
+    return _document(load_text(text, name, base_dir))[0]
+
+
+def _document(src: Source) -> tuple[Document, list[str]]:
+    path = Path(src.name) if src.name != "<string>" else None
+    if v1.detect(src) == "v2":
+        errors = validate(src)
+        if errors:
+            raise ValidationError(errors)
+        doc = _checked(src, src.data, "v2", path, lambda p: p)
+        doc.aliases, doc.anchors = src.aliases, src.anchors
+        return doc, []
+
+    message = v1.DEPRECATION.format(file=src.name)
+    print(message, file=sys.stderr)
+    warnings.warn(message, DeprecationWarning, stacklevel=3)
+    conversion = v1.convert(src)
+    doc = _checked(src, conversion.data, "v1", path, lambda p: _v1_path(conversion.origins, p))
+    doc.warnings[:0] = conversion.warnings
+    return doc, list(conversion.warnings)
+
+
+def _checked(src: Source, data: dict, fmt: str, path: Optional[Path], source_path) -> Document:
+    # pdflatex must be able to print every character of the text and .bib fields.
+    errors = charset.check_data(src, data, source_path, show_path=fmt == "v2")
+    if errors:
+        raise ValidationError(errors)
+    doc = _from_data(src, data, fmt, path, source_path)
+    errors = [e for s in doc.sections if s.bib is not None for e in charset.check_publications(s.bib, s.publications)]
+    if errors:
+        raise ValidationError(errors)
+    return doc
+
+
+def _v1_path(origins: dict[YamlPath, YamlPath], path: YamlPath) -> YamlPath:
+    while path and path not in origins:
+        path = path[:-1]
+    return origins.get(path, ())
+
+
+def _from_data(src: Source, data: dict, fmt: str, path: Optional[Path], source_path) -> Document:
+    try:
+        return model.from_data(data, src.base_dir, fmt, path)
+    except model.ModelError as e:
+        raise src.error(e.message, source_path(e.path)) from None
+
+
+def render_tex(doc: Document) -> RenderResult:
+    """Render the LaTeX source and the support files it needs."""
+    return latex.render(doc)
+
+
+def render_html(doc: Document, today: Optional[datetime.date] = None) -> HtmlResult:
+    """Render the HTML live preview. ``today`` is the date printed for ``date: auto``."""
+    return html.render(doc, today=today)
+
+
+def split_path(path: str) -> tuple[Union[str, int], ...]:
+    """A ``data-path`` value as a YAML path."""
+    return html.split_path(path)
+
+
+def build_pdf(
+    doc: Document,
+    out: Union[str, Path, None] = None,
+    engine: str = "auto",
+    source_date_epoch: Optional[int] = None,
+) -> bytes:
+    """Compile the CV to PDF with ``engine`` (auto, pdflatex or docker), write ``out`` if given, and return the bytes."""
+    workdir = Path(out).resolve().parent if out is not None else Path.cwd()
+    pdf = _engine.compile_pdf(render_tex(doc), engine=engine, source_date_epoch=source_date_epoch, workdir=workdir)
+    if out is not None:
+        Path(out).parent.mkdir(parents=True, exist_ok=True)
+        Path(out).write_bytes(pdf)
+    return pdf
+
+
+def migrate_text(v1_text: str, name: str = "<string>") -> str:
+    """Convert v1 YAML text to v2 YAML text. Warnings go to ``warnings.warn``."""
+    migration = _migrate(v1_text, name)
+    for warning in migration.warnings:
+        warnings.warn(warning, UserWarning, stacklevel=2)
+    return migration.text
+

cv_tools/bib.py

@@ -0,0 +1,122 @@
+"""BibTeX loading, author names and highlight matching. Fields are LaTeX, printed as written."""
+
+from __future__ import annotations
+
+import codecs
+import re
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+
+import latexcodec  # noqa: F401  (registers the "ulatex" codec; a pybtex dependency)
+
+from pybtex.database import Person, parse_file
+from pybtex.exceptions import PybtexError
+
+from .loader import CVError
+
+
+@dataclass(frozen=True)
+class Author:
+    name: str  # LaTeX, as written in the .bib file
+    highlighted: bool
+
+
+@dataclass(frozen=True)
+class Publication:
+    """One .bib entry. Text fields are LaTeX from the .bib file; None when missing."""
+
+    key: str
+    authors: tuple[Author, ...]
+    title: str | None
+    venue: str | None
+    year: str | None
+    url: str | None  # a plain URL, BibTeX escapes resolved
+    venue_field: str | None = None  # "journal" or "booktitle", where the venue came from
+
+
+def format_name(person: Person) -> str:
+    """The full name with its von and Jr. parts, which cv-tools 1.x dropped."""
+    parts = (
+        person.first_names + person.middle_names + person.prelast_names + person.last_names + person.lineage_names
+    )
+    return " ".join(" ".join(parts).split())
+
+
+def bib_url(url: str) -> str:
+    """A BibTeX ``url`` field as a plain URL, escapes and braces resolved."""
+    url = re.sub(r"\\([%#_&$~])", r"\1", url)
+    return re.sub(r"(?<!\\)[{}]", "", url).strip()
+
+
+def _decode(name: str) -> str:
+    """LaTeX accents to Unicode, so ``Jos{\\'e}`` and ``José`` compare equal."""
+    try:
+        name = codecs.decode(name, "ulatex")
+    except (ValueError, LookupError):  # pragma: no cover - latexcodec passes unknown input through
+        pass
+    return unicodedata.normalize("NFC", name)
+
+
+def _normalize(name: str) -> str:
+    name = _decode(name).replace("{", "").replace("}", "")
+    return " ".join(name.split()).casefold()
+
+
+def _join(*parts: str) -> str:
+    return " ".join(p for p in parts if p)
+
+
+def _name_forms(person: Person) -> set[str]:
+    first = " ".join(person.first_names + person.middle_names)
+    last = _join(*person.prelast_names, *person.last_names)
+    jr = " ".join(person.lineage_names)
+    forms = {format_name(person), _join(first, last) + (f", {jr}" if jr else "")}
+    if first:
+        forms.add(f"{last}, {jr}, {first}" if jr else f"{last}, {first}")
+        if jr:
+            forms.add(f"{last} {jr}, {first}")
+    return {_normalize(f) for f in forms}
+
+
+def matches(person: Person, names: list[str]) -> bool:
+    """True if any of ``names`` is this author's full name, ignoring case, braces, spacing and accent spelling."""
+    wanted = {_normalize(n) for n in names} - {""}
+    return bool(wanted & _name_forms(person))
+
+
+def _field(fields, name: str) -> str | None:
+    value = fields.get(name)
+    return value if value is not None and value.strip() else None
+
+
+def load(path: Path, highlight: list[str]) -> tuple[list[Publication], list[str]]:
+    """Entries of a .bib file in file order, and warnings about missing fields."""
+    if not Path(path).is_file():
+        raise CVError(f"BibTeX file not found: {path}")
+    try:
+        data = parse_file(str(path), bib_format="bibtex")
+    except (PybtexError, UnicodeDecodeError) as e:
+        raise CVError(f"cannot read BibTeX file {path}: {e}") from None
+
+    publications, warnings = [], []
+    for key, entry in data.entries.items():
+        persons = entry.persons.get("author", [])
+        authors = tuple(Author(format_name(p), matches(p, highlight)) for p in persons)
+        fields = entry.fields
+        title, year = _field(fields, "title"), _field(fields, "year")
+        missing = [f for f, present in (("author", authors), ("title", title), ("year", year)) if not present]
+        for name in missing:
+            warnings.append(f"{path}: warning: entry '{key}' has no {name}; it is left out of the citation")
+        publications.append(
+            Publication(
+                key=key,
+                authors=authors,
+                title=title,
+                venue=_field(fields, "journal") or _field(fields, "booktitle"),
+                venue_field="journal" if _field(fields, "journal") else "booktitle" if _field(fields, "booktitle") else None,
+                year=year,
+                url=bib_url(fields["url"]) if _field(fields, "url") else None,
+            )
+        )
+    return publications, warnings

cv_tools/charset.py

@@ -0,0 +1,142 @@
+"""Checks that pdflatex can print every character (``templates/latex/unicode.txt``) before it runs."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path
+from typing import Any, Callable, Iterator, Optional
+
+from .loader import CVError, Source, YamlPath
+from .markup import Latex, to_latex
+
+# Keys whose values are never printed as text.
+_NOT_TEXT = frozenset({"version", "layout", "bib", "highlight", "url", "orcid", "linkedin", "github", "twitter"})
+
+# hyperref reads URL arguments with other catcodes, so any character works there.
+_URL_COMMAND = re.compile(r"\\(?:href|url)\s*\{")
+
+_YAML_LINE_BREAK = re.compile("\r\n|[\n\r\x85\u2028\u2029]")
+
+
+@lru_cache(maxsize=1)
+def supported() -> frozenset[int]:
+    """Code points above ASCII that print in every font of the class."""
+    text = (resources.files("cv_tools") / "templates" / "latex" / "unicode.txt").read_text(encoding="utf-8")
+    return frozenset(int(line.split()[0], 16) for line in text.splitlines() if line and not line.startswith("#"))
+
+
+def prints(c: str) -> bool:
+    return ord(c) < 0x80 or ord(c) in supported()
+
+
+def _without_urls(latex: str) -> str:
+    out, i = [], 0
+    for match in _URL_COMMAND.finditer(latex):
+        if match.start() < i:
+            continue
+        depth, j = 1, match.end()
+        while j < len(latex) and depth:
+            if latex[j] == "\\":
+                j += 2
+                continue
+            depth += {"{": 1, "}": -1}.get(latex[j], 0)
+            j += 1
+        out.append(latex[i : match.end()])
+        i = j - 1 if depth == 0 else len(latex)
+    out.append(latex[i:])
+    return "".join(out)
+
+
+def problems(latex: str, uppercased: bool = False) -> list[tuple[str, Optional[str]]]:
+    """``(character, upper-case form)`` for each character of ``latex`` that pdflatex cannot print."""
+    # The upper-case form is set when only it fails (titles are upper-cased).
+    found: dict[str, Optional[str]] = {}
+    for c in _without_urls(latex):
+        if c in found:
+            continue
+        if not prints(c):
+            found[c] = None
+        elif uppercased and not all(prints(u) for u in c.upper()):
+            found[c] = c.upper()
+    return list(found.items())
+
+
+def describe(c: str, upper: Optional[str] = None) -> str:
+    name = unicodedata.name(c, "")
+    shown = repr(c) if unicodedata.category(c)[0] != "C" else "a control character"
+    what = f"the character {shown} (U+{ord(c):04X}{' ' + name if name else ''})"
+    if upper is not None:
+        return (f"{what} becomes {upper!r} in the upper-cased name or section title, which pdflatex cannot "
+                "print with the fonts of the cv-tools class; leave it out of the name and titles")
+    return (f"{what} cannot be printed by pdflatex with the fonts of the cv-tools class; "
+            "replace it or leave it out")
+
+
+def _texts(value: Any, path: YamlPath) -> Iterator[tuple[YamlPath, str]]:
+    if isinstance(value, dict):
+        if list(value) == ["latex"] and isinstance(value["latex"], str):
+            yield path, value["latex"]
+            return
+        for key, child in value.items():
+            if key not in _NOT_TEXT:
+                yield from _texts(child, path + (key,))
+    elif isinstance(value, list):
+        for i, child in enumerate(value):
+            yield from _texts(child, path + (i,))
+    elif isinstance(value, str):
+        yield path, to_latex(value)  # URLs in links come out escaped
+
+
+def _uppercased(path: YamlPath) -> bool:
+    return path == ("name",) or (len(path) == 3 and path[0] == "sections" and path[2] == "title")
+
+
+def _offset(text: str, line: int, col: int) -> int:
+    start = 0
+    for _ in range(line - 1):
+        match = _YAML_LINE_BREAK.search(text, start)
+        if match is None:
+            return len(text)
+        start = match.end()
+    return start + col - 1
+
+
+def _position(text: str, start: int) -> tuple[int, int]:
+    breaks = list(_YAML_LINE_BREAK.finditer(text, 0, start))
+    line_start = breaks[-1].end() if breaks else 0
+    return len(breaks) + 1, start - line_start + 1
+
+
+def check_data(src: Source, data: dict, source_path: Callable[[YamlPath], YamlPath],
+               show_path: bool = True) -> list[CVError]:
+    """An error for each character of a text field that pdflatex cannot print."""
+    from .validate import format_path
+
+    errors = []
+    for path, latex in _texts(data, ()):
+        found = problems(latex, _uppercased(path))
+        if not found:
+            continue
+        where = src.position(source_path(path))
+        start = _offset(src.text, *where) if where else 0
+        for c, upper in found:
+            index = src.text.find(c, start)
+            line, col = _position(src.text, index) if index != -1 else (where or (None, None))
+            prefix = f"{format_path(path)}: " if show_path else ""
+            errors.append(CVError(prefix + describe(c, upper), src.name, line, col))
+    return sorted(errors, key=lambda e: (e.line or 0, e.col or 0))
+
+
+def check_publications(bib_path: Path, publications) -> list[CVError]:
+    """An error for each character of a used .bib field that pdflatex cannot print."""
+    errors = []
+    for pub in publications:
+        fields = [("author", a.name) for a in pub.authors]
+        fields += [("title", pub.title), (pub.venue_field, pub.venue), ("year", pub.year)]
+        for field, value in fields:
+            for c, _ in problems(value or ""):
+                errors.append(CVError(f"entry '{pub.key}', field '{field}': {describe(c)}", str(bib_path)))
+    return errors