Skip to main content

ipydex – ipython based debugging and exploring

CircleCI PyPI version

The module contains two main components:

Component 1: displaytools

  • a jupyter-notebook-extension (%loadext ipydex.displaytools)
  • introduces magic comments (like ##:, ##:T, ##:S) which cause that either the return value or the right hand side of an assignment of a line is displayed (T means additional transposition and S means only .shape attribute is displayed)
  • display intermediate results (→ more readable notebooks), without introducing additional print or display statements
  • Example invocation: x = np.random.rand() ##:
    • inserts the line display("x := {}".format(x)) to the source code of the cell (before its execution)
  • see documentation-notebook

Security advice: Because the extension manipulates the source code before its execution, it might cause unwanted and strange behavior. Thus, this program is distributed in the hope that it will be useful, but without any warranty.

Component 2: Useful Python functions and classes

The following functions are meant to be used in ordinary python-scripts:

  • IPS()
    • start an embedded IPython shell in the calling scope
    • useful to explore what objects are available and what are their abilities
    • some additional features compared to IPython.embed()
  • ST()
    • start the IPython debugger
  • activate_ips_on_exception()
    • activate an embedded IPython shell in the scope where an exception occurred
    • useful to investigate what happened
    • see below how to make use of in connection with pytest
    • set magic variable __mu to 1 and exit the shell (CTRL+D) in order to move up one level in the frame stack
      • useful to determine the reason of an exception (which is often not in the same frame as where the exception finally happened)
  • dirsearch(name, obj)
    • search the keys of a dict or the attributes of an object
    • useful to explore semi known modules, classes and data-structures
  • Container
    • versatile class for debugging and convenient creation of case-specific data structures

Traceback Format After import ipydex

Importing ipydex replaces sys.excepthook by IPython's colored traceback formatter (ultratb.FormattedTB). The level of detail is controlled by the environment variable IPYDEX_TB_MODE:

Value Output
plain (default) compact, like the normal Python traceback (but colored)
context additionally shows some lines of source code before and after the relevant line of each frame
verbose like context, plus the values of function arguments and of the variables in the relevant line of each frame

The values are case-insensitive; 0, 1, 2 are accepted as well. An invalid value causes a warning and the fallback to plain.

Note: in verbose mode the variable values are printed completely (via repr). Large lists or dicts can make the traceback extremely long, which is especially inefficient for LLM agents processing the output.

Example:

IPYDEX_TB_MODE=verbose python my_script.py

The mode can also be set from within Python (this overrides the environment variable):

import ipydex
ipydex.color_excepthook(mode="context")  # or ip_syshook(...) (alias)

Note: the traceback printed by activate_ips_on_exception() before the IPython shell starts is not affected by this setting.

Notes

This package has grown over more than a decade. It is only partially covered by unittests. Its internals are not exemplary for recommended coding practice. It certainly contains bugs. No warranty for any purpose is given.

Nevertheless it might be useful.

ipydex Usage in Unittests (Using pytest)

In your test directory add a file conftest.py:

# This file enables the ipydex excepthook together with pytest.
# The custom excepthook can be activated by `activate_ips_on_exception()`
# in your test-file.

# To prevent unwanted dependencies the custom excepthook is only active if a
# special environment variable is "True". Use the following command for this:
#
# export PYTEST_IPS=True


import os
if os.getenv("PYTEST_IPS") == "True":

    import ipydex

    # This function is just an optional reminder
    def pytest_runtest_setup(item):
        print("This invocation of pytest is customized")


    def pytest_exception_interact(node, call, report):
        # the option `leave_ut=True` causes the excepthook to leave functions
        # from the unittest package. This is a convenience feature such that
        # the code wakes up in your own testcode
        ipydex.ips_excepthook(
            call.excinfo.type, call.excinfo.value, call.excinfo.tb, leave_ut=True
        )

Use ipydex.Container for Debugging e.g. in Jupyter Notebooks

from ipydex import Container

# ...

def func1(x, debug_container=None):
    y = complicated_func1(x)
    res = complicated_func2(x, y)

    # convenient way to non-intrusively gather internal information
    if debug_container is not None:
        debug_container.fetch_locals()
        # now the following attributes exists:
        # debug_container.x
        # debug_container.y
        # debug_container.res

    return res

# create debug container
dc = Container()

# call the function which should be debugged, pass the container
# as keyword argument
res = func1(100, debug_container=dc)

# after the function returned dc contains new attributes which allow to
# investigate *internal* behavior of func1
print(C.x)
print(C.y)
print(C.res)

Metadata

Release files for ipydex 0.22.0

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

Source distribution (sdist)

Source distribution for ipydex 0.22.0
File Size Uploaded Provenance Actions
ipydex-0.22.0.tar.gz 133.6 kB Without provenance Details for ipydex-0.22.0.tar.gz

Built distribution (wheel)

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

Total release size: 176.8 kB

Release files / ipydex-0.22.0.tar.gz

Download URL ipydex-0.22.0.tar.gz
Size 133.6 kB
Tags Source
SHA-256 checksum
How to use checksums
459999cc68388b6c0d8da1f7e5559003a0c0ba92475222f828d5a335564cac00
BLAKE2b-256 checksum
How to use checksums
7f070533a402cfaad29c2ff548a5e90fceba8bb6301664bc9fc9b5d189d50421
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.11.4

Release files / ipydex-0.22.0-py3-none-any.whl

Download URL ipydex-0.22.0-py3-none-any.whl
Size 43.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
52b70ae352ad112f56cb564f86127791ddb59d5935c4057d07fbbf318d163cec
BLAKE2b-256 checksum
How to use checksums
0b4331d720ec8f254294863af3919613e2222111900b37aaa088efa41a54359c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.11.4

Security for ipydex 0.22.0

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

Release history Release notifications | RSS feed

This release

0.22.0 This release

2 release files No provenance

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