Generated {{ timestamp }} · Commit {{ commit }} · {{ total_models }} registered model types
diff --git a/src/mobius/_builder.py b/src/mobius/_builder.py
index d00727379..c801b888a 100644
--- a/src/mobius/_builder.py
+++ b/src/mobius/_builder.py
@@ -34,6 +34,7 @@
from mobius._configs import (
BaseModelConfig,
)
+from mobius._flags import flags
from mobius._model_package import ModelPackage
from mobius._registry import registry
from mobius._weight_loading import _download_weights
@@ -121,7 +122,10 @@ def call(self, model: ir.Model) -> ir.passes.PassResult:
def _optimize(model: ir.Model) -> None:
"""Apply default optimization passes to a model in-place."""
pass_ = ir.passes.PassManager(_DEFAULT_PASSES, steps=2)
- with _suppress_dedup_empty_initializer_warnings():
+ if flags.suppress_dedup_warning:
+ with _suppress_dedup_empty_initializer_warnings():
+ pass_(model)
+ else:
pass_(model)
diff --git a/src/mobius/_flags.py b/src/mobius/_flags.py
new file mode 100644
index 000000000..6043139c2
--- /dev/null
+++ b/src/mobius/_flags.py
@@ -0,0 +1,139 @@
+# Copyright (c) ONNX Project Contributors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Runtime feature flags for mobius.
+
+Flags control experimental or environment-specific behaviour. Each flag can be
+set via an environment variable (``MOBIUS_``) or programmatically
+by assigning to the :data:`flags` singleton.
+
+Environment variable values are read each time a :class:`_Flags` instance is
+constructed. The global :data:`flags` singleton is constructed at import time,
+so env vars should be set before importing mobius. Valid truthy strings are
+``1``, ``true``, ``yes``; falsy are ``0``, ``false``, ``no``
+(case-insensitive). Any other value falls back to the field default.
+
+**Adding new flags:** add a field to :class:`_Flags` with a
+``dataclasses.field(default_factory=...)`` that calls :func:`_env_bool`,
+plus a docstring string literal immediately after the field for documentation
+generation.
+
+Example::
+
+ from mobius import flags, override_flags
+
+ # Check a flag
+ if flags.suppress_dedup_warning:
+ ...
+
+ # Programmatic override (persists until changed)
+ flags.suppress_dedup_warning = False
+
+ # Scoped override for tests
+ with override_flags(suppress_dedup_warning=False):
+ ...
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+
+def _env_bool(name: str, default: bool) -> bool:
+ """Read a boolean from an environment variable.
+
+ Returns *default* if the variable is unset or has an unrecognised value.
+ """
+ val = os.environ.get(name, "")
+ if val.lower() in ("1", "true", "yes"):
+ return True
+ if val.lower() in ("0", "false", "no"):
+ return False
+ return default
+
+
+@dataclasses.dataclass
+class _Flags:
+ """Runtime feature flags singleton.
+
+ Each flag maps to a ``MOBIUS_`` environment variable read when
+ a :class:`_Flags` instance is constructed. The global :data:`flags`
+ singleton is constructed at import time. Flags can be overridden
+ programmatically at any point or scoped temporarily with
+ :func:`override_flags`.
+
+ **Available flags**
+
+ .. list-table::
+ :header-rows: 1
+
+ * - Flag
+ - Env var
+ - Default
+ - Description
+ * - ``suppress_dedup_warning``
+ - ``MOBIUS_SUPPRESS_DEDUP_WARNING``
+ - ``True``
+ - Suppress "has no constant value" warnings from the initializer
+ deduplication pass.
+ """
+
+ suppress_dedup_warning: bool = dataclasses.field(
+ default_factory=lambda: _env_bool("MOBIUS_SUPPRESS_DEDUP_WARNING", True)
+ )
+ """Suppress "has no constant value" warnings from the initializer-deduplication pass.
+
+ These warnings are expected noise when optimisation passes run before weights
+ are loaded. Set ``MOBIUS_SUPPRESS_DEDUP_WARNING=0`` to see all warnings.
+ """
+
+
+# Global singleton โ import and use this directly.
+flags = _Flags()
+
+
+def list_flags() -> dict[str, object]:
+ """Return the current value of all flags as a plain dict snapshot."""
+ return dataclasses.asdict(flags)
+
+
+@contextmanager
+def override_flags(**kwargs: bool) -> Iterator[None]:
+ """Temporarily override one or more flags within a ``with`` block.
+
+ Restores the original values on exit, even if an exception is raised.
+ Intended for use in tests.
+
+ .. note::
+ **Thread safety:** ``override_flags`` is not thread-safe โ concurrent
+ calls in different threads may interleave the save/restore cycle
+ (TOCTOU). For pytest, this is safe when running with ``-n auto``
+ because xdist spawns separate worker *processes* (not threads), so
+ each worker has its own copy of the flag singleton.
+
+ Raises:
+ ValueError: If any key in *kwargs* is not a known flag name.
+
+ Example::
+
+ with override_flags(suppress_dedup_warning=False):
+ build(model_id)
+ """
+ valid = {f.name for f in dataclasses.fields(_Flags)}
+ unknown = sorted(set(kwargs) - valid)
+ if unknown:
+ available = ", ".join(sorted(valid))
+ raise ValueError(
+ f"Unknown flag name(s): {', '.join(unknown)}. Available flags: {available}"
+ )
+ old = {k: getattr(flags, k) for k in kwargs}
+ for k, v in kwargs.items():
+ setattr(flags, k, v)
+ try:
+ yield
+ finally:
+ for k, v in old.items():
+ setattr(flags, k, v)
diff --git a/src/mobius/_flags_test.py b/src/mobius/_flags_test.py
new file mode 100644
index 000000000..50975f7a5
--- /dev/null
+++ b/src/mobius/_flags_test.py
@@ -0,0 +1,110 @@
+# Copyright (c) ONNX Project Contributors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for the feature flag system."""
+
+from __future__ import annotations
+
+import pytest
+
+from mobius import _flags
+
+
+class TestDefaultValues:
+ """Flags have the expected defaults when no env vars are set."""
+
+ def test_suppress_dedup_warning_default_on(self, monkeypatch):
+ monkeypatch.delenv("MOBIUS_SUPPRESS_DEDUP_WARNING", raising=False)
+ f = _flags._Flags()
+ assert f.suppress_dedup_warning is True
+
+
+class TestEnvVarOverride:
+ """Flags are read from environment variables at construction time."""
+
+ @pytest.mark.parametrize("val", ["1", "true", "True", "TRUE", "yes", "YES"])
+ def test_truthy_values(self, monkeypatch, val):
+ monkeypatch.setenv("MOBIUS_SUPPRESS_DEDUP_WARNING", val)
+ f = _flags._Flags()
+ assert f.suppress_dedup_warning is True
+
+ @pytest.mark.parametrize("val", ["0", "false", "False", "FALSE", "no", "NO"])
+ def test_falsy_values(self, monkeypatch, val):
+ monkeypatch.setenv("MOBIUS_SUPPRESS_DEDUP_WARNING", val)
+ f = _flags._Flags()
+ assert f.suppress_dedup_warning is False
+
+ def test_unknown_value_falls_back_to_default(self, monkeypatch):
+ monkeypatch.setenv("MOBIUS_SUPPRESS_DEDUP_WARNING", "maybe")
+ f = _flags._Flags()
+ assert f.suppress_dedup_warning is True # default
+
+
+class TestProgrammaticOverride:
+ """Flags can be assigned directly on the singleton."""
+
+ def test_assign_and_restore(self):
+ original = _flags.flags.suppress_dedup_warning
+ try:
+ _flags.flags.suppress_dedup_warning = not original
+ assert _flags.flags.suppress_dedup_warning is not original
+ finally:
+ _flags.flags.suppress_dedup_warning = original
+
+
+class TestOverrideFlagsContextManager:
+ """override_flags() restores original values on exit."""
+
+ def test_single_flag_restored(self):
+ original = _flags.flags.suppress_dedup_warning
+ with _flags.override_flags(suppress_dedup_warning=not original):
+ assert _flags.flags.suppress_dedup_warning is not original
+ assert _flags.flags.suppress_dedup_warning is original
+
+ def test_restored_on_exception(self):
+ original = _flags.flags.suppress_dedup_warning
+ exc = RuntimeError("boom")
+ try:
+ with _flags.override_flags(suppress_dedup_warning=not original):
+ raise exc
+ except RuntimeError:
+ pass
+ assert _flags.flags.suppress_dedup_warning is original
+
+ def test_nested_overrides(self):
+ original = _flags.flags.suppress_dedup_warning
+ with _flags.override_flags(suppress_dedup_warning=not original):
+ assert _flags.flags.suppress_dedup_warning is not original
+ with _flags.override_flags(suppress_dedup_warning=original):
+ assert _flags.flags.suppress_dedup_warning is original
+ assert _flags.flags.suppress_dedup_warning is not original
+ assert _flags.flags.suppress_dedup_warning is original
+
+ def test_unknown_flag_raises_value_error(self):
+ with (
+ pytest.raises(ValueError, match="Unknown flag"),
+ _flags.override_flags(nonexistent_flag=True),
+ ):
+ pass # pragma: no cover
+
+
+class TestListFlags:
+ """list_flags() returns a plain dict of all current flag values."""
+
+ def test_returns_dict(self):
+ result = _flags.list_flags()
+ assert isinstance(result, dict)
+
+ def test_contains_suppress_dedup_warning(self):
+ assert "suppress_dedup_warning" in _flags.list_flags()
+
+ def test_values_match_singleton(self):
+ result = _flags.list_flags()
+ assert result["suppress_dedup_warning"] == _flags.flags.suppress_dedup_warning
+
+ def test_returns_snapshot_not_live_view(self):
+ """list_flags() returns a copy, not a live reference."""
+ snapshot = _flags.list_flags()
+ original = _flags.flags.suppress_dedup_warning
+ with _flags.override_flags(suppress_dedup_warning=not original):
+ assert snapshot["suppress_dedup_warning"] == original