Merge branch 'master' of github.com:python-escpos/python-escpos

v2.1.3

.travis.yml

@@ -34,3 +34,7 @@ before_install:
 script:
     - tox
     - codecov
+notifications:
+  email:
+    on_success: never
+    on_failure: change

CHANGELOG.rst

@@ -1,6 +1,31 @@
 *********
 Changelog
 *********
+2016-08-10 - Version 2.1.3 - "Ethics Gradient"
+----------------------------------------------
+
+changes
+^^^^^^^
+- configure readthedocs and travis
+- update doc with hint on image preprocessing
+- add fix for printing large images (by splitting them into multiple images)
+
+contributors
+^^^^^^^^^^^^
+- Patrick Kanzler
+
+2016-08-02 - Version 2.1.2 - "Death and Gravity"
+------------------------------------------------
+
+changes
+^^^^^^^
+- fix File-printer: flush after every call of _raw()
+- fix lists in documentation
+- fix CODE128: by adding the control character to the barcode-selection-sequence the barcode became unusable
+
+contributors
+^^^^^^^^^^^^
+- Patrick Kanzler
 
 2016-08-02 - Version 2.1.1 - "Contents May Differ"
 --------------------------------------------------

doc/index.rst

@@ -18,6 +18,7 @@ Content
    user/raspi
    user/todo
    user/usage
+   user/barcode
 
 .. toctree::
    :maxdepth: 1

doc/user/barcode.rst

@@ -0,0 +1,34 @@
+Printing Barcodes
+-----------------
+:Last Reviewed: 2016-07-31
+
+Most ESC/POS-printers implement barcode-printing.
+The barcode-commandset is implemented in the barcode-method.
+For a list of compatible barcodes you should check the manual of your printer.
+As a rule of thumb: even older Epson-models support most 1D-barcodes.
+To be sure just try some implementations and have a look at the notices below.
+
+barcode-method
+~~~~~~~~~~~~~~
+The barcode-method is rather low-level and orients itself on the implementation of ESC/POS.
+In the future this class could be supplemented by a high-level class that helps the user generating the payload.
+
+.. py:currentmodule:: escpos.escpos
+
+.. automethod:: Escpos.barcode
+    :noindex:
+
+CODE128
+~~~~~~~
+Code128 barcodes need a certain format.
+For now the user has to make sure that the payload is correct.
+For alphanumeric CODE128 you have to preface your payload with `{B`.
+
+.. code-block:: Python
+
+   from escpos.printer import Dummy, Serial
+   p = Serial()
+   # print CODE128 012ABCDabcd
+   p.barcode("{B012ABCDabcd", "CODE128", function_type="B")
+
+A very good description on CODE128 is also on `Wikipedia <https://en.wikipedia.org/wiki/Code_128>`_.

doc/user/methods.rst

@@ -88,6 +88,7 @@ set("align", "font", "type", width, height, invert, smooth, flip)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Set text properties.
+
 * ``align`` set horizontal position for text, the possible values are:
    
   * CENTER
@@ -106,6 +107,7 @@ cut("mode")
 ^^^^^^^^^^^
 
 Cut paper.
+
 * ``mode`` set a full or partial cut. *Default:* full
 
 **Partial cut is not implemented in all printers.**
@@ -132,6 +134,7 @@ control("align")
 ^^^^^^^^^^^^^^^^
 
 Carrier feed and tabs.
+
 * ``align`` is a string which takes any of the following values:
   
   * LF *for Line Feed*

doc/user/printers.rst

@@ -32,6 +32,7 @@ Network("host", port)
 ^^^^^^^^^^^^^^^^^^^^^
 
 Based on socket
+
 * ``host`` is an alphanumeric host name, could be either DNS host name or IP address.
 * ``port`` to write to (default = 9100)
 
@@ -40,7 +41,8 @@ Problems with a network-attached printer can have numerous causes. Make sure tha
 Often you can check the IP address by triggering the self-test of the device. As a next step try to send text
 manually to the device. You could use for example:
 
-::
+.. ::
+
     echo "OK\n" | nc IPADDRESS 9100
     # the port number is often 9100
 
@@ -50,4 +52,5 @@ File("file\_name")
 ^^^^^^^^^^^^^^^^^^
 
 Printcap printers
+
 * ``file_name`` is the full path to the device file name

doc/user/usage.rst

@@ -204,6 +204,37 @@ Here you can download an example, that will print a set of common barcodes:
 
     * :download:`barcode.bin </download/barcode.bin>` by `@mike42 <https://github.com/mike42>`_
 
+Hint: preprocess printing
+-------------------------
+
+Printing images directly to the printer is rather slow.
+One factor that slows down the process is the transmission over e.g. serial port.
+
+Apart from configuring your printer to use the maximum baudrate (in the case of serial-printers), there is not much
+that you can do.
+However you could use the :py:class:`escpos.printer.Dummy`-printer to preprocess your image.
+This is probably best explained by an example:
+
+.. code-block:: Python
+
+   from escpos.printer import Serial, Dummy
+
+   p = Serial()
+   d = Dummy()
+
+   # create ESC/POS for the print job, this should go really fast
+   d.text("This is my image:\n")
+   d.image("funny_cat.png")
+   d.cut()
+
+   # send code to printer
+   p._raw(d.output)
+
+This way you could also store the code in a file and print later.
+You could then for example print the code from another process than your main-program and thus reduce the waiting time.
+(Of course this will not make the printer print faster.)
+
+
 How to update your code for USB printers
 ----------------------------------------
 

readthedocs.yml

@@ -0,0 +1,7 @@
+formats:
+  - pdf
+  - epub
+requirements_file: doc/requirements.txt
+python:
+  version: 2
+  setup_py_install: true

src/escpos/constants.py

@@ -168,10 +168,7 @@ BARCODE_TYPE_B = {
     'NW7':                         _SET_BARCODE_TYPE(71),
     'CODABAR':                     _SET_BARCODE_TYPE(71),  # Same as NW7
     'CODE93':                      _SET_BARCODE_TYPE(72),
-    # These are all the same barcode, but using different charcter sets
-    'CODE128A':                    _SET_BARCODE_TYPE(73) + b'{A',  # CODE128 character set A
-    'CODE128B':                    _SET_BARCODE_TYPE(73) + b'{B',  # CODE128 character set B
-    'CODE128C':                    _SET_BARCODE_TYPE(73) + b'{C',  # CODE128 character set C
+    'CODE128':                     _SET_BARCODE_TYPE(73),
     'GS1-128':                     _SET_BARCODE_TYPE(74),
     'GS1 DATABAR OMNIDIRECTIONAL': _SET_BARCODE_TYPE(75),
     'GS1 DATABAR TRUNCATED':       _SET_BARCODE_TYPE(76),

src/escpos/escpos.py

@@ -56,7 +56,8 @@ class Escpos(object):
         """
         pass
 
-    def image(self, img_source, high_density_vertical=True, high_density_horizontal=True, impl="bitImageRaster"):
+    def image(self, img_source, high_density_vertical=True, high_density_horizontal=True, impl="bitImageRaster",
+              fragment_height=1024):
         """ Print an image
 
         You can select whether the printer should print in high density or not. The default value is high density.
@@ -76,9 +77,20 @@ class Escpos(object):
         :param high_density_vertical: print in high density in vertical direction *default:* True
         :param high_density_horizontal: print in high density in horizontal direction *default:* True
         :param impl: choose image printing mode between `bitImageRaster`, `graphics` or `bitImageColumn`
+        :param fragment_height: Images larger than this will be split into multiple fragments *default:* 1024
 
         """       
         im = EscposImage(img_source)
+
+        if im.height > fragment_height:
+            fragments = im.split(fragment_height)
+            for fragment in fragments:
+                self.image(fragment,
+                           high_density_vertical=high_density_vertical,
+                           high_density_horizontal=high_density_horizontal,
+                           impl=impl,
+                           fragment_height=fragment_height)
+            return
         
         if impl == "bitImageRaster":
             # GS v 0, raster format bit image

src/escpos/image.py

@@ -8,6 +8,12 @@ This module contains the image format handler :py:class:`EscposImage`.
 :license: GNU GPL v3
 """
 
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+from __future__ import unicode_literals
+
+import math
 from PIL import Image, ImageOps
 
 
@@ -30,6 +36,9 @@ class EscposImage(object):
         else:
             img_original = Image.open(img_source)
 
+        # store image for eventual further processing (splitting)
+        self.img_original = img_original
+
         # Convert to white RGB background, paste over white background
         # to strip alpha.
         img_original = img_original.convert('RGBA')
@@ -88,3 +97,21 @@ class EscposImage(object):
         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
+
+        :param fragment_height: height of fragment
+        :return: list of PIL objects
+        """
+        passes = int(math.ceil(self.height/fragment_height))
+        fragments = []
+        for n in range(0, passes):
+            left = 0
+            right = self.width
+            upper = n * fragment_height
+            lower = min((n + 1) * fragment_height, self.height)
+            box = (left, upper, right, lower)
+            fragments.append(self.img_original.crop(box))
+        return fragments

src/escpos/printer.py

@@ -229,13 +229,15 @@ class File(Escpos):
 
     """
 
-    def __init__(self, devfile="/dev/usb/lp0", *args, **kwargs):
+    def __init__(self, devfile="/dev/usb/lp0", auto_flush=True, *args, **kwargs):
         """
 
         :param devfile : Device file under dev filesystem
+        :param auto_flush: automatically call flush after every call of _raw()
         """
         Escpos.__init__(self, *args, **kwargs)
         self.devfile = devfile
+        self.auto_flush = auto_flush
         self.open()
 
     def open(self):
@@ -256,6 +258,8 @@ class File(Escpos):
         :type msg: bytes
         """
         self.device.write(msg)
+        if self.auto_flush:
+            self.flush()
 
     def close(self):
         """ Close system file """

test/test_function_image.py

@@ -130,3 +130,12 @@ def test_graphics_transparent():
     instance = printer.Dummy()
     instance.image('test/resources/black_transparent.png', impl="graphics")
     assert(instance.output == b'\x1d(L\x0c\x000p0\x01\x011\x02\x00\x02\x00\xc0\x00\x1d(L\x02\x0002')
+
+
+def test_large_graphics():
+    """
+    Test whether 'large' graphics that induce a fragmentation are handled correctly.
+    """
+    instance = printer.Dummy()
+    instance.image('test/resources/black_white.png', impl="bitImageRaster", fragment_height=1)
+    assert(instance.output == b'\x1dv0\x00\x01\x00\x01\x00\xc0\x1dv0\x00\x01\x00\x01\x00\x00')

test/test_image.py

@@ -43,6 +43,20 @@ def test_image_white():
         _load_and_check_img('canvas_white.' + img_format, 1, 1, b'\x00', [b'\x00'])
 
 
+def test_split():
+    """
+    test whether the split-function works as expected
+    """
+    im = EscposImage('test/resources/black_white.png')
+    (upper_part, lower_part) = im.split(1)
+    upper_part = EscposImage(upper_part)
+    lower_part = EscposImage(lower_part)
+    assert(upper_part.width == lower_part.width == 2)
+    assert(upper_part.height == lower_part.height == 1)
+    assert(upper_part.to_raster_format() == b'\xc0')
+    assert(lower_part.to_raster_format() == b'\x00')
+
+
 def _load_and_check_img(filename, width_expected, height_expected, raster_format_expected, column_format_expected):
     """
     Load an image, and test whether raster & column formatted output, sizes, etc match expectations.

test/test_printer_file.py

@@ -0,0 +1,70 @@
+#!/usr/bin/python
+#  -*- coding: utf-8 -*-
+"""tests for the File printer
+
+:author: `Patrick Kanzler <patrick.kanzler@fablab.fau.de>`_
+:organization: `python-escpos <https://github.com/python-escpos>`_
+:copyright: Copyright (c) 2016 `python-escpos <https://github.com/python-escpos>`_
+:license: GNU GPL v3
+"""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+from __future__ import unicode_literals
+
+import six
+
+import mock
+from hypothesis import given
+from hypothesis.strategies import text
+
+import escpos.printer as printer
+
+if six.PY3:
+    mock_open_call = 'builtins.open'
+else:
+    mock_open_call = '__builtin__.open'
+
+@given(path=text())
+@mock.patch(mock_open_call)
+@mock.patch('escpos.escpos.Escpos.__init__')
+def test_load_file_printer(mock_escpos, mock_open, path):
+    """test the loading of the file-printer"""
+    printer.File(devfile=path)
+    assert mock_escpos.called
+    mock_open.assert_called_with(path, "wb")
+
+
+@given(txt=text())
+@mock.patch.object(printer.File, 'device')
+@mock.patch(mock_open_call)
+@mock.patch('escpos.escpos.Escpos.__init__')
+def test_auto_flush(mock_escpos, mock_open, mock_device, txt):
+    """test auto_flush in file-printer"""
+    p = printer.File(auto_flush=False)
+    # inject the mocked device-object
+    p.device = mock_device
+    p._raw(txt)
+    assert not mock_device.flush.called
+    mock_device.reset_mock()
+    p = printer.File(auto_flush=True)
+    # inject the mocked device-object
+    p.device = mock_device
+    p._raw(txt)
+    assert mock_device.flush.called
+
+
+@given(txt=text())
+@mock.patch.object(printer.File, 'device')
+@mock.patch(mock_open_call)
+def test_flush_on_close(mock_open, mock_device, txt):
+    """test flush on close in file-printer"""
+    p = printer.File(auto_flush=False)
+    # inject the mocked device-object
+    p.device = mock_device
+    p._raw(txt)
+    assert not mock_device.flush.called
+    p.close()
+    assert mock_device.flush.called
+    assert mock_device.close.called