0.2.0

This version adds a new structured logger layer to mvx-common.

The logger is not a thin wrapper around Python’s standard logging package. It introduces a small structured logging system with explicit event metadata, payload processing, context-based configuration, event policies, sink abstraction, and operation-level logging through log_invocation.

The main goal is to support library-grade structured diagnostics without forcing one global logging configuration or one delivery backend.

Added

Structured event model

Added the core event model:

LogLevel
LogEventMeta
LogEvent

These types describe structured log events before they are delivered to sinks.

Log contexts

Added LogContext as the main object-level coordinator of the logging pipeline.

A context can:

build event metadata
apply local event policy
normalize payload data
create LogEvent objects
emit events through the effective sink
handle logging infrastructure errors

Context configuration supports inheritance for sink, payload processor, and logging error handling policy.

Event policy remains local to the context.

Package-level logger facade

Added package-level functions for configuring and accessing logger-wide resources:

configure_log_sink()
get_log_sink()
close_log_sink()
reset_logger()

configure_log_context()
get_log_context()
get_root_log_context()
reset_log_contexts()

These functions provide a registry-based setup path for applications that want named shared sinks and contexts.

Payload processing

Added the payload-processing layer.

The base abstractions are:

LogPayloadProcessorProto
LogPayloadProvider

The default implementation is:

LogPayloadProcessor

The default processor supports bounded payload normalization, verbosity levels, object-owned payload representation through LogPayloadProvider, and type-based adapters.

Event policies

Added LogEventPolicyProto for metadata-based event selection.

Policies receive LogEventMeta and decide whether an event should enter the logging pipeline.

Sink abstraction

Added the sink contract layer:

LogSinkProto
LogSinkDescriptor
LogSinkClassProto
LogSinkTerminator

This makes it possible to use direct sinks or package-managed sinks with descriptor-based idempotence and conflict detection.

Ready-to-use sinks

Added ready-to-use sinks backed by Python’s standard logging package:

StreamLogSink
FileLogSink

StreamLogSink targets stdout or stderr.

FileLogSink writes to a configured file and uses the async sink runtime for delivery.

Async sink runtime

Added AsyncioLogSink as a reusable base for custom sinks that need asynchronous backend delivery behind the synchronous log(event) sink boundary.

It provides:

thread-safe event acceptance
lazy startup
queueing and pending-event accounting
overflow handling
start/stop lifecycle
wait handles
package-managed threaded runtime creation

Concrete subclasses provide descriptor identity and backend-specific event delivery.

Operation-level logging

Added the log_invocation component.

log_invocation is a decorator for public API methods. It records operation lifecycle outcomes:

invoke
success
failed
cancelled

The component supports context resolution, entity id resolution, selected argument logging, context fields, result logging, verbosity-gated fields, error/cancellation handling, and custom payload shaping through context_formatter.

Documentation

Added a full documentation section for the logger.

The documentation describes both ordinary usage and extension points for library authors and custom integrations.