Magic Encode

Module escpos.magicencode

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. The code is based on the encoding-code in py-xml-escpos by @fvdsn.


Patrick Kanzler




Copyright (c) 2016 Patrick Kanzler and Frédéric van der Essen



class escpos.magicencode.Encoder(codepage_map)[source]

Bases: object

Takes a list of available code spaces. Picks 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 be. Nevertheless, the API of this class doesn’t return the byte.

The caller use to do the character conversion itself.

$ python -m timeit -s “{u’ö’:’a’}.get(u’ö’)” 100000000 loops, best of 3: 0.0133 usec per loop

$ python -m timeit -s “u’ö’.encode(‘latin1’)” 100000000 loops, best of 3: 0.0141 usec per loop


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.

can_encode(encoding, char)[source]

Determine if a character is encodeable in the given code page.

  • encoding – The name of the encoding.

  • char – The character to attempt to encode.

encode(text, encoding, defaultchar='?')[source]

Encode text under the given encoding

  • text – Text to encode

  • encoding – Encoding name to use (must be defined in capabilities)

  • defaultchar – Fallback for non-encodable characters


The order of our search is a specific one:

  1. code pages that we already tried before; there is a good chance they might work again, reducing the search space, and by re-using already used encodings we might also reduce the number of codepage change instructiosn we have to send. Still, any performance gains will presumably be fairly minor.

  2. code pages in lower ESCPOS slots first. Presumably, they are more likely to be supported, so if a printer profile is missing or incomplete, we might increase our change that the code page we pick for this character is actually supported.

escpos.magicencode.split_writable_text(encoder, text, encoding)[source]

Splits off as many characters from the begnning of text as are writable with “encoding”. Returns a 2-tuple (writable, rest).

class escpos.magicencode.MagicEncode(driver, encoding=None, disabled=False, defaultsymbol='?', encoder=None)[source]

Bases: object

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 to the printer profile, and if a character cannot be encoded with the current profile, it will attempt to find a suitable one.

If the printer does not support a suitable code page, it can insert an error character.


Sets 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.


Write the text, automatically switching encodings.

write_with_encoding(encoding, text)[source]