fix: output_file= is now changelog= #77

Author: nedbat

changelog.d/20250419_192659_nedbat_title_in_template.rst

@@ -0,0 +1,40 @@
+.. A new scriv changelog fragment.
+..
+.. Uncomment the section that is right (remove the leading dots).
+.. For top level release notes, leave all the headers commented out.
+..
+.. Removed
+.. .......
+..
+.. - A bullet item for the Removed category.
+..
+.. Added
+.. .....
+..
+.. - A bullet item for the Added category.
+..
+Changed
+.......
+
+- The ``output_file`` setting is now called ``changelog`` since some uses of
+  scriv only read the file.  An ``output_file`` entry in the config file will
+  still work to set the name.  Closes `issue 77`_.
+
+.. _issue 77: https://github.com/nedbat/scriv/issues/77
+
+..
+.. Deprecated
+.. ..........
+..
+.. - A bullet item for the Deprecated category.
+..
+.. Fixed
+.. .....
+..
+.. - A bullet item for the Fixed category.
+..
+.. Security
+.. ........
+..
+.. - A bullet item for the Security category.
+..

docs/commands.rst

@@ -136,7 +136,7 @@ date.
 Instead of using the title template, you can provide an exact title to use for
 the new entry with the ``--title`` option.
 
-The output file is specified by the :ref:`config_output_file` setting.  Scriv
+The output file is specified by the :ref:`config_changelog` setting.  Scriv
 looks in the file for a special marker (usually in a comment) to determine
 where to insert the new entry.  The marker is "scriv-insert-here", but can be
 changed with the :ref:`config_insert_marker` setting.  Using a marker like

docs/configuration.rst

@@ -228,6 +228,17 @@ See :ref:`categories`.
 Default: ``Removed, Added, Changed, Deprecated, Fixed, Security``
 
 
+.. _config_changelog:
+
+changelog
+---------
+
+The changelog file managed and read by scriv.  The old name
+for this setting is :ref:`output_file <deprecated_config>`.
+
+Default: ``CHANGELOG.${config:format}``
+
+
 .. _config_end_marker:
 
 end_marker
@@ -338,16 +349,6 @@ The `Jinja`_ template to use for new fragments.
 Default: ``file: new_fragment.${config:format}.j2``
 
 
-.. _config_output_file:
-
-output_file
------------
-
-The changelog file updated by ":ref:`cmd_collect`".
-
-Default: ``CHANGELOG.${config:format}``
-
-
 .. _config_rst_header_chars:
 
 rst_header_chars
@@ -384,7 +385,18 @@ source file.
 
 Default: (empty)
 
-.. [[[end]]] (checksum: ac66a08483626b8550ebec22bbc3af04)
+.. [[[end]]] (checksum: acce6a163b5e8567a695069a8b5146e3)
+
+
+.. _deprecated_config:
+
+Deprecated Settings
+===================
+
+Some names in the config file have been updated. The old names will continue to
+work, but the new names are preferred:
+
+- ``output_file`` is now ``changelog``.
 
 
 .. _git_settings:

src/scriv/config.py

@@ -72,12 +72,13 @@ class _Options:
         },
     )
 
-    output_file = attr.ib(
+    changelog = attr.ib(
         type=str,
         default="CHANGELOG.${config:format}",
         metadata={
             "doc": """\
-                The changelog file updated by ":ref:`cmd_collect`".
+                The changelog file managed and read by scriv.  The old name
+                for this setting is :ref:`output_file <deprecated_config>`.
                 """,
         },
     )
@@ -294,6 +295,20 @@ def read(cls) -> Config:
             attr.validate(config._options)
         return config
 
+    def get_set_option(self, scriv_data, config_name, opt_name):
+        """
+        Set one option from a config file setting.
+        """
+        try:
+            val: Any = scriv_data[config_name]
+        except KeyError:
+            pass
+        else:
+            attrdef = attr.fields_dict(_Options)[opt_name]
+            if callable(attrdef.converter):
+                val = attrdef.converter(val)
+            setattr(self._options, opt_name, val)
+
     def read_one_config(self, configfile: str) -> None:
         """
         Read one configuration file, adding values to `self`.
@@ -306,18 +321,19 @@ def read_one_config(self, configfile: str) -> None:
             return
         logger.debug(f"{configfile} was read")
 
-        section_names = ["scriv", "tool.scriv"]
         section_name = next(
-            (name for name in section_names if parser.has_section(name)), None
+            (
+                name
+                for name in ["scriv", "tool.scriv"]
+                if parser.has_section(name)
+            ),
+            None,
         )
         if section_name:
+            scriv_data = parser[section_name]
             for attrdef in attr.fields(_Options):
-                try:
-                    val: Any = parser[section_name][attrdef.name]
-                except KeyError:
-                    pass
-                else:
-                    setattr(self._options, attrdef.name, val)
+                self.get_set_option(scriv_data, attrdef.name, attrdef.name)
+            self.get_set_option(scriv_data, "output_file", "changelog")
 
     def read_one_toml(self, tomlfile: str) -> None:
         """
@@ -351,14 +367,8 @@ def read_one_toml(self, tomlfile: str) -> None:
                 # No settings for us
                 return
             for attrdef in attr.fields(_Options):
-                try:
-                    val = scriv_data[attrdef.name]
-                except KeyError:
-                    pass
-                else:
-                    if callable(attrdef.converter):
-                        val = attrdef.converter(val)
-                    setattr(self._options, attrdef.name, val)
+                self.get_set_option(scriv_data, attrdef.name, attrdef.name)
+            self.get_set_option(scriv_data, "output_file", "changelog")
 
     def resolve_value(self, value: str) -> str:
         """

src/scriv/scriv.py

@@ -67,7 +67,7 @@ def combine_fragments(self, fragments: Iterable[Fragment]) -> SectionDict:
     def changelog(self) -> Changelog:
         """Get the Changelog object."""
         return Changelog(
-            path=Path(self.config.output_file),
+            path=Path(self.config.changelog),
             config=self.config,
         )
 

tests/test_config.py

@@ -13,16 +13,18 @@
 
 CONFIG1 = """\
 [scriv]
-output_file = README.md
+changelog = README.md
 categories = New, Different, Gone, Bad
 """
 
+OLD_CONFIG1 = CONFIG1.replace("changelog = ", "output_file = ")
+
 CONFIG2 = """\
 [someotherthing]
 no_idea = what this is
 
 [tool.scriv]
-output_file = README.md
+changelog = README.md
 categories =
     New
     Different
@@ -59,7 +61,7 @@
     GENERIC_TOML_CONFIG
     + """
 [tool.scriv]
-output_file = "README.md"
+changelog = "README.md"
 categories = [
     "New",
     "Different",
@@ -73,6 +75,8 @@
 """
 )
 
+OLD_TOML_CONFIG = TOML_CONFIG.replace("changelog = ", "output_file = ")
+
 
 def test_defaults(temp_dir):
     # No configuration files anywhere, just get all the defaults.
@@ -90,7 +94,7 @@ def test_defaults(temp_dir):
         "Fixed",
         "Security",
     ]
-    assert config.output_file == "CHANGELOG.rst"
+    assert config.changelog == "CHANGELOG.rst"
     assert config.insert_marker == "scriv-insert-here"
     assert config.rst_header_chars == "=-"
     assert config.md_header_level == "1"
@@ -100,11 +104,12 @@ def test_defaults(temp_dir):
     assert config.version == ""
 
 
-def test_reading_config(temp_dir):
-    (temp_dir / "setup.cfg").write_text(CONFIG1)
+@pytest.mark.parametrize("config_text", [CONFIG1, OLD_CONFIG1])
+def test_reading_config(config_text, temp_dir):
+    (temp_dir / "setup.cfg").write_text(config_text)
     config = Config.read()
     assert config.fragment_directory == "changelog.d"
-    assert config.output_file == "README.md"
+    assert config.changelog == "README.md"
     assert config.categories == ["New", "Different", "Gone", "Bad"]
 
 
@@ -227,7 +232,7 @@ def test_override_default_name(changelog_d):
 def test_file_reading(changelog_d):
     # Any setting can be read from a file, even where it doesn't make sense.
     (changelog_d / "hello.txt").write_text("Xyzzy")
-    text = Config(output_file="file:hello.txt").output_file
+    text = Config(changelog="file:hello.txt").changelog
     assert text == "Xyzzy"
 
 
@@ -301,7 +306,7 @@ def test_rst_chars_is_two_chars(chars):
 def test_md_format(changelog_d):
     (changelog_d / "scriv.ini").write_text("[scriv]\nformat = md\n")
     config = Config.read()
-    assert config.output_file == "CHANGELOG.md"
+    assert config.changelog == "CHANGELOG.md"
     template = re.sub(r"\s+", " ", config.new_fragment_template)
     assert template.startswith("<!-- A new scriv changelog fragment.")
 
@@ -312,9 +317,11 @@ class TestTomlConfig:
     """
 
     @pytest.mark.skipif(tomllib is None, reason="No TOML support installed")
-    def test_reading_toml_file(self, temp_dir):
-        (temp_dir / "pyproject.toml").write_text(TOML_CONFIG)
+    @pytest.mark.parametrize("config_text", [TOML_CONFIG, OLD_TOML_CONFIG])
+    def test_reading_toml_file(self, config_text, temp_dir):
+        (temp_dir / "pyproject.toml").write_text(config_text)
         config = Config.read()
+        assert config.changelog == "README.md"
         assert config.categories == ["New", "Different", "Gone", "Bad"]
 
     def test_toml_without_us(self, temp_dir):
@@ -371,12 +378,12 @@ def test_command_running(mocker, cmd_output, result):
     mocker.patch(
         "scriv.config.run_shell_command", lambda cmd: (True, cmd_output)
     )
-    text = Config(output_file="command: doesnt-matter").output_file
+    text = Config(changelog="command: doesnt-matter").changelog
     assert text == result
 
 
 def test_real_command_running():
-    text = Config(output_file="command: echo Xyzzy 2 3").output_file
+    text = Config(changelog="command: echo Xyzzy 2 3").changelog
     assert text == "Xyzzy 2 3"
 
 
@@ -385,15 +392,15 @@ def test_real_command_running():
     [
         (
             "xyzzyplugh",
-            "Couldn't read 'output_file' setting: Command 'xyzzyplugh' failed:",
+            "Couldn't read 'changelog' setting: Command 'xyzzyplugh' failed:",
         ),
         (
             "'hi!2><",
-            "Couldn't read 'output_file' setting: Command \"'hi!2><\" failed:",
+            "Couldn't read 'changelog' setting: Command \"'hi!2><\" failed:",
         ),
     ],
 )
 def test_bad_command(fake_run_command, bad_cmd, msg_rx):
     # Any setting can be the output of a command.
     with pytest.raises(ScrivException, match=msg_rx):
-        _ = Config(output_file=f"command: {bad_cmd}").output_file
+        _ = Config(changelog=f"command: {bad_cmd}").changelog