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.
- type ictruck.vehicles.ActiveFlavors = ictruck.vehicles.Omniflavor | frozenset[int | str]¶
- type ictruck.vehicles.ActiveFlavorsLiberal = ictruck.vehicles.Omniflavor | collections.abc.Sequence[int | str] | collections.abc.Set[int | str]¶
- type ictruck.vehicles.ActiveFlavorsRegistry = frigid.dictionaries.Dictionary[str | None, ictruck.vehicles.Omniflavor | frozenset[int | str]]¶
- type ictruck.vehicles.ActiveFlavorsRegistryLiberal = collections.abc.Mapping[str | None, ictruck.vehicles.Omniflavor | collections.abc.Sequence[int | str] | collections.abc.Set[int | str]]¶
- type ictruck.vehicles.ModulesConfigurationsRegistryLiberal = collections.abc.Mapping[str, ictruck.configuration.ModuleConfiguration]¶
- type ictruck.vehicles.ReportersRegistry = accretive.dictionaries.Dictionary[tuple[str, int | str], icecream.icecream.IceCreamDebugger]¶
- type ictruck.vehicles.TraceLevelsRegistryLiberal = collections.abc.Mapping[str | None, int]¶
- ictruck.vehicles.modulecfgs: ictruck.vehicles.ModulesConfigurationsRegistry = ictruck.vehicles.ModulesConfigurationsRegistry( {'ictruck': ModuleConfiguration(flavors=frigid.dictionaries.Dictionary( {'note': FlavorConfiguration(formatter_factory=None, include_context=None, prefix_emitter='NOTE| '), 'error': FlavorConfiguration(formatter_factory=None, include_context=None, prefix_emitter='ERROR| ')} ), formatter_factory=None, include_context=None, prefix_emitter=None)} )¶
- ictruck.vehicles.omniflavor: ictruck.vehicles.Omniflavor = <Omniflavor.Instance: 1>¶
- type ictruck.vehicles.ProduceTruckActiveFlavorsArgument = ictruck.vehicles.Omniflavor | collections.abc.Sequence[int | str] | collections.abc.Set[int | str] | collections.abc.Mapping[str | None, ictruck.vehicles.Omniflavor | collections.abc.Sequence[int | str] | collections.abc.Set[int | str]] | absence.objects.AbsentSingleton¶
- type ictruck.vehicles.ProduceTruckEvnActiveFlavorsArgument = str | None | absence.objects.AbsentSingleton¶
- type ictruck.vehicles.ProduceTruckEvnTraceLevelsArgument = str | None | absence.objects.AbsentSingleton¶
- type ictruck.vehicles.ProduceTruckFlavorsArgument = collections.abc.Mapping[int | str, ictruck.configuration.FlavorConfiguration] | absence.objects.AbsentSingleton¶
- type ictruck.vehicles.ProduceTruckGeneralcfgArgument = ictruck.configuration.VehicleConfiguration | absence.objects.AbsentSingleton¶
- type ictruck.vehicles.ProduceTruckModulecfgsArgument = collections.abc.Mapping[str, ictruck.configuration.ModuleConfiguration] | absence.objects.AbsentSingleton¶
- type ictruck.vehicles.ProduceTruckPrinterFactoryArgument = io.TextIOBase | collections.abc.Callable[[str, int | str], collections.abc.Callable[[str], None]] | absence.objects.AbsentSingleton¶
- type ictruck.vehicles.ProduceTruckTraceLevelsArgument = int | collections.abc.Mapping[str | None, int] | absence.objects.AbsentSingleton¶
- type ictruck.vehicles.RegisterModuleFormatterFactoryArgument = collections.abc.Callable[[ictruck.configuration.FormatterControl, str, int | str], collections.abc.Callable[[typing_extensions.Any], str]] | absence.objects.AbsentSingleton¶
- type ictruck.vehicles.RegisterModuleIncludeContextArgument = bool | absence.objects.AbsentSingleton¶
- type ictruck.vehicles.RegisterModulePrefixEmitterArgument = str | collections.abc.Callable[[str, int | str], str] | absence.objects.AbsentSingleton¶
- 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.
- Variables:
Instance (ictruck.vehicles.Omniflavor)
- 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:
DataclassObject
Vends flavors of Icecream debugger.
- Variables:
active_flavors (frigid.dictionaries.Dictionary[ str | None, ictruck.vehicles.Omniflavor | frozenset[ int | str ] ]) –
Mapping of module names to active flavor sets.
Key
None
applies globally. Module-specific entries override globals for that module.generalcfg (ictruck.configuration.VehicleConfiguration) –
General configuration.
Top of configuration inheritance hierarchy. Default is suitable for application use.
modulecfgs (ictruck.vehicles.ModulesConfigurationsRegistry) –
Registry of per-module configurations.
Modules inherit configuration from their parent packages. Top-level packages inherit from general instance configruration.
printer_factory (io.TextIOBase | collections.abc.Callable[ [ str, int | str ], collections.abc.Callable[ [ str ], None ] ]) –
Factory which produces callables to output text somewhere.
May also be writable text stream. Factories take two arguments, module name and flavor, and return a callable which takes one argument, the string produced by a formatter.
trace_levels (frigid.dictionaries.Dictionary[ str | None, int ]) –
Mapping of module names to maximum trace depths.
Key
None
applies globally. Module-specific entries override globals for that module._debuggers (accretive.dictionaries.Dictionary[ tuple[ str, int | str ], icecream.icecream.IceCreamDebugger ]) – Cache of debugger instances by module and flavor.
_debuggers_lock (_thread.allocate_lock) – Access lock for cache of debugger instances.
- 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.- Parameters:
self
alias (str)
- Return type:
typing_extensions.Self
- 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.
- Parameters:
self
name (str | absence.objects.AbsentSingleton)
configuration (ictruck.configuration.ModuleConfiguration | absence.objects.AbsentSingleton)
- Return type:
typing_extensions.Self
- 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.- Parameters:
alias (str) – Alias under which the truck is installed in builtins.
active_flavors (ictruck.vehicles.Omniflavor | collections.abc.Sequence[ int | str ] | collections.abc.Set[ int | str ] | collections.abc.Mapping[ str | None, ictruck.vehicles.Omniflavor | collections.abc.Sequence[ int | str ] | collections.abc.Set[ int | str ] ] | absence.objects.AbsentSingleton) –
Flavors to activate.
Can be collection, which applies globally across all registered modules. Or, can be mapping of module names to sets.
Module-specific entries merge with global entries.
generalcfg (ictruck.configuration.VehicleConfiguration | absence.objects.AbsentSingleton) –
General configuration for the truck.
Top of configuration inheritance hierarchy. If absent, defaults to a suitable configuration for application use.
printer_factory (io.TextIOBase | collections.abc.Callable[ [ str, int | str ], collections.abc.Callable[ [ str ], None ] ] | absence.objects.AbsentSingleton) –
Factory which produces callables to output text somewhere.
May also be writable text stream. Factories take two arguments, module name and flavor, and return a callable which takes one argument, the string produced by a formatter.
If absent, uses a default.
trace_levels (int | collections.abc.Mapping[ str | None, int ] | absence.objects.AbsentSingleton) –
Maximum trace depths.
Can be an integer, which applies globally across all registered modules. Or, can be a mapping of module names to integers.
Module-specific entries override global entries.
evname_active_flavors (str | None | absence.objects.AbsentSingleton) –
Name of environment variable for active flavors or
None
.If absent, then a default environment variable name is used.
If
None
, then active flavors are not parsed from the process environment.If active flavors are supplied directly to a function, which also accepts this argument, then active flavors are not parsed from the process environment.
evname_trace_levels (str | None | absence.objects.AbsentSingleton) –
Name of environment variable for trace levels or
None
.If absent, then a default environment variable name is used.
If
None
, then trace levels are not parsed from the process environment.If trace levels are supplied directly to a function, which also accepts this argument, then trace levels are not parsed from the process environment.
- Return type:
- 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.
- Parameters:
active_flavors (ictruck.vehicles.Omniflavor | collections.abc.Sequence[ int | str ] | collections.abc.Set[ int | str ] | collections.abc.Mapping[ str | None, ictruck.vehicles.Omniflavor | collections.abc.Sequence[ int | str ] | collections.abc.Set[ int | str ] ] | absence.objects.AbsentSingleton) –
Flavors to activate.
Can be collection, which applies globally across all registered modules. Or, can be mapping of module names to sets.
Module-specific entries merge with global entries.
generalcfg (ictruck.configuration.VehicleConfiguration | absence.objects.AbsentSingleton) –
General configuration for the truck.
Top of configuration inheritance hierarchy. If absent, defaults to a suitable configuration for application use.
modulecfgs (collections.abc.Mapping[ str, ictruck.configuration.ModuleConfiguration ] | absence.objects.AbsentSingleton) –
Module configurations for the truck.
If absent, defaults to global modules registry.
printer_factory (io.TextIOBase | collections.abc.Callable[ [ str, int | str ], collections.abc.Callable[ [ str ], None ] ] | absence.objects.AbsentSingleton) –
Factory which produces callables to output text somewhere.
May also be writable text stream. Factories take two arguments, module name and flavor, and return a callable which takes one argument, the string produced by a formatter.
If absent, uses a default.
trace_levels (int | collections.abc.Mapping[ str | None, int ] | absence.objects.AbsentSingleton) –
Maximum trace depths.
Can be an integer, which applies globally across all registered modules. Or, can be a mapping of module names to integers.
Module-specific entries override global entries.
evname_active_flavors (str | None | absence.objects.AbsentSingleton) –
Name of environment variable for active flavors or
None
.If absent, then a default environment variable name is used.
If
None
, then active flavors are not parsed from the process environment.If active flavors are supplied directly to a function, which also accepts this argument, then active flavors are not parsed from the process environment.
evname_trace_levels (str | None | absence.objects.AbsentSingleton) –
Name of environment variable for trace levels or
None
.If absent, then a default environment variable name is used.
If
None
, then trace levels are not parsed from the process environment.If trace levels are supplied directly to a function, which also accepts this argument, then trace levels are not parsed from the process environment.
- Return type:
- 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.- Parameters:
name (str | absence.objects.AbsentSingleton) –
Name of the module to register.
If absent, infers the current module name.
flavors (collections.abc.Mapping[ int | str, ictruck.configuration.FlavorConfiguration ] | absence.objects.AbsentSingleton) – Registry of flavor identifiers to configurations.
formatter_factory (collections.abc.Callable[ [ ictruck.configuration.FormatterControl, str, int | str ], collections.abc.Callable[ [ typing_extensions.Any ], str ] ] | absence.objects.AbsentSingleton) –
Factory which produces formatter callable.
Takes formatter control, module name, and flavor as arguments. Returns formatter to convert an argument to a string.
include_context (bool | absence.objects.AbsentSingleton) – Include stack frame with output?
prefix_emitter (str | collections.abc.Callable[ [ str, int | str ], str ] | absence.objects.AbsentSingleton) –
String or factory which produces output prefix string.
Factory takes formatter control, module name, and flavor as arguments. Returns prefix string.
- Return type:
Module ictruck.configuration
¶
Portions of configuration hierarchy.
- type ictruck.configuration.Formatter = collections.abc.Callable[[typing_extensions.Any], str]¶
- type ictruck.configuration.FormatterFactory = collections.abc.Callable[[ictruck.configuration.FormatterControl, str, int | str], collections.abc.Callable[[typing_extensions.Any], str]]¶
- type ictruck.configuration.PrefixEmitterUnion = str | collections.abc.Callable[[str, int | str], str]¶
- type ictruck.configuration.FlavorsRegistry = frigid.dictionaries.Dictionary[int | str, ictruck.configuration.FlavorConfiguration]¶
- type ictruck.configuration.FlavorsRegistryLiberal = collections.abc.Mapping[int | str, ictruck.configuration.FlavorConfiguration]¶
- class ictruck.configuration.FlavorConfiguration(*, formatter_factory=None, include_context=None, prefix_emitter=None)¶
Bases:
DataclassObject
Per-flavor configuration.
- Variables:
formatter_factory (collections.abc.Callable[ [ ictruck.configuration.FormatterControl, str, int | str ], collections.abc.Callable[ [ typing_extensions.Any ], str ] ] | None) –
Factory which produces formatter callable.
Takes formatter control, module name, and flavor as arguments. Returns formatter to convert an argument to a string.
Default
None
inherits from cumulative configuration.include_context (bool | None) –
Include stack frame with output?
Default
None
inherits from cumulative configuration.prefix_emitter (str | collections.abc.Callable[ [ str, int | str ], str ] | None) –
String or factory which produces output prefix string.
Factory takes formatter control, module name, and flavor as arguments. Returns prefix string.
Default
None
inherits from cumulative configuration.
- class ictruck.configuration.FormatterControl(*, columns_count_effective=None)¶
Bases:
DataclassObject
Contextual data for formatter and prefix factories.
- Variables:
columns_count_effective (int | None) –
Available line length after accounting for embellishments.
May be
None
if not determinable.
- class ictruck.configuration.ModuleConfiguration(*, flavors=<factory>, formatter_factory=None, include_context=None, prefix_emitter=None)¶
Bases:
DataclassObject
Per-module or per-package configuration.
- Variables:
flavors (frigid.dictionaries.Dictionary[ int | str, ictruck.configuration.FlavorConfiguration ]) – Registry of flavor identifiers to configurations.
formatter_factory (collections.abc.Callable[ [ ictruck.configuration.FormatterControl, str, int | str ], collections.abc.Callable[ [ typing_extensions.Any ], str ] ] | None) –
Factory which produces formatter callable.
Takes formatter control, module name, and flavor as arguments. Returns formatter to convert an argument to a string.
Default
None
inherits from cumulative configuration.include_context (bool | None) –
Include stack frame with output?
Default
None
inherits from cumulative configuration.prefix_emitter (str | collections.abc.Callable[ [ str, int | str ], str ] | None) –
String or factory which produces output prefix string.
Factory takes formatter control, module name, and flavor as arguments. Returns prefix string.
Default
None
inherits from cumulative configuration.
- class ictruck.configuration.VehicleConfiguration(*, flavors=<factory>, formatter_factory=<function VehicleConfiguration.<lambda>>, include_context=False, prefix_emitter='ic| ')¶
Bases:
DataclassObject
Per-vehicle configuration.
- Variables:
flavors (frigid.dictionaries.Dictionary[ int | str, ictruck.configuration.FlavorConfiguration ]) – Registry of flavor identifiers to configurations.
formatter_factory (collections.abc.Callable[ [ ictruck.configuration.FormatterControl, str, int | str ], collections.abc.Callable[ [ typing_extensions.Any ], str ] ]) –
Factory which produces formatter callable.
Takes formatter control, module name, and flavor as arguments. Returns formatter to convert an argument to a string.
include_context (bool) – Include stack frame with output?
prefix_emitter (str | collections.abc.Callable[ [ str, int | str ], str ]) –
String or factory which produces output prefix string.
Factory takes formatter control, module name, and flavor as arguments. Returns prefix string.
- ictruck.configuration.produce_default_flavors()¶
Produces flavors for trace depths 0 through 9.
- Return type:
frigid.dictionaries.Dictionary[ int | str, ictruck.configuration.FlavorConfiguration ]
Module ictruck.printers
¶
Printers, printer factories, and auxiliary functions and types.
- type ictruck.printers.Printer = collections.abc.Callable[[str], None]¶
- type ictruck.printers.PrinterFactory = collections.abc.Callable[[str, int | str], collections.abc.Callable[[str], None]]¶
- type ictruck.printers.PrinterFactoryUnion = io.TextIOBase | collections.abc.Callable[[str, int | str], collections.abc.Callable[[str], None]]¶
- ictruck.printers.produce_simple_printer(target, mname, flavor, force_color=False)¶
Produces printer which uses standard Python ‘print’.
- Parameters:
target (io.TextIOBase)
mname (str)
force_color (bool)
- Return type:
collections.abc.Callable[ [ str ], None ]
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)¶
-
Text stream invalid for use with Rich console.
- 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:
DataclassObject
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.
- Variables:
exc_info_discoverer (collections.abc.Callable[ [ ], tuple[ type[ BaseException ] | None, BaseException | None, builtins.traceback | None ] ]) – Returns information on current exception.
pid_discoverer (collections.abc.Callable[ [ ], int ]) – Returns ID of current process.
thread_discoverer (collections.abc.Callable[ [ ], threading.Thread ]) – Returns current thread.
time_formatter (collections.abc.Callable[ [ str ], str ]) – Returns current time in specified format.
- class ictruck.recipes.sundae.FlavorSpecification(*, color, emoji, label, stack=False)¶
Bases:
DataclassObject
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:
DataclassObject
Format control for prefix emission.
- Variables:
colorize (bool) – Attempt to colorize?
label_as (ictruck.recipes.sundae.PrefixLabelPresentations) –
How to present prefix label.
Words
: As words likeTRACE0
orERROR
.Emoji
: As emoji like🔎
or❌
.For both emoji and words:
Emoji | Words
.styles (accretive.dictionaries.Dictionary[ str, rich.style.Style ]) – Mapping of interpolant names to
rich
style objects.template (str) –
String format for prefix.
The following interpolants are supported:
flavor
: Decorated flavor.module_qname
: Qualified name of invoking module.timestamp
: Current timestamp, formatted as string.process_id
: ID of current process according to OS kernel.thread_id
: ID of current thread.thread_name
: Name of current thread.ts_format (str) –
String format for prefix timestamp.
Used by
time.strftime()
or equivalent.
- 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)¶
-
Argument class is invalid.
- exception ictruck.exceptions.AttributeNondisplacement(object_, name)¶
Bases:
Omnierror
,AttributeError
Cannot displace existing attribute.
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:
Object
,BaseException
Base for all exceptions raised by package API.