Bump actions/setup-python from 5.1.1 to 5.2.0 (#655)

Bumps [actions/setup-python](https://github.com/actions/setup-python) from 5.1.1 to 5.2.0.
- [Release notes](https://github.com/actions/setup-python/releases)
- [Commits](https://github.com/actions/setup-python/compare/v5.1.1...v5.2.0)

---
updated-dependencies:
- dependency-name: actions/setup-python
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/workflows/pythonpackage-windows.yml

@@ -19,7 +19,7 @@ jobs:
       with:
         submodules: 'recursive'
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5.0.0
+      uses: actions/setup-python@v5.2.0
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
@@ -44,12 +44,14 @@ jobs:
       env:
         ESCPOS_CAPABILITIES_FILE: D:\a\python-escpos\python-escpos\capabilities-data\dist\capabilities.json
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
       with:
-        directory: ./coverage/reports/
         env_vars: OS,PYTHON
         fail_ci_if_error: true
-        files: ./coverage.xml,!./cache
+        files: ./coverage.xml
+        exclude: "**/.mypy_cache"
         flags: unittests
         name: coverage-tox-${{ matrix.python-version }}
         verbose: true

.github/workflows/pythonpackage.yml

@@ -22,7 +22,7 @@ jobs:
       with:
         submodules: 'recursive'
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5.0.0
+      uses: actions/setup-python@v5.2.0
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
@@ -54,12 +54,14 @@ jobs:
       env:
         ESCPOS_CAPABILITIES_FILE: /home/runner/work/python-escpos/python-escpos/capabilities-data/dist/capabilities.json
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
       with:
-        directory: ./coverage/reports/
         env_vars: OS,PYTHON
         fail_ci_if_error: true
-        files: ./coverage.xml,!./cache
+        files: ./coverage.xml
+        exclude: "**/.mypy_cache"
         flags: unittests
         name: coverage-tox-${{ matrix.python-version }}
         verbose: true

.vscode/settings.json

@@ -12,7 +12,7 @@
   "editor.formatOnPaste": true,
   "python.formatting.provider": "black",
   "editor.codeActionsOnSave": {
-    "source.organizeImports": true
+    "source.organizeImports": "explicit"
   },
   "python.testing.unittestEnabled": false,
   "python.testing.pytestEnabled": true,

CHANGELOG.rst

@@ -1,6 +1,18 @@
 Changelog
 =========
 
+202x-xx-xx - Version 3.x - ""
+-------------------------------------------
+
+
+changes
+^^^^^^^
+
+
+contributors
+^^^^^^^^^^^^
+
+
 2023-12-17 - Version 3.1 - "Rubric Of Ruin"
 -------------------------------------------
 This is the minor release of the new version 3.1.

README.rst

@@ -100,4 +100,4 @@ Disclaimer
 
 None of the vendors cited in this project agree or endorse any of the
 patterns or implementations.
-Its names are used only to maintain context.
+Their names are used only to maintain context.

capabilities-data

@@ -1 +1 @@
-Subproject commit 4006299c0fa82bc4d4c297663628346ce3eff6c5
+Subproject commit e3bf6056ee75cf70ffaccb925081fffa7ad6ced5

doc/spelling_wordlist.txt

@@ -91,6 +91,7 @@ docstrings
 ean
 Ean
 encodable
+Errno
 fff
 fullimage
 io
@@ -124,6 +125,7 @@ Todo
 traceback
 udev
 usb
+USBTimeoutError
 usec
 virtualenvs
 whitespaces

doc/user/usage.rst

@@ -213,6 +213,14 @@ If something is wrong, an ``CharCodeError`` will be raised.
 After you have manually set the codepage the printer won't change it anymore.
 You can revert to normal behavior by setting charcode to ``AUTO``.
 
+Resolving bus timeout issues during printing images
+---------------------------------------------------
+
+If an error message such as "USBTimeoutError: [Errno 110] Operation timed out" occurs,
+setting a sleep time between printing fragments can help.
+
+This can be done with the :meth:`.set_sleep_in_fragment()` method.
+
 Advanced Usage: Print from binary blob
 --------------------------------------
 

examples/docker-flask/requirements.txt

@@ -4,9 +4,9 @@ blinker==1.6.2
 click==8.1.3
 Flask==2.3.2
 itsdangerous==2.1.2
-Jinja2==3.1.2
+Jinja2==3.1.4
 MarkupSafe==2.1.2
-Pillow==10.0.1
+Pillow==10.3.0
 pycups==2.0.1
 pypng==0.20220715.0
 pyserial==3.5
@@ -17,4 +17,4 @@ PyYAML==6.0
 qrcode==7.4.2
 six==1.16.0
 typing_extensions==4.5.0
-Werkzeug==3.0.1
+Werkzeug==3.0.3

src/escpos/cli.py

@@ -209,6 +209,38 @@ ESCPOS_COMMANDS: List[Dict[str, Any]] = [
             },
         ],
     },
+    {
+        "parser": {
+            "name": "software_columns",
+            "help": "Print a list of texts arranged into columns",
+        },
+        "defaults": {
+            "func": "software_columns",
+        },
+        "arguments": [
+            {
+                "option_strings": ("--text_list",),
+                "help": "list of texts to print",
+                "nargs": "+",
+                "type": str,
+                "required": True,
+            },
+            {
+                "option_strings": ("--widths",),
+                "help": "list of column widths",
+                "nargs": "+",
+                "type": int,
+                "required": True,
+            },
+            {
+                "option_strings": ("--align",),
+                "help": "list of column alignments",
+                "nargs": "+",
+                "type": str,
+                "required": True,
+            },
+        ],
+    },
     {
         "parser": {
             "name": "cut",

src/escpos/config.py

@@ -76,7 +76,18 @@ class Config:
 
         if "printer" in config:
             self._printer_config = config["printer"]
-            self._printer_name = self._printer_config.pop("type").title()
+            printer_name = self._printer_config.pop("type")
+            class_names = {
+                "usb": "Usb",
+                "serial": "Serial",
+                "network": "Network",
+                "file": "File",
+                "dummy": "Dummy",
+                "cupsprinter": "CupsPrinter",
+                "lp": "LP",
+                "win32raw": "Win32Raw",
+            }
+            self._printer_name = class_names.get(printer_name.lower(), printer_name)
 
             if not self._printer_name or not hasattr(printer, self._printer_name):
                 raise exceptions.ConfigSyntaxError(

src/escpos/escpos.py

@@ -12,6 +12,7 @@ This module contains the abstract base class :py:class:`Escpos`.
 from __future__ import annotations
 
 import textwrap
+import time
 import warnings
 from abc import ABCMeta, abstractmethod  # abstract base class support
 from re import match as re_match
@@ -107,6 +108,8 @@ SW_BARCODE_NAMES = {
     for name in barcode.PROVIDED_BARCODES
 }
 
+Alignment = Union[Literal["center", "left", "right"], str]
+
 
 class Escpos(object, metaclass=ABCMeta):
     """ESC/POS Printer object.
@@ -121,6 +124,9 @@ class Escpos(object, metaclass=ABCMeta):
     #   object -> The connection object (Usb(), Serial(), Network(), etc.)
     _device: Union[Literal[False], Literal[None], object] = False
 
+    # sleep time in fragments:
+    _sleep_in_fragment_ms: int = 0
+
     def __init__(self, profile=None, magic_encode_args=None, **kwargs) -> None:
         """Initialize ESCPOS Printer.
 
@@ -176,6 +182,21 @@ class Escpos(object, metaclass=ABCMeta):
         """
         raise NotImplementedError()
 
+    def set_sleep_in_fragment(self, sleep_time_ms: int) -> None:
+        """Configures the currently active sleep time after sending a fragment.
+
+        If during printing an image an issue like "USBTimeoutError: [Errno 110]
+        Operation timed out" occurs, setting this value to roughly 300
+        milliseconds can help resolve the issue.
+
+        :param sleep_time_ms: sleep time in milliseconds
+        """
+        self._sleep_in_fragment_ms = sleep_time_ms
+
+    def _sleep_in_fragment(self) -> None:
+        """Sleeps the preconfigured time after sending a fragment."""
+        time.sleep(self._sleep_in_fragment_ms / 1000)
+
     def image(
         self,
         img_source,
@@ -244,6 +265,7 @@ class Escpos(object, metaclass=ABCMeta):
                     impl=impl,
                     fragment_height=fragment_height,
                 )
+                self._sleep_in_fragment()
             return
 
         if impl == "bitImageRaster":
@@ -897,6 +919,115 @@ class Escpos(object, metaclass=ABCMeta):
         col_count = self.profile.get_columns(font) if columns is None else columns
         self.text(textwrap.fill(txt, col_count))
 
+    @staticmethod
+    def _padding(
+        text: str,
+        width: int,
+        align: Alignment = "center",
+    ) -> str:
+        """Add fill space to meet the width.
+
+        The align parameter sets the alignment of the text in space.
+        """
+        align = align.lower()
+        if align == "center":
+            text = f"{text:^{width}}"
+        elif align == "left":
+            text = f"{text:<{width}}"
+        elif align == "right":
+            text = f"{text:>{width}}"
+
+        return text
+
+    @staticmethod
+    def _truncate(text: str, width: int, placeholder: str = ".") -> str:
+        """Truncate an string at a max width or leave it untouched.
+
+        Add a placeholder at the end of the output text if it has been truncated.
+        """
+        ph_len = len(placeholder)
+        max_len = width - ph_len
+        return f"{text[:max_len]}{placeholder}" if len(text) > width else text
+
+    @staticmethod
+    def _repeat_last(iterable, max_iterations: int = 1000):
+        """Iterate over the items of a list repeating the last one until max_iterations."""
+        i = 0
+        while i < max_iterations:
+            try:
+                yield iterable[i]
+            except IndexError:
+                yield iterable[-1]
+            i += 1
+
+    def _rearrange_into_cols(self, text_list: list, widths: list[int]) -> list:
+        """Wrap and convert a list of strings into an array of text columns.
+
+        Set the width of each column by passing a list of widths.
+        Wrap if possible and|or truncate strings longer than its column width.
+        Reorder the wrapped items into an array of text columns.
+        """
+        n_cols = len(text_list)
+        wrapped = [
+            textwrap.wrap(text, widths[i], break_long_words=False)
+            for i, text in enumerate(text_list)
+        ]
+        max_len = max(*[len(text_group) for text_group in wrapped])
+        text_colums = []
+        for i in range(max_len):
+            row = ["" for _ in range(n_cols)]
+            for j, item in enumerate(wrapped):
+                if i in range(len(item)):
+                    row[j] = self._truncate(item[i], widths[j])
+            text_colums.append(row)
+        return text_colums
+
+    def _add_padding_into_cols(
+        self,
+        text_list: list[str],
+        widths: list[int],
+        align: list[Alignment],
+    ) -> list:
+        """Add padding, width and alignment into the items of a list of strings."""
+        return [
+            self._padding(text, widths[i], align[i]) for i, text in enumerate(text_list)
+        ]
+
+    def software_columns(
+        self,
+        text_list: list,
+        widths: Union[list[int], int],
+        align: Union[list[Alignment], Alignment],
+    ) -> None:
+        """Print a list of strings arranged horizontally in columns.
+
+        :param text_list: list of strings, each item in the list will be printed as a column.
+
+        :param widths: width of each column by passing a list of widths,
+            or a single total width to arrange columns of the same size.
+            If the list of width items is shorter than the list of strings then
+            the last width of the list will be applied till the last string (column).
+
+        :param align: alignment of the text into each column by passing a list of alignments,
+            or a single alignment for all the columns.
+            If the list of alignment items is shorter than the list of strings then
+            the last alignment of the list will be applied till the last string (column).
+        """
+        n_cols = len(text_list)
+
+        if isinstance(widths, int):
+            widths = [round(widths / n_cols)]
+        widths = list(self._repeat_last(widths, max_iterations=n_cols))
+
+        if isinstance(align, str):
+            align = [align]
+        align = list(self._repeat_last(align, max_iterations=n_cols))
+
+        columns = self._rearrange_into_cols(text_list, widths)
+        for row in columns:
+            padded = self._add_padding_into_cols(row, widths, align)
+            self.textln("".join(padded))
+
     def set(
         self,
         align: Optional[str] = None,
@@ -934,8 +1065,8 @@ class Escpos(object, metaclass=ABCMeta):
         :param double_width: doubles the width of the text
         :param custom_size: uses custom size specified by width and height
             parameters. Cannot be used with double_width or double_height.
-        :param width: text width multiplier when custom_size is used, decimal range 1-8
+        :param width: requires custom_size=True, text width multiplier when custom_size is used, decimal range 1-8
-        :param height: text height multiplier when custom_size is used, decimal range 1-8
+        :param height: requires custom_size=True, text height multiplier when custom_size is used, decimal range 1-8
         :param density: print density, value from 0-8, if something else is supplied the density remains unchanged
         :param invert: True enables white on black printing
         :param smooth: True enables text smoothing. Effective on 4x4 size text and larger

src/escpos/katakana.py

@@ -4,7 +4,10 @@
 I doubt that this currently works correctly.
 """
 
+import types
+import typing
 
+jaconv: typing.Optional[types.ModuleType]
 try:
     import jaconv
 except ImportError:

test/test_functions/test_function_software_columns.py

@@ -0,0 +1,80 @@
+#!/usr/bin/python
+#  -*- coding: utf-8 -*-
+"""tests for software_columns
+
+:author: Benito López and the python-escpos developers
+:organization: `python-escpos <https://github.com/python-escpos>`_
+:copyright: Copyright (c) 2024 `python-escpos <https://github.com/python-escpos>`_
+:license: MIT
+"""
+
+
+import pytest
+
+
+def test_rearrange_into_cols(driver) -> None:
+    """
+    GIVEN a list of columnable text
+    WHEN the column width is different for each column and some strings exceed the max width
+    THEN check the strings are properly wrapped, truncated and rearranged into some columns
+    """
+
+    output = driver._rearrange_into_cols(
+        text_list=["fits", "row1 row2", "truncate and wrap"], widths=[4, 5, 6]
+    )
+    assert output == [["fits", "row1", "trunc."], ["", "row2", "and"], ["", "", "wrap"]]
+
+
+def test_add_padding_into_cols(driver) -> None:
+    """
+    GIVEN a list of strings
+    WHEN adding padding and different alignments to each string
+    THEN check the strings are correctly padded and aligned
+    """
+
+    output = driver._add_padding_into_cols(
+        text_list=["col1", "col2", "col3"],
+        widths=[6, 6, 6],
+        align=["center", "left", "right"],
+    )
+    assert output == [" col1 ", "col2  ", "  col3"]
+
+
+@pytest.mark.parametrize("text_list", ["", [], None])
+@pytest.mark.parametrize("widths", [30.5, "30", None])
+@pytest.mark.parametrize("align", ["invalid_align_name", "", None])
+def test_software_columns_invalid_args(driver, text_list, widths, align) -> None:
+    """
+    GIVEN a dummy printer object
+    WHEN non valid params are passed
+    THEN check raise exception
+    """
+    bad_text_list = {"text_list": text_list, "widths": 5, "align": "left"}
+    bad_widths = {"text_list": ["valid"], "widths": widths, "align": "left"}
+    bad_align = {"text_list": ["valid"], "widths": 5, "align": align}
+
+    bad_args = [bad_text_list, bad_widths, bad_align]
+    for kwargs in bad_args:
+        with pytest.raises(Exception):
+            driver.software_columns(**kwargs)
+        driver.close()
+
+
+@pytest.mark.parametrize(
+    "text_list",
+    [
+        ["col1", "col2", "col3"],
+        ["wrap this string", "wrap this string", "wrap this string"],
+        ["truncate_this_string", "truncate_this_string", "truncate_this_string"],
+    ],
+)
+@pytest.mark.parametrize("widths", [[10, 10, 10], [10], 30])
+@pytest.mark.parametrize("align", [["center", "left", "right"], ["center"], "center"])
+def test_software_columns_valid_args(driver, text_list, widths, align) -> None:
+    """
+    GIVEN a dummy printer object
+    WHEN valid params are passed
+    THEN check no errors
+    """
+    driver.software_columns(text_list=text_list, widths=widths, align=align)
+    driver.close()

test/test_magicencode.py

@@ -7,7 +7,8 @@
 :copyright: Copyright (c) 2016 `python-escpos <https://github.com/python-escpos>`_
 :license: MIT
 """
-
+import types
+import typing
 
 import hypothesis.strategies as st
 import pytest
@@ -111,6 +112,7 @@ class TestMagicEncode:
             assert driver.output == b"\x1bt\x00? ist teuro."
 
 
+jaconv: typing.Optional[types.ModuleType]
 try:
     import jaconv
 except ImportError: