From e595bc21508505fff4566c094f759fa928fcc6f8 Mon Sep 17 00:00:00 2001 From: Patrick Kanzler Date: Thu, 26 Jan 2017 00:23:50 +0100 Subject: [PATCH] doc update methods and printers and use autodoc --- doc/user/methods.rst | 143 +++--------------------------------------- doc/user/printers.rst | 89 ++++++++++++++++---------- src/escpos/printer.py | 6 +- 3 files changed, 66 insertions(+), 172 deletions(-) diff --git a/doc/user/methods.rst b/doc/user/methods.rst index 09b6df5..5a150ad 100644 --- a/doc/user/methods.rst +++ b/doc/user/methods.rst @@ -1,144 +1,17 @@ ******* Methods ******* - -.. note:: **TODO** Merge this page with the API-description. (Make the API-description more pretty and then - replace this with the API-description.) +:Last Reviewed: 2017-01-25 Escpos class ------------ -Escpos inherits its methods to the printers. The following methods are -defined: +The core part of this libraries API is the Escpos class. +You use it by instantiating a :doc:`printer ` which is a child of Escpos. +The following methods are available: -image("image\_name.ext") -^^^^^^^^^^^^^^^^^^^^^^^^ +.. autoclass:: escpos.escpos.Escpos + :members: + :member-order: bysource + :noindex: -Prints an image. It adjusts the size in order to print it. - -* ``image_name.ext`` is the complete file name and location of any image type (jpg, gif, png, bmp) - -Raises ``ImageSizeError`` exception. - -qr("text") -^^^^^^^^^^ - -Prints a QR code. The size has been adjusted to Version 4, so it can be -enough small to be printed but also enough big to be read by a smart -phone. - -* ``text`` Any text that needs to be QR encoded. It could be a slogan, - salutation, url, etc. - -barcode("code", "barcode\_type", width, height, "position", "font") -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Prints a barcode. - -* ``code`` is an alphanumeric code to be printed as bar code -* ``barcode_type`` must be one of the following type of codes for function type A: - - * UPC-A - * UPC-E - * EAN13 - * EAN8 - * CODE39 - * ITF - * NW7 - - And for function type B: - - * Any type above - * CODE93 - * CODE128 - * GS1-128 - * GS1 DataBar Omnidirectional - * GS1 DataBar Truncated - * GS1 DataBar Limited - * GS1 DataBar Expanded - - -* ``width`` is a numeric value in the range between (1,255) *Default:* 64 -* ``height`` is a numeric value in the range between (2,6) *Default:* 3 -* ``position`` is where to place the code around the bars, could be one of the following values: - - * ABOVE - * BELOW - * BOTH - * OFF > *Default:* BELOW - -* ``font`` is one of the 2 type of fonts, values could be: - - * A - * B > *Default:* A - -* ``function_type`` chooses between ESCPOS function type A or B. A is default, B has more barcode options. Choose which one based upon your printer support and required barcode. - - * A - * B > *Default* A - -* Raises ``BarcodeTypeError``, ``BarcodeSizeError``, ``BarcodeCodeError`` exceptions. - -text("text") -^^^^^^^^^^^^ - -Prints raw text. Raises ``TextError`` exception. - -set("align", "font", "text_type", width, height, invert, smooth, flip) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Set text properties. - -* ``align`` set horizontal position for text, the possible values are: - - * CENTER - * LEFT - * RIGHT > > *Default:* left - -* ``font`` type could be ``A`` or ``B``. *Default:* A -* ``text_type`` type could be ``B`` (Bold), ``U`` (Underline) or ``normal``. *Default:* normal -* ``width`` is a numeric value, 1 is for regular size, and 2 is twice the standard size. *Default*: 1 -* ``height`` is a numeric value, 1 is for regular size and 2 is twice the standard size. *Default*: 1 -* ``invert`` is a boolean value, True enables white on black printing. *Default*: False -* ``smooth`` is a boolean value, True enables text smoothing. *Default*: False -* ``flip`` is a boolean value, True enables upside-down text. *Default*: False - -cut("mode") -^^^^^^^^^^^ - -Cut paper. - -* ``mode`` set a full or partial cut. *Default:* full - -**Partial cut is not implemented in all printers.** - -cashdraw(pin) -^^^^^^^^^^^^^ - -Sends a pulse to the cash drawer on the specified pin. - -* ``pin`` is a numeric value which defines the pin to be used to send the pulse, it could be 2 or 5. Raises ``CashDrawerError()`` - -hw("operation") -^^^^^^^^^^^^^^^ - -Hardware operations. - -* ``operation`` is any of the following options: - - * INIT - * SELECT - * RESET - -control("align") -^^^^^^^^^^^^^^^^ - -Carrier feed and tabs. - -* ``align`` is a string which takes any of the following values: - - * LF *for Line Feed* - * FF *for Form Feed* - * CR *for Carriage Return* - * HT *for Horizontal Tab* - * VT *for Vertical Tab* diff --git a/doc/user/printers.rst b/doc/user/printers.rst index 073aef3..1e3484b 100644 --- a/doc/user/printers.rst +++ b/doc/user/printers.rst @@ -1,56 +1,77 @@ ******** Printers ******** +:Last Reviewed: 2017-01-25 -.. note:: **TODO** Merge this page into the API-description. +As of now there are 5 different type of printer implementations. -There 3 different type of printers: +USB +--- +The USB-class uses pyusb and libusb to communicate with USB-based +printers. Note that this driver is not suited for USB-to-Serial-adapters +and similiar devices, but only for those implementing native USB. -USB(idVendor, idProduct, interface, in\_ep, out\_ep) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. autoclass:: escpos.printer.Usb + :members: + :special-members: + :member-order: bysource + :noindex: -Based on pyusb and libusb-1.0 +Serial +------ +This driver uses pyserial in order to communicate with serial devices. +If you are using an USB-based adapter to connect to the serial port, +then you should also use this driver. +The configuration is often based on DIP-switches that you can set on your +printer. For the hardware-configuration please refer to your printer's manual. -* ``idVendor`` is the Vendor ID -* ``idProduct`` is the Product ID -* ``interface`` is the USB device interface (default = 0) -* ``in_ep`` is the input end point (default = 0x82) -* ``out_ep`` is the output end point (default = 0x01) +.. autoclass:: escpos.printer.Serial + :members: + :special-members: + :member-order: bysource + :noindex: -Serial("devfile", baudrate, bytesize, timeout) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Network +------- -Based on pyserial, default values are based on the defaults set by -DIP\_SWITCH\_1 on the documentation(hardware side). +This driver is based on the socket class. -* ``devfile`` is an alphanumeric device file name under /dev filesystem (default = /ev/ttyS0) -* ``baudrate`` is the Baud rate for serial transmission (default = 9600) -* ``bytesize`` sets the serial buffer size (default = 8) -* ``timeout`` defines Read/Write timeout (default = 1) +.. autoclass:: escpos.printer.Network + :members: + :special-members: + :member-order: bysource + :noindex: -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) - -Troubleshooting: +Troubleshooting +^^^^^^^^^^^^^^^ Problems with a network-attached printer can have numerous causes. Make sure that your device has a proper IP address. 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 + echo "OK\n" | nc IPADDRESS 9100 + # the port number is often 9100 As a last resort try to reset the interface of the printer. This should be described in its manual. -File("file\_name") -^^^^^^^^^^^^^^^^^^ +File +---- +This printer "prints" just into a file-handle. Especially on \*nix-systems this comes very handy. -Printcap printers +.. autoclass:: escpos.printer.File + :members: + :special-members: + :member-order: bysource + :noindex: + +Dummy +----- +The Dummy-printer is mainly for testing- and debugging-purposes. It stores +all of the "output" as raw ESC/POS in a string and returns that. + +.. autoclass:: escpos.printer.Dummy + :members: + :member-order: bysource + :noindex: -* ``file_name`` is the full path to the device file name diff --git a/src/escpos/printer.py b/src/escpos/printer.py index ec936b5..1fe9cf1 100644 --- a/src/escpos/printer.py +++ b/src/escpos/printer.py @@ -182,9 +182,9 @@ class Network(Escpos): def __init__(self, host, port=9100, timeout=60, *args, **kwargs): """ - :param host : Printer's hostname or IP address - :param port : Port to write to - :param timeout : timeout in seconds for the socket-library + :param host: Printer's hostname or IP address + :param port: Port to write to + :param timeout: timeout in seconds for the socket-library """ Escpos.__init__(self, *args, **kwargs) self.host = host