Merge branch 'master' into belono/issue445

.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

.github/workflows/pythonpackage.yml

@@ -22,7 +22,7 @@ jobs:
       with:
         submodules: 'recursive'
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4.7.0
+      uses: actions/setup-python@v4.7.1
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies

CHANGELOG.rst

@@ -1,6 +1,26 @@
 Changelog
 =========
 
+20xx-xx-xx - Version x.x - ""
+-----------------------------
+`Release description`
+
+changes
+^^^^^^^
+- some
+- thing
+- has
+- changed
+
+- fix the encoding search so that lower encodings are found first
+
+contributors
+^^^^^^^^^^^^
+- list
+- contributors
+
+-  Scott Rotondo  in `#570 <https://github.com/python-escpos/python-escpos/issues/570>`_
+
 2023-05-11 - Version 3.0a9 - "Pride Comes Before A Fall"
 --------------------------------------------------------
 This release is the 10th alpha release of the new version 3.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/dev/release-process.rst

@@ -8,3 +8,4 @@ Release process
 * Set annotated tag for release and push to public github
 * Build wheel
 * Load wheel to PyPi
+* Prepare project for next release with an empty changelog entry

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

@@ -67,6 +67,7 @@ Heuel
 Qian
 Lehtonen
 Kanzler
+Rotondo
 
 barcode
 barcodes
@@ -89,6 +90,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

examples/docker-flask/requirements.txt

@@ -6,7 +6,7 @@ Flask==2.3.2
 itsdangerous==2.1.2
 Jinja2==3.1.2
 MarkupSafe==2.1.2
-Pillow==9.5.0
+Pillow==10.0.1
 pycups==2.0.1
 pypng==0.20220715.0
 pyserial==3.5

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)
 

src/escpos/magicencode.py

@@ -155,7 +155,8 @@ class Encoder(object):
 
     def __encoding_sort_func(self, item):
         key, index = item
-        return (key in self.used_encodings, index)
+        used = key in self.used_encodings
+        return (not used, index)
 
     def find_suitable_encoding(self, char):
         """Search in a specific order for a suitable encoding.

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"
     )

test/test_magicencode.py

@@ -32,6 +32,13 @@ class TestEncoder:
         assert not Encoder({"CP437": 1}).find_suitable_encoding("€")
         assert Encoder({"CP858": 1}).find_suitable_encoding("€") == "CP858"
 
+    def test_find_suitable_encoding_unnecessary_codepage_swap(self):
+        enc = Encoder({"CP857": 1, "CP437": 2, "CP1252": 3, "CP852": 4, "CP858": 5})
+        # desired behavior would be that the encoder always stays in the lower
+        # available codepages if possible
+        for character in ("Á", "É", "Í", "Ó", "Ú"):
+            assert enc.find_suitable_encoding(character) == "CP857"
+
     def test_get_encoding(self):
         with pytest.raises(ValueError):
             Encoder({}).get_encoding_name("latin1")

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