calkit-python 0.48.1__tar.gz → 0.48.2__tar.gz

calkit_python-0.48.2/.calkit/env-locks/tex/amd64.json

@@ -0,0 +1,27 @@
+{
+    "RepoDigests": [
+        "sha256:a6df16eb0634a94defc9c794f6a4a94addca2cc41857f2e89c4db332591676c0"
+    ],
+    "Architecture": "amd64",
+    "Os": "linux",
+    "RootFS": {
+        "Type": "layers",
+        "Layers": [
+            "sha256:d81fb2a7c6ee3be05fdefaa7fd223be219c1ab172083ec1b994c3ecda33ac0a8",
+            "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
+            "sha256:05364db6671946629d30df5e2b0e64ac1ddf9584c850821e1310798b81dae7a6",
+            "sha256:eca883d1959b8c01c3803666dd78acfab745385c182f0134f57d6b13b0eaa5a8",
+            "sha256:b3f81a4dd621eb52ef44f1fd2708b2551d657e13f6ddcd08ebb07c072bff71ed",
+            "sha256:827badad9c1d1c760a817bd906551372d602a9d4f09326f36a91db0c97a8bad1",
+            "sha256:c9e8d9eec8adf285383a9342d7d3f5eb17ff30c83678505135caffe2d2685b1d",
+            "sha256:e2dcd8f807ab6625ede0dffebdd2280a48bdeba51fe464b5e8bceb15dd33d384",
+            "sha256:a7896112a0671141d2eb2860c8bf898f671bc9bdd32444d85a6cb0b11d095ded",
+            "sha256:a7080e7b80de5013eacc71c8d75a7160ff39e0f255a86138b0bbe2e7ed74a064",
+            "sha256:b29c7c1282fc0ab03ceb8cb5b0011ee14bdef43aa8a3f34a76d806f56dbeb41f",
+            "sha256:267d6598e62980803a111eaf396233bb26c552794580d0f9e3d622a717574e09",
+            "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
+        ]
+    },
+    "DockerfileMD5": null,
+    "DepsMD5s": {}
+}

calkit_python-0.48.2/.calkit/env-locks/tex/arm64.json

@@ -0,0 +1,27 @@
+{
+    "RepoDigests": [
+        "sha256:a6df16eb0634a94defc9c794f6a4a94addca2cc41857f2e89c4db332591676c0"
+    ],
+    "Architecture": "arm64",
+    "Os": "linux",
+    "RootFS": {
+        "Type": "layers",
+        "Layers": [
+            "sha256:1e9178dc90058fa454a60803300219ee8c17e515be8718817ed824b96fa1207b",
+            "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
+            "sha256:1b7eb283ff126198a9f292a2511133a8ab8c82bda9c4d4819cbe6f4be53f6dc4",
+            "sha256:eb05c3b16772fda838693e3621020572ef46903a9480f57cd7347bd6e30f5cfc",
+            "sha256:608ed5df5926ca9cf8ea98ee0c4b06b8cd7fae822caeaa9153d6a88569707e74",
+            "sha256:e23d740627c00ac7d052a5ba064c71e07ebf6a97a335c259f44feb0bd3c1c4e8",
+            "sha256:921b4a27c98023d4ee54c3713d11ed094201b1448a590eebb8739296b9978799",
+            "sha256:7449d2f5a570e6301afc4b03a710a7006950d9d85372e20fde07f863a8aee3b0",
+            "sha256:e28e00624817a4447d03fbd25e6533747ce1ce6bbbc08cc157050bcc88129b30",
+            "sha256:bae81d2da5d28845b37687b158dc3c03b6fb7d1629c475432d35166a3dd0ad1b",
+            "sha256:d4c5c89019ab226aac376b4574f957689a126740a2e759a02be63157e11a292c",
+            "sha256:e9db30e578d1626eb17b4121b169932e7935bf41660e5a7be2b2627d6d4870c1",
+            "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
+        ]
+    },
+    "DockerfileMD5": null,
+    "DepsMD5s": {}
+}

{calkit_python-0.48.1 → calkit_python-0.48.2}/.pre-commit-config.yaml

@@ -85,9 +85,10 @@ repos:
         # the pipeline changes. Prettier and ruamel disagree about where a
         # long 'desc:' value goes, so formatting it here just means the two
         # take turns reformatting the same file.
-        # Likewise the example projects' results files, which are stage
-        # outputs and have to match what the stage wrote byte for byte.
-        exclude: calkit|^hub/|(^|/)dvc\.yaml$|^examples/.*/results/
+        # Likewise results files, here and in the example projects, which
+        # are stage outputs and have to match what the stage wrote byte for
+        # byte.
+        exclude: calkit|^hub/|(^|/)dvc\.yaml$|^(examples/.*/)?results/
 
   - repo: local
     hooks:

{calkit_python-0.48.1 → calkit_python-0.48.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: calkit-python
-Version: 0.48.1
+Version: 0.48.2
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues
@@ -47,6 +47,7 @@ Requires-Dist: python-dotenv>=1
 Requires-Dist: pywin32; platform_system == 'Windows'
 Requires-Dist: requests
 Requires-Dist: rich
+Requires-Dist: ruamel-yaml<0.20,>=0.19.1
 Requires-Dist: sqlitedict>=2.1.0
 Requires-Dist: texsoup>=0.3.3
 Requires-Dist: toml>=0.10.2

{calkit_python-0.48.1 → calkit_python-0.48.2}/calkit/cli/latex.py

@@ -10,6 +10,7 @@ import shutil
 import string
 import subprocess
 import sys
+from collections.abc import Callable
 from copy import deepcopy
 from pathlib import Path
 
@@ -189,6 +190,186 @@ def from_questions(
             json2latex.dump(command_name, values, f)
 
 
+@latex_app.command(name="from-markdown")
+def from_markdown(
+    md_path: Annotated[
+        str, typer.Argument(help="The Markdown file to build.")
+    ],
+    outputs: Annotated[
+        list[str],
+        typer.Option(
+            "--output",
+            "-o",
+            help="Where to write the PDF, or the LaTeX with a .tex "
+            "extension; can be given more than once.",
+        ),
+    ],
+    environment: Annotated[
+        str | None,
+        typer.Option(
+            "--environment",
+            "-e",
+            help="Environment to run pandoc and LaTeX in, e.g., one using "
+            "Calkit's LaTeX image, which includes both.",
+        ),
+    ] = None,
+    template_path: Annotated[
+        str | None, typer.Option("--template", help="Pandoc template.")
+    ] = None,
+    filters: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--filter", help="Pandoc Lua filter; can be given more than once."
+        ),
+    ] = None,
+    pandoc_args: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--pandoc-arg",
+            help="Another argument for pandoc; can be given more than once.",
+        ),
+    ] = None,
+    no_check: Annotated[
+        bool,
+        typer.Option("--no-check", help="Don't check the environment first."),
+    ] = False,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Print commands.")
+    ] = False,
+) -> None:
+    """Build a Markdown file into a PDF with pandoc and LaTeX.
+
+    Value markers are filled from their results files, which keeps the
+    Markdown itself current too, and each value links to the question on
+    the project's hub whose evidence cites it. The template gets the Calkit
+    version and the project's URL as the ``calkit-version``,
+    ``project-url``, and ``project`` variables.
+    """
+    import calkit.docx
+    import calkit.markdown
+
+    def question_url(value: calkit.markdown.MarkdownValue) -> str | None:
+        # The question whose evidence cites this value, or failing that,
+        # the first to cite its file
+        if project_url is None:
+            return None
+        first = None
+        for n, q in enumerate(ck_info.get("questions") or [], start=1):
+            evidence = q.get("evidence") if isinstance(q, dict) else None
+            for ev in evidence or []:
+                if not isinstance(ev, dict) or ev.get("path") != value.path:
+                    continue
+                keys = [ev.get("key"), *(ev.get("values") or {}).values()]
+                if value.key in keys:
+                    return f"{project_url}/questions/{n}"
+                first = first or n
+        return f"{project_url}/questions/{first}" if first else None
+
+    def to_latex(tex_path: str) -> None:
+        # Images are pointed at from where the LaTeX is, by a filter that
+        # runs before the others, so they see the paths LaTeX will
+        build_dir = os.path.dirname(tex_path) or "."
+        os.makedirs(build_dir, exist_ok=True)
+        stem = Path(tex_path).stem
+        src_path = f"{build_dir}/{stem}.pandoc.md"
+        with open(src_path, "w", encoding="utf-8", newline="\n") as f:
+            f.write(
+                calkit.markdown.prepare_for_pdf(
+                    text, md_path, link=question_url
+                )
+            )
+        prefix = Path(os.path.relpath(md_dir, build_dir)).as_posix()
+        repoint = f"{build_dir}/{stem}.images.lua"
+        with open(repoint, "w", encoding="utf-8", newline="\n") as f:
+            f.write(calkit.markdown.image_prefix_filter(prefix))
+        args = [src_path, "-o", tex_path, "--standalone"]
+        if template_path is not None:
+            args += ["--template", template_path]
+        for path in [repoint, *(filters or [])]:
+            args += ["--lua-filter", path]
+        args += [f"--variable=calkit-version:{version}"]
+        if project_url is not None:
+            args += [
+                f"--variable=project-url:{project_url}",
+                f"--variable=project:{project_url.split('://', 1)[1]}",
+            ]
+        args += pandoc_args or []
+        if environment is not None:
+            cmd = _tex_cmd(
+                ["pandoc", *args], environment, no_check, verbose, dep="pandoc"
+            )
+        else:
+            pandoc = calkit.docx.find_pandoc()
+            if pandoc is None:
+                raise_error(
+                    "Pandoc is needed; name an environment that has it, "
+                    "e.g., one using Calkit's LaTeX image, or install it"
+                )
+            cmd = [pandoc, *args]
+        try:
+            subprocess.check_call(cmd)
+        except subprocess.CalledProcessError:
+            raise_error(f"Pandoc failed to convert {md_path}")
+
+    for output in outputs:
+        if not output.endswith((".pdf", ".tex")):
+            raise_error("Outputs must be .pdf or .tex files")
+    # Paths go into the build directory's, so they have to be the
+    # project's own
+    rel = os.path.relpath(md_path)
+    if rel == ".." or rel.startswith(".." + os.sep) or os.path.isabs(rel):
+        raise_error(f"{md_path} isn't in this project")
+    md_path = Path(rel).as_posix()
+    md_dir = os.path.dirname(md_path) or "."
+    ck_info = calkit.load_calkit_info()
+    project_url = None
+    if ck_info.get("owner") and ck_info.get("name"):
+        hub = str(ck_info.get("hub") or "calkit.io").rstrip("/")
+        if "://" not in hub:
+            hub = "https://" + hub
+        project_url = f"{hub}/{ck_info['owner']}/{ck_info['name']}"
+    # A local version's commit is the project's own, which isn't Calkit's
+    version = calkit.__version__.split("+")[0]
+    with open(md_path, encoding="utf-8") as f:
+        text = f.read()
+    try:
+        text, changed = calkit.markdown.set_values(text, md_path)
+    except calkit.markdown.MarkdownParseError as e:
+        raise_error(str(e))
+    if changed:
+        with open(md_path, "w", encoding="utf-8", newline="\n") as f:
+            f.write(text)
+    for output in outputs:
+        if output.endswith(".tex"):
+            to_latex(output)
+    if not any(o.endswith(".pdf") for o in outputs):
+        return
+    # A PDF is built where Calkit keeps what it derives from the file, and
+    # dated by the file's last commit rather than the build directory's,
+    # which has none of its own
+    build_dir = Path(".calkit", "markdown", md_path, "pdf").as_posix()
+    tex_path = f"{build_dir}/{Path(md_path).stem}.tex"
+    to_latex(tex_path)
+    cmd = [sys.executable, "-m", "calkit", "latex", "build"]
+    if environment is not None:
+        cmd += ["-e", environment]
+    if no_check:
+        cmd += ["--no-check"]
+    env = os.environ.copy()
+    epoch = calkit.latex.get_source_date_epoch(md_path)
+    if epoch is not None:
+        env["SOURCE_DATE_EPOCH"] = epoch
+    try:
+        subprocess.check_call(cmd + [tex_path], env=env)
+    except subprocess.CalledProcessError:
+        raise_error(f"LaTeX failed to build {tex_path}")
+    for output in outputs:
+        if output.endswith(".pdf"):
+            if os.path.dirname(output):
+                os.makedirs(os.path.dirname(output), exist_ok=True)
+            shutil.copyfile(Path(tex_path).with_suffix(".pdf"), output)
+
+
 def _tex_cmd(
     tex_cmd: list[str],
     environment: str | None,
@@ -2773,6 +2954,12 @@ def merge_docx(
                     and existing.resolved == tc.resolved
                 ):
                     continue
+                # Word can't carry these, so they come from the source
+                tc.id, tc.issue, tc.attrs = (
+                    existing.id,
+                    existing.issue,
+                    existing.attrs,
+                )
                 # Word knows neither emails nor what the source already
                 # recorded, so carry those over for unchanged messages
                 known = {(e.author, e.text): e for e in existing.entries}
@@ -2850,3 +3037,270 @@ def merge_docx(
         f"already there, {counts['pending']} pending, {counts['unplaced']} "
         f"unplaced); {added} comments added, {updated} updated"
     )
+
+
+comments_app = typer.Typer(no_args_is_help=True)
+latex_app.add_typer(
+    comments_app,
+    name="comments",
+    help="Work with review comments in LaTeX source.",
+)
+
+_ID_OPTION = typer.Option("--id", help="ID of the thread.")
+_LINE_OPTION = typer.Option(
+    "--line", "-l", help="Number of any line in the thread."
+)
+
+
+def _new_entry(
+    text: str, author: str | None, email: str | None
+) -> calkit.latex.Entry:
+    import datetime
+
+    import git
+
+    if author is None:
+        try:
+            author = git.Git().config("--get", "user.name").strip()
+            email = email or git.Git().config("--get", "user.email").strip()
+        except git.GitCommandError:
+            raise_error("Set --author, or Git's user.name")
+    date = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")
+    return calkit.latex.Entry(author, text, email or None, date)
+
+
+def _edit_comment(
+    tex_path: str,
+    id: str | None,
+    line: int | None,
+    edit: Callable[[calkit.latex.TexComment], None],
+) -> calkit.latex.TexComment:
+    """Apply an edit to one thread and write the file back, giving the
+    thread an ID if it had none."""
+    if (id is None) == (line is None):
+        raise_error("Specify one of --id or --line")
+    if not os.path.isfile(tex_path):
+        raise_error(f"{tex_path} does not exist")
+    lines = Path(tex_path).read_text(encoding="utf-8").split("\n")
+    tc = calkit.latex.find_comment(lines, id=id, lineno=line)
+    if tc is None:
+        raise_error(f"No comment thread in {tex_path} at {id or line}")
+    edit(tc)
+    tc.id = tc.id or calkit.latex.new_comment_id()
+    calkit.latex.write_comment(lines, tc)
+    Path(tex_path).write_text("\n".join(lines), encoding="utf-8")
+    return tc
+
+
+@comments_app.command(name="list")
+def list_comments(
+    tex_path: Annotated[
+        str,
+        typer.Argument(
+            help="Document to list comments from, including files it inputs."
+        ),
+    ],
+    unresolved: Annotated[
+        bool,
+        typer.Option("--unresolved", "-u", help="Only list open threads."),
+    ] = False,
+    as_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """List the comment threads in a LaTeX document."""
+    if not os.path.isfile(tex_path):
+        raise_error(f"{tex_path} does not exist")
+    out = [
+        c
+        for c in calkit.latex.list_comments(tex_path)
+        if not (unresolved and c["resolved"])
+    ]
+    if as_json:
+        typer.echo(json.dumps(out, indent=2))
+        return
+    for c in out:
+        status = " (resolved)" if c["resolved"] else ""
+        typer.echo(f"{c['path']}:{c['line']} [{c['id'] or '-'}]{status}")
+        if c["highlight"]:
+            typer.echo(f'  On "{c["highlight"]["text"]}"')
+        for m in c["messages"]:
+            typer.echo(f"  {m['author']}: {m['text']}")
+
+
+@comments_app.command(name="locate")
+def locate_paragraph(
+    tex_path: Annotated[
+        str,
+        typer.Argument(help="Document to search, including files it inputs."),
+    ],
+    text: Annotated[
+        str | None,
+        typer.Option(
+            "--text", help="Rendered text, e.g., a line copied from the PDF."
+        ),
+    ] = None,
+    path: Annotated[
+        str | None,
+        typer.Option("--path", help="File with the line to look up."),
+    ] = None,
+    line: Annotated[
+        int | None,
+        typer.Option("--line", "-l", help="Line to look up in --path."),
+    ] = None,
+    as_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Find the paragraph some rendered text is in, or a source line is in.
+
+    This is how a place in a PDF built without SyncTeX, or by someone else,
+    can be matched to the source.
+    """
+    if (text is None) == (line is None):
+        raise_error("Specify one of --text or --path and --line")
+    if not os.path.isfile(tex_path):
+        raise_error(f"{tex_path} does not exist")
+    found = calkit.latex.locate_block(tex_path, text, path, line)
+    if found is None:
+        raise_error("No matching paragraph found")
+    out = {
+        "path": found.path,
+        "line": found.lineno,
+        "end_line": found.lines[-1].lineno,
+        "text": found.text or calkit.latex.display_text(found),
+    }
+    if as_json:
+        typer.echo(json.dumps(out, indent=2))
+    else:
+        typer.echo(f"{out['path']}:{out['line']}")
+
+
+@comments_app.command(name="add")
+def add_comment(
+    tex_path: Annotated[str, typer.Argument(help="File to comment in.")],
+    line: Annotated[
+        int,
+        typer.Option(
+            "--line",
+            "-l",
+            help="A line in, or just above, the paragraph to comment on.",
+        ),
+    ],
+    text: Annotated[str, typer.Option("--text", "-m", help="The comment.")],
+    highlight: Annotated[
+        str | None,
+        typer.Option(
+            "--highlight", help="Rendered text in the paragraph it's about."
+        ),
+    ] = None,
+    occ: Annotated[
+        int,
+        typer.Option(
+            "--occ", help="Which occurrence of the highlight text, from 0."
+        ),
+    ] = 0,
+    author: Annotated[
+        str | None,
+        typer.Option("--author", help="Defaults to Git's user.name."),
+    ] = None,
+    email: Annotated[
+        str | None,
+        typer.Option("--email", help="Defaults to Git's user.email."),
+    ] = None,
+    as_json: Annotated[
+        bool, typer.Option("--json", help="Output the thread as JSON.")
+    ] = False,
+) -> None:
+    """Start a comment thread above a paragraph, printing its ID."""
+    if not os.path.isfile(tex_path):
+        raise_error(f"{tex_path} does not exist")
+    lines = Path(tex_path).read_text(encoding="utf-8").split("\n")
+    tc = calkit.latex.TexComment(
+        [_new_entry(text, author, email)],
+        highlight=highlight or None,
+        highlight_occ=occ,
+        id=calkit.latex.new_comment_id(),
+    )
+    try:
+        calkit.latex.add_comment(lines, line, tc)
+    except ValueError as e:
+        raise_error(str(e))
+    Path(tex_path).write_text("\n".join(lines), encoding="utf-8")
+    if as_json:
+        blks = calkit.latex.file_blocks(tex_path, lines)
+        typer.echo(
+            json.dumps(
+                calkit.latex.comment_to_dict(tex_path, tc, blks), indent=2
+            )
+        )
+    else:
+        typer.echo(tc.id)
+
+
+@comments_app.command(name="reply")
+def reply_to_comment(
+    tex_path: Annotated[str, typer.Argument(help="File the thread is in.")],
+    text: Annotated[str, typer.Option("--text", "-m", help="The reply.")],
+    id: Annotated[str | None, _ID_OPTION] = None,
+    line: Annotated[int | None, _LINE_OPTION] = None,
+    author: Annotated[
+        str | None,
+        typer.Option("--author", help="Defaults to Git's user.name."),
+    ] = None,
+    email: Annotated[
+        str | None,
+        typer.Option("--email", help="Defaults to Git's user.email."),
+    ] = None,
+) -> None:
+    """Reply to a comment thread."""
+    entry = _new_entry(text, author, email)
+    tc = _edit_comment(tex_path, id, line, lambda tc: tc.entries.append(entry))
+    typer.echo(tc.id)
+
+
+@comments_app.command(name="resolve")
+def resolve_comment(
+    tex_path: Annotated[str, typer.Argument(help="File the thread is in.")],
+    id: Annotated[str | None, _ID_OPTION] = None,
+    line: Annotated[int | None, _LINE_OPTION] = None,
+) -> None:
+    """Mark a comment thread resolved."""
+
+    def edit(tc: calkit.latex.TexComment) -> None:
+        tc.resolved = True
+
+    typer.echo(_edit_comment(tex_path, id, line, edit).id)
+
+
+@comments_app.command(name="reopen")
+def reopen_comment(
+    tex_path: Annotated[str, typer.Argument(help="File the thread is in.")],
+    id: Annotated[str | None, _ID_OPTION] = None,
+    line: Annotated[int | None, _LINE_OPTION] = None,
+) -> None:
+    """Mark a resolved comment thread open again."""
+
+    def edit(tc: calkit.latex.TexComment) -> None:
+        tc.resolved = False
+
+    typer.echo(_edit_comment(tex_path, id, line, edit).id)
+
+
+@comments_app.command(name="delete")
+def delete_comment(
+    tex_path: Annotated[str, typer.Argument(help="File the thread is in.")],
+    id: Annotated[str | None, _ID_OPTION] = None,
+    line: Annotated[int | None, _LINE_OPTION] = None,
+) -> None:
+    """Delete a comment thread and its replies."""
+    if (id is None) == (line is None):
+        raise_error("Specify one of --id or --line")
+    if not os.path.isfile(tex_path):
+        raise_error(f"{tex_path} does not exist")
+    lines = Path(tex_path).read_text(encoding="utf-8").split("\n")
+    tc = calkit.latex.find_comment(lines, id=id, lineno=line)
+    if tc is None:
+        raise_error(f"No comment thread in {tex_path} at {id or line}")
+    del lines[tc.lineno - 1 : tc.lineno - 1 + tc.nlines]
+    Path(tex_path).write_text("\n".join(lines), encoding="utf-8")

{calkit_python-0.48.1 → calkit_python-0.48.2}/calkit/git.py

@@ -131,7 +131,8 @@ def get_staged_files(
         repo = get_repo(path)
     cmd = ["--staged", "--name-only"]
     if path is not None:
-        cmd.append(path)
+        # A staged deletion's path is gone, so Git would read it as a ref
+        cmd += ["--", path]
     diff = repo.git.diff(cmd)
     paths = diff.split("\n")
     return [p for p in paths if p]
@@ -166,7 +167,8 @@ def get_staged_files_with_status(
         repo = get_repo(path)
     cmd = ["--staged", "--name-status"]
     if path is not None:
-        cmd.append(path)
+        # A staged deletion's path is gone, so Git would read it as a ref
+        cmd += ["--", path]
     diff = repo.git.diff(cmd)
     paths = diff.split("\n")
     res = []