Add versions module.

consolekit/versions.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+#
+#  versions.py
+"""
+Tool to get software versions.
+"""
+#
+#  Copyright © 2023 Dominic Davis-Foster <dominic@davis-foster.co.uk>
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a copy
+#  of this software and associated documentation files (the "Software"), to deal
+#  in the Software without restriction, including without limitation the rights
+#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  copies of the Software, and to permit persons to whom the Software is
+#  furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included in all
+#  copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+#  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+#  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+#  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+#  DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+#  OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+#  OR OTHER DEALINGS IN THE SOFTWARE.
+#
+
+# stdlib
+import platform
+import sys
+import textwrap
+from typing import Any, Callable, List, Mapping, Union
+
+# 3rd party
+import click
+from domdf_python_tools.compat import importlib_metadata
+from domdf_python_tools.stringlist import StringList
+from domdf_python_tools.words import LF
+
+__all__ = ("get_formatted_versions", "version_callback")
+
+
+def get_formatted_versions(
+		dependencies: Union[List[str], Mapping[str, str]],
+		show_python: bool = True,
+		show_platform: bool = True,
+		) -> StringList:
+	"""
+	Return the versions of software dependencies, one per line.
+
+	:param dependencies: Either a list of dependency names,
+	    or a mapping of dependency name to a more human-readable form.
+	:param show_python:
+	:param show_platform:
+	"""
+
+	versions = StringList()
+
+	if not isinstance(dependencies, Mapping):
+		dependencies = {d: d for d in dependencies}
+
+	for dependency_name, display_name in dependencies.items():
+
+		dep_version = importlib_metadata.version(dependency_name)
+		versions.append(f"{display_name}: {dep_version}")
+
+	if show_python:
+		versions.append(f"Python: {sys.version.replace(LF, ' ')}")
+
+	if show_platform:
+		versions.append(' '.join(platform.system_alias(platform.system(), platform.release(), platform.version())))
+
+	return versions
+
+
+def get_version_callback(
+		tool_version: str,
+		tool_name: str,
+		dependencies: Union[List[str], Mapping[str, str]],
+		) -> Callable[[click.Context, click.Option, int], Any]:
+	"""
+	Creates a callback for :class:`~.version_option`.
+
+	With each ``--version`` argument the callback displays the package version,
+	then adds the python version, and finally adds dependency versions.
+
+
+	:param tool_version: The version of the tool to show the version of.
+	:param tool_name: The name of the tool to show the version of.
+	:param dependencies: Either a list of dependency names,
+	    or a mapping of dependency name to a more human-readable form.
+	"""
+
+	def version_callback(ctx: click.Context, param: click.Option, value: int) -> None:
+		"""
+		Callback for displaying the package version (and optionally the Python runtime).
+		"""
+
+		if not value or ctx.resilient_parsing:
+			return
+
+		if value > 2:
+			versions = textwrap.indent(
+					get_formatted_versions(dependencies),  # type: ignore[arg-type]
+					"  ",
+					)
+			click.echo(tool_name)
+			click.echo(f"  Version: {tool_version}")
+			click.echo(versions)
+		elif value > 1:
+			python_version = sys.version.replace('\n', ' ')
+			click.echo(f"{tool_name} version {tool_version}, Python {python_version}")
+		else:
+			click.echo(f"{tool_name} version {tool_version}")
+
+		ctx.exit()
+
+	return version_callback

doc-source/api/versions.rst

@@ -0,0 +1,5 @@
+=============================
+:mod:`consolekit.versions`
+=============================
+
+.. automodule:: consolekit.versions

requirements.txt

@@ -1,6 +1,6 @@
 click>=7.1.2
 colorama>=0.4.3; python_version < "3.10" and platform_system == "Windows"
 deprecation-alias>=0.1.1
-domdf-python-tools>=2.6.0
+domdf-python-tools>=3.8.0
 mistletoe>=0.7.2
 typing-extensions!=3.10.0.1,>=3.10.0.0

tests/test_versions.py

@@ -0,0 +1,66 @@
+# stdlib
+import sys
+
+# this package
+from consolekit import click_command
+from consolekit.options import version_option
+from consolekit.testing import CliRunner
+from consolekit.versions import get_formatted_versions, get_version_callback
+
+
+def test_get_formatted_versions():
+	dependencies = ["click", "deprecation-alias", "domdf-python-tools", "mistletoe", "typing-extensions"]
+
+	sl = get_formatted_versions(dependencies)
+	for line, dep in zip(sl, dependencies):
+		assert line.startswith(f"{dep}:")
+	assert sl[-2].startswith("Python: 3.")
+
+	sl = get_formatted_versions(dependencies, show_platform=False)
+	for line, dep in zip(sl, [*dependencies]):
+		assert line.startswith(f"{dep}:")
+	assert sl[-1].startswith("Python: 3.")
+
+	sl = get_formatted_versions(dependencies, show_python=False)
+	assert len(sl) == len(dependencies) + 1
+
+	sl = get_formatted_versions(dependencies, show_python=False, show_platform=False)
+	assert len(sl) == len(dependencies)
+
+	sl = get_formatted_versions({
+			"click": "pkg1",
+			"deprecation-alias": "pkg2",
+			"domdf-python-tools": "pkg3",
+			"mistletoe": "pkg4",
+			"typing-extensions": "pkg5"
+			})
+	for line, name in zip(sl, ["pkg1", "pkg2", "pkg3", "pkg4", "pkg5"]):
+		assert line.startswith(f"{name}:")
+	assert sl[-2].startswith("Python: 3.")
+
+
+def test_version_callback(cli_runner: CliRunner):
+
+	@version_option(
+			get_version_callback(
+					"1.2.3",
+					"my-tool",
+					["click", "deprecation-alias", "domdf-python-tools", "mistletoe", "typing-extensions"]
+					)
+			)
+	@click_command()
+	def main() -> None:
+		sys.exit(1)
+
+	result = cli_runner.invoke(main, args="--version")
+	assert result.stdout.rstrip() == "my-tool version 1.2.3"
+	assert result.exit_code == 0
+
+	result = cli_runner.invoke(main, args=["--version", "--version"])
+	assert result.stdout.startswith("my-tool version 1.2.3, Python 3.")
+	assert result.exit_code == 0
+
+	result = cli_runner.invoke(main, args=["--version", "--version", "--version"])
+	print(result.stdout)
+	assert result.stdout.startswith("my-tool\n  Version: 1.2.3\n  click: ")
+	assert result.exit_code == 0