Main Functions

This module contains the primary functions for generating interactive SVG QR codes.

Main API interface for the SegnoMMS plugin.

This module contains the primary public functions that users interact with: - write(): Generate interactive SVG from existing QR code - write_advanced(): Generate QR code with advanced features - register_with_segno(): Register plugin with Segno

segnomms.plugin.interface.write(qr_code, out, **kwargs)[source]

Write an interactive SVG representation of a QR code.

This is the main entry point for the Segno plugin system. It generates an SVG with custom shapes and optional interactive features.

Parameters:

qr_code (Any) – Segno QR code object to render.
out (Union[TextIO, BinaryIO, str]) – Output destination — file path (str), text stream, or binary stream.
**kwargs (Any) – Additional rendering options.

Keyword Arguments:

options (Refer to the user guide for a complete list of supported)
defaults (and)
https – //segnomms.readthedocs.io/en/latest/api/main.html

Raises:

ValueError – If an invalid option combination is provided.
TypeError – If the output type is not supported.

Return type:

Optional[Dict[str, Any]]

Example

>>> import segno
>>> from segnomms import write
>>> qr = segno.make("Hello, World!")
>>> # Basic usage
>>> with open('output.svg', 'w') as f:
...     write(qr, f, shape='connected', scale=15)
>>> # With circle frame and centerpiece
>>> with open('framed.svg', 'w') as f:
...     write(qr, f, frame_shape='circle', centerpiece_enabled=True,
...           centerpiece_size=0.2, centerpiece_shape='circle')

segnomms.plugin.interface.write_advanced(content, out, **kwargs)[source]

Write advanced QR code(s) with ECI, mask patterns, or structured append.

This function provides enhanced QR code generation with advanced features including international character encoding, manual mask pattern selection, and multi-symbol structured append sequences.

Parameters:

content (str) – Text content to encode
out (Union[TextIO, BinaryIO, str]) – Output path or stream for the generated QR code(s)
**kwargs (Any) –
Advanced configuration options:

Basic Parameters: * scale (int): Module size in pixels (default: 10) * border (int): Quiet zone modules (default: 4) * dark (str): Dark module color (default: ‘black’) * light (str): Light module color (default: ‘white’)

Advanced QR Generation: * eci_enabled (bool): Enable Extended Channel Interpretation * mask_pattern (int): Manual mask pattern selection (0-7) * structured_append (bool): Enable structured append for long content * auto_mask (bool): Use automatic mask pattern selection (default: True) * boost_error (bool): Use higher error correction when possible

Export Options: * export_config (bool): Export configuration file (default: True) * use_hash_naming (bool): Use content-based filenames (default: False) * config_format (str): Configuration format - ‘json’ or ‘yaml’ (default: ‘json’)

Rendering Options: All standard rendering options from write() are supported

Returns:

Generation result containing:

files (list): List of all generated files
config_files (list): Configuration files created
warnings (list): Any generation warnings
advanced_config (dict): Advanced QR configuration used
fallback_used (bool): Whether fallback generation was used

Return type:

dict

Example

>>> result = write_advanced(
...     "Hello, 世界! This is a long message with international characters.",
...     "output.svg",
...     eci_enabled=True,
...     structured_append=True,
...     export_config=True
... )
>>> print(f"Generated {len(result['files'])} files")

segnomms.plugin.interface.register_with_segno()[source]

Register the SegnoMMS plugin with Segno.

This function attempts to register the write function as a plugin for the Segno library. Note that in modern Segno versions, plugin registration typically happens automatically via entry points defined in pyproject.toml.

Returns:: True if registration successful or already registered, False otherwise
Return type:: bool

Write Function

segnomms.write(qr_code, out, **kwargs)[source]

Write an interactive SVG representation of a QR code.

This is the main entry point for the Segno plugin system. It generates an SVG with custom shapes and optional interactive features.

Parameters:

qr_code (Any) – Segno QR code object to render.
out (Union[TextIO, BinaryIO, str]) – Output destination — file path (str), text stream, or binary stream.
**kwargs (Any) – Additional rendering options.

Keyword Arguments:

options (Refer to the user guide for a complete list of supported)
defaults (and)
https – //segnomms.readthedocs.io/en/latest/api/main.html

Raises:

ValueError – If an invalid option combination is provided.
TypeError – If the output type is not supported.

Return type:

Optional[Dict[str, Any]]

Example

>>> import segno
>>> from segnomms import write
>>> qr = segno.make("Hello, World!")
>>> # Basic usage
>>> with open('output.svg', 'w') as f:
...     write(qr, f, shape='connected', scale=15)
>>> # With circle frame and centerpiece
>>> with open('framed.svg', 'w') as f:
...     write(qr, f, frame_shape='circle', centerpiece_enabled=True,
...           centerpiece_size=0.2, centerpiece_shape='circle')

The write function is the main entry point for using the plugin. It accepts a Segno QR code object and writes it to the specified output with custom shapes and styling options.

Quick Parameter Reference

Most commonly used parameters with valid ranges:

Essential Parameters Quick Reference
Parameter	Type	Range/Options	Description
shape	str	circle, square, diamond, star, connected, etc.	Module shape (see Shape Reference for full list)
scale	int	1-100	Module size in pixels
border	int	0-20	Quiet zone size in modules
dark/light	str	hex colors, CSS names	Module colors
safe_mode	bool	True/False	Preserve scannability with simple shapes
size_ratio	float	0.1-1.0	Shape size (for circle, dot, hexagon)
star_points	int	3-12	Star points (for star shape)
centerpiece_size	float	0.0-0.5	Logo area size (Phase 4 feature)

For complete parameter lists with defaults and detailed descriptions, see the sections below.

Detailed Parameters Reference

Shape Parameters

Different shapes accept different parameters:

Shape-Specific Parameters
Shape	Parameter	Type	Default	Description
circle	size_ratio	float	0.9	Circle size relative to module (0.1-1.0)
dot	size_ratio	float	0.6	Dot size relative to module (0.1-1.0)
star	star_points	int	5	Number of star points (3-12)
star	inner_ratio	float	0.5	Inner to outer radius ratio (0.1-0.9)
triangle	direction	str	‘up’	Direction: up, down, left, right
hexagon	size_ratio	float	0.9	Hexagon size relative to module (0.1-1.0)
cross	thickness	float	0.2	Cross arm thickness (0.1-0.8)
cross	sharp	bool	False	Use tapered arms

Core Parameters

Core Rendering Parameters
Parameter	Type	Default	Description
scale	int	10	Size of each module in pixels (1-100)
border	int	4	Quiet zone size in modules (0-20)
dark	str	‘black’	Color for dark modules
light	str	‘white’	Color for light modules
safe_mode	bool	True	Use simple shapes for special patterns
merge	str	‘none’	Merging strategy: ‘none’, ‘soft’, ‘aggressive’

Phase 4 Parameters

Frame Shape Parameters

Frame Shape Configuration
Parameter	Type	Default	Description
frame_shape	str	‘square’	Frame type: ‘square’, ‘circle’, ‘rounded-rect’, ‘squircle’, ‘custom’
frame_corner_radius	float	0.0	Corner radius for rounded-rect (0.0-1.0)
frame_clip_mode	str	‘clip’	Edge treatment: ‘clip’ (sharp) or ‘fade’ (gradient)
frame_custom_path	str	None	Custom SVG path for ‘custom’ frame shape

Centerpiece Parameters

Centerpiece Logo Area Configuration
Parameter	Type	Default	Description
centerpiece_enabled	bool	False	Enable centerpiece area clearing
centerpiece_shape	str	‘rect’	Logo area shape: ‘rect’, ‘circle’, ‘squircle’
centerpiece_size	float	0.0	Size as fraction of QR code (0.0-0.5)
centerpiece_offset_x	float	0.0	X offset from center (-0.5 to 0.5)
centerpiece_offset_y	float	0.0	Y offset from center (-0.5 to 0.5)
centerpiece_margin	int	2	Module margin around centerpiece (0-10)

Quiet Zone Parameters

Enhanced Quiet Zone Configuration
Parameter	Type	Default	Description
quiet_zone_style	str	‘none’	Background style: ‘none’, ‘solid’, ‘gradient’
quiet_zone_color	str	‘transparent’	Color for solid quiet zone
quiet_zone_gradient	dict	None	Gradient config with type, colors, positions

Examples

Basic usage:

import segno
from segnomms import write

qr = segno.make("Hello, World!")
with open('output.svg', 'w') as f:
    write(qr, f)

With custom shape and colors:

with open('styled.svg', 'w') as f:
    write(qr, f,
          shape='connected',
          scale=20,
          dark='#1e40af',
          light='#dbeafe')

Star shape with parameters:

with open('star.svg', 'w') as f:
    write(qr, f,
          shape='star',
          star_points=8,
          inner_ratio=0.3)

Phase 4 Examples

Circle frame with centerpiece:

with open('circle_frame.svg', 'w') as f:
    write(qr, f,
          frame_shape='circle',
          centerpiece_enabled=True,
          centerpiece_shape='circle',
          centerpiece_size=0.15,
          border=6)

Professional business card style:

with open('business_card.svg', 'w') as f:
    write(qr, f,
          scale=20,
          border=6,
          frame_shape='rounded-rect',
          frame_corner_radius=0.2,
          centerpiece_enabled=True,
          centerpiece_shape='circle',
          centerpiece_size=0.12,
          quiet_zone_style='gradient',
          quiet_zone_gradient={
              'type': 'radial',
              'colors': ['#ffffff', '#f8f9fa']
          },
          shape='squircle',
          merge='soft')

Event poster with vibrant styling:

with open('event_poster.svg', 'w') as f:
    write(qr, f,
          scale=25,
          border=8,
          frame_shape='circle',
          frame_clip_mode='fade',
          centerpiece_enabled=True,
          centerpiece_size=0.16,
          centerpiece_offset_x=0.1,
          quiet_zone_style='gradient',
          quiet_zone_gradient={
              'type': 'linear',
              'x1': '0%', 'y1': '0%',
              'x2': '100%', 'y2': '100%',
              'colors': ['#7c3aed', '#c084fc']
          },
          shape='star',
          dark='#ffffff')