ipydex – ipython based debugging and exploring
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 (Tmeans additional transposition andSmeans only.shapeattribute is displayed) - display intermediate results (→ more readable notebooks), without
introducing additional
printordisplaystatements - Example invocation:
x = np.random.rand() ##:- inserts the line
display("x := {}".format(x))to the source code of the cell (before its execution)
- inserts the line
- 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
__muto1and 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.