Create and use constants for return codes (#166)

* convert return values to constants

* convert to a sharable set of constants

* update functional tests to use constants

* add changelog fragment

* clean up inaccurate comment

* Update src/antsibull_changelog/constants.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* prepend with RC_ for clarity (based on feedback)

---------

Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/166-use-constants.yml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - "Replaces numbers with constants for return codes (https://github.com/ansible-community/antsibull-changelog/issues/77)."

src/antsibull_changelog/cli.py

@@ -30,6 +30,7 @@
     HAS_ARGCOMPLETE = False
 
 from . import __version__ as _version
+from . import constants as C
 from .ansible import get_ansible_release
 from .changes import ChangesBase, add_release, load_changes
 from .config import ChangelogConfig, CollectionDetails, PathsConfig, TextFormat
@@ -319,7 +320,7 @@ def run(args: list[str]) -> int:
 
         if getattr(arguments, "func", None) is None:
             parser.print_help()
-            return 2
+            return C.RC_BAD_CLI_ARG
 
         verbosity = arguments.verbose
         setup_logger(verbosity)
@@ -329,7 +330,7 @@ def run(args: list[str]) -> int:
         LOGGER.error(str(e))
         if verbosity > 2:
             traceback.print_exc()
-        return 5
+        return C.RC_COMMAND_FAILED
     except SystemExit as e:
         # All cases that sys.exit is called directly or indirectly in the above
         # code (that we are aware of) always return an int.
@@ -339,7 +340,7 @@ def run(args: list[str]) -> int:
             traceback.print_exc()
         else:
             print("ERROR: Uncaught exception. Run with -v to see traceback.")
-        return 1
+        return C.RC_UNHANDLED_ERROR
 
 
 def command_init(args: Any) -> int:
@@ -355,11 +356,11 @@ def command_init(args: Any) -> int:
 
     if not is_other_project and paths.galaxy_path is None:
         LOGGER.error("The file galaxy.yml does not exists in the collection root!")
-        return 5
+        return C.RC_COMMAND_FAILED
     LOGGER.debug('Checking for existance of "{}"', paths.config_path)
     if os.path.exists(paths.config_path):
         LOGGER.error('A configuration file already exists at "{}"!', paths.config_path)
-        return 5
+        return C.RC_COMMAND_FAILED
 
     collection_details = CollectionDetails(paths)
 
@@ -379,17 +380,17 @@ def command_init(args: Any) -> int:
     except Exception as exc:  # pylint: disable=broad-except
         LOGGER.error('Cannot create fragments directory "{}"', fragments_dir)
         LOGGER.info("Exception: {}", str(exc))
-        return 5
+        return C.RC_COMMAND_FAILED
 
     try:
         config.store()
         print('Created config file "{0}"'.format(paths.config_path))
     except Exception as exc:  # pylint: disable=broad-except
         LOGGER.error('Cannot create config file "{}"', paths.config_path)
         LOGGER.info("Exception: {}", str(exc))
-        return 5
+        return C.RC_COMMAND_FAILED
 
-    return 0
+    return C.RC_SUCCESS
 
 
 def _determine_flatmap(
@@ -707,7 +708,7 @@ def command_release(args: Any) -> int:
             flatmap=flatmap,
         )
 
-    return 0
+    return C.RC_SUCCESS
 
 
 def command_generate(args: Any) -> int:  # pylint: disable=too-many-locals
@@ -738,10 +739,10 @@ def command_generate(args: Any) -> int:  # pylint: disable=too-many-locals
             changes.restrict_to(version)
         except ValueError as exc:
             print(f"Cannot restrict to version '{version}': {exc}")
-            return 5
+            return C.RC_COMMAND_FAILED
     if not changes.has_release:
         print("Cannot create changelog when not at least one release has been added.")
-        return 5
+        return C.RC_COMMAND_FAILED
     plugins, fragments = _do_refresh(
         args, paths, collection_details, config, changes, None, None
     )
@@ -758,7 +759,7 @@ def command_generate(args: Any) -> int:  # pylint: disable=too-many-locals
             "When an explicit output path is specified and more than one output format"
             " is configured, you need to explicitly specify an output format"
         )
-        return 5
+        return C.RC_COMMAND_FAILED
     output_formats = (
         [TextFormat.from_extension(output_format)]
         if output_format
@@ -777,7 +778,7 @@ def command_generate(args: Any) -> int:  # pylint: disable=too-many-locals
             only_latest=only_latest,
         )
 
-    return 0
+    return C.RC_SUCCESS
 
 
 def command_lint(args: Any) -> int:
@@ -833,7 +834,7 @@ def lint_fragments(
     for message in messages:
         print(message)
 
-    return 3 if messages else 0
+    return C.RC_INVALID_FRAGMENT if messages else C.RC_SUCCESS
 
 
 def command_lint_changelog_yaml(args: Any) -> int:
@@ -853,7 +854,7 @@ def command_lint_changelog_yaml(args: Any) -> int:
     for message in messages:
         print(message)
 
-    return 3 if messages else 0
+    return C.RC_INVALID_FRAGMENT if messages else C.RC_SUCCESS
 
 
 def main() -> int:
@@ -865,17 +866,11 @@ def main() -> int:
     heavy lifting.
 
     :returns: A program return code.
-
-    Return codes:
-        :0: Success
-        :1: Unhandled error.  See the Traceback for more information.
-        :2: There was a problem with the command line arguments
-        :3: Found invalid changelog fragments
-        :4: Needs to be run on a newer version of Python
-        :5: Problem occured which prevented the execution of the command
+    See constants.py for the return codes.
     """
+
     if sys.version_info < (3, 6):
         print("Needs Python 3.6 or later")
-        return 4
+        return C.RC_OLD_PYTHON
 
     return run(sys.argv)

src/antsibull_changelog/constants.py

@@ -0,0 +1,16 @@
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or
+# https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2020, Ansible Project
+"""
+Constants used by antsibull-changelog.
+"""
+
+
+# Return codes used in cli.py and test files.
+RC_SUCCESS = 0  # Success
+RC_UNHANDLED_ERROR = 1  # Unhandled error.  See the Traceback for more information.
+RC_BAD_CLI_ARG = 2  # There was a problem with the command line arguments.
+RC_INVALID_FRAGMENT = 3  # Found invalid changelog fragments.
+RC_OLD_PYTHON = 4  # Needs to be run on a newer version of Python.
+RC_COMMAND_FAILED = 5  # Problem occurred which prevented the execution of the command.

tests/functional/test_changelog_archive.py

@@ -15,6 +15,7 @@
 from fixtures import collection_changelog  # noqa: F401; pylint: disable=unused-variable
 from fixtures import create_plugin
 
+from antsibull_changelog import constants as C
 from antsibull_changelog.config import PathsConfig
 
 
@@ -43,7 +44,10 @@ def test_changelog_release_keep_fragments(  # pylint: disable=redefined-outer-na
     collection_changelog.set_plugin_cache("1.0.0", {})
 
     # Release
-    assert collection_changelog.run_tool("release", ["-v", "--date", "2020-01-02"]) == 0
+    assert (
+        collection_changelog.run_tool("release", ["-v", "--date", "2020-01-02"])
+        == C.RC_SUCCESS
+    )
 
     diff = collection_changelog.diff()
     assert diff.added_dirs == []
@@ -83,7 +87,10 @@ def test_changelog_release_keep_fragments(  # pylint: disable=redefined-outer-na
     )
 
     # Refresh
-    assert collection_changelog.run_tool("generate", ["-v", "--refresh-fragments"]) == 0
+    assert (
+        collection_changelog.run_tool("generate", ["-v", "--refresh-fragments"])
+        == C.RC_SUCCESS
+    )
 
     diff = collection_changelog.diff()
     assert diff.added_dirs == []
@@ -142,7 +149,10 @@ def test_changelog_release_remove_fragments(  # pylint: disable=redefined-outer-
     collection_changelog.set_plugin_cache("1.0.0", {})
 
     # Release
-    assert collection_changelog.run_tool("release", ["-v", "--date", "2020-01-02"]) == 0
+    assert (
+        collection_changelog.run_tool("release", ["-v", "--date", "2020-01-02"])
+        == C.RC_SUCCESS
+    )
 
     diff = collection_changelog.diff()
     assert diff.added_dirs == []
@@ -179,7 +189,10 @@ def test_changelog_release_remove_fragments(  # pylint: disable=redefined-outer-
     )
 
     # Refresh should be ignored
-    assert collection_changelog.run_tool("generate", ["-v", "--refresh-fragments"]) == 0
+    assert (
+        collection_changelog.run_tool("generate", ["-v", "--refresh-fragments"])
+        == C.RC_SUCCESS
+    )
     assert collection_changelog.diff().unchanged
 
     # Add fragment with same filename, but different content
@@ -193,7 +206,7 @@ def test_changelog_release_remove_fragments(  # pylint: disable=redefined-outer-
         collection_changelog.run_tool(
             "release", ["-v", "--version", "1.1.0", "--date", "2020-01-02"]
         )
-        == 0
+        == C.RC_SUCCESS
     )
 
     diff = collection_changelog.diff()
@@ -251,7 +264,7 @@ def test_changelog_release_remove_fragments(  # pylint: disable=redefined-outer-
         collection_changelog.run_tool(
             "release", ["-v", "--version", "1.2.0", "--date", "2020-01-02"]
         )
-        == 0
+        == C.RC_SUCCESS
     )
 
     diff = collection_changelog.diff()
@@ -322,7 +335,10 @@ def test_changelog_release_archive_fragments(  # pylint: disable=redefined-outer
     collection_changelog.set_plugin_cache("1.0.0", {})
 
     # Release
-    assert collection_changelog.run_tool("release", ["-v", "--date", "2020-01-02"]) == 0
+    assert (
+        collection_changelog.run_tool("release", ["-v", "--date", "2020-01-02"])
+        == C.RC_SUCCESS
+    )
 
     diff = collection_changelog.diff()
     assert diff.added_dirs == [".archive", ".archive/v1.0.0"]
@@ -373,7 +389,10 @@ def test_changelog_release_archive_fragments(  # pylint: disable=redefined-outer
     )
 
     # Refresh
-    assert collection_changelog.run_tool("generate", ["-v", "--refresh-fragments"]) == 0
+    assert (
+        collection_changelog.run_tool("generate", ["-v", "--refresh-fragments"])
+        == C.RC_SUCCESS
+    )
 
     diff = collection_changelog.diff()
     assert diff.added_dirs == []
@@ -418,6 +437,6 @@ def test_changelog_release_archive_fragments(  # pylint: disable=redefined-outer
         collection_changelog.run_tool(
             "generate", ["-v", "--refresh-fragments", "without-archives"]
         )
-        == 0
+        == C.RC_SUCCESS
     )
     assert collection_changelog.diff().unchanged