DOCSEARCHbyAlgolia
Submit Docs

Segno

repository·master·Indexed 21 days ago

https://github.com/heuer/segno

A pure Python QR Code and Micro QR Code encoder with no dependencies that implements the ISO/IEC 18004:2015(E) specification. It supports multiple serialization formats including SVG, PNG, PDF, and EPS, and provides both a Python API and a command-line tool. Features include error correction level boosting, extensive module color customization, and an optional qrcode-artistic plugin for creating animated QR codes or overlaying them on background images using Pillow.

Tokens
27K
Snippets
99
Records
129
Agent score
71%

What's inside segno

  1. Compare Segno features with other Python QR libraries

    master

    Segno provides a broader feature set compared to other popular Python QR libraries like qrcode and qrcodegen. Key advantages of Segno include:

    • Micro QR Code Support: Full support for Micro QR Code versions M1 - M4.
    • Advanced Encoding Modes: Supports Kanji, Hanzi (when explicitly enabled), ECI, and Structured Append.
    • Compliance: Complies with ISO/IEC 18004:2015(E) for both standard QR codes (using mask 5) and Micro QR codes.
    • Extensive Output Formats: Native support for PNG, SVG, EPS, PDF, PAM, PBM, PPM, XBM, XPM, LaTeX, and Text/ANSI output. It also supports data URI for PNG and SVG.
    • Color & Animation: Supports colored QR codes and animated QR codes (GIF, APNG, WebP) via plugins.
    • Extensibility: Uses a plugin system to support additional formats like JPEG or animated formats.
    • Zero Dependencies: Unlike qrcode which may require Pillow, Segno has no mandatory 3rd party dependencies for its core functionality.

  2. Use Numeric mode for digits

    master

    Numeric mode is the most efficient way to encode digits. It is supported by both standard QR Codes and Micro QR Codes. Note that this mode does not support the minus (-) or plus (+) signs.

    Segno automatically detects numeric mode when the input is a string or integer containing only digits.

    import segno

# Automatic detection
qrcode = segno.make('64')
print(qrcode.mode)  # 'numeric'

# Segno defaults to Micro QR Code for numeric data as it is more efficient
print(qrcode.designator)  # e.g., 'M1'

  3. Use Kanji mode for efficient Japanese encoding

    master

    Kanji mode allows for very compact encoding of Kanji characters, requiring significantly less space than UTF-8 encoding in byte mode.

    import segno

# Automatic Kanji detection
qrcode = segno.make('ビートルズ')
print(qrcode.mode)  # 'kanji'

  4. How error correction level boosting works in Segno

    master

    By default, Segno uses a behavior called 'error correction level boosting'. If you do not specify a version (via the --version CLI flag or the version parameter in segno.make), Segno selects the smallest possible (Micro) QR Code version and then applies the highest possible error correction level for that version.

    Note that the QR Code version takes precedence: Segno will never increase the QR Code version just to achieve a higher error correction level. However, if a higher error correction level can be achieved within the same version, Segno will automatically 'boost' it to improve readability.

    If you explicitly provide an --error level (via the --error CLI flag or the error parameter in segno.make), Segno treats that value as the minimum required level and may still boost it higher if the version allows it.

    import segno
# Default behavior: Segno boosts error correction within the chosen version
qrcode = segno.make('The Long and Winding Road')
print(qrcode.designator)  # Output: '2-M'

  5. How QR Code encoding modes work in Segno

    master

    Segno follows the ISO/IEC 18004 standard, which defines several modes to encode data as efficiently as possible. By default, Segno automatically detects and selects the most efficient encoding/mode for your data.

    While you can manually specify a mode using the mode parameter in segno.make() or via CLI flags (--mode or -m), it is generally recommended to let Segno decide to ensure optimal efficiency.

    Available modes include:

    • Numeric: Most efficient for digits only (no signs like + or -).
    • Alphanumeric: Supports uppercase letters, spaces, and specific symbols ($%*+-./:).
    • Kanji: Highly efficient for Kanji characters.
    • Byte: A fallback mode for all other data. Segno attempts to use ISO 8859-1 first, falling back to UTF-8 if necessary.
    • Hanzi: A non-standard mode for Hanzi characters that must be enabled explicitly.
    import segno
# Let Segno decide the mode automatically
qrcode = segno.make('12345')
print(qrcode.mode)  # Output: 'numeric'

  6. Use Byte mode for general data

    master

    Byte mode is the universal fallback for any data that cannot be represented by Numeric, Alphanumeric, or Kanji modes. Segno attempts to encode data using ISO 8859-1 for efficiency, falling back to UTF-8 if the characters are not supported by ISO 8859-1.

    import segno

# Byte mode is used for mixed case or special characters
qrcode = segno.make('Let it be')
print(qrcode.mode)  # 'byte'

  7. How Structured Append works in Segno

    master

    Structured Append mode allows you to split a single message across multiple QR codes. This is useful for encoding data that is too large for a single QR code.

    Key constraints and behaviors:

    • It is not available for Micro QR codes.
    • Segno provides the segno.make_sequence factory function to create these sequences.
    • The function returns instances of segno.QRCodeSequence.
    • A sequence can contain up to 16 QR codes.
    • If the content fits into a single QR code, the QRCodeSequence behaves like a standard segno.QRCode instance.
    import segno
# Creates a sequence of QR codes using Structured Append
qrcode_seq = segno.make_sequence('Your long message here', version=1)

  8. Use Segno helper factory functions

    master

    The segno.helpers module provides factory functions to generate specialized QR codes for common data formats. These functions can either return a QRCode object directly or return the raw data string (the URI/format string) for manual encoding.

    Supported specialized formats include:

    • WIFI configurations: via make_wifi or make_wifi_data.
    • Geographic locations: via make_geo or make_geo_data.
    • vCards and MeCards: (see contact information documentation).
    • EPC QR Codes: (see EPC QR Codes documentation).

  9. Extend Segno output formats using plugins

    master

    While Segno has extensive native support, you can extend its capabilities using its plugin system. This allows for support of additional formats such as:

    • JPEG output
    • Animated QR codes (GIF, APNG, WebP)

    Refer to the plugin documentation for specific implementation details.

  10. Choose between QR Codes and Micro QR Codes

    master

    Segno provides several ways to control whether a QR Code or a Micro QR Code is generated:

    1. segno.make(content, micro=False): The default factory function. It chooses the minimal possible version. If micro=True, it attempts to create a Micro QR Code. If micro=False, it enforces a standard QR Code.
    2. segno.make_qr(content): Explicitly enforces the creation of a standard QR Code.
    3. segno.make_micro(content): Explicitly enforces the creation of a Micro QR Code.

    Note: If you request a Micro QR Code but specify an error correction level of H, Segno will automatically generate a standard QR Code instead because H is not available for Micro QR Codes.

    import segno

# Force a Micro QR Code
micro = segno.make_micro('The Beatles')

# Force a standard QR Code
qr = segno.make_qr('The Beatles')

# Disallow Micro QR Codes using the general factory
qr_no_micro = segno.make('The Beatles', micro=False)

  11. Use Alphanumeric mode for uppercase and symbols

    master

    Alphanumeric mode is used for data containing uppercase letters (A-Z), spaces, and the symbols $%*+-./:.

    Note: Lowercase characters are NOT supported by alphanumeric mode and will cause Segno to switch to byte mode.

    import segno

# Alphanumeric example
qrcode = segno.make('REVOLUTION NO. 9')
print(qrcode.mode)  # 'alphanumeric'

# Lowercase triggers byte mode
qrcode_byte = segno.make('Revolution No. 9')
print(qrcode_byte.mode)  # 'byte'

  12. How Segno plugins work

    master

    Segno uses an egg entry point architecture to support plugins. The segno.QRCode class provides the interface for these plugins.

    To be recognized by Segno, all plugins must register themselves using the segno.plugin.converter entry point. Once a plugin is installed and detected, it is accessible via a dynamically generated method on the segno.QRCode instance following the pattern to_<plugin_name>, where <plugin_name> is the name defined in the entry point configuration.

    import segno
qrcode = segno.make('data')
# If the plugin name is 'simple', call:
qrcode.to_simple()