API Reference

This section contains the complete API reference for SegnoMMS.

• Main Functions
  • write()
  • write_advanced()
  • register_with_segno()
  • Write Function
  • Quick Parameter Reference
  • Detailed Parameters Reference
  • Examples
• Configuration
  • Configuration Models
  • Main Configuration Class
  • Configuration Parameters
  • Phase Configuration
  • Plugin Configuration
  • Phase 4 Configuration
  • Shape Options
• Constants Module
  • Enums
  • Constants
  • Utility Functions
  • Complete Example
• Intent-Based API
  • Overview
  • Intent Categories
  • Result Models
  • Usage Examples
  • Best Practices
  • Intent Processing Flow
  • Transformation Types
  • Future Enhancements
• Shape Renderers
  • Shape Factory
  • Basic Shapes
  • Connected Shapes
  • Shape Interface
  • Creating Custom Shapes
• Animation and Effects
  • Overview
  • Animation Parameters
  • Usage Examples
  • Technical Details
  • Accessibility
  • Performance Considerations
  • Best Practices
  • Animation Combinations
  • Limitations
  • Browser Compatibility
• SVG Generation
  • SVG Builder System
  • Main SVG Builder
  • Core SVG Builder
  • Path Clipping
  • SVG Models
  • Example Usage
• Color Analysis
  • Color Analysis Functions
  • Core Functions
  • Palette Management
  • Color Standards
  • Example Usage
• Accessibility
  • Accessibility System
  • Accessibility Enhancer
  • ARIA Roles
  • Configuration
  • Example Usage
• Core Components
  • Interfaces
  • Module Detector
  • Matrix Manipulation
  • Algorithms
  • Phase 4 Core Components
  • Extending the Plugin
  • Module Types
  • Architecture Overview
• Frame Shapes
  • Frame Shape Generator
  • Available Frame Shapes
  • Examples
  • Usage with QR Codes
• Validation
  • Phase 4 Validator
  • Validation Classes
  • Error Correction Guidelines
  • Frame Validation
  • Examples
  • Validation Results
  • Common Warnings
  • Best Practices
• Exception Handling
  • Exception Hierarchy
  • Base Exception
  • Configuration Errors
  • Rendering Errors
  • Intent Processing Errors
  • Color Errors
  • Capability Errors
  • Dependency Errors
  • Error Handling Best Practices
• Degradation System
  • Overview
  • Architecture
  • Core Components
  • Built-in Degradation Rules
  • Custom Degradation Rules
  • Integration with Intent System
  • Production Monitoring
  • Performance Considerations
  • Best Practices
  • Future Enhancements

Main Module

The top-level package re-exports key classes and functions for convenience (segnomms.write, configuration models, exceptions, and factories). See the section pages in this API reference for authoritative docs on each area.

Quick Reference

Basic Usage

The main entry point is the write() function:

from segnomms import write

write(qr, output, shape='connected', scale=10)

Intent-Based API with Error Handling

For advanced features with graceful degradation:

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

try:
    intents = IntentsConfig(
        style=StyleIntents(
            module_shape="squircle",
            patterns={"finder": "rounded"}
        )
    )
    payload = PayloadConfig(text="Hello World")
    result = render_with_intents(payload, intents)

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

except IntentValidationError as e:
    print(f"Invalid intent at {e.intent_path}: {e.original_value}")
except UnsupportedIntentError as e:
    print(f"Feature '{e.feature}' not supported, alternatives: {e.alternatives}")

Production Error Recovery

Robust error handling for production systems:

def generate_qr_with_fallback(payload, intents, max_retries=3):
    """Generate QR with comprehensive error recovery."""
    for attempt in range(max_retries):
        try:
            result = render_with_intents(payload, intents)
            return {"success": True, "svg": result.svg_content, "warnings": result.warnings}

        except IntentValidationError as e:
            # Fix validation issues and retry
            intents = fix_validation_issues(intents, e)

        except UnsupportedIntentError as e:
            # Apply feature fallbacks
            intents = apply_feature_fallbacks(intents, e.feature, e.alternatives)

        except Exception as e:
            if attempt == max_retries - 1:
                # Last attempt - return minimal QR
                return {"success": False, "error": str(e), "svg": generate_minimal_qr(payload)}

    return {"success": False, "error": "Max retries exceeded"}