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.
Assorted recipes for extending the core functionality of the package.

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.ActiveFlavorsRegistry¶: alias of Dictionary[str | None, Omniflavor | frozenset[int | str]]

ictruck.vehicles.ActiveFlavorsRegistryLiberal¶: alias of Mapping[str | None, Omniflavor | Sequence[int | str] | Set[int | str]]

class ictruck.vehicles.ModulesConfigurationsRegistry(*iterables: Annotated[Mapping[str, ModuleConfiguration] | Iterable[tuple[str, ModuleConfiguration]], Doc('Zero or more iterables from which to initialize dictionary data. Each iterable must be dictionary or sequence of key-value pairs. Duplicate keys will result in an error.')], **entries: Annotated[ModuleConfiguration, Doc('Zero or more keyword arguments from which to initialize dictionary data.')])¶

Bases: Dictionary[str, ModuleConfiguration]

Accretive dictionary specifically for module registrations.

copy() → Self¶: Provides fresh copy of dictionary.

get(key: H, default: V | AbsentSingleton = absence.absent) → Annotated[V, Doc('Value of entry, if it exists. Else, supplied default value or ``None``.')]¶: Retrieves entry associated with key, if it exists.

items() → ItemsView[H, V]¶: Provides iterable view over dictionary items.

keys() → KeysView[H]¶: Provides iterable view over dictionary keys.

setdefault(key: H, default: V) → V¶: Returns value for key, setting it to default if missing.

update(*iterables: Annotated[Mapping[H, V] | Iterable[tuple[H, V]], Doc('Zero or more iterables from which to initialize dictionary data. Each iterable must be dictionary or sequence of key-value pairs. Duplicate keys will result in an error.')], **entries: Annotated[V, Doc('Zero or more keyword arguments from which to initialize dictionary data.')]) → Self¶: Adds new entries as a batch. Returns self.

values() → ValuesView[V]¶: Provides iterable view over dictionary values.

with_data(*iterables: Annotated[Mapping[H, V] | Iterable[tuple[H, V]], Doc('Zero or more iterables from which to initialize dictionary data. Each iterable must be dictionary or sequence of key-value pairs. Duplicate keys will result in an error.')], **entries: Annotated[V, Doc('Zero or more keyword arguments from which to initialize dictionary data.')]) → Self¶: Creates new dictionary with same behavior but different data.

ictruck.vehicles.ModulesConfigurationsRegistryLiberal¶: alias of Mapping[str, ModuleConfiguration]

class ictruck.vehicles.Omniflavor(value)¶

Bases: Enum

Singleton to match any flavor.

Instance = 1¶

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, ~ictruck.vehicles.Omniflavor | 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: ~ictruck.vehicles.Annotated[~ictruck.vehicles.ModulesConfigurationsRegistry, 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 ')] = functools.partial(<function produce_simple_printer>, <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>), 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. Preserves global 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, Omniflavor | 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[ModulesConfigurationsRegistry, 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.active_flavors_from_environment(evname: str | AbsentSingleton = absence.absent) → Dictionary[str | None, Omniflavor | frozenset[int | str]]¶: Extracts active flavors from named environment variable.

ictruck.vehicles.install(alias: Annotated[str, Doc(' Alias under which the truck is installed in builtins. ')] = 'ictr', active_flavors: Annotated[Omniflavor | Sequence[int | str] | Set[int | str] | Mapping[str | None, Omniflavor | 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, evname_active_flavors: Annotated[str | None | AbsentSingleton, Doc(' Name of environment variable for active flavors or ``None``.\n\n If absent, then a default environment variable name is used.\n\n If ``None``, then active flavors are not parsed from the process\n environment.\n\n If active flavors are supplied directly to a function,\n which also accepts this argument, then active flavors are not\n parsed from the process environment.\n ')] = absence.absent, evname_trace_levels: Annotated[str | None | AbsentSingleton, Doc(' Name of environment variable for trace levels or ``None``.\n\n If absent, then a default environment variable name is used.\n\n If ``None``, then trace levels are not parsed from the process\n environment.\n\n If trace levels are supplied directly to a function,\n which also accepts this argument, then trace levels are not\n parsed from the process environment.\n ')] = absence.absent) → Truck¶

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: Annotated[Omniflavor | Sequence[int | str] | Set[int | str] | Mapping[str | None, Omniflavor | 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, modulecfgs: Annotated[Mapping[str, ModuleConfiguration] | AbsentSingleton, Doc(' Module configurations for the truck.\n\n If absent, defaults to global modules registry.\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, evname_active_flavors: Annotated[str | None | AbsentSingleton, Doc(' Name of environment variable for active flavors or ``None``.\n\n If absent, then a default environment variable name is used.\n\n If ``None``, then active flavors are not parsed from the process\n environment.\n\n If active flavors are supplied directly to a function,\n which also accepts this argument, then active flavors are not\n parsed from the process environment.\n ')] = absence.absent, evname_trace_levels: Annotated[str | None | AbsentSingleton, Doc(' Name of environment variable for trace levels or ``None``.\n\n If absent, then a default environment variable name is used.\n\n If ``None``, then trace levels are not parsed from the process\n environment.\n\n If trace levels are supplied directly to a function,\n which also accepts this argument, then trace levels are not\n parsed from the process environment.\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) → ModuleConfiguration¶

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: str | AbsentSingleton = absence.absent) → Dictionary[str | None, int]¶: Extracts trace levels from named environment variable.

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.printers`¶

Printers, printer factories, and auxiliary functions and types.

ictruck.printers.Printer¶: alias of Callable[[str], None]

ictruck.printers.PrinterFactory¶: alias of Callable[[str, int | str], Callable[[str], None]]

ictruck.printers.produce_simple_printer(target: TextIOBase, mname: str, flavor: int | str, force_color: bool = False) → Callable[[str], None]¶: Produces printer which uses standard Python ‘print’.

Module `ictruck.recipes.logging`¶

Recipes for integration with standard logging.

ictruck.recipes.logging.install(alias: Annotated[str, Doc(' Alias under which the truck is installed in builtins. ')] = 'ictr', additional_aliases: Annotated[Mapping[str, str] | AbsentSingleton, Doc(' Mapping of builtins attribute names to flavors. ')] = absence.absent) → Truck¶

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: str, flavor: int | str) → Callable[[str], None]¶: Produces printer which maps flavors to logging levels.

ictruck.recipes.logging.produce_truck() → 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: Any)¶

Bases: Omnierror, TypeError

Text stream invalid for use with Rich console.

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

args¶

class ictruck.recipes.rich.Modes(value)¶

Bases: Enum

Operation modes for Rich truck.

Formatter = 'formatter'¶

Printer = 'printer'¶

ictruck.recipes.rich.install(alias: Annotated[str, Doc(' Alias under which the truck is installed in builtins. ')] = 'ictr', flavors: Annotated[Mapping[int | str, FlavorConfiguration] | AbsentSingleton, Doc(' Registry of flavor identifiers to configurations. ')] = absence.absent, active_flavors: Annotated[Omniflavor | Sequence[int | str] | Set[int | str] | Mapping[str | None, Omniflavor | 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, 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, mode: Annotated[Modes, Doc(' Operation mode.\n\n ``Formatter`` uses Rich to highlight and pretty text prior to\n printing (output). Text from non-Rich formatters will be printed\n as-is. Safer, but slightly more boring option.\n ``Printer`` uses Rich to highlight and pretty text while printing\n (output). Text from non-Rich formatters will be potentially be\n highlighted and prettied. If the text already contains ANSI SGR\n sequences (e.g., terminal colorization), then it might be\n reprocessed by the printer, causing visual artifacts. Less safe,\n but more vibrant option.\n ')] = Modes.Formatter, stderr: Annotated[bool, Doc(' Output to standard diagnostic stream? ')] = True) → Truck¶

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: Console, control: FormatterControl, mname: str, flavor: int | str) → Callable[[Any], str]¶: Produces formatter which uses Rich highlighter and prettier.

ictruck.recipes.rich.produce_console_printer(console: Console, mname: str, flavor: int | str) → Callable[[str], None]¶: 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: FormatterControl, mname: str, flavor: int | str) → Callable[[Any], str]¶: Produces formatter which uses Rich prettier.

ictruck.recipes.rich.produce_truck(flavors: Annotated[Mapping[int | str, FlavorConfiguration] | AbsentSingleton, Doc(' Registry of flavor identifiers to configurations. ')] = absence.absent, active_flavors: Annotated[Omniflavor | Sequence[int | str] | Set[int | str] | Mapping[str | None, Omniflavor | 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, 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, mode: Annotated[Modes, Doc(' Operation mode.\n\n ``Formatter`` uses Rich to highlight and pretty text prior to\n printing (output). Text from non-Rich formatters will be printed\n as-is. Safer, but slightly more boring option.\n ``Printer`` uses Rich to highlight and pretty text while printing\n (output). Text from non-Rich formatters will be potentially be\n highlighted and prettied. If the text already contains ANSI SGR\n sequences (e.g., terminal colorization), then it might be\n reprocessed by the printer, causing visual artifacts. Less safe,\n but more vibrant option.\n ')] = Modes.Formatter, stderr: Annotated[bool, Doc(' Output to standard diagnostic stream? ')] = True) → Truck¶: Produces icecream truck which integrates with Rich.

ictruck.recipes.rich.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, 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 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: ~typing.Annotated[~typing.Callable[[], tuple[type[BaseException] | None, BaseException | None, ~types.TracebackType | None]], Doc(' Returns information on current exception. ')] = <built-in function exc_info>, pid_discoverer: ~typing.Annotated[~typing.Callable[[], int], Doc(' Returns ID of current process. ')] = <built-in function getpid>, thread_discoverer: ~typing.Annotated[~typing.Callable[[], ~threading.Thread], Doc(' Returns current thread. ')] = <function current_thread>, time_formatter: ~typing.Annotated[~typing.Callable[[str], str], Doc(' Returns current time in specified format. ')] = <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.

exc_info_discoverer: Annotated[Callable[[], tuple[type[BaseException] | None, BaseException | None, TracebackType | None]], Doc(' Returns information on current exception. ')]¶

pid_discoverer: Annotated[Callable[[], int], Doc(' Returns ID of current process. ')]¶

thread_discoverer: Annotated[Callable[[], Thread], Doc(' Returns current thread. ')]¶

time_formatter: Annotated[Callable[[str], str], Doc(' Returns current time in specified format. ')]¶

class ictruck.recipes.sundae.FlavorSpecification(*, color: Annotated[str, Doc(' Name of prefix color. ')], emoji: Annotated[str, Doc(' Prefix emoji. ')], label: Annotated[str, Doc(' Prefix label. ')], stack: Annotated[bool, Doc(' Include stack trace? ')] = False)¶

Bases: object

Specification for custom flavor.

color: Annotated[str, Doc(' Name of prefix color. ')]¶

emoji: Annotated[str, Doc(' Prefix emoji. ')]¶

label: Annotated[str, Doc(' Prefix label. ')]¶

stack: Annotated[bool, Doc(' Include stack trace? ')]¶

class ictruck.recipes.sundae.PrefixDecorations(value)¶

Bases: IntFlag

Decoration styles for prefix emission.

as_integer_ratio()¶

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)

bit_count()¶

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> (13).bit_count()
3

bit_length()¶

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

conjugate()¶: Returns self, the complex conjugate of any int.

from_bytes(byteorder, *, signed=False)¶

Return the integer represented by the given array of bytes.

bytes: Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Indicates whether two’s complement is used to represent the integer.

to_bytes(length, byteorder, *, signed=False)¶

Return an array of bytes representing an integer.

length: Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

Color = 1¶

Emoji = 2¶

Plain = 0¶

denominator¶: the denominator of a rational number in lowest terms

imag¶: the imaginary part of a complex number

numerator¶: the numerator of a rational number in lowest terms

real¶: the real part of a complex number

class ictruck.recipes.sundae.PrefixFormatControl(*, colorize: ~typing.Annotated[bool, Doc(' Attempt to colorize? ')] = True, label_as: ~ictruck.recipes.sundae.Annotated[~ictruck.recipes.sundae.PrefixLabelPresentations, Doc(' How to present prefix label.\n\n ``Words``: As words like ``TRACE0`` or ``ERROR``.\n ``Emoji``: As emoji like ``🔎`` or ``❌``.\n\n For both emoji and words: ``Emoji | Words``.\n ')] = <PrefixLabelPresentations.Words: 1>, styles: ~accretive.dictionaries.Annotated[~accretive.dictionaries.Dictionary[str, ~rich.style.Style], Doc(' Mapping of interpolant names to ``rich`` style objects. ')] = <factory>, template: ~typing.Annotated[str, Doc(' String format for prefix.\n\n The following interpolants are supported:\n ``flavor``: Decorated flavor.\n ``module_qname``: Qualified name of invoking module.\n ``timestamp``: Current timestamp, formatted as string.\n ``process_id``: ID of current process according to OS kernel.\n ``thread_id``: ID of current thread.\n ``thread_name``: Name of current thread.\n ')] = '{flavor}| ', ts_format: ~typing.Annotated[str, Doc(' String format for prefix timestamp.\n\n Used by :py:func:`time.strftime` or equivalent.\n ')] = '%Y-%m-%d %H:%M:%S.%f')¶

Bases: object

Format control for prefix emission.

colorize: Annotated[bool, Doc(' Attempt to colorize? ')]¶

label_as: Annotated[PrefixLabelPresentations, Doc(' How to present prefix label.\n\n ``Words``: As words like ``TRACE0`` or ``ERROR``.\n ``Emoji``: As emoji like ``🔎`` or ``❌``.\n\n For both emoji and words: ``Emoji | Words``.\n ')]¶

styles: Annotated[Dictionary[str, Style], Doc(' Mapping of interpolant names to ``rich`` style objects. ')]¶

template: Annotated[str, Doc(' String format for prefix.\n\n The following interpolants are supported:\n ``flavor``: Decorated flavor.\n ``module_qname``: Qualified name of invoking module.\n ``timestamp``: Current timestamp, formatted as string.\n ``process_id``: ID of current process according to OS kernel.\n ``thread_id``: ID of current thread.\n ``thread_name``: Name of current thread.\n ')]¶

ts_format: Annotated[str, Doc(' String format for prefix timestamp.\n\n Used by :py:func:`time.strftime` or equivalent.\n ')]¶

class ictruck.recipes.sundae.PrefixLabelPresentations(value)¶

Bases: IntFlag

How prefix label should be presented.

as_integer_ratio()¶

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)

bit_count()¶

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> (13).bit_count()
3

bit_length()¶

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

conjugate()¶: Returns self, the complex conjugate of any int.

from_bytes(byteorder, *, signed=False)¶

Return the integer represented by the given array of bytes.

bytes: Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Indicates whether two’s complement is used to represent the integer.

to_bytes(length, byteorder, *, signed=False)¶

Return an array of bytes representing an integer.

length: Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

Emoji = 2¶

Nothing = 0¶

Words = 1¶

denominator¶: the denominator of a rational number in lowest terms

imag¶: the imaginary part of a complex number

numerator¶: the numerator of a rational number in lowest terms

real¶: the real part of a complex number

ictruck.recipes.sundae.produce_module_configuration(colorize: Annotated[bool | AbsentSingleton, Doc(' Attempt to colorize output prefixes? ')] = absence.absent, prefix_label_as: Annotated[PrefixLabelPresentations | AbsentSingleton, Doc(' How to present prefix labels (words, emoji, or both). ')] = absence.absent, prefix_styles: Annotated[Mapping[str, Style] | AbsentSingleton, Doc(' Mapping of interpolant names to Rich style objects. ')] = absence.absent, prefix_template: Annotated[str | AbsentSingleton, Doc(' String template for prefix formatting. ')] = absence.absent, prefix_ts_format: Annotated[str | AbsentSingleton, Doc(' Timestamp format string for prefix. ')] = absence.absent, console_factory: Annotated[Callable[[], Console] | AbsentSingleton, Doc(' Factory function that produces Rich console instances. ')] = absence.absent, auxiliaries: Annotated[Auxiliaries | AbsentSingleton, Doc(' Auxiliary functions for formatting. ')] = absence.absent) → ModuleConfiguration¶: Produces module configuration with sundae-specific flavor settings.

ictruck.recipes.sundae.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, colorize: Annotated[bool | AbsentSingleton, Doc(' Attempt to colorize output prefixes? ')] = absence.absent, prefix_label_as: Annotated[PrefixLabelPresentations | AbsentSingleton, Doc(' How to present prefix labels (words, emoji, or both). ')] = absence.absent, prefix_styles: Annotated[Mapping[str, Style] | AbsentSingleton, Doc(' Mapping of interpolant names to Rich style objects. ')] = absence.absent, prefix_template: Annotated[str | AbsentSingleton, Doc(' String template for prefix formatting. ')] = absence.absent, prefix_ts_format: Annotated[str | AbsentSingleton, Doc(' Timestamp format string for prefix. ')] = absence.absent, console_factory: Annotated[Callable[[], Console] | AbsentSingleton, Doc(' Factory function that produces Rich console instances. ')] = absence.absent, auxiliaries: Annotated[Auxiliaries | AbsentSingleton, Doc(' Auxiliary functions for formatting. ')] = absence.absent) → ModuleConfiguration¶: Registers module with sundae-specific flavor configurations.

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¶

API¶

Package ictruck¶

Module ictruck.vehicles¶

Module ictruck.configuration¶

Module ictruck.printers¶

Module ictruck.recipes.logging¶

Module ictruck.recipes.rich¶

Module ictruck.recipes.sundae¶

Module ictruck.exceptions¶

Package `ictruck`¶

Module `ictruck.vehicles`¶

Module `ictruck.configuration`¶

Module `ictruck.printers`¶

Module `ictruck.recipes.logging`¶

Module `ictruck.recipes.rich`¶

Module `ictruck.recipes.sundae`¶

Module `ictruck.exceptions`¶