httk.core.report

Unified reporting for the httk logger hierarchy.

Library code reports diagnostics with logging.getLogger() under httk.*. Console/file handlers and per-task collections are consumers of that same record stream. Context is supplied at emission sites with extra={"context": ...}, as one string or a list of strings. A general level and optional per-context levels control each consumer; a context level can also demote a context by being higher than the general level.

rearm() lets a new task collect warnings already seen by an earlier task. With no configuration or collection, importing this module changes no logging or warnings state. Installing any handler on "httk", including the collecting handler, suppresses logging.lastResort for this hierarchy, so server processes using collect_reports() should also call configure_reporting() for console output.

Attributes

DEFAULT_LOGGER
LOG_LEVELS
DEFAULT_MAXIMUM_BYTES
DEFAULT_BACKUP_COUNT

Classes

JsonFormatter	Render one record as a single line of JSON.
ReportFilter	Accept records at a general or context-specific threshold.
ReportCollection	Store append-only records accepted by one collect_reports() block.

Functions

resolve_level(level)	Return the numeric level for a protocol log-level name.
context_logger(logger, *contexts)	Return an adapter which attaches contexts to every record.
configure_reporting(*[, level, json_logs, ...])	Install one console handler for a reporting logger hierarchy.
add_report_file(path, *[, level, json_logs, ...])	Add one rotating report file handler and return the path it writes.
reset_reporting([logger])	Remove the reporting handlers installed for logger.
collect_reports([level, context_levels, rearm])	Collect records for the current context until the with block exits.
active_collections()	Return the collect_reports() collections active in this context.
rearm()	Invalidate warning deduplication caches without changing warning policy.

Module Contents

httk.core.report.DEFAULT_LOGGER = 'httk'

httk.core.report.LOG_LEVELS = ('debug', 'info', 'warning', 'error', 'critical')

httk.core.report.DEFAULT_MAXIMUM_BYTES = 4194304

httk.core.report.DEFAULT_BACKUP_COUNT = 3

class httk.core.report.JsonFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: logging.Formatter

Render one record as a single line of JSON.

format(record)

Render record as one JSON line, including non-standard fields.

Parameters:

record (logging.LogRecord) – Log record to serialize.

Returns:

JSON text containing the record’s report fields.

Return type:

str

httk.core.report.resolve_level(level)

Return the numeric level for a protocol log-level name.

Parameters:

level (str | int) – Numeric level or case-insensitive logging level name.

Returns:

Numeric logging threshold.

Raises:

ValueError – If level is not a recognized logging level name.

Return type:

int

class httk.core.report.ReportFilter(level='warning', context_levels=None)

Bases: logging.Filter

Accept records at a general or context-specific threshold.

A context threshold replaces the general threshold for records carrying that context, so it can deliberately demote a noisy context by using a higher level.

Parameters:

• level (str | int) – General minimum level for records without an overriding context.

• context_levels (collections.abc.Mapping[str, str | int] | None) – Optional per-context minimum levels.

level

context_levels

minimum_level

filter(record)

Return whether record meets its applicable reporting threshold.

Parameters:

record (logging.LogRecord) – Log record to test against the general or context level.

Returns:

Whether the record should be handled.

Return type:

bool

httk.core.report.context_logger(logger, *contexts)

Return an adapter which attaches contexts to every record.

Passed adapters are flattened so their extra values survive logging’s default adapter processing. Custom adapter process() logic is deliberately bypassed.

Parameters:

• logger (logging.Logger | logging.LoggerAdapter) – Logger or adapter whose records receive the contexts.

• *contexts (str) – Context names to attach to each emitted record.

Returns:

A logger adapter that merges these contexts with call-specific ones.

Return type:

logging.LoggerAdapter

httk.core.report.configure_reporting(*, level='warning', json_logs=False, context_levels=None, capture_warnings=False, logger=DEFAULT_LOGGER)

Install one console handler for a reporting logger hierarchy.

The general level and optional per-context levels control admission to the handler. When requested, warning capture is rearmed and kept in the same logging pipeline.

Parameters:

• level (str | int) – General minimum level for reports.

• json_logs (bool) – Whether to render records as JSON lines.

• context_levels (collections.abc.Mapping[str, str | int] | None) – Optional minimum levels for named contexts.

• capture_warnings (bool) – Whether to route Python warnings through logging.

• logger (str) – Logger hierarchy that receives the handler.

Raises:

ValueError – If a supplied log level is not recognized.

httk.core.report.add_report_file(path, *, level='info', json_logs=False, context_levels=None, maximum_bytes=DEFAULT_MAXIMUM_BYTES, backup_count=DEFAULT_BACKUP_COUNT, logger=DEFAULT_LOGGER)

Add one rotating report file handler and return the path it writes.

Parameters:

• path (pathlib.Path) – File path for the rotating report log.

• level (str | int) – General minimum level for reports.

• json_logs (bool) – Whether to render records as JSON lines.

• context_levels (collections.abc.Mapping[str, str | int] | None) – Optional minimum levels for named contexts.

• maximum_bytes (int) – Maximum size of one report file before rotation.

• backup_count (int) – Number of rotated report files to retain.

• logger (str) – Logger hierarchy that receives the handler.

Returns:

The report path supplied by the caller.

Raises:

ValueError – If a supplied log level is not recognized.

Return type:

pathlib.Path

httk.core.report.reset_reporting(logger=DEFAULT_LOGGER)

Remove the reporting handlers installed for logger.

Parameters:

logger (str) – Logger hierarchy whose handlers are reset.

class httk.core.report.ReportCollection(report_filter)

Store append-only records accepted by one collect_reports() block.

Parameters:

report_filter (ReportFilter) – Threshold policy used to accept records.

records: list[logging.LogRecord] = []

filter

httk.core.report.collect_reports(level='warning', *, context_levels=None, rearm=True)

Collect records for the current context until the with block exits.

Warning-registry invalidation is process-global. Concurrent collection scopes can double-collect or zero-collect repeated warnings, so callers should avoid task switches inside the block or pass rearm=False.

The active collections are stored in a contextvars.ContextVar, so nested and copied execution contexts retain their own collection scope. Entering a collection installs the shared collecting handler and captures warnings; by default it rearms warning registries first. Exiting restores the prior collection scope and warning-capture state.

Parameters:

• level (str | int) – General minimum level for collected records.

• context_levels (collections.abc.Mapping[str, str | int] | None) – Optional minimum levels for named contexts.

• rearm (bool) – Whether to invalidate warning deduplication before collection.

Returns:

A context manager yielding the collection for the current context.

Raises:

ValueError – If a supplied log level is not recognized.

Return type:

contextlib.AbstractContextManager[ReportCollection]

httk.core.report.active_collections()

Return the collect_reports() collections active in this context.

Outermost first; the last entry is the innermost enclosing block. Code that presents collected records (for example a server building a response) reads them from here instead of threading a collection through call signatures.

Returns:

Active collections from the outermost to the innermost scope.

Return type:

tuple[ReportCollection, Ellipsis]

httk.core.report.rearm()

Invalidate warning deduplication caches without changing warning policy.

CPython’s warnings._filters_mutated is the primary mechanism used by warnings.catch_warnings. Other implementations get an identical temporary public filter entry, whose version bump is retained after it is removed. This is process-global: overlapping collection scopes in tasks can double-collect or zero-collect repeated warnings; avoid task switches in a collection block or use rearm=False.