Segno’s low level API

segno.make(), segno.make_qr(), and segno.make_micro() return a segno.QRCode which implements almost no logic but uses the result of segno.encoder.encode() glued together with the functionality of segno.writers to provide a simple (supposed to be user-friendly) API.

A completely different API is possible by utilizing segno.encoder.encode() which returns just a tuple: (matrix, version, error, mask, segments). The module segno.writers is independent of the segno.encoder module and vice versa.

segno.encoder

QR Code and Micro QR Code encoder.

“QR Code” and “Micro QR Code” are registered trademarks of DENSO WAVE INCORPORATED.

exception segno.encoder.QRCodeError

Generic QR Code error.

exception segno.encoder.VersionError

Indicates errors related to the QR Code version.

exception segno.encoder.ModeError

Indicates errors related to QR Code mode.

exception segno.encoder.ErrorLevelError

Indicates errors related to QR Code error correction level.

exception segno.encoder.MaskError

Indicates errors related to QR Code data mask.

exception segno.encoder.DataOverflowError

Indicates a problem that the provided data does not fit into the provided QR Code version or the data is too large in general.

segno.encoder.encode(content, error=None, version=None, mode=None, mask=None, encoding=None, eci=False, micro=None, boost_error=True)

Creates a (Micro) QR Code.

See segno.make() for a detailed description of the parameters.

Contrary to make this function returns a named tuple: (matrix, version, error, mask, segments)

Note that version is always an integer referring to the values of the segno.consts constants. error is None iff a M1 QR Code was generated, otherwise it is always an integer.

Return type:namedtuple
segno.encoder.encode_sequence(content, error=None, version=None, mode=None, mask=None, encoding=None, eci=False, boost_error=True, symbol_count=None)

EXPERIMENTAL: Creates a sequence of QR Codes in Structured Append mode.

Returns:Iterable of named tuples, see encode() for details.

segno.writers

Standard serializers and utility functions for serializers.

The serializers are independent of the segno.QRCode (and the segno.encoder.Code) class; they just need a matrix (tuple of bytearrays) and the version constant.

segno.writers.as_png_data_uri(matrix, version, scale=1, border=None, color=u'#000', background=u'#fff', compresslevel=9, addad=True)

Converts the provided matrix into a PNG data URI.

Return type:str
segno.writers.as_svg_data_uri(matrix, version, scale=1, border=None, color=u'#000', background=None, xmldecl=False, svgns=True, title=None, desc=None, svgid=None, svgclass=u'segno', lineclass=u'qrline', omitsize=False, unit=u'', encoding=u'utf-8', svgversion=None, nl=False, encode_minimal=False, omit_charset=False)

Converts the matrix to a SVG data URI.

The XML declaration is omitted by default (set xmldecl to True to enable it), further the newline is omitted by default (set nl to True to enable it).

Aside from the missing out parameter and the different xmldecl and nl default values and the additional parameter encode_minimal and omit_charset this function uses the same parameters as the usual SVG serializer.

Parameters:
  • encode_minimal (bool) – Indicates if the resulting data URI should use minimal percent encoding (disabled by default).
  • omit_charset (bool) – Indicates if the ;charset=... should be omitted (disabled by default)
Return type:

str

segno.writers.save(matrix, version, out, kind=None, **kw)

Serializes the matrix in any of the supported formats.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • out – A filename or a writable file-like object with a name attribute. If a stream like io.ByteIO or io.StringIO object without a name attribute is provided, use the kind parameter to specify the serialization format.
  • kind – If the desired output format cannot be extracted from the filename, this parameter can be used to indicate the serialization format (i.e. “svg” to enforce SVG output)
  • kw – Any of the supported keywords by the specific serialization method.
segno.writers.writable(*args, **kwds)

Returns a writable file-like object.

Usage:

with writable(file_name_or_path, 'wb') as f:
    ...
Parameters:
  • file_or_path – Either a file-like object or a filename.
  • mode (str) – String indicating the writing mode (i.e. 'wb')
segno.writers.write_eps(matrix, version, out, scale=1, border=None, color=u'#000', background=None)

Serializes the QR Code as EPS document.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • out – Filename or a file-like object supporting to write strings.
  • scale – Indicates the size of a single module (default: 1 which corresponds to 1 point (1/72 inch) per module).
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
  • color – Color of the modules (default: black). The color can be provided as (R, G, B) tuple (this method acceppts floats as R, G, B values), as web color name (like “red”) or in hexadecimal format (#RGB or #RRGGBB).
  • background – Optional background color (default: None = no background color). See color for valid values.
segno.writers.write_pam(matrix, version, out, scale=1, border=None, color=u'#000', background=u'#fff')

Serializes the matrix as PAM image.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • out – Filename or a file-like object supporting to write binary data.
  • scale – Indicates the size of a single module (default: 1 which corresponds to 1 x 1 pixel per module).
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
  • color – Color of the modules (default: black). The color can be provided as (R, G, B) tuple, as web color name (like “red”) or in hexadecimal format (#RGB or #RRGGBB).
  • background – Optional background color (default: white). See color for valid values. In addition, None is accepted which indicates a transparent background.
segno.writers.write_pbm(matrix, version, out, scale=1, border=None, plain=False)

Serializes the matrix as PBM image.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • out – Filename or a file-like object supporting to write binary data.
  • scale – Indicates the size of a single module (default: 1 which corresponds to 1 x 1 pixel per module).
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
  • plain (bool) – Indicates if a P1 (ASCII encoding) image should be created (default: False). By default a (binary) P4 image is created.
segno.writers.write_pdf(matrix, version, out, scale=1, border=None, compresslevel=9)

Serializes the QR Code as PDF document.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • out – Filename or a file-like object supporting to write bytes.
  • scale – Indicates the size of a single module (default: 1 which corresponds to 1 x 1 pixel per module).
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
  • compresslevel (int) – Integer indicating the compression level (default: 9). 1 is fastest and produces the least compression, 9 is slowest and produces the most. 0 is no compression.
segno.writers.write_png(matrix, version, out, scale=1, border=None, color=u'#000', background=u'#fff', compresslevel=9, dpi=None, addad=True)

Serializes the QR Code as PNG image.

By default, the generated PNG will be a greyscale image with a bitdepth of 1. If different colors are provided, an indexed-color image with the same bitdepth is generated.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • out – Filename or a file-like object supporting to write bytes.
  • scale – Indicates the size of a single module (default: 1 which corresponds to 1 x 1 pixel per module).
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
  • color – Color of the modules (default: black). The color can be provided as (R, G, B) tuple, as web color name (like “red”) or in hexadecimal format (#RGB or #RRGGBB).
  • background – Optional background color (default: white). See color for valid values. In addition, None is accepted which indicates a transparent background.
  • dpi (int) – Optional DPI setting. By default (None), the PNG won’t have any DPI information. Note that the DPI value is converted into meters since PNG does not support any DPI information.
  • compresslevel (int) – Integer indicating the compression level (default: 9). 1 is fastest and produces the least compression, 9 is slowest and produces the most. 0 is no compression.
segno.writers.write_svg(matrix, version, out, scale=1, border=None, color=u'#000', background=None, xmldecl=True, svgns=True, title=None, desc=None, svgid=None, svgclass=u'segno', lineclass=u'qrline', omitsize=False, unit=None, encoding=u'utf-8', svgversion=None, nl=True)

Serializes the QR Code as SVG document.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • out – Filename or a file-like object supporting to write bytes.
  • scale – Indicates the size of a single module (default: 1 which corresponds to 1 x 1 pixel per module).
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
  • color – Color of the modules (default: #000). Any value which is supported by SVG can be used. In addition, None is a valid value. The resulting path won’t have a stroke attribute.
  • background – Optional background color (default: None = no background color). See color for valid values.
  • xmldecl (bool) – Inidcates if the XML declaration header should be written (default: True)
  • svgns (bool) – Indicates if the SVG namespace should be written (default: True).
  • title (str) – Optional title of the generated SVG document.
  • desc (str) – Optional description of the generated SVG document.
  • svgid – The ID of the SVG document (if set to None (default), the SVG element won’t have an ID).
  • svgclass – The CSS class of the SVG document (if set to None, the SVG element won’t have a class).
  • lineclass – The CSS class of the path element (which draws the “black” modules (if set to None, the path won’t have a class).
  • omitsize (bool) – Indicates if width and height attributes should be omitted (default: False). If these attributes are omitted, a viewBox attribute will be added to the document.
  • unit (str) – Unit for width / height and other coordinates. By default, the unit is unspecified and all values are in the user space. Valid values: em, ex, px, pt, pc, cm, mm, in, and percentages
  • encoding (str) – Encoding of the XML document. “utf-8” by default.
  • svgversion (float) – SVG version (default: None)
  • nl (bool) – Indicates if the document should have a trailing newline (default: True)
segno.writers.write_svg_debug(matrix, version, out, scale=15, border=None, fallback_color=u'fuchsia', color_mapping=None, add_legend=True)

Internal SVG serializer which is useful to debugging purposes.

This function is not exposed to the QRCode class by intention and the resulting SVG document is very inefficient (lots of <rect/>s). Dark modules are black and light modules are white by default. Provide a custom color_mapping to override these defaults. Unknown modules are red by default.

Parameters:
  • matrix – The matrix
  • version – Version constant
  • out – binary file-like object or file name
  • scale – Scaling factor
  • border – Quiet zone
  • fallback_color – Color which is used for modules which are not 0x0 or 0x1 and for which no entry in color_mapping is defined.
  • color_mapping – dict of module values to color mapping (optional)
  • add_legend (bool) – Indicates if the bit values should be added to the matrix (default: True)
segno.writers.write_terminal(matrix, version, out, border=None)

Function to write to a terminal which supports ANSI escape codes.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version.
  • out – Filename or a file-like object supporting to write text.
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
segno.writers.write_terminal_win(matrix, version, border=None)

Function to write a QR Code to a MS Windows terminal.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
segno.writers.write_tex(matrix, version, out, scale=1, border=None, color=u'black', unit=u'pt', url=None)

Serializes the matrix as LaTeX PGF picture.

Requires the PGF/TikZ package (i.e. \usepackage{pgf}) in the LaTeX source.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • out – Filename or a file-like object supporting to write text data.
  • scale – Indicates the size of a single module (default: 1 which corresponds to 1 x 1 in the provided unit per module).
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
  • color (str) – LaTeX color name. The color name is taken at it is, so ensure that it refers either to a default color name or that the color was defined previously.
  • unit – Unit of the drawing (default: pt)
  • url – Optional URL where the QR Code should point to. Requires the “hyperref” package. Default: None.
segno.writers.write_txt(matrix, version, out, border=None, color=u'1', background=u'0')

Serializes QR code in a text format.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • out – Filename or a file-like object supporting to write text.
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
  • color – Character to use for the black modules (default: ‘1’)
  • background – Character to use for the white modules (default: ‘0’)
segno.writers.write_xbm(matrix, version, out, scale=1, border=None, name=u'img')

Serializes the matrix as XBM image.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • out – Filename or a file-like object supporting to write text data.
  • scale – Indicates the size of a single module (default: 1 which corresponds to 1 x 1 in the provided unit per module).
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
  • name – Prefix for the variable names. Default: “img”. The prefix is used to construct the variable names: `#define <prefix>_width` `static unsigned char <prefix>_bits[]`
segno.writers.write_xpm(matrix, version, out, scale=1, border=None, color=u'#000', background=u'#fff', name=u'img')

Serializes the matrix as XPM image.

Parameters:
  • matrix – The matrix to serialize.
  • version (int) – The (Micro) QR code version
  • out – Filename or a file-like object supporting to write binary data.
  • scale – Indicates the size of a single module (default: 1 which corresponds to 1 x 1 pixel per module).
  • border (int) – Integer indicating the size of the quiet zone. If set to None (default), the recommended border size will be used (4 for QR Codes, 2 for a Micro QR Codes).
  • color – Color of the modules (default: black). The color can be provided as (R, G, B) tuple, as web color name (like “red”) or in hexadecimal format (#RGB or #RRGGBB).
  • background – Optional background color (default: white). See color for valid values. None indicates a transparent background.
  • name (str) – Name of the image (must be a valid C-identifier). Default: “img”.