Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

ictr

Package Version PyPI - Status Tests Status Code Coverage Percentage Project License Python Versions

🖋️ Ictr is a system for logging and debug printing in Python applications. It provides a clean, type-safe API for emitting diagnostic messages with minimal boilerplate, featuring standard message flavors, hierarchical trace levels for debugging depth, automatic exception tracebacks, and optional rich rendering with colors and styling.

Designed as an alternative to traditional print debugging and verbose logging setup, ictr can install a global dispatcher into the Python builtins, similar to the well-known icecream package, for effortless access throughout your application — no import statements needed in every module. Perfect for both quick debugging sessions and production logging with per-module configuration.

Key Features ⭐

🎨 Standard Message Flavors: Pre-configured note, monition, error, abort, future, success, and advice flavors with semantic labels and optional emoji/color styling.

🔢 Hierarchical Trace Levels: Ten trace levels (0-9) with automatic indentation for visualizing call depth and execution flow.

💥 Automatic Exception Tracebacks: errorx and abortx flavors capture and format active exceptions with full stack traces.

🌳 Module Hierarchy: Global and per-module configs with inheritance for precise control over active flavors, trace levels, output formatting, etc….

🚀 Zero-Import Access: Global dispatcher available in builtins after initial setup — no import statements needed in every module.

🖨️ Printer Factory: Dynamically associate output functions with reporters based on module name, flavor, etc…. Swap in customized print, logging, or other sinks as desired.

📚 Library-Friendly: Non-intrusive registration for libraries without stepping on application debugger/logging configuration.

Installation 📦

Method: Install Python Package

Install via uv pip command:

uv pip install ictr

Or, install via pip:

pip install ictr

Examples 💡

For more detailed examples, please see the examples documentation.

Basic Usage

Install an ictr dispatcher as a Python builtin (default alias, ictr) and then use it anywhere in your codebase:

import ictr

ictr.install( )

# Emit messages with different flavors
ictr( 'note' )( 'Application started.' )       # NOTE|  Application started.
ictr( 'error' )( 'Connection failed.' )        # ERROR|  Connection failed.
ictr( 'success' )( 'Task completed.' )         # SUCCESS|  Task completed.

Trace Levels

Use numeric trace levels (0-9) for hierarchical debugging output:

import ictr

ictr.install( trace_levels = { None: 3 } )  # Enable levels 0-3 globally

ictr( 0 )( 'Top-level operation' )          # TRACE0|  Top-level operation
ictr( 1 )( 'Sub-operation details' )        #   TRACE1|  Sub-operation details
ictr( 2 )( 'More detail' )                  #     TRACE2|  More detail
ictr( 4 )( 'Too verbose' )                  # (suppressed - level > 3)

Exception Handling

Use errorx or abortx flavors to capture active exceptions with tracebacks:

import ictr

ictr.install( )

try:
    result = 1 / 0
except ZeroDivisionError:
    ictr( 'errorx' )( 'Calculation failed.' )
    # ERROR|  Calculation failed.
    #
    # [ZeroDivisionError] division by zero
    #   File 'example.py', line 8, in <module>
    #       result = 1 / 0

Library Integration

Libraries can register their own configurations without overriding those of the application:

# mylibrary/__init__.py
import ictr

ictr.register_address( 'mylibrary' )

When install is called by the application, any addresses that were previously registered via register_address are incorporated into the installed dispatcher. This allows applications to setup output after libraries have registered their configurations.

Motivation 🚚

Why ictr?

There is nothing wrong with the icecream or logging packages. However, there are times that the author of ictr (and its predecessor, icecream-truck) has wanted, for various reasons, more than these packages inherently offer:

  • Coexistence: Application and libraries can coexist without configuration clashes.

  • Granularity: Control of debug output by depth threshold and subsystem.

    • Only one default debugging level (DEBUG) with logging. Libraries cannot safely extend this. (See point about coexistence).

    • No concept of debugging level with ic builtin. Need to orchestrate multiple icecream.IceCreamDebugger instances to support this. (In fact, this is what icecream-truck does.)

    • While logger hierarchies in logging do support the notion of software subsystems, hierarchies are not always the most convenient or abbreviated way of representing subsystems which span parts or entireties of modules.

  • Signal: Prevention of undesirable library chatter.

    • The logging root logger will log all messages, at its current log level or higher, which propagate up to it. Many Python libraries have opt-out rather than opt-in logging, so you see all of their DEBUG and INFO spam unless you surgically manipulate their loggers or squelch the overall log level.

    • Use of the ic builtin is only recommended for temporary debugging. It cannot be left in production code without spamming. While the enabled flag on the ic builtin can be set to false, it is easy to forget and also applies to every place where ic is used in the code. (See point about granularity.)

  • Extensibility: More natural integration with packages like rich via robust recipes.

    • While it is not difficult to change the argToStringFunction on ic to be rich.pretty.pretty_repr, there is some repetitive code involved in each project which wants to do this. And, from a safety perspective, there should be a fallback if rich fails to import.

    • Similarly, one can add a rich.logging.RichHandler instance to a logger instance with minimal effort. However, depending on the the target output stream, one may also need to build a rich.console.Console first and pass that to the handler. This handler will also compete with whatever handler has been set on the root logger. So, some care must be taken to prevent propagation. Again, this is repetitive code across projects and there are import safety fallbacks to consider.

About the Name 📝

The name ictr has multiple origins and interpretations:

  • 🍦 Shortened from icecream-truck: The package from which ictr is derived and redesigned. The abbreviation maintains the connection to its predecessor while establishing its own identity.

  • 🎯 Short and memorable: Four letters that are easy to type and remember. The Python package distribution name and import name are the same, reducing cognitive overhead.

  • 📊 Backronym interpretations: While ictr works perfectly well as just a name, several backronyms capture different aspects of its purpose:

    • Inspection-Capable Trace Reporting (emphasizes diagnostic capabilities)

    • Intelligent Configurable Trace Reporter (emphasizes smart behavior)

    • I See Textual Reports (playful take on the phonetic sound)

Pronunciation? You can spell it out. But, if that is too many syllables, then maybe “eyes-tra” but probably not “ick-ter”, because it is not that revulsive.

Contribution 🤝

Contribution to this project is welcome! However, it must follow the code of conduct for the project.

Please file bug reports and feature requests in the issue tracker or submit pull requests to improve the source code or documentation.

For development guidance and standards, please see the development guide.

Additional Indicia

GitHub last commit Copier Hatch pre-commit Pyright Ruff PyPI - Implementation PyPI - Wheel

Other Projects by This Author 🌟

  • python-absence (absence on PyPI)

    🕳️ A Python library package which provides a sentinel for absent values - a falsey, immutable singleton that represents the absence of a value in contexts where None or False may be valid values.

  • python-accretive (accretive on PyPI)

    🌌 A Python library package which provides accretive data structures - collections which can grow but never shrink.

  • python-classcore (classcore on PyPI)

    🏭 A Python library package which provides foundational class factories and decorators for providing classes with attributes immutability and concealment and other custom behaviors.

  • python-detextive (detextive on PyPI)

    🕵️ A Python library which provides consolidated text detection capabilities for reliable content analysis. Offers MIME type detection, character set detection, and line separator processing.

  • python-dynadoc (dynadoc on PyPI)

    📝 A Python library package which bridges the gap between rich annotations and automatic documentation generation with configurable renderers and support for reusable fragments.

  • python-falsifier (falsifier on PyPI)

    🎭 A very simple Python library package which provides a base class for falsey objects - objects that evaluate to False in boolean contexts.

  • python-frigid (frigid on PyPI)

    🔒 A Python library package which provides immutable data structures - collections which cannot be modified after creation.

  • python-icecream-truck (icecream-truck on PyPI)

    🍦 Flavorful Debugging - A Python library which enhances the powerful and well-known icecream package with flavored traces, configuration hierarchies, customized outputs, ready-made recipes, and more.

  • python-librovore (librovore on PyPI)

    🐲 Documentation Search Engine - An intelligent documentation search and extraction tool that provides both a command-line interface for humans and an MCP (Model Context Protocol) server for AI agents. Search across Sphinx and MkDocs sites with fuzzy matching, extract clean markdown content, and integrate seamlessly with AI development workflows.

  • python-mimeogram (mimeogram on PyPI)

    📨 A command-line tool for exchanging collections of files with Large Language Models - bundle multiple files into a single clipboard-ready document while preserving directory structure and metadata… good for code reviews, project sharing, and LLM interactions.

Metadata

Release files for ictr 1.0a2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ictr 1.0a2
File Size Uploaded Provenance Actions
ictr-1.0a2.tar.gz 38.4 kB With provenance Details for ictr-1.0a2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ictr 1.0a2
File Interpreter ABI Platform Actions
ictr-1.0a2-py3-none-any.whl Python 3 none any Details for ictr-1.0a2-py3-none-any.whl

Total release size: 94.5 kB

Release files / ictr-1.0a2.tar.gz

Download URL ictr-1.0a2.tar.gz
Size 38.4 kB
Tags Source
SHA-256 checksum
How to use checksums
bff3dfa875896915d164468c9c94bc4329766b31733bd2d7cf596bf5f99f943d
BLAKE2b-256 checksum
How to use checksums
9e5a3672566806972928c8cf56f8d24784b32be8e93960cf0c78db14b25fb6a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

Release files / ictr-1.0a2-py3-none-any.whl

Download URL ictr-1.0a2-py3-none-any.whl
Size 56.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bf88ae7e2102f2605781d16992ba6ec48ece2a27bc44fab4a2d5c94af42865dc
BLAKE2b-256 checksum
How to use checksums
8130a98aed02362aadb86b11cc6b84c2cc291b886ab23165a9e4f6e46592af39
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

Security for ictr 1.0a2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ictr-1.0a2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page