From 1b4230fdd976ac273666e4c76d767f1ffc03d79d Mon Sep 17 00:00:00 2001 From: Patrick Kanzler Date: Thu, 10 Aug 2023 23:29:26 +0200 Subject: [PATCH] formatting --- examples/barcodes.py | 3 +- examples/codepage_tables.py | 5 ++- examples/docker-flask/app.py | 2 + examples/qr_code.py | 2 + examples/software_barcode.py | 1 + examples/weather.py | 27 +++++++------ setup.py | 13 +++++-- src/escpos/__init__.py | 4 +- src/escpos/capabilities.py | 5 +-- src/escpos/cli.py | 2 +- src/escpos/codepages.py | 4 +- src/escpos/escpos.py | 9 +++-- src/escpos/exceptions.py | 2 +- src/escpos/image.py | 29 +++++--------- src/escpos/magicencode.py | 44 +++++++++++++-------- src/escpos/printer.py | 75 ++++++++++++++++++++---------------- test/test_with_statement.py | 5 ++- 17 files changed, 128 insertions(+), 104 deletions(-) diff --git a/examples/barcodes.py b/examples/barcodes.py index 8fb26c1..cd905fc 100644 --- a/examples/barcodes.py +++ b/examples/barcodes.py @@ -1,5 +1,4 @@ -""" Example for printing barcodes. -""" +"""Example for printing barcodes.""" from escpos.printer import Usb # Adapt to your needs diff --git a/examples/codepage_tables.py b/examples/codepage_tables.py index b3a0c3c..7128942 100644 --- a/examples/codepage_tables.py +++ b/examples/codepage_tables.py @@ -1,5 +1,4 @@ -"""Prints code page tables. -""" +"""Prints code page tables.""" import sys @@ -19,6 +18,7 @@ from escpos.constants import ( def main(): + """Init printer and print codepage tables.""" dummy = printer.Dummy() dummy.hw("init") @@ -35,6 +35,7 @@ def main(): def print_codepage(printer, codepage): + """Print a codepage.""" if codepage.isdigit(): codepage = int(codepage) printer._raw(CODEPAGE_CHANGE + six.int2byte(codepage)) diff --git a/examples/docker-flask/app.py b/examples/docker-flask/app.py index f34a8e5..2f13cb2 100644 --- a/examples/docker-flask/app.py +++ b/examples/docker-flask/app.py @@ -1,3 +1,4 @@ +"""Example for a flask application.""" from flask import Flask from escpos.printer import CupsPrinter @@ -8,6 +9,7 @@ app = Flask(__name__) @app.route("/", methods=["GET"]) def do_print(): + """Print.""" # p = Usb(0x04b8, 0x0e28, 0) p = CupsPrinter(host="localhost", port=631, printer_name="TM-T20III") p.text("Hello World\n") diff --git a/examples/qr_code.py b/examples/qr_code.py index 24b9d60..85f9711 100644 --- a/examples/qr_code.py +++ b/examples/qr_code.py @@ -1,9 +1,11 @@ +"""Print example QR codes.""" import sys from escpos.printer import Usb def usage(): + """Print information on usage.""" print("usage: qr_code.py ") diff --git a/examples/software_barcode.py b/examples/software_barcode.py index 15b81bc..1428320 100644 --- a/examples/software_barcode.py +++ b/examples/software_barcode.py @@ -1,3 +1,4 @@ +"""Example file for software barcodes.""" from escpos.printer import Usb # Adapt to your needs diff --git a/examples/weather.py b/examples/weather.py index 1469dbf..23a0619 100644 --- a/examples/weather.py +++ b/examples/weather.py @@ -1,16 +1,17 @@ #!/usr/bin/python +"""Weather forecast example. +Adapted script from Adafruit +Weather forecast for Raspberry Pi w/Adafruit Mini Thermal Printer. +Retrieves data from DarkSky.net's API, prints current conditions and +forecasts for next two days. +Weather example using nice bitmaps. +Written by Adafruit Industries. MIT license. +Adapted and enhanced for escpos library by MrWunderbar666 -# Adapted script from Adafruit -# Weather forecast for Raspberry Pi w/Adafruit Mini Thermal Printer. -# Retrieves data from DarkSky.net's API, prints current conditions and -# forecasts for next two days. -# Weather example using nice bitmaps. -# Written by Adafruit Industries. MIT license. -# Adapted and enhanced for escpos library by MrWunderbar666 - -# Icons taken from https://adamwhitcroft.com/climacons/ -# Check out his github: https://github.com/AdamWhitcroft/climacons +Icons taken from https://adamwhitcroft.com/climacons/ +Check out his github: https://github.com/AdamWhitcroft/climacons +""" import calendar @@ -22,7 +23,7 @@ from datetime import datetime from escpos.printer import Usb -""" Setting up the main pathing """ +"""Set up the main pathing.""" this_dir, this_filename = os.path.split(__file__) GRAPHICS_PATH = os.path.join(this_dir, "graphics/climacons/") @@ -38,13 +39,14 @@ LONG = "114.189945" # Your Location def forecast_icon(idx): + """Get right icon for forecast.""" icon = data["daily"]["data"][idx]["icon"] image = GRAPHICS_PATH + icon + ".png" return image -# Dumps one forecast line to the printer def forecast(idx): + """Dump one forecast line to the printer.""" date = datetime.fromtimestamp(int(data["daily"]["data"][idx]["time"])) day = calendar.day_name[date.weekday()] lo = data["daily"]["data"][idx]["temperatureMin"] @@ -73,6 +75,7 @@ def forecast(idx): def icon(): + """Get icon.""" icon = data["currently"]["icon"] image = GRAPHICS_PATH + icon + ".png" return image diff --git a/setup.py b/setup.py index 64cf5b9..c1cec16 100755 --- a/setup.py +++ b/setup.py @@ -1,4 +1,5 @@ #!/usr/bin/env python +"""Setup script for python package.""" import os import sys @@ -14,14 +15,18 @@ sys.path.insert(0, src_dir) def read(fname): - """read file from same path as setup.py""" + """Read file from same path as setup.py.""" return open(os.path.join(os.path.dirname(__file__), fname)).read() setuptools_scm_template = """\ -# coding: utf-8 -# file generated by setuptools_scm -# don't change, don't track in version control +#!/usr/bin/python +# -*- coding: utf-8 -*- +\"\"\"Version identifier. + +file generated by setuptools_scm +don't change, don't track in version control +\"\"\" version = '{version}' """ diff --git a/src/escpos/__init__.py b/src/escpos/__init__.py index bf739e5..286a6e6 100644 --- a/src/escpos/__init__.py +++ b/src/escpos/__init__.py @@ -1,7 +1,5 @@ # -*- coding: utf-8 -*- -""" -python-escpos enables you to manipulate escpos-printers -""" +"""python-escpos enables you to manipulate escpos-printers.""" __all__ = ["constants", "escpos", "exceptions", "printer"] diff --git a/src/escpos/capabilities.py b/src/escpos/capabilities.py index 763aa1c..1a253da 100644 --- a/src/escpos/capabilities.py +++ b/src/escpos/capabilities.py @@ -1,3 +1,4 @@ +"""Handler for capabilities data.""" import atexit import logging import pickle @@ -58,9 +59,7 @@ PROFILES: Dict[str, Any] = CAPABILITIES["profiles"] class NotSupported(Exception): - """Raised if a requested feature is not supported by the - printer profile. - """ + """Raised if a requested feature is not supported by the printer profile.""" pass diff --git a/src/escpos/cli.py b/src/escpos/cli.py index 1c0bb39..01049bf 100644 --- a/src/escpos/cli.py +++ b/src/escpos/cli.py @@ -1,6 +1,6 @@ #!/usr/bin/env python # PYTHON_ARGCOMPLETE_OK -""" CLI +"""CLI. This module acts as a command line interface for python-escpos. It mirrors closely the available ESCPOS commands while adding a couple extra ones for convenience. diff --git a/src/escpos/codepages.py b/src/escpos/codepages.py index f858b08..b3f7720 100644 --- a/src/escpos/codepages.py +++ b/src/escpos/codepages.py @@ -14,7 +14,9 @@ class CodePageManager: @staticmethod def get_encoding_name(encoding): - # TODO resolve the encoding alias + """Get encoding name. + + .. todo:: Resolve the encoding alias.""" return encoding.upper() def get_encoding(self, encoding): diff --git a/src/escpos/escpos.py b/src/escpos/escpos.py index bfee881..7e07420 100644 --- a/src/escpos/escpos.py +++ b/src/escpos/escpos.py @@ -1,6 +1,6 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -""" Main class +"""Main class This module contains the abstract base class :py:class:`Escpos`. @@ -403,7 +403,8 @@ class Escpos(object): @staticmethod def check_barcode(bc, code): - """ + """Check if barcode is OK. + This method checks if the barcode is in the proper format. The validation concerns the barcode length and the set of characters, but won't compute/validate any checksum. The full set of requirement for each barcode type is available in the ESC/POS documentation. @@ -582,7 +583,7 @@ class Escpos(object): function_type=None, check=True, ): - """Print Barcode + """Print Barcode. This method allows to print barcodes. The rendering of the barcode is done by the printer and therefore has to be supported by the unit. By default, this method will check whether your barcode text is correct, that is @@ -886,7 +887,7 @@ class Escpos(object): double_height=False, custom_size=False, ): - """Set text properties by sending them to the printer + """Set text properties by sending them to the printer. :param align: horizontal position for text, possible values are: diff --git a/src/escpos/exceptions.py b/src/escpos/exceptions.py index cdb7eea..5be8eef 100644 --- a/src/escpos/exceptions.py +++ b/src/escpos/exceptions.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -""" ESC/POS Exceptions classes +"""ESC/POS Exceptions classes. Result/Exit codes: diff --git a/src/escpos/image.py b/src/escpos/image.py index 3396ed5..a5dbfea 100644 --- a/src/escpos/image.py +++ b/src/escpos/image.py @@ -1,4 +1,4 @@ -""" Image format handling class +"""Image format handling class. This module contains the image format handler :py:class:`EscposImage`. @@ -23,8 +23,7 @@ class EscposImage(object): """ def __init__(self, img_source): - """ - Load in an image + """Load in an image. :param img_source: PIL.Image, or filename to load one from. """ @@ -50,30 +49,23 @@ class EscposImage(object): @property def width(self): - """ - Width of image in pixels - """ + """Return width of image in pixels.""" width_pixels, _ = self._im.size return width_pixels @property def width_bytes(self): - """ - Width of image if you use 8 pixels per byte and 0-pad at the end. - """ + """Return width of image if you use 8 pixels per byte and 0-pad at the end.""" return (self.width + 7) >> 3 @property def height(self): - """ - Height of image in pixels - """ + """Height of image in pixels.""" _, height_pixels = self._im.size return height_pixels def to_column_format(self, high_density_vertical=True): - """ - Extract slices of an image as equal-sized blobs of column-format data. + """Extract slices of an image as equal-sized blobs of column-format data. :param high_density_vertical: Printed line height in dots """ @@ -90,14 +82,11 @@ class EscposImage(object): left += line_height def to_raster_format(self): - """ - Convert image to raster-format binary - """ + """Convert image to raster-format binary.""" return self._im.tobytes() def split(self, fragment_height): - """ - Split an image into multiple fragments after fragment_height pixels + """Split an image into multiple fragments after fragment_height pixels. :param fragment_height: height of fragment :return: list of PIL objects @@ -114,7 +103,7 @@ class EscposImage(object): return fragments def center(self, max_width): - """In-place image centering + """Center image in place. :param: Maximum width in order to deduce x offset for centering :return: None diff --git a/src/escpos/magicencode.py b/src/escpos/magicencode.py index 7393ad9..cdb2682 100644 --- a/src/escpos/magicencode.py +++ b/src/escpos/magicencode.py @@ -1,6 +1,6 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -""" Magic Encode +"""Magic Encode. This module tries to convert an UTF-8 string to an encoded string for the printer. It uses trial and error in order to guess the right codepage. @@ -24,8 +24,7 @@ from .exceptions import Error class Encoder(object): - """Takes a list of available code spaces. Picks the right one for a - given character. + """Take available code spaces and pick the right one for a given character. Note: To determine the code page, it needs to do the conversion, and thus already knows what the final byte in the target encoding would @@ -41,20 +40,24 @@ class Encoder(object): """ def __init__(self, codepage_map): + """Initialize encoder.""" self.codepages = codepage_map self.available_encodings = set(codepage_map.keys()) self.available_characters = {} self.used_encodings = set() def get_sequence(self, encoding): + """Get a sequence.""" return int(self.codepages[encoding]) def get_encoding_name(self, encoding): - """Given an encoding provided by the user, will return a + """Return a canonical encoding name. + + Given an encoding provided by the user, will return a canonical encoding name; and also validate that the encoding is supported. - TODO: Support encoding aliases: pc437 instead of cp437. + .. todo:: Support encoding aliases: pc437 instead of cp437. """ encoding = CodePages.get_encoding_name(encoding) if encoding not in self.codepages: @@ -68,7 +71,7 @@ class Encoder(object): @staticmethod def _get_codepage_char_list(encoding): - """Get codepage character list + """Get codepage character list. Gets characters 128-255 for a given code page, as an array. @@ -94,7 +97,7 @@ class Encoder(object): raise LookupError("Can't find a known encoding for {}".format(encoding)) def _get_codepage_char_map(self, encoding): - """Get codepage character map + """Get codepage character map. Process an encoding and return a map of UTF-characters to code points in this encoding. @@ -132,7 +135,7 @@ class Encoder(object): @staticmethod def _encode_char(char, charmap, defaultchar): - """Encode a single character with the given encoding map + """Encode a single character with the given encoding map. :param char: char to encode :param charmap: dictionary for mapping characters in this code page @@ -144,7 +147,7 @@ class Encoder(object): return ord(defaultchar) def encode(self, text, encoding, defaultchar="?"): - """Encode text under the given encoding + """Encode text under the given encoding. :param text: Text to encode :param encoding: Encoding name to use (must be defined in capabilities) @@ -161,7 +164,9 @@ class Encoder(object): return (key in self.used_encodings, index) def find_suitable_encoding(self, char): - """The order of our search is a specific one: + """Search in a specific order for a suitable encoding. + + It is the following order: 1. code pages that we already tried before; there is a good chance they might work again, reducing the search space, @@ -186,7 +191,9 @@ class Encoder(object): def split_writable_text(encoder, text, encoding): - """Splits off as many characters from the beginning of text as + """Split up the writable text. + + Splits off as many characters from the beginning of text as are writable with "encoding". Returns a 2-tuple (writable, rest). """ if not encoding: @@ -201,7 +208,9 @@ def split_writable_text(encoder, text, encoding): class MagicEncode(object): - """A helper that helps us to automatically switch to the right + """Help switching to the right code page. + + A helper that helps us to automatically switch to the right code page to encode any given Unicode character. This will consider the printers supported codepages, according @@ -215,7 +224,7 @@ class MagicEncode(object): def __init__( self, driver, encoding=None, disabled=False, defaultsymbol="?", encoder=None ): - """ + """Initialize magic encode. :param driver: :param encoding: If you know the current encoding of the printer @@ -237,7 +246,7 @@ class MagicEncode(object): self.disabled = disabled def force_encoding(self, encoding): - """Sets a fixed encoding. The change is emitted right away. + """Set a fixed encoding. The change is emitted right away. From now one, this buffer will switch the code page anymore. However, it will still keep track of the current code page. @@ -250,7 +259,6 @@ class MagicEncode(object): def write(self, text): """Write the text, automatically switching encodings.""" - if self.disabled: self.write_with_encoding(self.encoding, text) return @@ -279,12 +287,16 @@ class MagicEncode(object): self.write_with_encoding(encoding, to_write) def _handle_character_failed(self, char): - """Called when no codepage was found to render a character.""" + """Write a default symbol. + + Called when no codepage was found to render a character. + """ # Writing the default symbol via write() allows us to avoid # unnecesary codepage switches. self.write(self.defaultsymbol) def write_with_encoding(self, encoding, text): + """Write the text and inject necessary codepage switches.""" if text is not None and type(text) is not six.text_type: raise Error( "The supplied text has to be unicode, but is of type {type}.".format( diff --git a/src/escpos/printer.py b/src/escpos/printer.py index 7d0697f..93eb9aa 100644 --- a/src/escpos/printer.py +++ b/src/escpos/printer.py @@ -1,6 +1,6 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -""" This module contains the implementations of abstract base class :py:class:`Escpos`. +"""This module contains the implementations of abstract base class :py:class:`Escpos`. :author: `Manuel F Martinez `_ and others :organization: Bashlinux and `python-escpos `_ @@ -41,7 +41,7 @@ except ImportError: class Usb(Escpos): - """USB printer + """USB printer. This class describes a printer that natively speaks USB. @@ -63,7 +63,8 @@ class Usb(Escpos): *args, **kwargs ): # noqa: N803 - """ + """Initialize USB printer. + :param idVendor: Vendor ID :param idProduct: Product ID :param usb_args: Optional USB arguments (e.g. custom_match) @@ -123,7 +124,7 @@ class Usb(Escpos): print("Could not set configuration: {0}".format(str(e))) def _raw(self, msg): - """Print any command sent in raw format + """Print any command sent in raw format. :param msg: arbitrary code to be printed :type msg: bytes @@ -131,18 +132,18 @@ class Usb(Escpos): self.device.write(self.out_ep, msg, self.timeout) def _read(self): - """Reads a data buffer and returns it to the caller.""" + """Read a data buffer and return it to the caller.""" return self.device.read(self.in_ep, 16) def close(self): - """Release USB interface""" + """Release USB interface.""" if self.device: usb.util.dispose_resources(self.device) self.device = None class Serial(Escpos): - """Serial printer + """Serial printer. This class describes a printer that is connected by serial interface. @@ -166,7 +167,7 @@ class Serial(Escpos): *args, **kwargs ): - """ + """Initialize serial printer. :param devfile: Device file under dev filesystem :param baudrate: Baud rate for serial transmission @@ -190,7 +191,7 @@ class Serial(Escpos): self.open() def open(self): - """Setup serial port and set is as escpos device""" + """Set up serial port and set is as escpos device.""" if self.device is not None and self.device.is_open: self.close() self.device = serial.Serial( @@ -210,7 +211,7 @@ class Serial(Escpos): print("Unable to open serial printer on: {0}".format(str(self.devfile))) def _raw(self, msg): - """Print any command sent in raw format + """Print any command sent in raw format. :param msg: arbitrary code to be printed :type msg: bytes @@ -218,18 +219,18 @@ class Serial(Escpos): self.device.write(msg) def _read(self): - """Reads a data buffer and returns it to the caller.""" + """Read the data buffer and return it to the caller.""" return self.device.read(16) def close(self): - """Close Serial interface""" + """Close Serial interface.""" if self.device is not None and self.device.is_open: self.device.flush() self.device.close() class Network(Escpos): - """Network printer + """Network printer. This class is used to attach to a networked printer. You can also use this in order to attach to a printer that is forwarded with ``socat``. @@ -252,7 +253,7 @@ class Network(Escpos): """ def __init__(self, host, port=9100, timeout=60, *args, **kwargs): - """ + """Initialize network printer. :param host: Printer's hostname or IP address :param port: Port to write to @@ -265,7 +266,7 @@ class Network(Escpos): self.open() def open(self): - """Open TCP socket with ``socket``-library and set it as escpos device""" + """Open TCP socket with ``socket``-library and set it as escpos device.""" self.device = socket.socket(socket.AF_INET, socket.SOCK_STREAM) self.device.settimeout(self.timeout) self.device.connect((self.host, self.port)) @@ -274,7 +275,7 @@ class Network(Escpos): print("Could not open socket for {0}".format(self.host)) def _raw(self, msg): - """Print any command sent in raw format + """Print any command sent in raw format. :param msg: arbitrary code to be printed :type msg: bytes @@ -282,12 +283,11 @@ class Network(Escpos): self.device.sendall(msg) def _read(self): - """Read data from the TCP socket""" - + """Read data from the TCP socket.""" return self.device.recv(16) def close(self): - """Close TCP connection""" + """Close TCP connection.""" if self.device is not None: try: self.device.shutdown(socket.SHUT_RDWR) @@ -297,7 +297,7 @@ class Network(Escpos): class File(Escpos): - """Generic file printer + """Generic file printer. This class is used for parallel port printer or other printers that are directly attached to the filesystem. Note that you should stay away from using USB-to-Parallel-Adapter since they are unreliable @@ -311,7 +311,7 @@ class File(Escpos): """ def __init__(self, devfile="/dev/usb/lp0", auto_flush=True, *args, **kwargs): - """ + """Initialize file printer with device file. :param devfile: Device file under dev filesystem :param auto_flush: automatically call flush after every call of _raw() @@ -322,18 +322,18 @@ class File(Escpos): self.open() def open(self): - """Open system file""" + """Open system file.""" self.device = open(self.devfile, "wb") if self.device is None: print("Could not open the specified file {0}".format(self.devfile)) def flush(self): - """Flush printing content""" + """Flush printing content.""" self.device.flush() def _raw(self, msg): - """Print any command sent in raw format + """Print any command sent in raw format. :param msg: arbitrary code to be printed :type msg: bytes @@ -343,14 +343,14 @@ class File(Escpos): self.flush() def close(self): - """Close system file""" + """Close system file.""" if self.device is not None: self.device.flush() self.device.close() class Dummy(Escpos): - """Dummy printer + """Dummy printer. This class is used for saving commands to a variable, for use in situations where there is no need to send commands to an actual printer. This includes @@ -364,12 +364,12 @@ class Dummy(Escpos): """ def __init__(self, *args, **kwargs): - """ """ + """Init with empty output list.""" Escpos.__init__(self, *args, **kwargs) self._output_list = [] def _raw(self, msg): - """Print any command sent in raw format + """Print any command sent in raw format. :param msg: arbitrary code to be printed :type msg: bytes @@ -378,11 +378,11 @@ class Dummy(Escpos): @property def output(self): - """Get the data that was sent to this printer""" + """Get the data that was sent to this printer.""" return b"".join(self._output_list) def clear(self): - """Clear the buffer of the printer + """Clear the buffer of the printer. This method can be called if you send the contents to a physical printer and want to use the Dummy printer for new output. @@ -390,13 +390,20 @@ class Dummy(Escpos): del self._output_list[:] def close(self): + """Close not implemented for Dummy printer.""" pass if _WIN32PRINT: class Win32Raw(Escpos): + """Printer binding for win32 API. + + Uses the module pywin32 for printing. + """ + def __init__(self, printer_name=None, *args, **kwargs): + """Initialize default printer.""" Escpos.__init__(self, *args, **kwargs) if printer_name is not None: self.printer_name = printer_name @@ -406,6 +413,7 @@ if _WIN32PRINT: self.open() def open(self, job_name="python-escpos"): + """Open connection to default printer.""" if self.printer_name is None: raise Exception("Printer not found") self.hPrinter = win32print.OpenPrinter(self.printer_name) @@ -415,6 +423,7 @@ if _WIN32PRINT: win32print.StartPagePrinter(self.hPrinter) def close(self): + """Close connection to default printer.""" if not self.hPrinter: return win32print.EndPagePrinter(self.hPrinter) @@ -449,7 +458,7 @@ if _CUPSPRINT: """ def __init__(self, printer_name=None, *args, **kwargs): - """CupsPrinter class constructor. + """Class constructor for CupsPrinter. :param printer_name: CUPS printer name (Optional) :type printer_name: str @@ -478,7 +487,7 @@ if _CUPSPRINT: return self.conn.getPrinters() def open(self, job_name="python-escpos"): - """Setup a new print job and target printer. + """Set up a new print job and target the printer. A call to this method is required to send new jobs to the same CUPS connection. @@ -492,7 +501,7 @@ if _CUPSPRINT: self.tmpfile = tempfile.NamedTemporaryFile(delete=True) def _raw(self, msg): - """Append any command sent in raw format to temporary file + """Append any command sent in raw format to temporary file. :param msg: arbitrary code to be printed :type msg: bytes diff --git a/test/test_with_statement.py b/test/test_with_statement.py index 2c0f161..a4f922c 100644 --- a/test/test_with_statement.py +++ b/test/test_with_statement.py @@ -13,8 +13,9 @@ import escpos.printer as printer def test_with_statement(): - """Use with statement""" + """Use with statement + + .. todo:: Extend these tests as they don't really do anything at the moment""" dummy_printer = printer.Dummy() with escpos.EscposIO(dummy_printer) as p: p.writelines("Some text.\n") - # TODO extend these tests as they don't really do anything at the moment