Improve diagnostic output (#577)

* add extended version information

* autodocument argparser

* add spelling exception

* fix docstrings

* add annotations

* use typing types

* add test

.github/ISSUE_TEMPLATE.md

@@ -18,7 +18,8 @@ I have:
  **Printer:** Manufacturer Model XVI
 
 <!-- since version 2.0.1 you can type 'python-escpos version' in your shell.
-Alternatively you could use '__version__' in module escpos. -->
+Starting with python-escpos version 3.0, please replace the information below
+with the output of `python-escpos version_extended`. -->
  **python-escpos version:** 0.0.0
 
  **python version:** 0.0

doc/conf.py

@@ -43,6 +43,7 @@ extensions = [
     "sphinx.ext.graphviz",
     "sphinx.ext.inheritance_diagram",
     "sphinx.ext.imgconverter",
+    "sphinxarg.ext",
     "sphinxcontrib.datatemplates",
     "sphinxcontrib.spelling",
 ]

doc/index.rst

@@ -24,6 +24,7 @@ are relevant to the user of this library.
    user/printers
    user/raspi
    user/usage
+   user/cli-user
    user/barcode
 
 Printer profiles

doc/requirements.txt

@@ -11,5 +11,6 @@ python-barcode>=0.11.0,<1
 importlib-metadata
 importlib_resources
 sphinxcontrib.datatemplates
+sphinx-argparse
 sphinx-autodoc-typehints
 pycups

doc/spelling_wordlist.txt

@@ -89,6 +89,7 @@ ean
 Ean
 encodable
 fff
+fullimage
 io
 json
 latin

doc/user/cli-user.rst

@@ -0,0 +1,10 @@
+CLI
+===
+
+:Last Reviewed: 2023-09-25
+
+Documentation of the command line interface, callable with ``python-escpos``.
+
+.. argparse::
+   :ref: escpos.cli.generate_parser
+   :prog: python-escpos

src/escpos/cli.py

@@ -9,8 +9,9 @@ It requires you to have a configuration file. See documentation for details.
 
 """
 
-
 import argparse
+import platform
+from typing import Any, Dict, List
 
 try:
     import argcomplete
@@ -21,7 +22,9 @@ import sys
 
 import six
 
-from . import config, version
+from . import config
+from . import printer as escpos_printer_module
+from . import version
 
 
 # Must be defined before it's used in DEMO_FUNCTIONS
@@ -92,7 +95,7 @@ DEMO_FUNCTIONS = {
 # parser: A dict of args for command_parsers.add_parser
 # defaults: A dict of args for subparser.set_defaults
 # arguments: A list of dicts of args for subparser.add_argument
-ESCPOS_COMMANDS = [
+ESCPOS_COMMANDS: List[Dict[str, Any]] = [
     {
         "parser": {
             "name": "qr",
@@ -297,7 +300,7 @@ ESCPOS_COMMANDS = [
             },
             {
                 "option_strings": ("--histeq",),
-                "help": "Equalize the histrogram",
+                "help": "Equalize the histogram",
                 "type": str_to_bool,
             },
             {
@@ -454,12 +457,39 @@ ESCPOS_COMMANDS = [
 ]
 
 
-def main():
-    """Handle main entry point of CLI script.
+def print_extended_information() -> None:
+    """Print diagnostic information for bug reports."""
+    print(f"* python-escpos version: `{version.version}`")
+    print(
+        f"* python version: `{platform.python_implementation()} v{platform.python_version()}`"
+    )
+    print(f"* platform: `{platform.platform()}`")
+    print(
+        f"* printer driver `USB` is usable: `{escpos_printer_module.Usb.is_usable()}`"
+    )
+    print(
+        f"* printer driver `File` is usable: `{escpos_printer_module.File.is_usable()}`"
+    )
+    print(
+        f"* printer driver `Network` is usable: `{escpos_printer_module.Network.is_usable()}`"
+    )
+    print(
+        f"* printer driver `Serial` is usable: `{escpos_printer_module.Serial.is_usable()}`"
+    )
+    print(f"* printer driver `LP` is usable: `{escpos_printer_module.LP.is_usable()}`")
+    print(
+        f"* printer driver `Dummy` is usable: `{escpos_printer_module.Dummy.is_usable()}`"
+    )
+    print(
+        f"* printer driver `CupsPrinter` is usable: `{escpos_printer_module.CupsPrinter.is_usable()}`"
+    )
+    print(
+        f"* printer driver `Win32Raw` is usable: `{escpos_printer_module.Win32Raw.is_usable()}`"
+    )
 
-    Handles loading of configuration and creating and processing of command
-    line arguments. Called when run from a CLI.
-    """
+
+def generate_parser() -> argparse.ArgumentParser:
+    """Generate an argparse parser."""
     parser = argparse.ArgumentParser(
         description="CLI for python-escpos",
         epilog="Printer configuration is defined in the python-escpos config"
@@ -520,10 +550,27 @@ def main():
     )
 
     parser_command_version = command_subparsers.add_parser(
-        "version", help="Print the version of python-escpos"
+        "version", help="Print the version information of python-escpos"
     )
     parser_command_version.set_defaults(version=True)
 
+    parser_command_version_extended = command_subparsers.add_parser(
+        "version_extended",
+        help="Print the extended version information of python-escpos (for bug reports)",
+    )
+    parser_command_version_extended.set_defaults(version_extended=True)
+
+    return parser
+
+
+def main():
+    """Handle main entry point of CLI script.
+
+    Handles loading of configuration and creating and processing of command
+    line arguments. Called when run from a CLI.
+    """
+    parser = generate_parser()
+
     # hook in argcomplete
     if "argcomplete" in globals():
         argcomplete.autocomplete(parser)
@@ -543,6 +590,11 @@ def main():
         print(version.version)
         sys.exit()
 
+    print_version_extended = command_arguments.pop("version_extended", None)
+    if print_version_extended:
+        print_extended_information()
+        sys.exit()
+
     # If there was a config path passed, grab it
     config_path = command_arguments.pop("config", None)
 

test/test_cli.py

@@ -81,6 +81,14 @@ class TestCLI:
         assert not result.stderr
         assert escpos.__version__ == result.stdout.strip()
 
+    def test_cli_version_extended(self):
+        """Test the extended version information"""
+        result = self.env.run("python-escpos", "version_extended")
+        assert not result.stderr
+        assert escpos.__version__ in result.stdout
+        # test that additional information on e.g. Serial is printed
+        assert "Serial" in result.stdout
+
     @pytest.mark.skip(
         reason="disable this test as it is not that easy anymore to predict the outcome of this call"
     )

tox.ini

@@ -33,6 +33,7 @@ changedir = doc
 deps = sphinx>=7.2.3
        setuptools_scm
        python-barcode
+       sphinx-argparse
        sphinxcontrib-spelling>=8.0.0
        sphinxcontrib.datatemplates
        sphinx-autodoc-typehints