Deprecated Options Migration Guide

This guide helps you migrate from deprecated configuration option names to their current equivalents. All deprecated options continue to work but emit DeprecationWarning messages to help you update your code.

Centerpiece Options (formerly “reserve”)

The reserve_* options have been renamed to centerpiece_* for clarity. The new names better describe the feature’s purpose: reserving space for a logo or centerpiece in the QR code center.

Deprecated Option	Current Option	Description
`reserve_center`	`centerpiece_enabled`	Enable centerpiece reservation
`reserve_shape`	`centerpiece_shape`	Shape of the reserved area
`reserve_size`	`centerpiece_size`	Size as fraction of QR code
`reserve_offset_x`	`centerpiece_offset_x`	Horizontal offset from center
`reserve_offset_y`	`centerpiece_offset_y`	Vertical offset from center
`reserve_margin`	`centerpiece_margin`	Margin around centerpiece

Migration Example

Before (deprecated):

from segnomms import write

write(
    qr,
    output,
    reserve_center=True,
    reserve_size=0.15,
    reserve_shape="circle",
    reserve_margin=2,
)

After (current):

from segnomms import write

write(
    qr,
    output,
    centerpiece_enabled=True,
    centerpiece_size=0.15,
    centerpiece_shape="circle",
    centerpiece_margin=2,
)

QR Advanced Options

The qr_* prefixed options have been renamed to use more intuitive names that align with Segno’s terminology.

Deprecated Option	Current Option	Description
`qr_eci`	`eci_enabled`	Enable Extended Channel Interpretation
`qr_encoding`	`encoding`	Character encoding
`qr_mask`	`mask_pattern`	QR code mask pattern (0-7)
`qr_symbol_count`	`symbol_count`	Number of symbols in sequence
`qr_boost_error`	`boost_error`	Boost error correction if possible
`multi_symbol`	`structured_append`	Enable structured append mode

Migration Example

Before (deprecated):

from segnomms.config import RenderingConfig

config = RenderingConfig.from_kwargs(
    qr_boost_error=True,
    qr_mask=3,
    qr_eci=True,
)

After (current):

from segnomms.config import RenderingConfig

config = RenderingConfig.from_kwargs(
    boost_error=True,
    mask_pattern=3,
    eci_enabled=True,
)

Conflict Handling

If you accidentally use both the deprecated and current option names in the same call, SegnoMMS handles this gracefully:

Same values: Only emits a deprecation warning (no error)

# This works but emits a warning
config = RenderingConfig.from_kwargs(
    reserve_size=0.15,
    centerpiece_size=0.15,  # Same value - just warns
)

Different values: Raises ValueError

# This raises ValueError due to conflict
config = RenderingConfig.from_kwargs(
    reserve_size=0.15,
    centerpiece_size=0.20,  # Different value - error!
)
# ValueError: Conflicting values for 'reserve_size' and 'centerpiece_size':
#             received 0.15 and 0.20.

Deprecation Policy

SegnoMMS follows semantic versioning with the following deprecation policy:

Pre-1.0.0 (current):: Deprecated options may be removed in any minor version bump (e.g., 0.5.0 to 0.6.0). We recommend migrating promptly when deprecation warnings appear.
Post-1.0.0 (future):: Deprecated options will be retained for at least one major version cycle. For example, options deprecated in 1.x will continue to work until 3.0.0.

Filtering Deprecation Warnings

If you need to suppress deprecation warnings temporarily (not recommended for production code), you can use Python’s warnings module:

import warnings
from segnomms.config import RenderingConfig

# Suppress only SegnoMMS deprecation warnings
with warnings.catch_warnings():
    warnings.filterwarnings(
        "ignore",
        category=DeprecationWarning,
        module=r"segnomms\..*"
    )
    config = RenderingConfig.from_kwargs(reserve_center=True)

Phase4Validator Rename

The Phase4Validator class has been renamed to CompositionValidator to better reflect its purpose as a validation system for visual composition, rather than a processing phase.

Before (deprecated):

from segnomms.validation import Phase4Validator

validator = Phase4Validator(config)
result = validator.validate_all()

After (current):

from segnomms.validation import CompositionValidator

validator = CompositionValidator(config)
result = validator.validate_all()

The old import continues to work but emits a DeprecationWarning.

phase4 Module Rename

The segnomms.validation.phase4 module has been renamed to segnomms.validation.composition. This module-level rename reflects the transition from internal development phase naming to descriptive functionality.

Before (deprecated):

from segnomms.validation.phase4 import Phase4Validator

validator = Phase4Validator(
    qr_version=5, error_level='M', matrix_size=37
)

After (current):

from segnomms.validation.composition import CompositionValidator

# Or use the package-level import (recommended):
from segnomms.validation import CompositionValidator

validator = CompositionValidator(
    qr_version=5, error_level='M', matrix_size=37
)

Importing from the old module path emits a DeprecationWarning at import time.

Phase4ValidatorConfig Rename

The configuration class Phase4ValidatorConfig has been renamed to CompositionValidatorConfig for consistency with the validator class.

Before (deprecated):

from segnomms.validation.models import Phase4ValidatorConfig

config = Phase4ValidatorConfig(
    qr_version=5,
    error_level='M',
    matrix_size=37
)

After (current):

from segnomms.validation.models import CompositionValidatorConfig

config = CompositionValidatorConfig(
    qr_version=5,
    error_level='M',
    matrix_size=37
)

The old class name continues to work but emits a DeprecationWarning.

enable_phase4 Parameter Rename

The enable_phase4 parameter has been renamed to enable_composition for consistency with the CompositionValidator naming.

Note

Both enable_phase4 and enable_composition are currently no-op parameters. Composition features (frames, centerpieces) are controlled by their individual parameters: frame_shape, frame_*, centerpiece_enabled, centerpiece_*, etc.

Before (deprecated):

from segnomms import write

write(
    qr,
    output,
    enable_phase4=True,
    frame_shape="circle",
    centerpiece_enabled=True,
)

After (current):

from segnomms import write

write(
    qr,
    output,
    enable_composition=True,  # Optional, composition features controlled by other params
    frame_shape="circle",
    centerpiece_enabled=True,
)

The deprecated parameter emits a DeprecationWarning but continues to work.