Segno’s low level API

segno.make(), segno.make_qr(), and segno.make_micro() return a segno.QRCode instance 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, 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 (expecting just a matrix) 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.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_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_png(matrix, version, out, scale=1, border=None, color=u'#000', background=u'#fff', compresslevel=9, dpi=None, addad=True, colormap=None)

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.
  • colormap (dict) – Optional module type -> color mapping. If provided, the color and background arguments are ignored. All undefined module types will have the default colors (light: white, dark: black). See color for valid color values. None is accepted as valid color value as well (becomes transparent).
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_pdf(matrix, version, out, scale=1, border=None, color=u'#000', background=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).
  • 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: None = no background color). See color for valid values.
  • 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_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_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_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_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”.
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_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_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).