Add a print subcommand

Closes #115

Author: kurtmckee

changelog.d/20250311_074712_kurtmckee_print_command_issue_115.rst

@@ -0,0 +1,5 @@
+Added
+.....
+
+- Add a ``print`` subcommand that can write changelog entries to STDOUT
+  or to a file.

docs/commands.rst

@@ -230,4 +230,30 @@ If your changelog file is in reStructuredText format, you will need `pandoc`_
 
 .. _pandoc: https://pandoc.org/
 
+scriv github-release
+====================
+
+.. [[[cog show_help("print") ]]]
+
+.. code::
+
+    $ scriv print --help
+    Usage: scriv print [OPTIONS]
+
+      Print collected fragments, or print an entry from the changelog.
+
+    Options:
+      --version TEXT       The version of the changelog entry to extract.
+      --output PATH        The path to a file to write the output to.
+      -v, --verbosity LVL  Either CRITICAL, ERROR, WARNING, INFO or DEBUG
+      --help               Show this message and exit.
+.. [[[end]]] (checksum: f652a3470da5f726b13ba076471b2444)
+
+The ``print`` command writes a changelog entry to STDOUT.
+
+If ``--output`` is provided, the changelog entry is written to the given file.
+
+If ``--version`` is given, the changelog entry is extracted from the CHANGELOG;
+if not, then the changelog entry is generated from fragment files.
+
 .. include:: include/links.rst

src/scriv/cli.py

@@ -9,6 +9,7 @@
 from .collect import collect
 from .create import create
 from .ghrel import github_release
+from .print import print_
 
 click_log.basic_config(logging.getLogger())
 
@@ -28,3 +29,4 @@ def cli() -> None:  # noqa: D401
 cli.add_command(create)
 cli.add_command(collect)
 cli.add_command(github_release)
+cli.add_command(print_)

src/scriv/print.py

@@ -0,0 +1,69 @@
+"""Collecting fragments."""
+
+from __future__ import annotations
+
+import logging
+import os
+import pathlib
+import sys
+
+import click
+
+from .scriv import Scriv
+from .util import Version, scriv_command
+
+logger = logging.getLogger(__name__)
+
+
+@click.command(name="print")
+@click.option(
+    "--version",
+    default=None,
+    help="The version of the changelog entry to extract.",
+)
+@click.option(
+    "--output",
+    type=click.Path(),
+    default=None,
+    help="The path to a file to write the output to.",
+)
+@scriv_command
+def print_(
+    version: str | None,
+    output: pathlib.Path | None,
+) -> None:
+    """
+    Print collected fragments, or print an entry from the changelog.
+    """
+    scriv = Scriv()
+    changelog = scriv.changelog()
+    newline = os.linesep
+
+    if version is None:
+        logger.info(f"Generating entry from {scriv.config.fragment_directory}")
+        frags = scriv.fragments_to_combine()
+        if not frags:
+            logger.info("No changelog fragments to collect")
+            sys.exit(2)
+        contents = changelog.entry_text(scriv.combine_fragments(frags)).strip()
+    else:
+        logger.info(f"Extracting entry for {version} from {changelog.path}")
+        changelog.read()
+        newline = changelog.newline
+        target_version = Version(version)
+        for etitle, sections in changelog.entries().items():
+            if etitle is None:
+                continue
+            eversion = Version.from_text(etitle)
+            if eversion == target_version:
+                contents = f"{changelog.newline * 2}".join(sections).strip()
+                break
+        else:
+            logger.info(f"Unable to find version {version} in the changelog")
+            sys.exit(2)
+
+    if output:
+        with open(output, "wt", encoding="utf-8", newline=newline) as file:
+            file.write(contents)
+    else:
+        print(contents)

tests/conftest.py

@@ -61,9 +61,10 @@ def cli_invoke(temp_dir: Path):
     """
 
     def invoke(command, expect_ok=True):
-        runner = CliRunner()
+        runner = CliRunner(mix_stderr=False)
         result = runner.invoke(scriv_cli, command)
-        print(result.output)
+        print(result.stdout, end="")
+        print(result.stderr, end="", file=sys.stderr)
         if result.exception:
             traceback.print_exception(
                 None, result.exception, result.exception.__traceback__

tests/test_print.py

@@ -0,0 +1,55 @@
+"""Test print logic."""
+
+import freezegun
+
+CHANGELOG_HEADER = """\
+
+1.2 - 2020-02-25
+================
+"""
+
+
+FRAG = """\
+Fixed
+-----
+
+- Launching missiles no longer targets ourselves.
+"""
+
+
+def test_print_fragment(cli_invoke, changelog_d, temp_dir, capsys):
+    # Sections are ordered by the config file.
+    # Fragments in sections are in time order.
+    (changelog_d / "20170616_nedbat.rst").write_text(FRAG)
+    with freezegun.freeze_time("2020-02-25T15:18:19"):
+        cli_invoke(["print"])
+    std = capsys.readouterr()
+    assert std.out == FRAG
+
+
+def test_print_fragment_output(cli_invoke, changelog_d, temp_dir, capsys):
+    (changelog_d / "20170616_nedbat.rst").write_text(FRAG)
+    output_file = temp_dir / "output.txt"
+    with freezegun.freeze_time("2020-02-25T15:18:19"):
+        cli_invoke(["print", "--output", output_file])
+    std = capsys.readouterr()
+    assert std.out == ""
+    assert output_file.read_text().strip() == FRAG.strip()
+
+
+def test_print_changelog(cli_invoke, changelog_d, temp_dir, capsys):
+    (temp_dir / "CHANGELOG.rst").write_text(CHANGELOG_HEADER + FRAG)
+    with freezegun.freeze_time("2020-02-25T15:18:19"):
+        cli_invoke(["print", "--version", "1.2"])
+    std = capsys.readouterr()
+    assert std.out == FRAG
+
+
+def test_print_changelog_output(cli_invoke, changelog_d, temp_dir, capsys):
+    (temp_dir / "CHANGELOG.rst").write_text(CHANGELOG_HEADER + FRAG)
+    output_file = temp_dir / "output.txt"
+    with freezegun.freeze_time("2020-02-25T15:18:19"):
+        cli_invoke(["print", "--version", "1.2", "--output", output_file])
+    std = capsys.readouterr()
+    assert std.out == ""
+    assert output_file.read_text().strip() == FRAG.strip()