API

Package ictruck

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.

• Truck: Core class managing debugger instances with support for trace levels, custom flavors, and configurable output sinks.

• install: Installs a configured Truck instance into Python builtins for universal access.

• register_module: Registers module-specific configurations, ideal for libraries to define their own debugging behavior without affecting others.

• ModuleConfiguration: Defines per-module settings, including prefixes, flavors, and formatters, with inheritance from a global configuration.

• produce_logging_truck: Recipe for creating a Truck integrated with Python’s logging module.

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.

ictruck.vehicles.ActiveFlavors

alias of frozenset[int | str]

ictruck.vehicles.ActiveFlavorsRegistry

alias of Dictionary[str | None, frozenset[int | str]]

ictruck.vehicles.ActiveFlavorsRegistryLiberal

alias of Mapping[str | None, Sequence[int | str] | Set[int | str]]

ictruck.vehicles.Printer

alias of Callable[[str], None]

ictruck.vehicles.PrinterFactory

alias of Callable[[str, int | str], Callable[[str], None]]

ictruck.vehicles.TraceLevelsRegistry

alias of Dictionary[str | None, int]

ictruck.vehicles.TraceLevelsRegistryLiberal

alias of Mapping[str | None, int]

class ictruck.vehicles.Truck(*, active_flavors: ~frigid.dictionaries.Annotated[~frigid.dictionaries.Dictionary[str | None, frozenset[int | str]], Doc(' Mapping of module names to active flavor sets.\n\n                Key ``None`` applies globally. Module-specific entries\n                override globals for that module.\n            ')] = <factory>, generalcfg: ~ictruck.configuration.Annotated[~ictruck.configuration.VehicleConfiguration, Doc(' General configuration.\n\n                Top of configuration inheritance hierarchy.\n                Default is suitable for application use.\n            ')] = <factory>, modulecfgs: ~accretive.dictionaries.Annotated[~accretive.dictionaries.Dictionary[str, ~ictruck.configuration.ModuleConfiguration], Doc(' Registry of per-module configurations.\n\n                Modules inherit configuration from their parent packages.\n                Top-level packages inherit from general instance\n                configruration.\n            ')] = <factory>, printer_factory: ~types.Annotated[~io.TextIOBase | ~collections.abc.Callable[[str, int | str], ~collections.abc.Callable[[str], None]], Doc(' Factory which produces callables to output text somewhere.\n\n                May also be writable text stream.\n                Factories take two arguments, module name and flavor, and\n                return a callable which takes one argument, the string\n                produced by a formatter.\n            ')] = <factory>, trace_levels: ~frigid.dictionaries.Annotated[~frigid.dictionaries.Dictionary[str | None, int], Doc(' Mapping of module names to maximum trace depths.\n\n                Key ``None`` applies globally. Module-specific entries\n                override globals for that module.\n            ')] = <factory>, _debuggers: ~accretive.dictionaries.Annotated[~accretive.dictionaries.Dictionary[tuple[str, int | str], ~icecream.icecream.IceCreamDebugger], Doc(' Cache of debugger instances by module and flavor. ')] = <factory>, _debuggers_lock: ~_thread.Annotated[~_thread.allocate_lock, Doc(' Access lock for cache of debugger instances. ')] = <factory>)

Bases: object

Vends flavors of Icecream debugger.

install(alias: str = 'ictr') → Self

Installs truck into builtins with provided alias.

Replaces an existing truck, preserving its module configurations.

Library developers should call register_module() instead.

register_module(name: str | AbsentSingleton = absence.absent, configuration: ModuleConfiguration | AbsentSingleton = absence.absent) → Self

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.

active_flavors: Annotated[Dictionary[str | None, frozenset[int | str]], Doc(' Mapping of module names to active flavor sets.\n\n                Key ``None`` applies globally. Module-specific entries\n                override globals for that module.\n            ')]

generalcfg: Annotated[VehicleConfiguration, Doc(' General configuration.\n\n                Top of configuration inheritance hierarchy.\n                Default is suitable for application use.\n            ')]

modulecfgs: Annotated[Dictionary[str, ModuleConfiguration], Doc(' Registry of per-module configurations.\n\n                Modules inherit configuration from their parent packages.\n                Top-level packages inherit from general instance\n                configruration.\n            ')]

printer_factory: Annotated[TextIOBase | Callable[[str, int | str], Callable[[str], None]], Doc(' Factory which produces callables to output text somewhere.\n\n                May also be writable text stream.\n                Factories take two arguments, module name and flavor, and\n                return a callable which takes one argument, the string\n                produced by a formatter.\n            ')]

trace_levels: Annotated[Dictionary[str | None, int], Doc(' Mapping of module names to maximum trace depths.\n\n                Key ``None`` applies globally. Module-specific entries\n                override globals for that module.\n            ')]

ictruck.vehicles.install(alias: Annotated[str, Doc(' Alias under which the truck is installed in builtins. ')] = 'ictr', active_flavors: Annotated[Sequence[int | str] | Set[int | str] | Mapping[str | None, Sequence[int | str] | Set[int | str]] | AbsentSingleton, Doc(' Flavors to activate.\n\n            Can be collection, which applies globally across all registered\n            modules. Or, can be mapping of module names to sets.\n\n            Module-specific entries merge with global entries.\n        ')] = absence.absent, generalcfg: Annotated[VehicleConfiguration | AbsentSingleton, Doc(' General configuration for the truck.\n\n            Top of configuration inheritance hierarchy. If absent,\n            defaults to a suitable configuration for application use.\n        ')] = absence.absent, printer_factory: Annotated[TextIOBase | Callable[[str, int | str], Callable[[str], None]] | AbsentSingleton, Doc(' Factory which produces callables to output text somewhere.\n\n            May also be writable text stream.\n            Factories take two arguments, module name and flavor, and\n            return a callable which takes one argument, the string\n            produced by a formatter.\n\n            If absent, uses a default.\n        ')] = absence.absent, trace_levels: Annotated[int | Mapping[str | None, int] | AbsentSingleton, Doc(' Maximum trace depths.\n\n            Can be an integer, which applies globally across all registered\n            modules. Or, can be a mapping of module names to integers.\n\n            Module-specific entries override global entries.\n        ')] = absence.absent) → Truck

Produces truck and installs it into builtins with alias.

Replaces an existing truck, preserving its module configurations.

Library developers should call register_module() instead.

ictruck.vehicles.produce_truck(active_flavors: Annotated[Sequence[int | str] | Set[int | str] | Mapping[str | None, Sequence[int | str] | Set[int | str]] | AbsentSingleton, Doc(' Flavors to activate.\n\n            Can be collection, which applies globally across all registered\n            modules. Or, can be mapping of module names to sets.\n\n            Module-specific entries merge with global entries.\n        ')] = absence.absent, generalcfg: Annotated[VehicleConfiguration | AbsentSingleton, Doc(' General configuration for the truck.\n\n            Top of configuration inheritance hierarchy. If absent,\n            defaults to a suitable configuration for application use.\n        ')] = absence.absent, printer_factory: Annotated[TextIOBase | Callable[[str, int | str], Callable[[str], None]] | AbsentSingleton, Doc(' Factory which produces callables to output text somewhere.\n\n            May also be writable text stream.\n            Factories take two arguments, module name and flavor, and\n            return a callable which takes one argument, the string\n            produced by a formatter.\n\n            If absent, uses a default.\n        ')] = absence.absent, trace_levels: Annotated[int | Mapping[str | None, int] | AbsentSingleton, Doc(' Maximum trace depths.\n\n            Can be an integer, which applies globally across all registered\n            modules. Or, can be a mapping of module names to integers.\n\n            Module-specific entries override global entries.\n        ')] = absence.absent) → Truck

Produces icecream truck with some shorthand argument values.

ictruck.vehicles.register_module(name: Annotated[str | AbsentSingleton, Doc(' Name of the module to register.\n\n            If absent, infers the current module name.\n        ')] = absence.absent, flavors: Annotated[Mapping[int | str, FlavorConfiguration] | AbsentSingleton, Doc(' Registry of flavor identifiers to configurations. ')] = absence.absent, formatter_factory: Annotated[Callable[[FormatterControl, str, int | str], Callable[[Any], str]] | AbsentSingleton, Doc(' Factory which produces formatter callable.\n\n            Takes formatter control, module name, and flavor as arguments.\n            Returns formatter to convert an argument to a string.\n        ')] = absence.absent, include_context: Annotated[bool | AbsentSingleton, Doc(' Include stack frame with output? ')] = absence.absent, prefix_emitter: Annotated[str | Callable[[str, int | str], str] | AbsentSingleton, Doc(' String or factory which produces output prefix string.\n\n            Factory takes formatter control, module name, and flavor as\n            arguments. Returns prefix string.\n        ')] = absence.absent) → None

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.

Module ictruck.configuration

Portions of configuration hierarchy.

class ictruck.configuration.FlavorConfiguration(*, formatter_factory: Annotated[Callable[[FormatterControl, str, int | str], Callable[[Any], str]] | None, Doc(' Factory which produces formatter callable.\n\n                Takes formatter control, module name, and flavor as arguments.\n                Returns formatter to convert an argument to a string.\n\n                Default ``None`` inherits from cumulative configuration.\n            ')] | None = None, include_context: Annotated[bool | None, Doc(' Include stack frame with output?\n\n                Default ``None`` inherits from cumulative configuration.\n            ')] | None = None, prefix_emitter: Annotated[str | Callable[[str, int | str], str] | None, Doc(' String or factory which produces output prefix string.\n\n                Factory takes formatter control, module name, and flavor as\n                arguments. Returns prefix string.\n\n                Default ``None`` inherits from cumulative configuration.\n            ')] | None = None)

Bases: object

Per-flavor configuration.

formatter_factory: Annotated[Callable[[FormatterControl, str, int | str], Callable[[Any], str]] | None, Doc(' Factory which produces formatter callable.\n\n                Takes formatter control, module name, and flavor as arguments.\n                Returns formatter to convert an argument to a string.\n\n                Default ``None`` inherits from cumulative configuration.\n            ')]

include_context: Annotated[bool | None, Doc(' Include stack frame with output?\n\n                Default ``None`` inherits from cumulative configuration.\n            ')]

prefix_emitter: Annotated[str | Callable[[str, int | str], str] | None, Doc(' String or factory which produces output prefix string.\n\n                Factory takes formatter control, module name, and flavor as\n                arguments. Returns prefix string.\n\n                Default ``None`` inherits from cumulative configuration.\n            ')]

ictruck.configuration.FlavorsRegistry

alias of Dictionary[int | str, FlavorConfiguration]

ictruck.configuration.FlavorsRegistryLiberal

alias of Mapping[int | str, FlavorConfiguration]

class ictruck.configuration.FormatterControl(*, columns_count_effective: Annotated[int | None, Doc(' Available line length after accounting for embellishments.\n\n                May be ``None`` if not determinable.\n            ')] | None = None)

Bases: object

Contextual data for formatter and prefix factories.

columns_count_effective: Annotated[int | None, Doc(' Available line length after accounting for embellishments.\n\n                May be ``None`` if not determinable.\n            ')]

class ictruck.configuration.ModuleConfiguration(*, flavors: ~frigid.dictionaries.Annotated[~frigid.dictionaries.Dictionary[int | str, ~ictruck.configuration.FlavorConfiguration], Doc(' Registry of flavor identifiers to configurations. ')] = <factory>, formatter_factory: ~typing.Annotated[~typing.Callable[[~ictruck.configuration.FormatterControl, str, int | str], ~typing.Callable[[~typing_extensions.Any], str]] | None, Doc(' Factory which produces formatter callable.\n\n                Takes formatter control, module name, and flavor as arguments.\n                Returns formatter to convert an argument to a string.\n\n                Default ``None`` inherits from cumulative configuration.\n            ')] | None = None, include_context: ~typing.Annotated[bool | None, Doc(' Include stack frame with output?\n\n                Default ``None`` inherits from cumulative configuration.\n            ')] | None = None, prefix_emitter: ~typing.Annotated[str | ~typing.Callable[[str, int | str], str] | None, Doc(' String or factory which produces output prefix string.\n\n                Factory takes formatter control, module name, and flavor as\n                arguments. Returns prefix string.\n\n                Default ``None`` inherits from cumulative configuration.\n            ')] | None = None)

Bases: object

Per-module or per-package configuration.

flavors: Annotated[Dictionary[int | str, FlavorConfiguration], Doc(' Registry of flavor identifiers to configurations. ')]

formatter_factory: Annotated[Callable[[FormatterControl, str, int | str], Callable[[Any], str]] | None, Doc(' Factory which produces formatter callable.\n\n                Takes formatter control, module name, and flavor as arguments.\n                Returns formatter to convert an argument to a string.\n\n                Default ``None`` inherits from cumulative configuration.\n            ')]

include_context: Annotated[bool | None, Doc(' Include stack frame with output?\n\n                Default ``None`` inherits from cumulative configuration.\n            ')]

prefix_emitter: Annotated[str | Callable[[str, int | str], str] | None, Doc(' String or factory which produces output prefix string.\n\n                Factory takes formatter control, module name, and flavor as\n                arguments. Returns prefix string.\n\n                Default ``None`` inherits from cumulative configuration.\n            ')]

class ictruck.configuration.VehicleConfiguration(*, flavors: ~frigid.dictionaries.Annotated[~frigid.dictionaries.Dictionary[int | str, ~ictruck.configuration.FlavorConfiguration], Doc(' Registry of flavor identifiers to configurations. ')] = <factory>, formatter_factory: ~typing.Annotated[~typing.Callable[[~ictruck.configuration.FormatterControl, str, int | str], ~typing.Callable[[~typing_extensions.Any], str]], Doc(' Factory which produces formatter callable.\n\n                Takes formatter control, module name, and flavor as arguments.\n                Returns formatter to convert an argument to a string.\n            ')] = <function VehicleConfiguration.<lambda>>, include_context: ~typing.Annotated[bool, Doc(' Include stack frame with output? ')] = False, prefix_emitter: ~typing.Annotated[str | ~typing.Callable[[str, int | str], str], Doc(' String or factory which produces output prefix string.\n\n                Factory takes formatter control, module name, and flavor as\n                arguments. Returns prefix string.\n            ')] = 'ic| ')

Bases: object

Per-vehicle configuration.

flavors: Annotated[Dictionary[int | str, FlavorConfiguration], Doc(' Registry of flavor identifiers to configurations. ')]

formatter_factory: Annotated[Callable[[FormatterControl, str, int | str], Callable[[Any], str]], Doc(' Factory which produces formatter callable.\n\n                Takes formatter control, module name, and flavor as arguments.\n                Returns formatter to convert an argument to a string.\n            ')]

include_context: Annotated[bool, Doc(' Include stack frame with output? ')]

prefix_emitter: Annotated[str | Callable[[str, int | str], str], Doc(' String or factory which produces output prefix string.\n\n                Factory takes formatter control, module name, and flavor as\n                arguments. Returns prefix string.\n            ')]

ictruck.configuration.produce_default_flavors() → Dictionary[int | str, FlavorConfiguration]

Produces flavors for trace depths 0 through 9.

Module ictruck.recipes

Useful icecream recipes which our trucks can vend.

Module ictruck.exceptions

Family of exceptions for package API.

exception ictruck.exceptions.ArgumentClassInvalidity(name: str, classes: type | tuple[type, ...])

Bases: Omnierror, TypeError

Argument class is invalid.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception ictruck.exceptions.AttributeNondisplacement(object_: Any, name: str)

Bases: Omnierror, AttributeError

Cannot displace existing attribute.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

name

attribute name

obj

object

exception ictruck.exceptions.FlavorInavailability(flavor: int | str)

Bases: Omnierror, ValueError

Requested flavor is not available.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception ictruck.exceptions.ModuleInferenceFailure

Bases: Omnierror, RuntimeError

Failure to infer invoking module from call stack.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

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

Bases: Omniexception, Exception

Base for error exceptions raised by package API.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

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

Bases: BaseException

Base for all exceptions raised by package API.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args