From ecfeeb9b13d61111340a471b088c7e4d0d0250fe Mon Sep 17 00:00:00 2001 From: Patrick Kanzler <4189642+patkan@users.noreply.github.com> Date: Thu, 5 Oct 2023 14:15:19 +0200 Subject: [PATCH] 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 | 3 +- doc/conf.py | 1 + doc/index.rst | 1 + doc/requirements.txt | 1 + doc/spelling_wordlist.txt | 1 + doc/user/cli-user.rst | 10 ++++++ src/escpos/cli.py | 72 +++++++++++++++++++++++++++++++++------ test/test_cli.py | 8 +++++ tox.ini | 1 + 9 files changed, 87 insertions(+), 11 deletions(-) create mode 100644 doc/user/cli-user.rst diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 36ed5e6..aac7d57 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -18,7 +18,8 @@ I have: **Printer:** Manufacturer Model XVI +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 diff --git a/doc/conf.py b/doc/conf.py index b3f1fb5..8cccf44 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -43,6 +43,7 @@ extensions = [ "sphinx.ext.graphviz", "sphinx.ext.inheritance_diagram", "sphinx.ext.imgconverter", + "sphinxarg.ext", "sphinxcontrib.datatemplates", "sphinxcontrib.spelling", ] diff --git a/doc/index.rst b/doc/index.rst index 65021fb..122fb19 100644 --- a/doc/index.rst +++ b/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 diff --git a/doc/requirements.txt b/doc/requirements.txt index ff1337b..3ad476b 100644 --- a/doc/requirements.txt +++ b/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 diff --git a/doc/spelling_wordlist.txt b/doc/spelling_wordlist.txt index 53d72a4..b00b484 100644 --- a/doc/spelling_wordlist.txt +++ b/doc/spelling_wordlist.txt @@ -89,6 +89,7 @@ ean Ean encodable fff +fullimage io json latin diff --git a/doc/user/cli-user.rst b/doc/user/cli-user.rst new file mode 100644 index 0000000..1893fa7 --- /dev/null +++ b/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 diff --git a/src/escpos/cli.py b/src/escpos/cli.py index 59b195e..6d99b90 100644 --- a/src/escpos/cli.py +++ b/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) diff --git a/test/test_cli.py b/test/test_cli.py index cd2828e..648dd6e 100644 --- a/test/test_cli.py +++ b/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" ) diff --git a/tox.ini b/tox.ini index 6a60800..08922e7 100644 --- a/tox.ini +++ b/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