feat: add a print subcommand (#140)

* Add a `print` subcommand

Closes #115

* Apply copy edit suggestions

Co-authored-by: Ned Batchelder <[email protected]>

* Address a failing test

* Update docs/commands.rst

* Update changelog.d/20250311_074712_kurtmckee_print_command_issue_115.rst

* Expand `print` command testing to 100% coverage

---------

Co-authored-by: Ned Batchelder <[email protected]>

Author: kurtmckee

changelog.d/20250311_074712_kurtmckee_print_command_issue_115.rst

@@ -0,0 +1,9 @@
+Added
+.....
+
+- Add a ``print`` command that can write changelog entries to standard out
+  or to a file, closing `issue 115`_. Thanks, `Kurt McKee <pull 140_>`_
+  
+.. _issue 115: https://github.com/nedbat/scriv/issues/115
+.. _pull 140: https://github.com/nedbat/scriv/pull/140
+

docs/commands.rst

@@ -230,4 +230,31 @@ If your changelog file is in reStructuredText format, you will need `pandoc`_
 
 .. _pandoc: https://pandoc.org/
 
+scriv print
+===========
+
+.. [[[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 standard out.
+
+If ``--output`` is provided, the changelog entry is written to the given file.
+
+If ``--version`` is given, the requested changelog entry is extracted
+from the CHANGELOG.
+If not, then the changelog entry is generated from uncollected 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,74 @@
+"""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():
+            eversion = Version.from_text(str(etitle))
+            if eversion is None:
+                continue
+            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:
+        # Standardize newlines to match either the platform default
+        # or to match the existing newlines found in the CHANGELOG.
+        contents_raw = newline.join(contents.splitlines()).encode("utf-8")
+        with open(output, "wb") as file:
+            file.write(contents_raw)
+    else:
+        # Standardize newlines to just '\n' when writing to STDOUT.
+        contents = "\n".join(contents.splitlines())
+        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,92 @@
+"""Test print logic."""
+
+import freezegun
+import pytest
+
+CHANGELOG_HEADER = """\
+
+1.2 - 2020-02-25
+================
+"""
+
+
+FRAG = """\
+Fixed
+-----
+
+- Launching missiles no longer targets ourselves.
+"""
+
+
+@pytest.mark.parametrize("newline", ("\r\n", "\n"))
+def test_print_fragment(newline, cli_invoke, changelog_d, temp_dir, capsys):
+    fragment = FRAG.replace("\n", newline).encode("utf-8")
+    (changelog_d / "20170616_nedbat.rst").write_bytes(fragment)
+
+    with freezegun.freeze_time("2020-02-25T15:18:19"):
+        cli_invoke(["print"])
+
+    std = capsys.readouterr()
+    assert std.out == FRAG
+
+
+@pytest.mark.parametrize("newline", ("\r\n", "\n"))
+def test_print_fragment_output(
+    newline, cli_invoke, changelog_d, temp_dir, capsys
+):
+    fragment = FRAG.replace("\n", newline).encode("utf-8")
+    (changelog_d / "20170616_nedbat.rst").write_bytes(fragment)
+    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()
+
+
+@pytest.mark.parametrize("newline", ("\r\n", "\n"))
+def test_print_changelog(newline, cli_invoke, changelog_d, temp_dir, capsys):
+    changelog = (CHANGELOG_HEADER + FRAG).replace("\n", newline).encode("utf-8")
+    (temp_dir / "CHANGELOG.rst").write_bytes(changelog)
+
+    with freezegun.freeze_time("2020-02-25T15:18:19"):
+        cli_invoke(["print", "--version", "1.2"])
+
+    std = capsys.readouterr()
+    assert std.out == FRAG
+
+
+@pytest.mark.parametrize("newline", ("\r\n", "\n"))
+def test_print_changelog_output(
+    newline, cli_invoke, changelog_d, temp_dir, capsys
+):
+    changelog = (CHANGELOG_HEADER + FRAG).replace("\n", newline).encode("utf-8")
+    (temp_dir / "CHANGELOG.rst").write_bytes(changelog)
+    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_bytes().decode() == FRAG.strip().replace(
+        "\n", newline
+    )
+
+
+def test_print_no_fragments(cli_invoke):
+    result = cli_invoke(["print"], expect_ok=False)
+
+    assert result.exit_code == 2
+    assert "No changelog fragments to collect" in result.stderr
+
+
+def test_print_version_not_in_changelog(cli_invoke, changelog_d, temp_dir):
+    (temp_dir / "CHANGELOG.rst").write_bytes(b"BOGUS\n=====\n\n1.0\n===")
+
+    result = cli_invoke(["print", "--version", "123.456"], expect_ok=False)
+
+    assert result.exit_code == 2
+    assert "Unable to find version 123.456 in the changelog" in result.stderr