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(file_or_path, mode, encoding=None)¶

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, dark='#000', light=None, xmldecl=True, svgns=True, title=None, desc=None, svgid=None, svgclass='segno', lineclass='qrline', omitsize=False, unit=None, encoding='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).
dark¶ – 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.
light¶ – 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, dark='#000', light='#fff', finder_dark=False, finder_light=False, data_dark=False, data_light=False, version_dark=False, version_light=False, format_dark=False, format_light=False, alignment_dark=False, alignment_light=False, timing_dark=False, timing_light=False, separator=False, dark_module=False, quiet_zone=False, compresslevel=9, dpi=None, addad=True)¶

Serializes the QR Code as PNG image.

By default, the generated PNG will be a greyscale image (black / white) with a bit depth of 1. If different colors are provided, an indexed-color image with the same bit depth is generated unless more than two colors are provided. This may require a bit depth of of 2 or 4.

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).
dark¶ – 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). None can be used to define transparency.
light¶ – Optional background color (default: white). See write_png.dark for valid values. In addition, None is accepted which indicates a transparent background.
finder_dark¶ – Color of the dark modules of the finder patterns. See write_png.dark for valid values.
finder_light¶ – Color of the light modules of the finder patterns. See write_png.dark for valid values.
data_dark¶ – Color of the dark data modules. See write_png.dark for valid values.
data_light¶ – Color of the light data modules. See write_png.dark for valid values.
version_dark¶ – Color of the dark modules of the version information. See write_png.dark for valid values.
version_light¶ – Color of the light modules of the version information. See write_png.dark for valid values.
format_dark¶ – Color of the dark modules of the format information. See write_png.dark for valid values.
format_light¶ – Color of the light modules of the format information. See write_png.dark for valid values.
alignment_dark¶ – Color of the dark modules of the alignment patterns. See write_png.dark for valid values.
alignment_light¶ – Color of the light modules of the alignment patterns. See write_png.dark for valid values.
timing_dark¶ – Color of the dark modules of the timing patterns. See write_png.dark for valid values.
timing_light¶ – Color of the light modules of the timing patterns. See write_png.dark for valid values.
separator¶ – Color of the separator. See write_png.dark for valid values.
dark_module¶ – Color of the dark module. See write_png.dark for valid values.
quiet_zone¶ – Color of the quiet zone / border. See write_png.dark for valid values.
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, dark='#000', light=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).
dark¶ – 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).
light¶ – Optional background color (default: None = no background color). See color for valid values.

segno.writers.write_pdf(matrix, version, out, scale=1, border=None, dark='#000', light=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).
dark¶ – 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).
light¶ – 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, dark='1', light='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).
dark¶ – Character to use for the black modules (default: ‘1’)
light¶ – 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, dark='#000', light='#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).
dark¶ – 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).
light¶ – 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, dark='#000', light='#fff', name='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).
dark¶ – 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).
light¶ – 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='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, dark='black', unit='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).
dark¶ (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).

segno.utils¶

Utility functions useful for writers or QR Code objects.

segno.utils.get_default_border_size(version)¶

Returns the default border size (quiet zone) for the provided version.

Parameters:	version¶ (int) – 1 .. 40 or a Micro QR Code version constant.
Return type:	int

segno.utils.get_border(version, border)¶

Returns border if not None, otherwise the default border size for the provided QR Code.

Parameters:	version¶ (int) – 1 .. 40 or a Micro QR Code version constant border¶ (int or None) – The size of the quiet zone or `None`.
Return type:	int

segno.utils.get_symbol_size(version, scale=1, border=None)¶

Returns the symbol size (width x height) with the provided border and scaling factor.

Parameters:

version¶ (int) – A version constant.
scale¶ (int or float) – Indicates the size of a single module (default: 1). The size of a module depends on the used output format; i.e. in a PNG context, a scaling factor of 2 indicates that a module has a size of 2 x 2 pixel. Some outputs (i.e. SVG) accept floating point values.
border¶ (int) – The border size or None to specify the default quiet zone (4 for QR Codes, 2 for Micro QR Codes).

Return type:

tuple (width, height)

segno.utils.check_valid_scale(scale)¶

Raises a ValueError iff scale is negative or zero.

Parameters:	scale¶ (float or int) – Scaling factor.

segno.utils.check_valid_border(border)¶

Raises a ValueError iff border is negative.

Parameters:	border¶ (int) – Indicating the size of the quiet zone.

segno.utils.matrix_to_lines(matrix, x, y, incby=1)¶

Converts the matrix into an iterable of ((x1, y1), (x2, y2)) tuples which represent a sequence (horizontal line) of dark modules.

The path starts at the 1st row of the matrix and moves down to the last row.

Parameters:	matrix¶ – An iterable of bytearrays. x¶ – Initial position on the x-axis. y¶ – Initial position on the y-axis. incby¶ – Value to move along the y-axis (default: 1).
Return type:	iterable of (x1, y1), (x2, y2) tuples

segno.utils.matrix_iter(matrix, version, scale=1, border=None)¶

Returns an iterator / generator over the provided matrix which includes the border and the scaling factor.

If either the scale or border value is invalid, a ValueError is raised.

Parameters:	matrix¶ – An iterable of bytearrays. version¶ (int) – A version constant. scale¶ (int) – The scaling factor (default: `1`). border¶ (int) – The border size or `None` to specify the default quiet zone (4 for QR Codes, 2 for Micro QR Codes).
Raises:	`ValueError` if an illegal scale or border value is provided

segno.utils.matrix_iter_verbose(matrix, version, scale=1, border=None)¶

EXPERIMENTAL: Returns an iterator / generator over the provided matrix which includes the border and the scaling factor.

This iterator / generator returns different values for dark / light modules and therefor the different parts (like the finder patterns, alignment patterns etc.) are distinguishable. If this information isn’t necessary, use the matrix_iter() function because it is much cheaper and faster.

If either the scale or border value is invalid, a py:exc:ValueError is raised.

Parameters:	matrix¶ – An iterable of bytearrays. version¶ (int) – A version constant. scale¶ (int) – The scaling factor (default: `1`). border¶ (int) – The border size or `None` to specify the default quiet zone (4 for QR Codes, 2 for Micro QR Codes).
Raises:	`ValueError` if an illegal scale or border value is provided