API

Package ictruck

Flexible factory for Icecream debuggers.

A debugging library that enhances the icecream package with flexible, flavorful traces and module-specific configurations. Designed for both application and library developers, it provides granular control over debug output while ensuring isolation between different configurations.

The package organizes its functionality across several modules, providing exceptions, configuration hierarchies, and specialized output recipes.

Module ictruck.vehicles

Vehicles which vend flavors of Icecream debugger.

class ictruck.vehicles.ModulesConfigurationsRegistry(*iterables, **entries)

Bases: Dictionary[str, ModuleConfiguration]

Accretive dictionary specifically for module registrations.

class ictruck.vehicles.Omniflavor(value)

Bases: Enum

Singleton to match any flavor.

class ictruck.vehicles.Truck(*, active_flavors=<factory>, generalcfg=<factory>, modulecfgs=<factory>, printer_factory=functools.partial(<function produce_simple_printer>, <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>), trace_levels=<factory>, _debuggers=<factory>, _debuggers_lock=<factory>)

Bases: object

Vends flavors of Icecream debugger.

install(alias='ictr')

Installs truck into builtins with provided alias.

Replaces an existing truck. Preserves global module configurations.

Library developers should call register_module() instead.

register_module(name=absence.absent, configuration=absence.absent)

Registers configuration for module.

If no module or package name is given, then the current module is inferred.

If no configuration is provided, then a default is generated.

ictruck.vehicles.active_flavors_from_environment(evname=absence.absent)

Extracts active flavors from named environment variable.

ictruck.vehicles.install(alias='ictr', active_flavors=absence.absent, generalcfg=absence.absent, printer_factory=absence.absent, trace_levels=absence.absent, evname_active_flavors=absence.absent, evname_trace_levels=absence.absent)

Produces truck and installs it into builtins with alias.

Replaces an existing truck, preserving global module configurations.

Library developers should call register_module() instead.

ictruck.vehicles.produce_truck(active_flavors=absence.absent, generalcfg=absence.absent, modulecfgs=absence.absent, printer_factory=absence.absent, trace_levels=absence.absent, evname_active_flavors=absence.absent, evname_trace_levels=absence.absent)

Produces icecream truck with some shorthand argument values.

ictruck.vehicles.register_module(name=absence.absent, flavors=absence.absent, formatter_factory=absence.absent, include_context=absence.absent, prefix_emitter=absence.absent)

Registers module configuration on the builtin truck.

If no truck exists in builtins, installs one which produces null printers.

Intended for library developers to configure debugging flavors without overriding anything set by the application or other libraries. Application developers should call install() instead.

ictruck.vehicles.trace_levels_from_environment(evname=absence.absent)

Extracts trace levels from named environment variable.

Module ictruck.configuration

Portions of configuration hierarchy.

class ictruck.configuration.FlavorConfiguration(*, formatter_factory=None, include_context=None, prefix_emitter=None)

Bases: object

Per-flavor configuration.

class ictruck.configuration.FormatterControl(*, columns_count_effective=None)

Bases: object

Contextual data for formatter and prefix factories.

class ictruck.configuration.ModuleConfiguration(*, flavors=<factory>, formatter_factory=None, include_context=None, prefix_emitter=None)

Bases: object

Per-module or per-package configuration.

class ictruck.configuration.VehicleConfiguration(*, flavors=<factory>, formatter_factory=<function VehicleConfiguration.<lambda>>, include_context=False, prefix_emitter='ic| ')

Bases: object

Per-vehicle configuration.

ictruck.configuration.produce_default_flavors()

Produces flavors for trace depths 0 through 9.

Module ictruck.printers

Printers, printer factories, and auxiliary functions and types.

ictruck.printers.produce_simple_printer(target, mname, flavor, force_color=False)

Produces printer which uses standard Python ‘print’.

Module ictruck.recipes.logging

Recipes for integration with standard logging.

ictruck.recipes.logging.install(alias='ictr', additional_aliases=absence.absent)

Produces truck and installs it into builtins with alias.

Replaces an existing truck, preserving global module configurations.

Library developers should call __.register_module() instead.

ictruck.recipes.logging.produce_printer(mname, flavor)

Produces printer which maps flavors to logging levels.

ictruck.recipes.logging.produce_truck()

Produces icecream truck which integrates with standard logging.

Module ictruck.recipes.rich

Recipes for Rich formatters and printers.

Note

To use this module, you must have the rich package installed.

exception ictruck.recipes.rich.ConsoleTextIoInvalidity(stream)

Bases: Omnierror, TypeError

Text stream invalid for use with Rich console.

class ictruck.recipes.rich.Modes(value)

Bases: Enum

Operation modes for Rich truck.

ictruck.recipes.rich.install(alias='ictr', flavors=absence.absent, active_flavors=absence.absent, trace_levels=absence.absent, mode=Modes.Formatter, stderr=True)

Produces truck and installs it into builtins with alias.

Replaces an existing truck, preserving global module configurations.

Library developers should call __.register_module() instead.

ictruck.recipes.rich.produce_console_formatter(console, control, mname, flavor)

Produces formatter which uses Rich highlighter and prettier.

ictruck.recipes.rich.produce_console_printer(console, mname, flavor)

Produces a printer that uses Rich console printing.

Note

May reprocess ANSI SGR codes or markup from formatters, potentially causing visual artifacts. Be careful to use this only with “safe” formatters.

ictruck.recipes.rich.produce_pretty_formatter(control, mname, flavor)

Produces formatter which uses Rich prettier.

ictruck.recipes.rich.produce_truck(flavors=absence.absent, active_flavors=absence.absent, trace_levels=absence.absent, mode=Modes.Formatter, stderr=True)

Produces icecream truck which integrates with Rich.

ictruck.recipes.rich.register_module(name=absence.absent, flavors=absence.absent, include_context=absence.absent, prefix_emitter=absence.absent)

Registers module with Rich prettier to format arguments.

Intended for library developers to configure debugging flavors without overriding anything set by the application or other libraries.

Module ictruck.recipes.sundae

Recipe for advanced formatters.

Note

To use this module, you must have the rich package installed.

class ictruck.recipes.sundae.Auxiliaries(*, exc_info_discoverer=<built-in function exc_info>, pid_discoverer=<built-in function getpid>, thread_discoverer=<function current_thread>, time_formatter=<built-in function strftime>)

Bases: object

Auxiliary functions used by formatters and interpolation.

Typically used by unit tests to inject mock dependencies, but can also be used to deeply customize output.

class ictruck.recipes.sundae.FlavorSpecification(*, color, emoji, label, stack=False)

Bases: object

Specification for custom flavor.

class ictruck.recipes.sundae.PrefixDecorations(value)

Bases: IntFlag

Decoration styles for prefix emission.

class ictruck.recipes.sundae.PrefixFormatControl(*, colorize=True, label_as=<PrefixLabelPresentations.Words: 1>, styles=<factory>, template='{flavor}| ', ts_format='%Y-%m-%d %H:%M:%S.%f')

Bases: object

Format control for prefix emission.

class ictruck.recipes.sundae.PrefixLabelPresentations(value)

Bases: IntFlag

How prefix label should be presented.

ictruck.recipes.sundae.produce_module_configuration(colorize=absence.absent, prefix_label_as=absence.absent, prefix_styles=absence.absent, prefix_template=absence.absent, prefix_ts_format=absence.absent, console_factory=absence.absent, auxiliaries=absence.absent)

Produces module configuration with sundae-specific flavor settings.

ictruck.recipes.sundae.register_module(name=absence.absent, colorize=absence.absent, prefix_label_as=absence.absent, prefix_styles=absence.absent, prefix_template=absence.absent, prefix_ts_format=absence.absent, console_factory=absence.absent, auxiliaries=absence.absent)

Registers module with sundae-specific flavor configurations.

Module ictruck.exceptions

Family of exceptions for package API.

exception ictruck.exceptions.ArgumentClassInvalidity(name, classes)

Bases: Omnierror, TypeError

Argument class is invalid.

exception ictruck.exceptions.AttributeNondisplacement(object_, name)

Bases: Omnierror, AttributeError

Cannot displace existing attribute.

exception ictruck.exceptions.FlavorInavailability(flavor)

Bases: Omnierror, ValueError

Requested flavor is not available.

exception ictruck.exceptions.ModuleInferenceFailure

Bases: Omnierror, RuntimeError

Failure to infer invoking module from call stack.

exception ictruck.exceptions.Omnierror(*posargs, **nomargs)

Bases: Omniexception, Exception

Base for error exceptions raised by package API.

exception ictruck.exceptions.Omniexception(*posargs, **nomargs)

Bases: BaseException

Base for all exceptions raised by package API.