Integration API (Advanced)#
This page covers integration helpers beyond basic @signal usage.
For bounded diagnostics without argument repr, native exception text or inherited
payloads, see scoped diagnostic capture.
DiagnosticBundle#
Use DiagnosticBundle to centralize warning/error emission from catalog
contracts and avoid hardcoded message strings.
from smonitor.integrations import DiagnosticBundle
bundle = DiagnosticBundle(CATALOG, META, PACKAGE_ROOT)
warn = bundle.warn
warn_once = bundle.warn_once
resolve = bundle.resolve
Declaration-only emission (0.20.0+)#
Use DiagnosticBundle(CATALOG, META, PACKAGE_ROOT, bootstrap_policy=False)
when a provider must emit catalog diagnostics without bootstrapping application
policy.
It registers the provider’s declarations without choosing application policy;
warning, info and support-tier emission does not install a console handler or
activate warning/logging hooks. Applications can still explicitly configure
their own diagnostics. The default True retains existing first-use behavior.
The lower-level emit_from_catalog(..., bootstrap_policy=False) and
smonitor.emit(..., bootstrap_policy=False) preserve the same handler ownership
boundary. Scoped capture remains independent. These keyword arguments were
introduced in 0.20.0; 0.19.0 does not provide them.
warn() and warn_once() also raise ordinary Python warnings. Their
stacklevel counts application frames and skips SMonitor’s @signal wrapper,
so the default value attributes a warning to the caller of the library function.
Plain warnings.warn() inside a decorated function still counts that wrapper;
adjust its stacklevel when using Python’s warning API directly.
When to use:
whenever the host library emits repeated warning families,
when you need stable
code+ templated message/hint resolution.
emit_from_catalog#
Use this helper when you want direct catalog emission without custom wrappers.
from smonitor.integrations import emit_from_catalog
emit_from_catalog(
CATALOG,
code="MYLIB-W001",
source="mylib.select",
extra={"selection": "all"},
)
CatalogException and CatalogWarning#
Use these classes to keep semantic exception/warning types while inheriting catalog-backed message quality.
Recommended pattern:
map each domain exception to one stable catalog code,
preserve existing exception class hierarchy,
keep user hints in catalog templates, not in ad-hoc
raisestrings.
ensure_configured#
Call once at package startup:
from smonitor.integrations import ensure_configured
ensure_configured(PACKAGE_ROOT)
This registers the package’s exact _smonitor.py catalog and signals. If the
application has already called configure(), its entire runtime policy is
preserved. Otherwise the helper bootstraps from the application’s discovered
configuration, or the provider’s defaults when none exists. The first bootstrap
selects policy; subsequent provider imports only register declarations. Environment
overrides keep their existing precedence.
Applications can explicitly apply a provider’s recommendations with
ensure_configured(PACKAGE_ROOT, use_provider_policy=True). This intentionally
reconfigures runtime policy, even after a previous import.
register_provider#
For libraries that only supply diagnostics, prefer:
from smonitor.integrations import register_provider
register_provider(PACKAGE_ROOT, provider="mylib")
Registration never installs handlers or bridges and never changes application
policy. It validates declarations, then merges them atomically under a lock.
Identical repeated registrations and identical shared definitions are accepted.
Conflicting code/signal definitions reject the entire registration with
ProviderRegistrationError (SMONITOR-PROVIDER-CONFLICT); changing an existing
provider identity’s declarations raises SMONITOR-PROVIDER-IDENTITY. Invalid
declarations raise SMONITOR-PROVIDER-INVALID. Loader failures propagate before
registration. Provider identities default to the resolved package directory.
Use unique, namespaced codes and signal names; explicit application catalog
overrides through configure() retain their existing behavior.
get_manager().get_providers() returns detached declarations, provenance and
unapplied recommendations. To render for another audience without reconfiguration,
use smonitor.resolve(code="MYLIB-W001", profile="agent", extra={...}).
context_extra#
Use context_extra(...) when a host library repeatedly assembles structured
diagnostic payloads and wants a stable cross-library contract.
from smonitor.integrations import context_extra
extra = context_extra(
caller="mylib.io.download_structure",
resource="181l.pdb",
provider="RCSB",
operation="download",
retry_attempt=2,
retry_max=5,
failure_class="network",
incident_kind="network",
recommended_action="retry",
next_step="check-network",
evidence={"expected": "download ok", "observed": "timeout"},
)
Use it for:
shared context keys (
caller,resource,provider,operation);retry/causal metadata;
decision metadata;
compact structured
evidence.
This keeps downstream normalized payloads predictable for QA, support, and agents.
reset_configured_packages (test-only)#
Use this helper in tests to reset integration state between scenarios.
Practical rule#
Keep functional logic in SMonitor and keep library-specific data in
mylib/_private/smonitor/ (catalog + meta). This minimizes drift and keeps
ecosystem integrations uniform.