Configuration options

Updated Nov 11, 2025

basicConfig

  • Accepts level, filename, stream (sys.stdout or sys.stderr), force, and handlers (an iterable of handler objects) either via keyword arguments or the BasicConfig dataclass.
  • filename and stream are mutually exclusive and cannot be combined with the handlers argument.
  • Passing force=True clears existing handlers on the root logger before installing the new one.
  • Formatting parameters (format, datefmt, and friends) are intentionally unsupported until formatter customization lands.

ConfigBuilder (imperative API)

from femtologging import (
    ConfigBuilder,
    LoggerConfigBuilder,
    StreamHandlerBuilder,
    FileHandlerBuilder,
    OverflowPolicy,
    LevelFilterBuilder,
)

builder = (
    ConfigBuilder()
    .with_handler("console", StreamHandlerBuilder.stderr())
    .with_handler(
        "audit",
        FileHandlerBuilder("/var/log/app.log").with_overflow_policy(
            OverflowPolicy.block()
        ),
    )
    .with_filter("info_only", LevelFilterBuilder().with_max_level("INFO"))
    .with_logger(
        "app.audit",
        LoggerConfigBuilder()
        .with_level("INFO")
        .with_handlers(["audit"])
        .with_filters(["info_only"])
        .with_propagate(False),
    )
    .with_root_logger(LoggerConfigBuilder().with_level("WARNING").with_handlers(["console"]))
)

builder.build_and_init()
  • with_default_level(level) sets a fallback for loggers that omit explicit levels. with_disable_existing_loggers(True) clears handlers and filters on previously created loggers that are not part of the new configuration (their ancestors are preserved automatically).
  • Only two filter builders exist today: LevelFilterBuilder and NameFilterBuilder. Filters are applied in the order they are declared in each LoggerConfigBuilder.
  • Formatter registration (with_formatter(id, FormatterBuilder)) is currently a placeholder. Registered formatters are stored in the serialized config, but handlers still treat any string other than "default" as unknown and raise HandlerConfigError.

dictConfig (restricted compatibility layer)

  • Supported handler classes: logging.StreamHandler, femtologging.StreamHandler, logging.FileHandler, femtologging.FileHandler, logging.handlers.RotatingFileHandler, and logging.handlers.SocketHandler (plus their femtologging equivalents).
  • Handler args are evaluated with ast.literal_eval, matching the stdlib behaviour for simple tuples. For socket handlers you can pass either (host, port) or a single Unix socket path; keyword arguments mirror the builder API (host, port, unix_path, capacity, connect_timeout_ms, write_timeout_ms, max_frame_size, tls, tls_domain, tls_insecure, backoff_* aliases).
  • Unsupported stdlib features raise ValueError: incremental updates, top-level filters sections, handler level, handler filters, and handler formatters. Although the schema accepts a formatters section, referencing a formatter from a handler currently results in ValueError("unknown formatter id").
  • A root section is mandatory. Named loggers support level, handlers, and propagate (bool).

fileConfig (INI compatibility)

  • fileConfig(path, defaults=None, disable_existing_loggers=True, encoding=None) parses CPython-style INI files via the Rust extension and translates them to the restricted dictConfig schema.
  • Default substitutions (%(foo)s) work across the INI file and any mapping you pass via defaults.
  • Formatters and handler-level overrides are not supported. Including [formatter_*] sections or specifying level/formatter inside [handler_*] entries raises ValueError.