Quick Start Guide

This guide will help you get started with SegnoMMS.

Getting Started

SegnoMMS offers two primary APIs: the Intent-Based API (recommended for modern applications) and the Legacy Write API (for simple use cases).

Modern Intent-Based API (Recommended)

The intent-based API provides high-level, declarative QR code generation with built-in error handling and graceful degradation:

from segnomms.intents import render_with_intents
from segnomms.intents.models import PayloadConfig, IntentsConfig, StyleIntents

# Define your intentions
intents = IntentsConfig(
    style=StyleIntents(
        module_shape="squircle",
        palette={"fg": "#1a1a2e", "bg": "#ffffff"},
        corner_radius=0.3
    )
)

# Generate QR with comprehensive error handling
result = render_with_intents(PayloadConfig(text="Hello, World!"), intents)

# Check results and handle any issues
if result.has_warnings:
    for warning in result.warnings:
        print(f"Notice: {warning.detail}")

# Save the result
with open('modern-qr.svg', 'w') as f:
    f.write(result.svg_content)

Legacy Write API (Simple Cases)

For simple use cases, the traditional write function is still available:

import segno
from segnomms import write

# Create a QR code
qr = segno.make("Hello, World!")

# Save as SVG with default settings
with open('simple.svg', 'w') as f:
    write(qr, f)

Type-Safe Configuration with Pydantic

SegnoMMS uses Pydantic for type-safe configuration with automatic validation:

from segnomms.config import RenderingConfig
from pydantic import ValidationError

# Type-safe configuration with validation
try:
    config = RenderingConfig.from_kwargs(
        shape='squircle',
        corner_radius=0.3,
        scale=15,
        dark='#1a1a2e',
        light='#ffffff',
        interactive=True
    )
    print("Configuration is valid!")
except ValidationError as e:
    print(f"Configuration error: {e}")

# Use with legacy API
qr = segno.make("Type-safe QR!")
with open('validated.svg', 'w') as f:
    write(qr, f, **config.to_kwargs())

Intent-Based Shape Configuration

The modern intent-based API makes shape configuration more intuitive:

from segnomms.intents.models import PayloadConfig, StyleIntents, FrameIntents, IntentsConfig
from segnomms.intents import render_with_intents

# Different shapes with intents
circle_intents = IntentsConfig(
    style=StyleIntents(module_shape="circle")
)

connected_intents = IntentsConfig(
    style=StyleIntents(
        module_shape="connected",
        patterns={"finder": "rounded", "data": "connected"}
    )
)

star_intents = IntentsConfig(
    style=StyleIntents(
        module_shape="star",
        corner_radius=0.4  # Star-specific parameters
    )
)

# Generate with different configurations
for name, intents in [("circle", circle_intents), ("connected", connected_intents), ("star", star_intents)]:
    result = render_with_intents(PayloadConfig(text="Hello!"), intents)
    with open(f'{name}.svg', 'w') as f:
        f.write(result.svg_content)

Legacy Shape API

For backward compatibility, the write function also supports various shape types:

# Circle shape
with open('circle.svg', 'w') as f:
    write(qr, f, shape='circle')

# Connected shape with smooth corners
with open('connected.svg', 'w') as f:
    write(qr, f, shape='connected')

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

Customizing Colors

Intent-Based Color Configuration (Recommended)

The intent-based API provides color palette configuration with automatic validation:

from segnomms.intents.models import PayloadConfig, IntentsConfig, StyleIntents
from segnomms.intents import render_with_intents

# Professional color palette
professional_intents = IntentsConfig(
    style=StyleIntents(
        module_shape="squircle",
        palette={
            "fg": "#1e40af",    # Professional blue
            "bg": "#f8fafc"     # Light background
        }
    )
)

# High contrast for accessibility
accessible_intents = IntentsConfig(
    style=StyleIntents(
        module_shape="rounded",
        palette={
            "fg": "#000000",    # Pure black
            "bg": "#ffffff"     # Pure white
        }
    )
)

# Brand colors with validation
try:
    brand_intents = IntentsConfig(
        style=StyleIntents(
            palette={
                "fg": "#invalid-color",  # This will raise validation error
                "bg": "#ffffff"
            }
        )
    )
except ValidationError as e:
    print(f"Color validation failed: {e}")

Legacy Color API

For simple cases, you can still use the write function directly:

# Blue QR code on light background
with open('colored.svg', 'w') as f:
    write(qr, f,
          shape='dot',
          dark='#1e40af',    # Dark blue
          light='#dbeafe')   # Light blue

# Transparent background
with open('transparent.svg', 'w') as f:
    write(qr, f,
          shape='connected',
          dark='#000000',
          light='transparent')

Safe Mode

By default, the plugin uses “safe mode” which ensures maximum scannability:

# Safe mode ON (default) - special patterns use simple shapes
with open('safe.svg', 'w') as f:
    write(qr, f, shape='star', safe_mode=True)

# Safe mode OFF - all modules use the selected shape
with open('unsafe.svg', 'w') as f:
    write(qr, f, shape='star', safe_mode=False)

Advanced Example

Here’s a more complex example combining various features:

import segno
from segnomms import write

# Create a QR code with high error correction
qr = segno.make("https://example.com", error='h')

# Save with custom styling
with open('advanced.svg', 'w') as f:
    write(qr, f,
          shape='connected-classy',      # Sophisticated connected shape
          scale=20,                      # Larger modules
          border=2,                      # Smaller quiet zone
          dark='#059669',               # Green
          light='#f0fdf4',              # Light green
          safe_mode=False,              # Apply shape to all modules
          svgclass='my-qr-code',        # Custom CSS class
          title='Scan Me!',             # Custom title
          xmldecl=False)                # No XML declaration

Working with Different QR Types

The plugin works with all Segno QR code types:

# Regular QR code
qr1 = segno.make("Regular QR")

# Micro QR code
qr2 = segno.make("Micro", micro=True)

# QR code with specific version
qr3 = segno.make("Version 10", version=10)

# All work with the plugin
for i, qr in enumerate([qr1, qr2, qr3]):
    with open(f'qr_{i}.svg', 'w') as f:
        write(qr, f, shape='connected')

Phase 4: Professional QR Codes

Create professional QR codes with custom frames and logo areas:

# Circle frame with logo area
qr = segno.make("https://example.com", error='h')

with open('professional.svg', 'w') as f:
    write(qr, f,
          scale=20,
          border=6,

          # Circular frame
          frame_shape='circle',

          # Logo area in center
          centerpiece_enabled=True,
          centerpiece_shape='circle',
          centerpiece_size=0.15,

          # Gradient background
          quiet_zone_style='gradient',
          quiet_zone_gradient={
              'type': 'radial',
              'colors': ['#ffffff', '#f0f0f0']
          },

          # Smooth module shapes
          shape='squircle',
          merge='soft')

Frame Shapes

Available frame shapes:

'square' - Standard rectangular QR code (default)
'circle' - Circular boundary
'rounded-rect' - Rectangle with rounded corners
'squircle' - Modern superellipse shape
'custom' - Define your own SVG path

Centerpiece Logo Areas

Reserve space for logos with automatic error correction validation:

# Reserve 15% of center for logo
write(qr, f,
      centerpiece_enabled=True,
      centerpiece_size=0.15,        # Size as fraction
      centerpiece_shape='circle',   # 'rect', 'circle', or 'squircle'
      centerpiece_margin=2)         # Safety margin in modules

Error Handling and Production Use

Intent-Based Error Handling (Recommended)

The intent-based API provides comprehensive error handling with specific exception types:

from segnomms.intents import render_with_intents
from segnomms.intents.models import PayloadConfig, IntentsConfig, StyleIntents
from segnomms.exceptions import IntentValidationError, UnsupportedIntentError

try:
    # This might have validation issues
    intents = IntentsConfig(
        style=StyleIntents(
            module_shape="pyramid",  # Might not be supported
            corner_radius=2.5        # Out of valid range
        )
    )
    result = render_with_intents(PayloadConfig(text="Hello!"), intents)

    # Check for degradation warnings
    if result.has_warnings:
        for warning in result.warnings:
            if warning.code == "FEATURE_DEGRADED":
                print(f"Feature '{warning.detail}' was degraded for compatibility")

except IntentValidationError as e:
    print(f"Invalid configuration: {e.message}")
    print(f"Field: {e.intent_path}")
    print(f"Suggestion: {e.suggestion}")

except UnsupportedIntentError as e:
    print(f"Feature not supported: {e.feature}")
    print(f"Try these alternatives: {e.alternatives}")

For complete error handling patterns, see Exception Handling.

Development Best Practices

For testing and development, use test constants to avoid magic strings:

from segnomms.constants import (
    ModuleShape, TEST_COLORS, create_config,
    QR_PAYLOADS, DEFAULT_SCALE, DEFAULT_BORDER
)

# Type-safe and maintainable
qr = segno.make(QR_PAYLOADS["url"])
config = create_config(
    shape=ModuleShape.SQUIRCLE.value,
    dark=TEST_COLORS["brand_primary"],
    light=TEST_COLORS["white"],
    scale=DEFAULT_SCALE,
    border=DEFAULT_BORDER
)

with open('professional.svg', 'w') as f:
    write(qr, f, **config)

Benefits of using constants:

Type safety - Prevent typos in shape names
IDE support - Autocomplete for all valid values
Consistency - Same colors/shapes across your project
Maintainability - Change values in one place

See Testing Documentation for comprehensive testing documentation.

Next Steps

Intent-Based API: See Intent-Based API for comprehensive intent configuration options
Error Handling: Review Exception Handling for production error handling patterns
Degradation System: Learn about Degradation System for graceful feature fallbacks
Shape Options: See Shape Reference for a complete list of available shapes
Examples: Explore Examples for usage patterns, including Intent-Based API examples
Testing: Read Testing Documentation for testing best practices and development guidelines
Full API Reference: Check API Reference for complete API documentation