Package-level API

This page documents the package-level functions used to configure and access logger-wide objects.

These functions are entry points into the package-level registries and wiring layer. They are separate from object-level APIs such as LogContext, sink classes, event models, and payload processors.

Use this page when you need to configure or retrieve named logger resources through the package-level API.

Sink facade

The sink facade manages package-level sink registration.

mvx.common.logger.configure_log_sink(*, name, sink_cls, **sink_kwargs)

Configure or retrieve a package-level named log sink.

If no sink is registered under name, the function asks sink_cls to build a descriptor, creates the sink, stores it in the package-level sink registry, and returns it.

If a sink with the same name and the same descriptor is already registered, the existing sink is returned.

If a sink with the same name but a different descriptor is already registered, a configuration conflict is raised.

Parameters:

  • name (str) – package-level sink name.

  • sink_cls (LogSinkClassProto) – sink class implementing the package-managed sink factory contract.

  • sink_kwargs (Any) – sink-specific configuration arguments passed to sink_cls.build_descriptor() and sink_cls.create().

Return type:

LogSinkProto

Returns:

configured log sink.

Raises:
mvx.common.logger.get_log_sink(name)

Return a package-level sink by name.

Parameters:

name (str) – package-level sink name.

Return type:

LogSinkProto | None

Returns:

registered sink, or None if no sink is registered under this name.

Raises:

  • TypeError – if name is not a string.

  • ValueError – if name is malformed.

mvx.common.logger.get_configured_log_sink_names()

Return names of package-level configured sinks.

Return type:

tuple[str, ...]

Returns:

tuple of registered sink names.

mvx.common.logger.has_configured_log_sinks()

Return whether the package-level sink registry contains any sinks.

Return type:

bool

Returns:

True if at least one sink is registered, False otherwise.

mvx.common.logger.close_log_sink(name)

Close and unregister a package-level sink by name.

If no sink is registered under name, the function returns False.

A sink cannot be closed while it is locally assigned to any package-level registered context. In that case, LogSinkIsInUseError is raised.

On successful close, the sink is removed from the registry and its terminator is called.

Parameters:

name (str) – package-level sink name.

Return type:

bool

Returns:

True if a registered sink was closed, False if the name was not registered.

Raises:

  • TypeError – if name is not a string.

  • ValueError – if name is malformed.

  • LogSinkIsInUseError – if the sink is locally assigned to one or more registered contexts.

  • LogSinkCloseError – if the sink terminator fails.

Context facade

The context facade manages package-level log contexts.

mvx.common.logger.get_root_log_context()

Return the package-level root log context.

The root context is created during package bootstrap and provides the default logging infrastructure for package-managed child contexts.

Return type:

LogContext

Returns:

root log context.

mvx.common.logger.get_log_context(namespace)

Return a package-level log context by namespace.

Parameters:

namespace (str) – registered context namespace.

Return type:

LogContext | None

Returns:

log context registered under namespace, or None if no such context exists.

Raises:

  • TypeError – if namespace is not a string.

  • ValueError – if namespace is empty or malformed.

mvx.common.logger.configure_log_context(namespace, *, log_sink=None, event_policy=None, payload_processor=None, log_error_handling_policy=None)

Create or update a package-level log context.

If the namespace already exists, only explicitly supplied local components are updated. Passing None does not reset an existing local component.

If the namespace does not exist, missing parent contexts are created automatically and the supplied components are applied only to the requested leaf context.

Parameters:

  • namespace (str) – context namespace to configure.

  • log_sink (LogSinkProto | None) – optional local sink for the configured context.

  • event_policy (LogEventPolicyProto | None) – optional local event policy for the configured context.

  • payload_processor (LogPayloadProcessorProto | None) – optional local payload processor for the configured context.

  • log_error_handling_policy (LogErrorHandlingPolicy | None) – optional local logging infrastructure error handling policy for the configured context.

Return type:

LogContext

Returns:

created or updated log context.

Raises:

  • TypeError – if namespace is not a string.

  • ValueError – if namespace is empty or malformed.

mvx.common.logger.get_log_context_namespaces()

Return namespaces of package-level registered log contexts.

The returned tuple includes the root context namespace.

Return type:

tuple[str, ...]

Returns:

tuple of registered context namespaces.

mvx.common.logger.has_log_context(namespace)

Return whether a package-level log context exists for the namespace.

Parameters:

namespace (str) – context namespace to check.

Return type:

bool

Returns:

True if a context is registered under namespace, False otherwise.

Raises:

  • TypeError – if namespace is not a string.

  • ValueError – if namespace is empty or malformed.

mvx.common.logger.reset_log_contexts()

Remove all package-level non-root log contexts.

The root context remains registered. Registered sinks are not closed or removed.

Return type:

None

Returns:

None.

Full logger reset

reset_logger() resets package-level logger state.

mvx.common.logger.reset_logger()

Reset package-level logger state.

The function closes all package-level registered sinks, clears package-level registries, and recreates the default bootstrap state.

Return type:

None

Returns:

None.

Raises:

LogSinkCloseError – if one or more registered sink terminators fail during reset.