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 thesegno.consts
constants.error
isNone
iff a M1 QR Code was generated, otherwise it is always an integer.Return type: namedtuple
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:
-
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 astroke
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, aviewBox
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).