API Reference

This page provides a formal reference for icecream's public API.

Core Functions

ic(*args)

The main icecream function. It inspects the variables and expressions passed to it and prints their names, values, and other context to standard error.

  • With arguments: ic(var1, var2, ...) prints the expression and value for each argument.
  • Without arguments: ic() prints the filename, line number, and parent function of the call.
  • Returns: The argument passed to it. If multiple arguments are passed, it returns a tuple of those arguments. If no arguments are passed, it returns None.

Global State Control

ic.enable()

Enables ic()'s output globally. This is the default state.

  • Signature: ic.enable()
  • Returns: None

ic.disable()

Disables ic()'s output globally. ic() calls will still execute and return their arguments, but nothing will be printed.

  • Signature: ic.disable()
  • Returns: None

Built-in Installation

install()

Makes ic() available in the global builtins, so you don't have to import it in every file.

  • Signature: install()
  • Returns: None

uninstall()

Removes ic() from the global builtins.

  • Signature: uninstall()
  • Returns: None

Output and Formatting

ic.format(*args)

Same as ic(), but returns the formatted output as a string instead of printing it to stderr.

  • Signature: ic.format(*args)
  • Returns: A formatted string.

ic.configureOutput(prefix, outputFunction, argToStringFunction, includeContext, contextAbsPath, lineWrapWidth)

Configures various aspects of ic()'s output. See the Configuration page for detailed examples.

  • prefix (str or callable): Sets the prefix for each line of output.
  • outputFunction (callable): A function to which output is sent, instead of stderr.
  • argToStringFunction (callable): A function that converts any argument to its string representation.
  • includeContext (bool): If True, includes file/line/function context for calls with arguments.
  • contextAbsPath (bool): If True, shows the absolute path for file context.
  • lineWrapWidth (int): The character width at which to wrap output lines.

Custom Serialization

argumentToString

A functools.singledispatch function that handles converting objects to strings for output. You can extend it to support custom types.

argumentToString.register(type)

A decorator used to register a new function for handling a specific type.

from icecream import argumentToString

@argumentToString.register(MyClass)
def _(obj):
    return f"MyClass with value {obj.value}"

argumentToString.unregister(type)

Removes a previously registered custom formatting function.

from icecream import argumentToString

argumentToString.unregister(MyClass)

argumentToString.registry

A view object that exposes the mapping of registered types to their formatting functions.