Esc/Pos
Module escpos.escpos
Main class.
This module contains the abstract base class Escpos
.
- author:
python-escpos developers
- organization:
Bashlinux and python-escpos
- copyright:
Copyright (c) 2012-2017 Bashlinux and python-escpos
- license:
MIT
- class escpos.escpos.Escpos(profile=None, magic_encode_args=None, **kwargs)[source]
Bases:
object
ESC/POS Printer object.
This class is the abstract base class for an Esc/Pos-printer. The printer implementations are children of this class.
- property device: Literal[None] | object
Implements a self-open mechanism.
An attempt to get the property before open the connection will cause the connection to open.
- set_sleep_in_fragment(sleep_time_ms)[source]
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.
- Parameters:
sleep_time_ms (
int
) – sleep time in milliseconds- Return type:
None
- image(img_source, high_density_vertical=True, high_density_horizontal=True, impl='bitImageRaster', fragment_height=960, center=False)[source]
Print an image.
You can select whether the printer should print in high density or not. The default value is high density. When printing in low density, the image will be stretched.
Esc/Pos supplies several commands for printing. This function supports three of them. Please try to vary the implementations if you have any problems. For example the printer IT80-002 will have trouble aligning images that are not printed in Column-mode.
The available printing implementations are:
bitImageRaster: prints with the GS v 0-command
graphics: prints with the GS ( L-command
bitImageColumn: prints with the ESC *-command
When trying to center an image make sure you have initialized the printer with a valid profile, that contains a media width pixel field. Otherwise the centering will have no effect.
- Parameters:
img_source – PIL image or filename to load: jpg, gif, png or bmp
high_density_vertical (
bool
) – print in high density in vertical direction default: Truehigh_density_horizontal (
bool
) – print in high density in horizontal direction default: Trueimpl (
str
) – choose image printing mode between bitImageRaster, graphics or bitImageColumnfragment_height (
int
) – Images larger than this will be split into multiple fragments default: 960center (
bool
) – Center image horizontally default: False
- Return type:
None
- qr(content, ec=0, size=3, model=2, native=False, center=False, impl=None, image_arguments=None)[source]
Print QR Code for the provided string.
- Parameters:
content – The content of the code. Numeric data will be more efficiently compacted.
ec – Error-correction level to use. One of QR_ECLEVEL_L (default), QR_ECLEVEL_M, QR_ECLEVEL_Q or QR_ECLEVEL_H. Higher error correction results in a less compact code.
size – Pixel size to use. Must be 1-16 (default 3)
model – QR code model to use. Must be one of QR_MODEL_1, QR_MODEL_2 (default) or QR_MICRO (not supported by all printers).
native – True to render the code on the printer, False to render the code as an image and send it to the printer (Default)
center – Centers the code default: False
impl – Image-printing-implementation, refer to
image()
for detailsimage_arguments (
Optional
[dict
]) – arguments passed toimage()
. Replaces impl and center. If impl or center are set, they will overwrite image_arguments.
- Return type:
None
- charcode(code='AUTO')[source]
Set Character Code Table.
Sets the control sequence from
CHARCODE
inescpos.constants
as active. It will be sent with the next text sequence. If you set the variable code toAUTO
it will try to automatically guess the right code page. (This is the standard behavior.)- Parameters:
code (
str
) – Name of CharCode- Raises:
- Return type:
None
- static check_barcode(bc, code)[source]
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.
As an example, using EAN13, the barcode 12345678901 will be correct, because it can be rendered by the printer. But it does not suit the EAN13 standard, because the checksum digit is missing. Adding a wrong checksum in the end will also be considered correct, but adding a letter won’t (EAN13 is numeric only).
Todo
Add a method to compute the checksum for the different standards
Todo
For fixed-length standards with mandatory checksum (EAN, UPC), compute and add the checksum automatically if missing.
- barcode(code, bc, height=64, width=3, pos='BELOW', font='A', align_ct=True, function_type=None, check=True, force_software=False)[source]
Print barcode.
Automatic hardware|software barcode renderer according to the printer capabilities.
Defaults to hardware barcode and its format types if supported. Automatically switches to software barcode renderer if hardware does not support a barcode type that is supported by software. (e.g. JAN, ISSN, etc.).
Set force_software=True to force the software renderer according to the profile. Set force_software=graphics|bitImageColumn|bitImageRaster to specify a renderer.
Ignores caps, special chars and whitespaces in barcode type names. So “EAN13”, “ean-13”, “Ean_13”, “EAN 13” are all accepted.
- Parameters:
code – alphanumeric data to be printed as bar code (payload).
bc – barcode format type (EAN13, CODE128, JAN, etc.).
height (
int
) – barcode module height (in printer dots), has to be between 1 and 255. default: 64width (
int
) – barcode module width (in printer dots), has to be between 2 and 6. default: 3pos (
str
) – text position (ABOVE, BELOW, BOTH, OFF) relative to the barcode (ignored in software renderer). default: BELOWfont (
str
) – select font A or B (ignored in software renderer). default: Aalign_ct (
bool
) – If True, center the barcode. default: Truefunction_type – ESCPOS function type A or B. None to guess it from profile (ignored in software renderer). default: None
check (
bool
) – If True, checks that the code meets the requirements of the barcode type. default: Trueforce_software (
Union
[bool
,str
]) – If True, force the use of software barcode renderer from profile. If “graphics”, “bitImageColumn” or “bitImageRaster”, force the use of specific renderer.
- Raises:
- Return type:
None
Note
- Get all supported formats at:
Hardware:
BARCODE_FORMATS
Software: Python barcode documentation
- text(txt)[source]
Print alpha-numeric text.
The text has to be encoded in the currently selected code page. The input text has to be encoded in Unicode.
- Parameters:
txt (
str
) – text to be printed- Raises:
- Return type:
None
- textln(txt='')[source]
Print alpha-numeric text with a newline.
The text has to be encoded in the currently selected code page. The input text has to be encoded in Unicode.
- Parameters:
txt (
str
) – text to be printed with a newline- Raises:
- Return type:
None
- ln(count=1)[source]
Print a newline or more.
- Parameters:
count (
int
) – number of newlines to print- Raises:
ValueError
if count < 0- Return type:
None
- block_text(txt, font='0', columns=None)[source]
Print text wrapped to specific columns.
Text has to be encoded in Unicode.
- Parameters:
txt – text to be printed
font – font to be used, can be
a
orb
columns – amount of columns
- Return type:
None
- Returns:
None
- software_columns(text_list, widths, align)[source]
Print a list of strings arranged horizontally in columns.
- Parameters:
text_list (
list
) – list of strings, each item in the list will be printed as a column.widths (
Union
[list
[int
],int
]) – 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).align (
Union
[list
[Union
[Literal
['center'
,'left'
,'right'
],str
]],Literal
['center'
,'left'
,'right'
],str
]) – 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).
- Return type:
None
- set(align=None, font=None, bold=None, underline=None, width=None, height=None, density=None, invert=None, smooth=None, flip=None, normal_textsize=None, double_width=None, double_height=None, custom_size=None)[source]
Set text properties by sending them to the printer.
If a value for a parameter is not supplied, nothing is sent for this type of format.
- Parameters:
align (
Optional
[str
]) –horizontal position for text, possible values are:
’center’
’left’
’right’
font (
Optional
[str
]) – font given as an index, a name, or one of the special values ‘a’ or ‘b’, referring to fonts 0 and 1.bold (
Optional
[bool
]) – text in boldunderline (
Optional
[int
]) – underline mode for text, decimal range 0-2normal_textsize (
Optional
[bool
]) – switch to normal text size if Truedouble_height (
Optional
[bool
]) – doubles the height of the textdouble_width (
Optional
[bool
]) – doubles the width of the textcustom_size (
Optional
[bool
]) – uses custom size specified by width and height parameters. Cannot be used with double_width or double_height.width (
Optional
[int
]) – requires custom_size=True, text width multiplier when custom_size is used, decimal range 1-8height (
Optional
[int
]) – requires custom_size=True, text height multiplier when custom_size is used, decimal range 1-8density (
Optional
[int
]) – print density, value from 0-8, if something else is supplied the density remains unchangedinvert (
Optional
[bool
]) – True enables white on black printingsmooth (
Optional
[bool
]) – True enables text smoothing. Effective on 4x4 size text and largerflip (
Optional
[bool
]) – True enables upside-down printing
- Return type:
None
- set_with_default(align='left', font='a', bold=False, underline=0, width=1, height=1, density=9, invert=False, smooth=False, flip=False, double_width=False, double_height=False, custom_size=False)[source]
Set default text properties by sending them to the printer.
This function has the behavior of the set()-method from before version 3. If a parameter to this method is not supplied, a default value will be sent. Otherwise this method forwards the values to the
escpos.Escpos.set()
.- Parameters:
align (
Optional
[str
]) –horizontal position for text, possible values are:
’center’
’left’
’right’
default: ‘left’
font (
Optional
[str
]) – font given as an index, a name, or one of the special values ‘a’ or ‘b’, referring to fonts 0 and 1.bold (
Optional
[bool
]) – text in bold, default: Falseunderline (
Optional
[int
]) – underline mode for text, decimal range 0-2, default: 0double_height (
Optional
[bool
]) – doubles the height of the textdouble_width (
Optional
[bool
]) – doubles the width of the textcustom_size (
Optional
[bool
]) – uses custom size specified by width and height parameters. Cannot be used with double_width or double_height.width (
Optional
[int
]) – text width multiplier when custom_size is used, decimal range 1-8, default: 1height (
Optional
[int
]) – text height multiplier when custom_size is used, decimal range 1-8, default: 1density (
Optional
[int
]) – print density, value from 0-8, if something else is supplied the density remains unchangedinvert (
Optional
[bool
]) – True enables white on black printing, default: Falsesmooth (
Optional
[bool
]) – True enables text smoothing. Effective on 4x4 size text and larger, default: Falseflip (
Optional
[bool
]) – True enables upside-down printing, default: False
- Return type:
None
- line_spacing(spacing=None, divisor=180)[source]
Set line character spacing.
If no spacing is given, we reset it to the default.
There are different commands for setting the line spacing, using a different denominator:
‘+’’ line_spacing/360 of an inch, 0 <= line_spacing <= 255 ‘3’ line_spacing/180 of an inch, 0 <= line_spacing <= 255 ‘A’ line_spacing/60 of an inch, 0 <= line_spacing <= 85
Some printers may not support all of them. The most commonly available command (using a divisor of 180) is chosen.
- Return type:
None
- cut(mode='FULL', feed=True)[source]
Cut paper.
Without any arguments the paper will be cut completely. With ‘mode=PART’ a partial cut will be attempted. Note however, that not all models can do a partial cut. See the documentation of your printer for details.
- Parameters:
mode (
str
) – set to ‘PART’ for a partial cut. default: ‘FULL’feed (
bool
) – print and feed before cutting. default: true
- Raises:
ValueError – if mode not in (‘FULL’, ‘PART’)
- Return type:
None
- cashdraw(pin)[source]
Send pulse to kick the cash drawer.
Kick cash drawer on pin 2 (
CD_KICK_2
) or pin 5 (CD_KICK_5
) according to the default parameters. For non default parameters send a decimal sequence i.e. [27,112,48] or [27,112,0,25,255].- Parameters:
pin – pin number, 2 or 5 or list of decimals
- Raises:
- Return type:
None
- linedisplay_select(select_display=False)[source]
Select the line display or the printer.
This method is used for line displays that are daisy-chained between your computer and printer. If you set select_display to true, only the display is selected and if you set it to false, only the printer is selected.
- Parameters:
select_display (
bool
) – whether the display should be selected or the printer- Return type:
None
- linedisplay_clear()[source]
Clear the line display and resets the .
This method is used for line displays that are daisy-chained between your computer and printer.
- Return type:
None
- linedisplay(text)[source]
Display text on a line display connected to your printer.
You should connect a line display to your printer. You can do this by daisy-chaining the display between your computer and printer.
- Parameters:
text (
str
) – Text to display- Return type:
None
- hw(hw)[source]
Hardware operations.
- Parameters:
hw (
str
) –hardware action, may be:
INIT
SELECT
RESET
- Return type:
None
- print_and_feed(n=1)[source]
Print data in print buffer and feed n lines.
If n not in range (0, 255) then a ValueError will be raised.
- Parameters:
n (
int
) – number of n to feed. 0 <= n <= 255. default: 1- Raises:
ValueError – if not 0 <= n <= 255
- Return type:
None
- control(ctl, count=5, tab_size=8)[source]
Feed control sequences.
- Parameters:
ctl (
str
) –string for the following control sequences:
LF for Line Feed
FF for Form Feed
CR for Carriage Return
HT for Horizontal Tab
VT for Vertical Tab
count (
int
) – integer between 1 and 32, controls the horizontal tab count. Defaults to 5.tab_size (
int
) – integer between 1 and 255, controls the horizontal tab size in characters. Defaults to 8
- Raises:
- Return type:
None
- panel_buttons(enable=True)[source]
Control the panel buttons on the printer (e.g. FEED).
When enable is set to False the panel buttons on the printer will be disabled. Calling the method with enable=True or without argument will enable the panel buttons.
If panel buttons are enabled, the function of the panel button, such as feeding, will be executed upon pressing the button. If the panel buttons are disabled, pressing them will not have any effect.
This command is effective until the printer is initialized, resetted or power-cycled. The default is enabled panel buttons.
Some panel buttons will always work, especially when the printer is opened. See for more information the manual of your printer and the escpos-command-reference.
- Parameters:
enable (
bool
) – controls the panel buttons- Return type:
None
- query_status(mode)[source]
Query the printer for its status.
Returns byte array containing it.
- Parameters:
mode (
bytes
) – Integer that sets the status mode queried to the printer. - RT_STATUS_ONLINE: Printer status. - RT_STATUS_PAPER: Paper sensor.- Return type:
bytes
- is_online()[source]
Query the online status of the printer.
- Return type:
bool
- Returns:
When online, returns
True
;False
otherwise.
- paper_status()[source]
Query the paper status of the printer.
Returns 2 if there is plenty of paper, 1 if the paper has arrived to the near-end sensor and 0 if there is no paper.
- Return type:
int
- Returns:
2: Paper is adequate. 1: Paper ending. 0: No paper.
- target(type='ROLL')[source]
Select where to print to.
Print to the thermal printer by default (ROLL) or print to the slip dot matrix printer if supported (SLIP)
- Return type:
None
- print_and_eject_slip()[source]
Print and eject.
Prints data from the buffer to the slip station and if the paper sensor is covered, reverses the slip out the front of the printer far enough to be accessible to the operator. The impact station opens the platen in all cases.
- Return type:
None
- use_slip_only()[source]
Select the Slip Station for all functions.
The receipt station is the default setting after the printer is initialized or the Clear Printer (0x10) command is received
- Return type:
None
- buzzer(times=2, duration=4)[source]
Activate the internal printer buzzer on supported printers.
The ‘times’ parameter refers to the ‘n’ escpos command parameter, which means how many times the buzzer will be ‘beeped’.
- Parameters:
times (
int
) – Integer between 1 and 9, indicates the buzzer beeps.duration (
int
) – Integer between 1 and 9, indicates the beep duration.
- Return type:
None
- Returns:
None
- class escpos.escpos.EscposIO(printer, autocut=True, autoclose=True, **kwargs)[source]
Bases:
object
ESC/POS Printer IO object.
Allows the class to be used together with the with-statement. You have to define a printer instance and assign it to the EscposIO class. This example explains the usage:
with EscposIO(printer.Serial('/dev/ttyUSB0')) as p: p.set(font='a', height=2, align='center', text_type='bold') p.printer.set(align='left') p.printer.image('logo.gif') p.writelines('Big line\\n', font='b') p.writelines('Привет') p.writelines('BIG TEXT', width=2)
After the with-statement the printer automatically cuts the paper if autocut is True.
- set(**kwargs)[source]
Set the printer-parameters.
Controls which parameters will be passed to
Escpos.set()
. For more information on the parameters see theset()
-methods documentation. These parameters can also be passed with this class’ constructor or thewritelines()
-method.- Parameters:
kwargs – keyword-parameters that will be passed to
Escpos.set()
- Return type:
None