stack-data

stack-data is a Python library that extracts detailed data from stack frames and tracebacks, going far beyond the raw line numbers and filenames that Python’s built-in traceback module provides. It groups source code into logical “pieces” (statements and compound-statement fragments) rather than raw lines, so context shown around an error never gets cropped mid-expression, and it truncates long pieces intelligently while always preserving the executing line in full.

Beyond source context, stack-data surfaces the actual variables and expressions relevant to a frame using the pure_eval library, safely evaluating only expressions that are guaranteed to have no side effects. This lets tools built on top of it show live variable values alongside code, not just a bare traceback. A markers-and-ranges API makes it straightforward to annotate rendered source with HTML, ANSI color codes, or other inline formatting for building syntax-highlighted, interactive tracebacks.

It is a foundational dependency in the Python debugging ecosystem: it powers IPython’s traceback rendering and is used by educational tools like futurecoder to produce clearer, more actionable error output for learners and developers alike.

What You Get

• FrameInfo - a class wrapping a frame or traceback object with cached, lazily-computed properties for source lines, scope, and variables.
• Piece-based context - source code grouped into logical statement/compound-statement pieces instead of raw lines, so context never crops mid-expression.
• Variable extraction - safe evaluation of interesting expressions (via pure_eval) in a frame’s scope, including attribute and subscript expressions, not just bare names.
• Markers and ranges API - RangeInLine/MarkerInLine/markers_from_ranges for inserting HTML, ANSI codes, or other inline annotations into rendered source lines without corrupting nested markup.
• Configurable Options - control how much context to show before/after the current line, whether to include the enclosing function signature, and how long pieces may run before truncation.
• Ready-made Formatter and Serializer - higher-level classes for producing complete formatted or JSON-serializable traceback output without hand-rolling the rendering loop.

Common Use Cases

• Custom debugger frontends - build a debugger or REPL that shows live variable values next to the exact source line being executed.
• Enhanced error pages - render tracebacks with syntax highlighting and inline variable annotations in web frameworks or notebook environments.
• Educational tooling - power beginner-friendly error explanations that highlight the specific expression that failed, as futurecoder does.
• REPL/notebook integrations - drive IPython-style rich tracebacks in a custom interactive shell or Jupyter-like environment.
• Logging and monitoring - capture structured, serializable frame/variable snapshots at exception time for later inspection rather than a flat string traceback.

Under The Hood

Architecture stack-data is organized as a small, focused core: core.py defines Source (a per-file AST/tokenization cache built on asttokens) and FrameInfo (the per-frame facade that exposes lines, variables, and scope as cached properties), utils.py holds low-level helpers (truncate, line_range, group_by_key_func, cached_property), and formatting.py/serializing.py layer a Formatter and Serializer on top of the core primitives for two different output modes (human-readable text/HTML and structured JSON-like data). The design deliberately separates “extraction” (core.py) from “presentation” (formatting.py, serializing.py), so a consumer can use FrameInfo directly for full control or reach for Formatter/Serializer for a batteries-included path; if the core FrameInfo/Source abstraction changed, every downstream consumer (including IPython) would need to update in lockstep, so the maintainers keep its public surface conservative.

Tech Stack The library is pure Python 3.8+ with three runtime dependencies: executing (to reliably identify the exact AST node currently executing, even across nested calls), asttokens (to map AST nodes back to precise source text ranges), and pure_eval (to safely evaluate side-effect-free expressions for variable display). It has no web framework, database, or CLI surface — it is a pure library dependency, distributed via PyPI and built with setuptools plus setuptools_scm for git-tag-based versioning, with an optional pygments integration behind the pygmented=True formatter flag for terminal/HTML syntax highlighting.

Code Quality The project has a substantial tests/ suite (test_core.py, test_formatter.py, test_serializer.py, test_utils.py) run via pytest across Python 3.8 through 3.14 in GitHub Actions CI, with coverage tracked through Coveralls; a STACK_DATA_SLOW_TESTS flag gates a slower, more exhaustive test path. Type hints are present throughout the public API (using typing.NamedTuple, Optional, Sequence, etc.), though the codebase predates full strict-typing conventions and doesn’t run mypy in CI. Naming and structure are consistent with the broader executing/asttokens/pure_eval family of libraries from the same author, and error conditions use an explicit assert_ helper that raises typed exceptions rather than silently swallowing failures.

What Makes It Unique While Python’s standard library traceback module gives raw line numbers and file paths, stack-data’s piece-based context model and safe variable evaluation are comparatively rare: most tracebacks either show a fixed number of raw lines (risking cropped multi-line statements) or require a full debugger session to inspect variables. By combining AST-aware piece boundaries with pure_eval’s side-effect-free expression evaluation, stack-data lets tools show meaningful variable state directly alongside a traceback without the risk of triggering property getters or other side effects during introspection — a distinction that matters a great deal when inspecting a frame at exception time in production code.