beautiful-traceback 0.1.0__tar.gz

beautiful_traceback-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.3
+Name: beautiful-traceback
+Version: 0.1.0
+Summary: Beautiful, readable Python tracebacks with colors and formatting
+Keywords: traceback,error,debugging,formatting
+Author: Michael Bianco
+Author-email: Michael Bianco <mike@mikebian.co>
+Requires-Dist: colorama>=0.4.6
+Requires-Python: >=3.9
+Project-URL: Repository, https://github.com/iloveitaly/beautiful-traceback
+Description-Content-Type: text/markdown
+
+# Beautiful Traceback
+
+> **Note:** This is a fork of the [pretty-traceback](https://github.com/mbarkhau/pretty-traceback) repo with simplified development and improvements for better integration with FastAPI, [structlog](https://github.com/iloveitaly/structlog-config), IPython, pytest, and more. This project is used in [python-starter-template](https://github.com/iloveitaly/python-starter-template) to provide better debugging experience in production environments.
+
+Human readable stacktraces for Python.
+
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
+[![Python Versions](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+## Quick Start
+
+The fastest way to see it in action:
+
+```bash
+# Clone and run an example
+git clone https://github.com/iloveitaly/beautiful-traceback
+cd beautiful-traceback
+uv run examples/simple.py
+```
+
+## Overview
+
+Beautiful Traceback groups together what belongs together, adds coloring and alignment. All of this makes it easier for you to see patterns and filter out the signal from the noise. This tabular format is best viewed in a wide terminal.
+
+![Comparison of standard Python traceback vs Beautiful Traceback](comparison.webp)
+
+## Installation
+
+### From PyPI (when published)
+
+```bash
+# Using uv (recommended)
+uv add beautiful-traceback
+
+# Using pip
+pip install beautiful-traceback
+```
+
+### Development Installation
+
+To install from source:
+
+```bash
+git clone https://github.com/iloveitaly/beautiful-traceback
+cd beautiful-traceback
+uv sync
+```
+
+Run examples:
+```bash
+uv run examples/simple.py
+```
+
+Run tests:
+```bash
+uv run pytest
+```
+
+## Usage
+
+Add the following to your `__main__.py` or the equivalent module which is your entry point.
+
+```python
+try:
+    import beautiful_traceback
+    beautiful_traceback.install()
+except ImportError:
+    pass    # no need to fail because of missing dev dependency
+```
+
+Please do not add this code e.g. to your `__init__.py` or any other module that your users may import. They may not want you to mess with how their tracebacks are printed.
+
+If you do feel the overwhelming desire to import the `beautiful_traceback` in code that others might import, consider using the `envvar` argument, which will cause the install function to effectively be a noop unless you set `ENABLE_BEAUTIFUL_TRACEBACK=1`.
+
+```python
+try:
+    import beautiful_traceback
+    beautiful_traceback.install(envvar='ENABLE_BEAUTIFUL_TRACEBACK')
+except ImportError:
+    pass    # no need to fail because of missing dev dependency
+```
+
+Note, that the hook is only installed if the existing hook is the default. Any existing hooks that were installed before the call of `beautiful_traceback.install` will be left in place.
+
+## LoggingFormatter
+
+A `logging.Formatter` subclass is also available (e.g. for integration with Flask, FastAPI, etc).
+
+```python
+import os
+from flask.logging import default_handler
+
+try:
+    if os.getenv('FLASK_DEBUG') == "1":
+        import beautiful_traceback
+        default_handler.setFormatter(beautiful_traceback.LoggingFormatter())
+except ImportError:
+    pass    # no need to fail because of missing dev dependency
+```
+
+## IPython and Jupyter Integration
+
+Beautiful Traceback works seamlessly in IPython and Jupyter notebooks:
+
+```python
+# Load the extension
+%load_ext beautiful_traceback
+
+# Unload if needed
+%unload_ext beautiful_traceback
+```
+
+The extension automatically installs beautiful tracebacks for your interactive session.
+
+## Pytest Integration
+
+Beautiful Traceback includes a pytest plugin that automatically enhances test failure output.
+
+### Automatic Activation
+
+The plugin activates automatically when `beautiful-traceback` is installed. No configuration needed!
+
+### Configuration Options
+
+Customize the plugin in your `pytest.ini` or `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+enable_beautiful_traceback = true                    # Enable/disable the plugin
+enable_beautiful_traceback_local_stack_only = true   # Show only local code (filter libraries)
+```
+
+Or in `pytest.ini`:
+
+```ini
+[pytest]
+enable_beautiful_traceback = true
+enable_beautiful_traceback_local_stack_only = true
+```
+
+## Examples
+
+Check out the [examples/](examples/) directory for detailed usage examples including basic usage, exception chaining, logging integration, and more.
+
+```bash
+# Quick single-exception example
+uv run examples/simple.py
+
+# Interactive demo with multiple exception types
+uv run examples/demo.py
+```
+
+## Configuration
+
+### Installation Options
+
+Beautiful Traceback supports several configuration options:
+
+```python
+beautiful_traceback.install(
+    color=True,                            # Enable colored output
+    only_tty=True,                         # Only activate for TTY output
+    only_hook_if_default_excepthook=True,  # Only install if default hook
+    local_stack_only=False,                # Filter to show only local code
+    envvar='ENABLE_BEAUTIFUL_TRACEBACK'    # Optional environment variable gate
+)
+```
+
+### Environment Variables
+
+- **`NO_COLOR`** - Disables colored output when set (respects [no-color.org](https://no-color.org) standard)
+- **`ENABLE_BEAUTIFUL_TRACEBACK`** - Controls activation when using the `envvar` parameter (set to `1` to enable)
+
+### LoggingFormatterMixin
+
+For more advanced logging integration, you can use `LoggingFormatterMixin` as a base class:
+
+```python
+import logging
+import beautiful_traceback
+
+class MyFormatter(beautiful_traceback.LoggingFormatterMixin, logging.Formatter):
+    def __init__(self):
+        super().__init__(fmt='%(levelname)s: %(message)s')
+```
+
+This gives you full control over the log format while adding beautiful traceback support.
+
+## Global Installation via PTH File
+
+You can enable beautiful-traceback across all Python projects without modifying any source code by using a `.pth` file. Python automatically executes import statements in `.pth` files during interpreter startup, making this perfect for development environments.
+
+Add this function to your `.zshrc` or `.bashrc`:
+
+```bash
+# Create a file to automatically import beautiful-traceback on startup
+python-inject-beautiful-traceback() {
+  local site_packages=$(python -c "import site; print(site.getsitepackages()[0])")
+
+  local pth_file=$site_packages/beautiful_traceback_injection.pth
+  local py_file=$site_packages/_beautiful_traceback_injection.py
+
+  cat <<'EOF' >"$py_file"
+def run_startup_script():
+  try:
+    import beautiful_traceback
+    beautiful_traceback.install()
+  except ImportError:
+    pass
+
+run_startup_script()
+EOF
+
+  echo "import _beautiful_traceback_injection" >"$pth_file"
+  echo "Beautiful traceback injection created: $pth_file"
+}
+```
+
+After sourcing your shell config, run `python-inject-beautiful-traceback` to enable beautiful tracebacks globally for that Python environment.
+
+## Alternatives
+
+Beautiful Traceback is heavily inspired by the backtrace module by [nir0s](https://github.com/nir0s/backtrace) but there are many others (sorted by github stars):
+
+- https://github.com/qix-/better-exceptions
+- https://github.com/cknd/stackprinter
+- https://github.com/onelivesleft/PrettyErrors
+- https://github.com/skorokithakis/tbvaccine
+- https://github.com/aroberge/friendly-traceback
+- https://github.com/HallerPatrick/frosch
+- https://github.com/nir0s/backtrace
+- https://github.com/mbarkhau/pretty-traceback
+- https://github.com/staticshock/colored-traceback.py
+- https://github.com/chillaranand/ptb
+- https://github.com/laurb9/rich-traceback
+- https://github.com/willmcgugan/rich#tracebacks
+
+## License
+
+MIT License - see [LICENSE.md](LICENSE.md) for details.

beautiful_traceback-0.1.0/README.md

@@ -0,0 +1,240 @@
+# Beautiful Traceback
+
+> **Note:** This is a fork of the [pretty-traceback](https://github.com/mbarkhau/pretty-traceback) repo with simplified development and improvements for better integration with FastAPI, [structlog](https://github.com/iloveitaly/structlog-config), IPython, pytest, and more. This project is used in [python-starter-template](https://github.com/iloveitaly/python-starter-template) to provide better debugging experience in production environments.
+
+Human readable stacktraces for Python.
+
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
+[![Python Versions](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+## Quick Start
+
+The fastest way to see it in action:
+
+```bash
+# Clone and run an example
+git clone https://github.com/iloveitaly/beautiful-traceback
+cd beautiful-traceback
+uv run examples/simple.py
+```
+
+## Overview
+
+Beautiful Traceback groups together what belongs together, adds coloring and alignment. All of this makes it easier for you to see patterns and filter out the signal from the noise. This tabular format is best viewed in a wide terminal.
+
+![Comparison of standard Python traceback vs Beautiful Traceback](comparison.webp)
+
+## Installation
+
+### From PyPI (when published)
+
+```bash
+# Using uv (recommended)
+uv add beautiful-traceback
+
+# Using pip
+pip install beautiful-traceback
+```
+
+### Development Installation
+
+To install from source:
+
+```bash
+git clone https://github.com/iloveitaly/beautiful-traceback
+cd beautiful-traceback
+uv sync
+```
+
+Run examples:
+```bash
+uv run examples/simple.py
+```
+
+Run tests:
+```bash
+uv run pytest
+```
+
+## Usage
+
+Add the following to your `__main__.py` or the equivalent module which is your entry point.
+
+```python
+try:
+    import beautiful_traceback
+    beautiful_traceback.install()
+except ImportError:
+    pass    # no need to fail because of missing dev dependency
+```
+
+Please do not add this code e.g. to your `__init__.py` or any other module that your users may import. They may not want you to mess with how their tracebacks are printed.
+
+If you do feel the overwhelming desire to import the `beautiful_traceback` in code that others might import, consider using the `envvar` argument, which will cause the install function to effectively be a noop unless you set `ENABLE_BEAUTIFUL_TRACEBACK=1`.
+
+```python
+try:
+    import beautiful_traceback
+    beautiful_traceback.install(envvar='ENABLE_BEAUTIFUL_TRACEBACK')
+except ImportError:
+    pass    # no need to fail because of missing dev dependency
+```
+
+Note, that the hook is only installed if the existing hook is the default. Any existing hooks that were installed before the call of `beautiful_traceback.install` will be left in place.
+
+## LoggingFormatter
+
+A `logging.Formatter` subclass is also available (e.g. for integration with Flask, FastAPI, etc).
+
+```python
+import os
+from flask.logging import default_handler
+
+try:
+    if os.getenv('FLASK_DEBUG') == "1":
+        import beautiful_traceback
+        default_handler.setFormatter(beautiful_traceback.LoggingFormatter())
+except ImportError:
+    pass    # no need to fail because of missing dev dependency
+```
+
+## IPython and Jupyter Integration
+
+Beautiful Traceback works seamlessly in IPython and Jupyter notebooks:
+
+```python
+# Load the extension
+%load_ext beautiful_traceback
+
+# Unload if needed
+%unload_ext beautiful_traceback
+```
+
+The extension automatically installs beautiful tracebacks for your interactive session.
+
+## Pytest Integration
+
+Beautiful Traceback includes a pytest plugin that automatically enhances test failure output.
+
+### Automatic Activation
+
+The plugin activates automatically when `beautiful-traceback` is installed. No configuration needed!
+
+### Configuration Options
+
+Customize the plugin in your `pytest.ini` or `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+enable_beautiful_traceback = true                    # Enable/disable the plugin
+enable_beautiful_traceback_local_stack_only = true   # Show only local code (filter libraries)
+```
+
+Or in `pytest.ini`:
+
+```ini
+[pytest]
+enable_beautiful_traceback = true
+enable_beautiful_traceback_local_stack_only = true
+```
+
+## Examples
+
+Check out the [examples/](examples/) directory for detailed usage examples including basic usage, exception chaining, logging integration, and more.
+
+```bash
+# Quick single-exception example
+uv run examples/simple.py
+
+# Interactive demo with multiple exception types
+uv run examples/demo.py
+```
+
+## Configuration
+
+### Installation Options
+
+Beautiful Traceback supports several configuration options:
+
+```python
+beautiful_traceback.install(
+    color=True,                            # Enable colored output
+    only_tty=True,                         # Only activate for TTY output
+    only_hook_if_default_excepthook=True,  # Only install if default hook
+    local_stack_only=False,                # Filter to show only local code
+    envvar='ENABLE_BEAUTIFUL_TRACEBACK'    # Optional environment variable gate
+)
+```
+
+### Environment Variables
+
+- **`NO_COLOR`** - Disables colored output when set (respects [no-color.org](https://no-color.org) standard)
+- **`ENABLE_BEAUTIFUL_TRACEBACK`** - Controls activation when using the `envvar` parameter (set to `1` to enable)
+
+### LoggingFormatterMixin
+
+For more advanced logging integration, you can use `LoggingFormatterMixin` as a base class:
+
+```python
+import logging
+import beautiful_traceback
+
+class MyFormatter(beautiful_traceback.LoggingFormatterMixin, logging.Formatter):
+    def __init__(self):
+        super().__init__(fmt='%(levelname)s: %(message)s')
+```
+
+This gives you full control over the log format while adding beautiful traceback support.
+
+## Global Installation via PTH File
+
+You can enable beautiful-traceback across all Python projects without modifying any source code by using a `.pth` file. Python automatically executes import statements in `.pth` files during interpreter startup, making this perfect for development environments.
+
+Add this function to your `.zshrc` or `.bashrc`:
+
+```bash
+# Create a file to automatically import beautiful-traceback on startup
+python-inject-beautiful-traceback() {
+  local site_packages=$(python -c "import site; print(site.getsitepackages()[0])")
+
+  local pth_file=$site_packages/beautiful_traceback_injection.pth
+  local py_file=$site_packages/_beautiful_traceback_injection.py
+
+  cat <<'EOF' >"$py_file"
+def run_startup_script():
+  try:
+    import beautiful_traceback
+    beautiful_traceback.install()
+  except ImportError:
+    pass
+
+run_startup_script()
+EOF
+
+  echo "import _beautiful_traceback_injection" >"$pth_file"
+  echo "Beautiful traceback injection created: $pth_file"
+}
+```
+
+After sourcing your shell config, run `python-inject-beautiful-traceback` to enable beautiful tracebacks globally for that Python environment.
+
+## Alternatives
+
+Beautiful Traceback is heavily inspired by the backtrace module by [nir0s](https://github.com/nir0s/backtrace) but there are many others (sorted by github stars):
+
+- https://github.com/qix-/better-exceptions
+- https://github.com/cknd/stackprinter
+- https://github.com/onelivesleft/PrettyErrors
+- https://github.com/skorokithakis/tbvaccine
+- https://github.com/aroberge/friendly-traceback
+- https://github.com/HallerPatrick/frosch
+- https://github.com/nir0s/backtrace
+- https://github.com/mbarkhau/pretty-traceback
+- https://github.com/staticshock/colored-traceback.py
+- https://github.com/chillaranand/ptb
+- https://github.com/laurb9/rich-traceback
+- https://github.com/willmcgugan/rich#tracebacks
+
+## License
+
+MIT License - see [LICENSE.md](LICENSE.md) for details.

beautiful_traceback-0.1.0/beautiful_traceback/__init__.py

@@ -0,0 +1,22 @@
+from .hook import install
+from .hook import uninstall
+from .formatting import LoggingFormatter
+from .formatting import LoggingFormatterMixin
+
+from ._extension import load_ipython_extension  # noqa: F401
+
+__version__ = "0.1.0"
+
+
+# retain typo for backward compatibility
+LoggingFormaterMixin = LoggingFormatterMixin
+
+
+__all__ = [
+    "install",
+    "uninstall",
+    "__version__",
+    "LoggingFormatter",
+    "LoggingFormatterMixin",
+    "LoggingFormaterMixin",
+]

beautiful_traceback-0.1.0/beautiful_traceback/_extension.py

@@ -0,0 +1,14 @@
+from typing import Any
+
+
+def load_ipython_extension(ip: Any) -> None:  # pragma: no cover
+    # prevent circular import
+    from beautiful_traceback import install
+
+    install()
+
+
+def unload_ipython_extension(ip: Any) -> None:  # pragma: no cover
+    from beautiful_traceback import uninstall
+
+    uninstall()

beautiful_traceback-0.1.0/beautiful_traceback/common.py

@@ -0,0 +1,28 @@
+import typing as typ
+
+
+class Entry(typ.NamedTuple):
+    module: str
+    call: str
+    lineno: str
+    src_ctx: str
+
+
+Entries = typ.List[Entry]
+
+
+class Traceback(typ.NamedTuple):
+    exc_name: str
+    exc_msg: str
+    entries: Entries
+
+    is_caused: bool
+    is_context: bool
+
+
+Tracebacks = typ.List[Traceback]
+
+ALIASES_HEAD = "Aliases for entries in sys.path:"
+TRACEBACK_HEAD = "Traceback (most recent call last):"
+CAUSE_HEAD = "The above exception was the direct cause of the following exception:"
+CONTEXT_HEAD = "During handling of the above exception, another exception occurred:"

beautiful_traceback-0.1.0/beautiful_traceback/formatting.py

@@ -0,0 +1,512 @@
+import os
+import re
+import sys
+import types
+import typing as typ
+import logging
+import traceback as tb
+import subprocess as sp
+import collections
+
+import colorama
+
+import beautiful_traceback.common as com
+
+DEFAULT_COLUMNS = 80
+
+
+def _get_terminal_width() -> int:
+    try:
+        columns = int(os.environ["COLUMNS"])
+        # lines   = int(os.environ['LINES'  ])
+        return columns
+    except (KeyError, ValueError):
+        pass
+
+    if not sys.stdout.isatty():
+        return DEFAULT_COLUMNS
+
+    if hasattr(os, "get_terminal_size"):
+        try:
+            size = os.get_terminal_size(0)
+            return size.columns
+        except OSError:
+            pass
+
+    try:
+        size_output = sp.check_output(["stty", "size"]).decode()
+        _, columns = [int(val) for val in size_output.strip().split()]
+        return columns
+    except sp.CalledProcessError:
+        pass
+    except IOError:
+        pass
+
+    return DEFAULT_COLUMNS
+
+
+FMT_MODULE: str = (
+    colorama.Fore.CYAN + colorama.Style.NORMAL + "{0}" + colorama.Style.RESET_ALL
+)
+FMT_CALL: str = (
+    colorama.Fore.YELLOW + colorama.Style.NORMAL + "{0}" + colorama.Style.RESET_ALL
+)
+FMT_LINENO: str = (
+    colorama.Fore.MAGENTA + colorama.Style.NORMAL + "{0}" + colorama.Style.RESET_ALL
+)
+FMT_CONTEXT: str = "{0}"
+
+FMT_ERROR_NAME: str = (
+    colorama.Fore.RED + colorama.Style.BRIGHT + "{0}" + colorama.Style.RESET_ALL
+)
+FMT_ERROR_MSG: str = colorama.Style.BRIGHT + "{0}" + colorama.Style.RESET_ALL
+
+
+class Row(typ.NamedTuple):
+    alias: str
+    short_module: str
+    full_module: str
+    call: str
+    lineno: str
+    context: str
+
+
+class PaddedRow(typ.NamedTuple):
+    alias: str
+    short_module: str
+    full_module: str
+    call: str
+    lineno: str
+    context: str
+
+
+Alias = str
+Prefix = str
+
+AliasPrefix = typ.Tuple[Alias, Prefix]
+AliasPrefixes = typ.List[AliasPrefix]
+
+
+class Context(typ.NamedTuple):
+    rows: typ.List[Row]
+    aliases: AliasPrefixes
+
+    max_row_width: int
+    is_wide_mode: bool
+
+    # for paddings
+    max_short_module_len: int
+    max_full_module_len: int
+
+    max_lineno_len: int
+    max_call_len: int
+    max_context_len: int
+
+
+def _iter_entry_paths(entries: com.Entries) -> typ.Iterable[str]:
+    for entry in entries:
+        module_abspath = os.path.abspath(entry.module)
+        is_valid_abspath = module_abspath != entry.module and os.path.exists(
+            module_abspath
+        )
+        if is_valid_abspath:
+            yield module_abspath
+        else:
+            yield entry.module
+
+
+# used by unit tests to override paths
+TEST_PATHS: typ.List[str] = []
+
+PWD = os.getcwd()
+
+
+def _py_paths() -> typ.List[str]:
+    if TEST_PATHS:
+        return TEST_PATHS
+
+    # NOTE (mb 2020-08-16): We don't know which path entry
+    #   was used to import a module. I guess we could figure it
+    #   out, but the preference here is to make the shortest
+    #   path possible.
+
+    paths = list(sys.path)
+    # NOTE (mb 2020-10-04): aliases must be sorted from longest to
+    #   shortest, so that the longer matches are used first.
+    paths.sort(key=len, reverse=True)
+
+    if "" in paths:
+        paths.remove("")
+
+    return paths
+
+
+def _iter_used_py_paths(entry_paths: typ.List[str]) -> typ.Iterable[str]:
+    _uniq_entry_paths = set(entry_paths)
+
+    for py_path in _py_paths():
+        is_path_used = False
+        for entry_path in list(_uniq_entry_paths):
+            if entry_path.startswith(py_path):
+                is_path_used = True
+                _uniq_entry_paths.remove(entry_path)
+
+        if is_path_used:
+            yield py_path
+
+
+def _iter_alias_prefixes(entry_paths: typ.List[str]) -> typ.Iterable[AliasPrefix]:
+    alias_index = 0
+
+    for py_path in _iter_used_py_paths(entry_paths):
+        if py_path.endswith("site-packages"):
+            alias = "<site>"
+        elif py_path.endswith("dist-packages"):
+            alias = "<dist>"
+        elif re.search(r"lib/python\d.\d+$", py_path):
+            alias = "<py>"
+        elif re.search(r"lib/Python\d.\d+\\lib$", py_path):
+            alias = "<py>"
+        elif py_path.startswith(PWD):
+            alias = "<pwd>"
+            py_path = PWD
+        else:
+            alias = f"<p{alias_index}>"
+            alias_index += 1
+
+        # Always end paths with a slash. This way relative paths don't
+        # start with a / and tooling can open files (e.g. Ctrl+Click),
+        # which would otherwise be parsed as absolute paths.
+        if not py_path.endswith("/"):
+            py_path = py_path + "/"
+
+        yield (alias, py_path)
+
+
+def _iter_entry_rows(
+    aliases: AliasPrefixes, entry_paths: typ.List[str], entries: com.Entries
+) -> typ.Iterable[Row]:
+    for abs_module, entry in zip(entry_paths, entries):
+        used_alias = ""
+        module_full = abs_module
+        module_short = abs_module
+
+        module = entry.module
+        if module.startswith("." + os.sep):
+            module = module[2:]
+
+        # NOTE (mb 2020-08-18): module may not be an absolute path,
+        #   but it's not shortened using an alias yet either.
+        if abs_module.endswith(module):
+            for alias, alias_path in aliases:
+                if abs_module.startswith(alias_path):
+                    new_module_short = abs_module[len(alias_path) :]
+
+                    new_len = len(new_module_short) + len(alias)
+                    old_len = len(module_short) + len(used_alias)
+                    if new_len < old_len:
+                        used_alias = alias
+                        module_short = new_module_short
+
+        yield Row(
+            used_alias,
+            module_short,
+            module_full,
+            entry.call or "",
+            entry.lineno or "",
+            entry.src_ctx or "",
+        )
+
+
+def _init_entries_context(
+    entries: com.Entries, term_width: typ.Optional[int] = None
+) -> Context:
+    if term_width is None:
+        _term_width = _get_terminal_width()
+    else:
+        _term_width = term_width
+
+    entry_paths = list(_iter_entry_paths(entries))
+    aliases = list(_iter_alias_prefixes(entry_paths))
+
+    # NOTE (mb 2020-10-04): When calculating widths of a column, we care more
+    #   about alignment than staying below the max_row_width. The limits are
+    #   only a best effort and padding will be added even if that means
+    #   wrapping. We rely on the aliases to reduce the wrapping.
+
+    # indent (4 spaces) + 3 x sep (2 spaces each)
+    max_row_width = _term_width - 10
+
+    rows = list(_iter_entry_rows(aliases, entry_paths, entries))
+
+    if rows:
+        max_short_module_len = max(
+            len(row.alias) + len(row.short_module) for row in rows
+        )
+        max_full_module_len = max(len(row.full_module) for row in rows)
+
+        max_lineno_len = max(len(row.lineno) for row in rows)
+        max_call_len = max(len(row.call) for row in rows)
+        max_context_len = max(len(row.context) for row in rows)
+    else:
+        max_short_module_len = 0
+        max_full_module_len = 0
+
+        max_lineno_len = 0
+        max_call_len = 0
+        max_context_len = 0
+
+    max_total_len = (
+        max_full_module_len + max_lineno_len + max_call_len + max_context_len
+    )
+    is_wide_mode = max_total_len < max_row_width
+
+    return Context(
+        rows,
+        aliases,
+        max_row_width,
+        is_wide_mode,
+        max_short_module_len,
+        max_full_module_len,
+        max_lineno_len,
+        max_call_len,
+        max_context_len,
+    )
+
+
+def _padded_rows(ctx: Context) -> typ.Iterable[PaddedRow]:
+    # Expand padding from left to right.
+    # This will mutate rows (updating strings with added padding)
+
+    for row in ctx.rows:
+        if ctx.is_wide_mode:
+            short_module = ""
+            full_module = row.full_module.ljust(ctx.max_full_module_len)
+        else:
+            short_module = row.short_module.ljust(
+                ctx.max_short_module_len - len(row.alias)
+            )
+            full_module = ""
+
+        # the max lengths are calculated upstream in `_init_entries_context`
+        padded_call = row.call.ljust(ctx.max_call_len)
+        padded_lineno = row.lineno.ljust(ctx.max_lineno_len)
+
+        yield PaddedRow(
+            row.alias,
+            short_module,
+            full_module,
+            padded_call,
+            padded_lineno,
+            row.context,
+        )
+
+
+def _aliases_to_lines(ctx: Context, color: bool = False) -> typ.Iterable[str]:
+    fmt_module = FMT_MODULE if color else "{0}"
+    if ctx.aliases:
+        alias_padding = max(len(alias) for alias, _ in ctx.aliases)
+        for alias, path in ctx.aliases:
+            yield "    " + alias.ljust(alias_padding) + ": " + fmt_module.format(path)
+
+
+def _rows_to_lines(
+    rows: typ.List[PaddedRow], color: bool = False, local_stack_only: bool = False
+) -> typ.Iterable[str]:
+    # apply colors and additional separators/ spacing
+    fmt_module = FMT_MODULE if color else "{0}"
+    fmt_call = FMT_CALL if color else "{0}"
+    fmt_lineno = FMT_LINENO if color else "{0}"
+    fmt_context = FMT_CONTEXT if color else "{0}"
+
+    # padding has already been added to the components at this point
+    for alias, short_module, full_module, call, lineno, context in rows:
+        if short_module:
+            _alias = alias
+            module = short_module
+        else:
+            _alias = ""
+            module = full_module
+
+        # append line number to file so editors can jump to the line
+        bare_module = module.strip()
+        bare_lineno = lineno.strip()
+        module_padding = " " * (
+            len(module) - len(bare_module) + len(lineno) - len(bare_lineno)
+        )
+
+        parts = (
+            "    ",
+            _alias,
+            " ",
+            fmt_module.format(bare_module),
+            ":",
+            fmt_lineno.format(bare_lineno),
+            module_padding,
+            "  ",
+            fmt_call.format(call),
+            "  ",
+            fmt_context.format(context),
+        )
+
+        line = "".join(parts)
+
+        if local_stack_only and not alias == "<pwd>":
+            continue
+
+        # bold any entries which are the current working directory
+        if alias == "<pwd>":
+            yield line.replace(colorama.Style.NORMAL, colorama.Style.BRIGHT)
+        else:
+            yield line
+
+
+def _traceback_to_entries(traceback: types.TracebackType) -> typ.Iterable[com.Entry]:
+    summary = tb.extract_tb(traceback)
+    for entry in summary:
+        module = entry[0]
+        call = entry[2]
+        lineno = str(entry[1])
+        context = entry[3] or ""
+        yield com.Entry(module, call, lineno, context)
+
+
+def _format_traceback(
+    ctx: Context,
+    traceback: com.Traceback,
+    color: bool = False,
+    local_stack_only: bool = False,
+) -> str:
+    padded_rows = list(_padded_rows(ctx))
+
+    lines = []
+    if ctx.aliases and not ctx.is_wide_mode:
+        lines.append(com.ALIASES_HEAD)
+        lines.extend(_aliases_to_lines(ctx, color))
+
+    lines.append(com.TRACEBACK_HEAD)
+    lines.extend(_rows_to_lines(padded_rows, color, local_stack_only))
+
+    if traceback.exc_name == "RecursionError" and len(lines) > 100:
+        prelude_index = 0
+
+        line_counts: typ.Dict[str, int] = collections.defaultdict(int)
+        for i, line in enumerate(lines):
+            line_counts[line] += 1
+            if line_counts[line] == 3:
+                prelude_index = i
+                break
+
+        if prelude_index > 0:
+            num_omitted = len(lines) - prelude_index - 2
+            lines = (
+                lines[:prelude_index]
+                + [f"    ... {num_omitted} omitted lines"]
+                + lines[-2:]
+            )
+
+    fmt_error_name = FMT_ERROR_NAME if color else "{0}"
+    error_line = fmt_error_name.format(traceback.exc_name)
+    if traceback.exc_msg:
+        fmt_error_msg = FMT_ERROR_MSG if color else "{0}"
+        error_line += ": " + fmt_error_msg.format(traceback.exc_msg)
+
+    lines.append(error_line)
+    return os.linesep.join(lines) + os.linesep
+
+
+def format_traceback(
+    traceback: com.Traceback, color: bool = False, local_stack_only: bool = False
+) -> str:
+    ctx = _init_entries_context(traceback.entries)
+    return _format_traceback(ctx, traceback, color, local_stack_only)
+
+
+def format_tracebacks(
+    tracebacks: typ.List[com.Traceback],
+    color: bool = False,
+    local_stack_only: bool = False,
+) -> str:
+    traceback_strs: typ.List[str] = []
+
+    for tb_tup in tracebacks:
+        if tb_tup.is_caused:
+            # traceback_strs.append("vvv caused by ^^^ - ")
+            traceback_strs.append(com.CAUSE_HEAD + os.linesep)
+        elif tb_tup.is_context:
+            # traceback_strs.append("vvv happend after ^^^ - ")
+            traceback_strs.append(com.CONTEXT_HEAD + os.linesep)
+
+        traceback_str = format_traceback(tb_tup, color, local_stack_only)
+        traceback_strs.append(traceback_str)
+
+    return os.linesep.join(traceback_strs).strip()
+
+
+def get_tb_attr(ex: BaseException) -> types.TracebackType:
+    return typ.cast(types.TracebackType, getattr(ex, "__traceback__", None))
+
+
+def exc_to_traceback_str(
+    exc_value: BaseException,
+    traceback: types.TracebackType,
+    color: bool = False,
+    local_stack_only: bool = False,
+) -> str:
+    # NOTE (mb 2020-08-13): wrt. cause vs context see
+    #   https://www.python.org/dev/peps/pep-3134/#enhanced-reporting
+    #   https://stackoverflow.com/questions/11235932/
+    tracebacks: typ.List[com.Traceback] = []
+
+    cur_exc_value: BaseException = exc_value
+    cur_traceback: types.TracebackType = traceback
+    
+    # Track seen exceptions to prevent infinite loops from circular references
+    seen_exceptions: typ.Set[int] = set()
+
+    while cur_exc_value:
+        # Check if we've seen this exception before (circular reference)
+        exc_id = id(cur_exc_value)
+        if exc_id in seen_exceptions:
+            # Circular reference detected, break the loop
+            break
+        seen_exceptions.add(exc_id)
+        
+        next_cause = getattr(cur_exc_value, "__cause__", None)
+        next_context = getattr(cur_exc_value, "__context__", None)
+
+        tb_tup = com.Traceback(
+            exc_name=type(cur_exc_value).__name__,
+            exc_msg=str(cur_exc_value),
+            entries=list(_traceback_to_entries(cur_traceback)),
+            is_caused=bool(next_cause),
+            is_context=bool(next_context),
+        )
+
+        tracebacks.append(tb_tup)
+
+        if next_cause:
+            cur_exc_value = next_cause
+            cur_traceback = get_tb_attr(next_cause)
+        elif next_context:
+            cur_exc_value = next_context
+            cur_traceback = get_tb_attr(next_context)
+        else:
+            break
+
+    tracebacks = list(reversed(tracebacks))
+
+    return format_tracebacks(tracebacks, color, local_stack_only)
+
+
+class LoggingFormatterMixin:
+    # pylint:disable=invalid-name   # logging module naming convention
+    # pylint:disable=no-self-use    # because mixin
+
+    def formatException(self, ei) -> str:
+        _, exc_value, traceback = ei
+        return exc_to_traceback_str(exc_value, traceback, color=True)
+
+
+class LoggingFormatter(LoggingFormatterMixin, logging.Formatter):
+    pass

beautiful_traceback-0.1.0/beautiful_traceback/hook.py

@@ -0,0 +1,76 @@
+import os
+import sys
+import types
+import typing as typ
+
+import colorama
+
+from beautiful_traceback import formatting
+
+
+def init_excepthook(color: bool, local_stack_only: bool) -> typ.Callable:
+    def excepthook(
+        exc_type: typ.Type[BaseException],
+        exc_value: BaseException,
+        traceback: types.TracebackType,
+    ) -> None:
+        # pylint:disable=unused-argument
+        tb_str = (
+            formatting.exc_to_traceback_str(
+                exc_value, traceback, color, local_stack_only
+            )
+            + "\n"
+        )
+        if color:
+            colorama.init()
+            try:
+                sys.stderr.write(tb_str)
+            finally:
+                colorama.deinit()
+        else:
+            sys.stderr.write(tb_str)
+
+    return excepthook
+
+
+def install(
+    envvar: typ.Optional[str] = None,
+    color: bool = True,
+    only_tty: bool = True,
+    only_hook_if_default_excepthook: bool = True,
+    local_stack_only: bool = False,
+) -> None:
+    """Hook the current excepthook to the beautiful_traceback.
+
+    If you set `only_tty=False`, beautiful_traceback will always
+    be active even when stdout is piped or redirected.
+
+    Color output respects the NO_COLOR environment variable
+    (https://no-color.org/). If NO_COLOR is set (regardless of
+    its value), color output will be disabled.
+    """
+    if envvar and os.environ.get(envvar, "0") == "0":
+        return
+
+    # Respect NO_COLOR environment variable
+    if "NO_COLOR" in os.environ:
+        color = False
+
+    isatty = getattr(sys.stderr, "isatty", lambda: False)
+    if only_tty and not isatty():
+        return
+
+    if not isatty():
+        color = False
+
+    # pylint:disable=comparison-with-callable   ; intentional
+    is_default_exepthook = sys.excepthook == sys.__excepthook__
+    if only_hook_if_default_excepthook and not is_default_exepthook:
+        return
+
+    sys.excepthook = init_excepthook(color=color, local_stack_only=local_stack_only)
+
+
+def uninstall() -> None:
+    """Restore the default excepthook."""
+    sys.excepthook = sys.__excepthook__

beautiful_traceback-0.1.0/beautiful_traceback/parsing.py

@@ -0,0 +1,116 @@
+import re
+import typing as typ
+
+import beautiful_traceback.common as com
+
+# TODO (mb 2020-08-12): path/module with doublequotes in them.
+#   Not even sure what python does with that.
+
+# https://regex101.com/r/GpKtqR/1
+LOCATION_PATTERN = r"""
+\s\s
+File
+    \s
+        \"(?P<module>[^\"]+)\"
+    ,\sline\s
+        (?P<lineno>\d+)
+    ,\sin\s
+        (?P<call>.*)
+"""
+LOCATION_RE = re.compile(LOCATION_PATTERN, flags=re.VERBOSE)
+
+
+def _parse_entries(entry_lines: typ.List[str]) -> typ.Iterable[com.Entry]:
+    i = 0
+    while i < len(entry_lines):
+        line = entry_lines[i]
+        i += 1
+        loc_match = LOCATION_RE.match(line)
+        if loc_match is None:
+            continue
+
+        if i < len(entry_lines):
+            maybe_src_ctx = entry_lines[i]
+        else:
+            maybe_src_ctx = ""
+
+        is_src_ctx = maybe_src_ctx.startswith("    ")
+        if is_src_ctx:
+            src_ctx = maybe_src_ctx.strip()
+            i += 1
+        else:
+            src_ctx = ""
+
+        module, lineno, call = loc_match.groups()
+
+        yield com.Entry(module, call, lineno, src_ctx)
+
+
+TRACE_HEADERS = {com.TRACEBACK_HEAD, com.CAUSE_HEAD, com.CONTEXT_HEAD}
+
+
+def _iter_tracebacks(trace: str) -> typ.Iterable[com.Traceback]:
+    lines = trace.strip().splitlines()
+
+    i = 0
+    while i < len(lines):
+        line = lines[i].strip()
+
+        # skip empty lines
+        if not line:
+            i += 1
+            continue
+
+        is_caused = False
+        is_context = False
+
+        if line.startswith(com.CAUSE_HEAD):
+            is_caused = True
+            i += 1
+        elif line.startswith(com.CONTEXT_HEAD):
+            is_context = True
+            i += 1
+
+        # skip empty lines and tb head
+        while i < len(lines):
+            line = lines[i].strip()
+            if not line or line.startswith(com.TRACEBACK_HEAD):
+                i += 1
+            else:
+                break
+
+        # accumulate entry lines
+        entry_lines: typ.List[str] = []
+        while i < len(lines) and lines[i].startswith("  "):
+            entry_lines.append(lines[i])
+            i += 1
+
+        exc_line = lines[i]
+        if ": " in exc_line:
+            exc_name, exc_msg = exc_line.split(": ", 1)
+        else:
+            exc_name = exc_line
+            exc_msg = ""
+
+        entries = list(_parse_entries(entry_lines))
+        yield com.Traceback(
+            exc_name=exc_name,
+            exc_msg=exc_msg,
+            entries=entries,
+            is_caused=is_caused,
+            is_context=is_context,
+        )
+
+        i += 1
+
+
+def parse_tracebacks(trace: str) -> com.Tracebacks:
+    """Parses a chain of tracebacks.
+
+    Args:
+        trace: The traceback in the default python format, starting with
+                   "Traceback (most recent call last):"
+               ending with the last line in the chain, e.g.
+                   "FileNotFoundError: [Errno 2] No such ..."
+    """
+    return list(_iter_tracebacks(trace))

beautiful_traceback-0.1.0/beautiful_traceback/pytest_plugin.py

@@ -0,0 +1,83 @@
+from . import formatting
+import pytest
+
+from pytest import Config
+
+
+def _get_option(config: Config, key: str):
+    val = None
+
+    # will throw an exception if option is not set
+    try:
+        val = config.getoption(key)
+    except Exception:
+        pass
+
+    if val is None:
+        val = config.getini(key)
+
+    return val
+
+
+def pytest_addoption(parser):
+    parser.addini(
+        "enable_beautiful_traceback",
+        "Enable the beautiful traceback plugin",
+        type="bool",
+        default=True,
+    )
+
+    parser.addini(
+        "enable_beautiful_traceback_local_stack_only",
+        "Show only local code (filter out library/framework internals)",
+        type="bool",
+        default=True,
+    )
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    """
+    Pytest stack traces are challenging to work with by default. This plugin allows beautiful_traceback to be used instead.
+
+    This little piece of code was hard-won:
+
+    https://grok.com/share/bGVnYWN5_951be3b1-6811-4fda-b220-c1dd72dedc31
+    """
+    outcome = yield
+    report = outcome.get_result()  # Get the generated TestReport object
+
+    # Check if the report is for the 'call' phase (test execution) and if it failed
+    if _get_option(item.config, "enable_beautiful_traceback") and report.failed:
+        value = call.excinfo.value
+        tb = call.excinfo.tb
+
+        formatted_traceback = formatting.exc_to_traceback_str(
+            value,
+            tb,
+            color=True,
+            local_stack_only=_get_option(
+                item.config, "enable_beautiful_traceback_local_stack_only"
+            ),
+        )
+        report.longrepr = formatted_traceback
+
+
+def pytest_exception_interact(node, call, report):
+    """
+    This can run during collection, not just test execution.
+
+    So, if there's an import or other pre-run error in pytest, this will apply the correct formatting.
+    """
+    if report.failed:
+        value = call.excinfo.value
+        tb = call.excinfo.tb
+        formatted_traceback = formatting.exc_to_traceback_str(
+            value,
+            tb,
+            color=True,
+            local_stack_only=_get_option(
+                node.config, "enable_beautiful_traceback_local_stack_only"
+            ),
+        )
+        report.longrepr = formatted_traceback

beautiful_traceback-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "beautiful-traceback"
+version = "0.1.0"
+description = "Beautiful, readable Python tracebacks with colors and formatting"
+keywords = ["traceback", "error", "debugging", "formatting"]
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["colorama>=0.4.6"]
+authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
+urls = { "Repository" = "https://github.com/iloveitaly/beautiful-traceback" }
+
+[build-system]
+requires = ["uv_build>=0.8.11,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# avoids the src/ directory structure
+module-root = ""
+
+[dependency-groups]
+dev = ["pytest>=8.3.3"]
+
+[project.entry-points.pytest11]
+beautiful_traceback = "beautiful_traceback.pytest_plugin"
+
+