beautiful-traceback 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

beautiful_traceback/__init__.py

@@ -1,12 +1,7 @@
-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"
-
+from .formatting import LoggingFormatter, LoggingFormatterMixin
+from .hook import install, uninstall
+from .json_formatting import exc_to_json
 
 # retain typo for backward compatibility
 LoggingFormaterMixin = LoggingFormatterMixin
@@ -15,8 +10,8 @@ LoggingFormaterMixin = LoggingFormatterMixin
 __all__ = [
     "install",
     "uninstall",
-    "__version__",
     "LoggingFormatter",
     "LoggingFormatterMixin",
     "LoggingFormaterMixin",
+    "exc_to_json",
 ]

beautiful_traceback/cli.py

@@ -0,0 +1,84 @@
+"""CLI commands for beautiful-traceback installation and configuration."""
+
+import sys
+from pathlib import Path
+
+import colorama
+
+
+def inject_pth() -> None:
+    """
+    Inject beautiful-traceback into the current Python environment via .pth file.
+
+    Creates a .pth file in site-packages that automatically imports beautiful_traceback
+    on interpreter startup. Only works within virtual environments.
+    """
+    if not _is_in_venv():
+        print("Error: Not running in a virtual environment", file=sys.stderr)
+        print(
+            "Beautiful traceback pth injection only works in virtual environments",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    site_packages = _get_site_packages()
+    pth_file = site_packages / "beautiful_traceback_injection.pth"
+    py_file = site_packages / "_beautiful_traceback_injection.py"
+
+    _create_injection_files(py_file, pth_file)
+
+    print(f"Beautiful traceback injection installed: {pth_file}")
+
+
+def _is_in_venv() -> bool:
+    """Check if running in a virtual environment."""
+    return hasattr(sys, "real_prefix") or (
+        hasattr(sys, "base_prefix") and sys.base_prefix != sys.prefix
+    )
+
+
+def _get_site_packages() -> Path:
+    """Get the site-packages directory for the current Python environment."""
+    import site
+
+    site_packages_list = site.getsitepackages()
+
+    if not site_packages_list:
+        print("Error: Could not find site-packages directory", file=sys.stderr)
+        sys.exit(1)
+
+    return Path(site_packages_list[0])
+
+
+def _create_injection_files(py_file: Path, pth_file: Path) -> None:
+    """Create the Python injection file and .pth file."""
+    # Check if files already exist
+    if py_file.exists() or pth_file.exists():
+        colorama.init()
+        try:
+            warning_msg = f"{colorama.Fore.RED}Warning: Beautiful traceback injection already exists. Overwriting...{colorama.Style.RESET_ALL}"
+            print(warning_msg, file=sys.stderr)
+        finally:
+            colorama.deinit()
+
+    py_content = """def run_startup_script():
+  try:
+    import beautiful_traceback
+    beautiful_traceback.install(only_tty=False)
+  except ImportError:
+    pass
+
+run_startup_script()
+"""
+
+    py_file.write_text(py_content)
+    pth_file.write_text("import _beautiful_traceback_injection\n")
+
+
+def main() -> None:
+    """Main CLI entrypoint."""
+    inject_pth()
+
+
+if __name__ == "__main__":
+    main()

beautiful_traceback/common.py

@@ -1,28 +1,70 @@
+"""Common data structures and constants for beautiful-traceback.
+
+This module provides an Internal Representation (IR) used to normalize Python's
+complex exception graph into a simplified, flat format suitable for both
+text and JSON rendering.
+
+These structures:
+1. Prevent circular imports between formatting modules.
+2. Bundle exceptions with their specific traceback entries.
+3. Flatten recursive exception chains (__cause__, __context__) into linear lists.
+"""
+
 import typing as typ
 
 
-class Entry(typ.NamedTuple):
+class StackFrameEntry(typ.NamedTuple):
+    """A normalized stack frame.
+
+    Attributes:
+        module: The path to the source file.
+        call: The name of the function or scope.
+        lineno: The line number as a string.
+        src_ctx: The source code line content.
+    """
+
     module: str
     call: str
     lineno: str
     src_ctx: str
 
 
-Entries = typ.List[Entry]
+StackFrameEntryList = typ.List[StackFrameEntry]
+
 
+class ExceptionTraceback(typ.NamedTuple):
+    """A normalized representation of a single exception and its stack.
+
+    This bundles the exception metadata with its specific traceback entries,
+    and explicitly marks its relationship to other exceptions in a chain.
+
+    Attributes:
+        exc_name: The class name of the exception.
+        exc_msg: The string representation of the exception.
+        stack_frames: A list of stack frames.
+        is_caused: True if this exception was the direct cause (__cause__).
+        is_context: True if this exception occurred during handling (__context__).
+    """
 
-class Traceback(typ.NamedTuple):
     exc_name: str
     exc_msg: str
-    entries: Entries
+    stack_frames: StackFrameEntryList
 
     is_caused: bool
     is_context: bool
 
 
-Tracebacks = typ.List[Traceback]
+ExceptionTracebackList = typ.List[ExceptionTraceback]
 
+# Standard headers used across different renderers
 ALIASES_HEAD = "Aliases for entries in sys.path:"
+"Header shown before the list of path aliases."
+
 TRACEBACK_HEAD = "Traceback (most recent call last):"
+"Standard Python header for a traceback."
+
 CAUSE_HEAD = "The above exception was the direct cause of the following exception:"
+"Header shown when an exception has an explicit __cause__."
+
 CONTEXT_HEAD = "During handling of the above exception, another exception occurred:"
+"Header shown when an exception has an implicit __context__."

beautiful_traceback/formatting.py

@@ -10,7 +10,15 @@ import collections
 
 import colorama
 
-import beautiful_traceback.common as com
+from beautiful_traceback.common import (
+    ALIASES_HEAD,
+    CAUSE_HEAD,
+    CONTEXT_HEAD,
+    TRACEBACK_HEAD,
+    ExceptionTraceback,
+    StackFrameEntry,
+    StackFrameEntryList,
+)
 
 DEFAULT_COLUMNS = 80
 
@@ -103,7 +111,7 @@ class Context(typ.NamedTuple):
     max_context_len: int
 
 
-def _iter_entry_paths(entries: com.Entries) -> typ.Iterable[str]:
+def _iter_entry_paths(entries: StackFrameEntryList) -> 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(
@@ -184,7 +192,7 @@ def _iter_alias_prefixes(entry_paths: typ.List[str]) -> typ.Iterable[AliasPrefix
 
 
 def _iter_entry_rows(
-    aliases: AliasPrefixes, entry_paths: typ.List[str], entries: com.Entries
+    aliases: AliasPrefixes, entry_paths: typ.List[str], entries: StackFrameEntryList
 ) -> typ.Iterable[Row]:
     for abs_module, entry in zip(entry_paths, entries):
         used_alias = ""
@@ -219,7 +227,7 @@ def _iter_entry_rows(
 
 
 def _init_entries_context(
-    entries: com.Entries, term_width: typ.Optional[int] = None
+    entries: StackFrameEntryList, term_width: typ.Optional[int] = None
 ) -> Context:
     if term_width is None:
         _term_width = _get_terminal_width()
@@ -361,19 +369,21 @@ def _rows_to_lines(
             yield line
 
 
-def _traceback_to_entries(traceback: types.TracebackType) -> typ.Iterable[com.Entry]:
+def _traceback_to_entries(traceback: types.TracebackType) -> StackFrameEntryList:
     summary = tb.extract_tb(traceback)
+    entries = []
     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)
+        entries.append(StackFrameEntry(module, call, lineno, context))
+    return entries
 
 
 def _format_traceback(
     ctx: Context,
-    traceback: com.Traceback,
+    traceback: ExceptionTraceback,
     color: bool = False,
     local_stack_only: bool = False,
 ) -> str:
@@ -381,10 +391,10 @@ def _format_traceback(
 
     lines = []
     if ctx.aliases and not ctx.is_wide_mode:
-        lines.append(com.ALIASES_HEAD)
+        lines.append(ALIASES_HEAD)
         lines.extend(_aliases_to_lines(ctx, color))
 
-    lines.append(com.TRACEBACK_HEAD)
+    lines.append(TRACEBACK_HEAD)
     lines.extend(_rows_to_lines(padded_rows, color, local_stack_only))
 
     if traceback.exc_name == "RecursionError" and len(lines) > 100:
@@ -416,14 +426,14 @@ def _format_traceback(
 
 
 def format_traceback(
-    traceback: com.Traceback, color: bool = False, local_stack_only: bool = False
+    traceback: ExceptionTraceback, color: bool = False, local_stack_only: bool = False
 ) -> str:
-    ctx = _init_entries_context(traceback.entries)
+    ctx = _init_entries_context(traceback.stack_frames)
     return _format_traceback(ctx, traceback, color, local_stack_only)
 
 
 def format_tracebacks(
-    tracebacks: typ.List[com.Traceback],
+    tracebacks: typ.List[ExceptionTraceback],
     color: bool = False,
     local_stack_only: bool = False,
 ) -> str:
@@ -432,10 +442,10 @@ def format_tracebacks(
     for tb_tup in tracebacks:
         if tb_tup.is_caused:
             # traceback_strs.append("vvv caused by ^^^ - ")
-            traceback_strs.append(com.CAUSE_HEAD + os.linesep)
+            traceback_strs.append(CAUSE_HEAD + os.linesep)
         elif tb_tup.is_context:
             # traceback_strs.append("vvv happend after ^^^ - ")
-            traceback_strs.append(com.CONTEXT_HEAD + os.linesep)
+            traceback_strs.append(CONTEXT_HEAD + os.linesep)
 
         traceback_str = format_traceback(tb_tup, color, local_stack_only)
         traceback_strs.append(traceback_str)
@@ -452,15 +462,16 @@ def exc_to_traceback_str(
     traceback: types.TracebackType,
     color: bool = False,
     local_stack_only: bool = False,
+    exc_msg_override: str | None = None,
 ) -> 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] = []
+    tracebacks: typ.List[ExceptionTraceback] = []
 
     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()
 
@@ -471,14 +482,18 @@ def exc_to_traceback_str(
             # 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_msg = str(cur_exc_value)
+        if exc_msg_override is not None and cur_exc_value is exc_value:
+            exc_msg = exc_msg_override
+
+        tb_tup = ExceptionTraceback(
             exc_name=type(cur_exc_value).__name__,
-            exc_msg=str(cur_exc_value),
-            entries=list(_traceback_to_entries(cur_traceback)),
+            exc_msg=exc_msg,
+            stack_frames=_traceback_to_entries(cur_traceback),
             is_caused=bool(next_cause),
             is_context=bool(next_context),
         )

beautiful_traceback/json_formatting.py

@@ -0,0 +1,204 @@
+"""JSON exception formatting for production logging.
+
+This module provides exc_to_json() which converts exceptions to structured
+dictionaries suitable for JSON logging in production environments.
+"""
+
+import types
+import typing as typ
+
+from beautiful_traceback.common import ExceptionTraceback, ExceptionTracebackList
+import beautiful_traceback.formatting as fmt
+
+
+def _row_to_json_frame(row: fmt.Row) -> dict[str, typ.Any]:
+    """Convert a Row to a JSON-serializable frame dict."""
+    return {
+        "module": row.short_module,
+        "alias": row.alias,
+        "function": row.call,
+        "lineno": int(row.lineno),
+    }
+
+
+def _format_traceback_json(
+    rows: list[fmt.Row],
+    exc_name: str,
+    exc_msg: str,
+    local_stack_only: bool,
+) -> dict[str, typ.Any]:
+    """Convert rows to a JSON-serializable traceback dict."""
+    if local_stack_only:
+        filtered_rows = [row for row in rows if row.alias == "<pwd>"]
+    else:
+        filtered_rows = rows
+
+    frames = [_row_to_json_frame(row) for row in filtered_rows]
+
+    return {
+        "exception": exc_name,
+        "message": exc_msg,
+        "frames": frames,
+    }
+
+
+def exc_to_json(
+    exc_value: BaseException,
+    traceback: types.TracebackType | None,
+    local_stack_only: bool = False,
+) -> dict[str, typ.Any]:
+    """Convert an exception to a JSON-serializable dictionary.
+
+    This function is designed for production JSON logging. It always uses
+    aliased paths (e.g., <pwd>/app.py, <site>/requests/sessions.py) and
+    respects the local_stack_only flag to filter library frames.
+
+    Args:
+        exc_value: The exception instance
+        traceback: The traceback object (can be None)
+        local_stack_only: If True, only include frames from <pwd> (current directory)
+
+    Returns:
+        A dictionary with exception details and stack frames, including any
+        chained exceptions. Structure:
+        {
+            "exception": "ExceptionName",
+            "message": "exception message",
+            "frames": [
+                {
+                    "module": "app.py",
+                    "alias": "<pwd>",
+                    "function": "function_name",
+                    "lineno": 42
+                },
+                ...
+            ],
+            "chain": [  # optional, if exception has __cause__ or __context__
+                {
+                    "exception": "CauseName",
+                    "message": "cause message",
+                    "relationship": "caused_by",  # or "context"
+                    "frames": [...]
+                }
+            ]
+        }
+
+    Example:
+        >>> import sys
+        >>> try:
+        ...     raise ValueError("test error")
+        ... except ValueError:
+        ...     exc_info = sys.exc_info()
+        ...     result = exc_to_json(exc_info[1], exc_info[2])
+        ...     print(result["exception"])
+        ValueError
+    """
+    tracebacks = _exc_to_traceback_list(exc_value, traceback)
+
+    if not tracebacks:
+        return {
+            "exception": type(exc_value).__name__,
+            "message": str(exc_value),
+            "frames": [],
+        }
+
+    main_tb = tracebacks[0]
+    entries = list(main_tb.stack_frames)
+
+    if not entries:
+        result = {
+            "exception": main_tb.exc_name,
+            "message": main_tb.exc_msg,
+            "frames": [],
+        }
+    else:
+        ctx = fmt._init_entries_context(entries, term_width=fmt.DEFAULT_COLUMNS)
+        result = _format_traceback_json(
+            ctx.rows,
+            main_tb.exc_name,
+            main_tb.exc_msg,
+            local_stack_only,
+        )
+
+    if len(tracebacks) > 1:
+        chain = []
+        for tb in tracebacks[1:]:
+            entries = list(tb.stack_frames)
+            if not entries:
+                chain_item = {
+                    "exception": tb.exc_name,
+                    "message": tb.exc_msg,
+                    "relationship": "caused_by" if tb.is_caused else "context",
+                    "frames": [],
+                }
+            else:
+                ctx = fmt._init_entries_context(entries, term_width=fmt.DEFAULT_COLUMNS)
+                chain_item = _format_traceback_json(
+                    ctx.rows,
+                    tb.exc_name,
+                    tb.exc_msg,
+                    local_stack_only,
+                )
+                chain_item["relationship"] = "caused_by" if tb.is_caused else "context"
+            chain.append(chain_item)
+
+        result["chain"] = chain
+
+    return result
+
+
+def _exc_to_traceback_list(
+    exc_value: BaseException,
+    traceback: types.TracebackType | None,
+) -> ExceptionTracebackList:
+    """Convert exception with chaining to a list of Traceback objects.
+
+    Handles __cause__ and __context__ chains, detecting circular references.
+    """
+    tracebacks: ExceptionTracebackList = []
+    seen_exceptions: set[int] = set()
+
+    current_exc = exc_value
+    current_tb = traceback
+    is_caused = False
+    is_context = False
+
+    while current_exc is not None:
+        exc_id = id(current_exc)
+
+        if exc_id in seen_exceptions:
+            break
+
+        seen_exceptions.add(exc_id)
+
+        entries = fmt._traceback_to_entries(current_tb) if current_tb else []
+
+        tb_obj = ExceptionTraceback(
+            exc_name=type(current_exc).__name__,
+            exc_msg=str(current_exc),
+            stack_frames=entries,
+            is_caused=is_caused,
+            is_context=is_context,
+        )
+        tracebacks.append(tb_obj)
+
+        next_exc = None
+        next_tb = None
+
+        if current_exc.__cause__ is not None:
+            next_exc = current_exc.__cause__
+            next_tb = next_exc.__traceback__
+            is_caused = True
+            is_context = False
+        elif (
+            current_exc.__context__ is not None and not current_exc.__suppress_context__
+        ):
+            next_exc = current_exc.__context__
+            next_tb = next_exc.__traceback__
+            is_caused = False
+            is_context = True
+
+        current_exc = next_exc
+        current_tb = next_tb
+
+    return tracebacks

beautiful_traceback/parsing.py

@@ -1,7 +1,14 @@
 import re
 import typing as typ
 
-import beautiful_traceback.common as com
+from beautiful_traceback.common import (
+    CAUSE_HEAD,
+    CONTEXT_HEAD,
+    TRACEBACK_HEAD,
+    ExceptionTraceback,
+    ExceptionTracebackList,
+    StackFrameEntry,
+)
 
 # TODO (mb 2020-08-12): path/module with doublequotes in them.
 #   Not even sure what python does with that.
@@ -20,7 +27,7 @@ File
 LOCATION_RE = re.compile(LOCATION_PATTERN, flags=re.VERBOSE)
 
 
-def _parse_entries(entry_lines: typ.List[str]) -> typ.Iterable[com.Entry]:
+def _parse_entries(entry_lines: typ.List[str]) -> typ.Iterable[StackFrameEntry]:
     i = 0
     while i < len(entry_lines):
         line = entry_lines[i]
@@ -43,13 +50,13 @@ def _parse_entries(entry_lines: typ.List[str]) -> typ.Iterable[com.Entry]:
 
         module, lineno, call = loc_match.groups()
 
-        yield com.Entry(module, call, lineno, src_ctx)
+        yield StackFrameEntry(module, call, lineno, src_ctx)
 
 
-TRACE_HEADERS = {com.TRACEBACK_HEAD, com.CAUSE_HEAD, com.CONTEXT_HEAD}
+TRACE_HEADERS = {TRACEBACK_HEAD, CAUSE_HEAD, CONTEXT_HEAD}
 
 
-def _iter_tracebacks(trace: str) -> typ.Iterable[com.Traceback]:
+def _iter_tracebacks(trace: str) -> typ.Iterable[ExceptionTraceback]:
     lines = trace.strip().splitlines()
 
     i = 0
@@ -64,17 +71,17 @@ def _iter_tracebacks(trace: str) -> typ.Iterable[com.Traceback]:
         is_caused = False
         is_context = False
 
-        if line.startswith(com.CAUSE_HEAD):
+        if line.startswith(CAUSE_HEAD):
             is_caused = True
             i += 1
-        elif line.startswith(com.CONTEXT_HEAD):
+        elif line.startswith(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):
+            if not line or line.startswith(TRACEBACK_HEAD):
                 i += 1
             else:
                 break
@@ -93,10 +100,10 @@ def _iter_tracebacks(trace: str) -> typ.Iterable[com.Traceback]:
             exc_msg = ""
 
         entries = list(_parse_entries(entry_lines))
-        yield com.Traceback(
+        yield ExceptionTraceback(
             exc_name=exc_name,
             exc_msg=exc_msg,
-            entries=entries,
+            stack_frames=entries,
             is_caused=is_caused,
             is_context=is_context,
         )
@@ -104,7 +111,7 @@ def _iter_tracebacks(trace: str) -> typ.Iterable[com.Traceback]:
         i += 1
 
 
-def parse_tracebacks(trace: str) -> com.Tracebacks:
+def parse_tracebacks(trace: str) -> ExceptionTracebackList:
     """Parses a chain of tracebacks.
 
     Args:

beautiful_traceback/pytest_plugin.py

@@ -19,6 +19,43 @@ def _get_option(config: Config, key: str):
     return val
 
 
+def _get_exception_message_override(excinfo: pytest.ExceptionInfo) -> str | None:
+    """Return pytest's verbose exception message when rewriting adds detail.
+
+    The plugin overrides pytest's longrepr rendering, which skips the
+    ExceptionInfo repr where pytest stores rewritten assertion diffs. Without
+    this, AssertionError messages collapse to str(exc) and omit left/right
+    details. Pulling reprcrash.message preserves that verbose message when
+    pytest provides one.
+    """
+    try:
+        repr_info = excinfo.getrepr(style="long")
+    except Exception:
+        return None
+
+    reprcrash = getattr(repr_info, "reprcrash", None)
+    if reprcrash is None:
+        return None
+
+    message = getattr(reprcrash, "message", None)
+    if not message:
+        return None
+
+    exc_name = type(excinfo.value).__name__
+    prefix = f"{exc_name}: "
+    if message.startswith(prefix):
+        message = message.removeprefix(prefix)
+
+    if not message or message == exc_name:
+        return None
+
+    exc_message = str(excinfo.value)
+    if message == exc_message:
+        return None
+
+    return message
+
+
 def pytest_addoption(parser):
     parser.addini(
         "enable_beautiful_traceback",
@@ -52,6 +89,8 @@ def pytest_runtest_makereport(item, call):
         value = call.excinfo.value
         tb = call.excinfo.tb
 
+        message_override = _get_exception_message_override(call.excinfo)
+
         formatted_traceback = formatting.exc_to_traceback_str(
             value,
             tb,
@@ -59,6 +98,7 @@ def pytest_runtest_makereport(item, call):
             local_stack_only=_get_option(
                 item.config, "enable_beautiful_traceback_local_stack_only"
             ),
+            exc_msg_override=message_override,
         )
         report.longrepr = formatted_traceback
 
@@ -72,6 +112,8 @@ def pytest_exception_interact(node, call, report):
     if report.failed:
         value = call.excinfo.value
         tb = call.excinfo.tb
+        message_override = _get_exception_message_override(call.excinfo)
+
         formatted_traceback = formatting.exc_to_traceback_str(
             value,
             tb,
@@ -79,5 +121,6 @@ def pytest_exception_interact(node, call, report):
             local_stack_only=_get_option(
                 node.config, "enable_beautiful_traceback_local_stack_only"
             ),
+            exc_msg_override=message_override,
         )
         report.longrepr = formatted_traceback

{beautiful_traceback-0.1.0.dist-info → beautiful_traceback-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: beautiful-traceback
-Version: 0.1.0
+Version: 0.3.0
 Summary: Beautiful, readable Python tracebacks with colors and formatting
 Keywords: traceback,error,debugging,formatting
 Author: Michael Bianco
@@ -10,14 +10,17 @@ Requires-Python: >=3.9
 Project-URL: Repository, https://github.com/iloveitaly/beautiful-traceback
 Description-Content-Type: text/markdown
 
-# Beautiful Traceback
+# Beautiful, Readable Python Stack Traces
 
-> **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.
+[![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/)
 
 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/)
+![Comparison of standard Python traceback vs Beautiful Traceback](comparison.webp)
+
+> [!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.
 
 ## Quick Start
 
@@ -34,7 +37,6 @@ uv run examples/simple.py
 
 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
 
@@ -202,7 +204,27 @@ This gives you full control over the log format while adding beautiful traceback
 
 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`:
+### Using the CLI Command
+
+The easiest way to inject beautiful-traceback into your current virtual environment:
+
+```bash
+beautiful-traceback
+```
+
+This command:
+- Only works within virtual environments (for safety)
+- Installs the `.pth` file into your current environment's site-packages
+- Displays the installation path every time it runs
+
+Output:
+```
+Beautiful traceback injection installed: /path/to/.venv/lib/python3.11/site-packages/beautiful_traceback_injection.pth
+```
+
+### Using a Shell Function (Alternative)
+
+Alternatively, add this function to your `.zshrc` or `.bashrc`:
 
 ```bash
 # Create a file to automatically import beautiful-traceback on startup
@@ -216,7 +238,7 @@ python-inject-beautiful-traceback() {
 def run_startup_script():
   try:
     import beautiful_traceback
-    beautiful_traceback.install()
+    beautiful_traceback.install(only_tty=False)
   except ImportError:
     pass
 
@@ -249,4 +271,4 @@ Beautiful Traceback is heavily inspired by the backtrace module by [nir0s](https
 
 ## License
 
-MIT License - see [LICENSE.md](LICENSE.md) for details.
+[MIT License](LICENSE.md)

beautiful_traceback-0.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+beautiful_traceback/__init__.py,sha256=e6zDdmcyc3H2aAmY5_9hAeMtCU_b3xyXwGhqrbOa-qo,438
+beautiful_traceback/_extension.py,sha256=klyo3XL4q3-Wdy4Lt6JYdh-Cfh_SkRCI7jCcQCwfWTM,311
+beautiful_traceback/cli.py,sha256=M4EWW9SUNiGH2VCpssxRDMNXNjrVpy_8t9T7jf66RKE,2405
+beautiful_traceback/common.py,sha256=Dg6J4rLdX9uKM6LxJaqSwtLkUjggZk-KrR5kpAIA4uo,2208
+beautiful_traceback/formatting.py,sha256=s4tjdejhYBXBmHlHiUa3bm9j0I6B2hka46JfHNdgKLk,15501
+beautiful_traceback/hook.py,sha256=6vYpqA-mD4G32HkX5WSyCMzkvMwB4RXP6wbVEIU6oaY,2078
+beautiful_traceback/json_formatting.py,sha256=WcgA6rk6YkFDRLXOTk95yVrK_HxNjvHHUqgr2RlK_O4,6071
+beautiful_traceback/parsing.py,sha256=39GvHo6kx5dyzTMfRjUTc8H9tRGIhFT8RcjxUvbZBZY,3094
+beautiful_traceback/pytest_plugin.py,sha256=IwZh5yUUsbLpUWZuVxVqSIGUVPO30_0xIHThc3xor54,3672
+beautiful_traceback-0.3.0.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
+beautiful_traceback-0.3.0.dist-info/entry_points.txt,sha256=EXsu7N89wqDpZPEwLHgYVncZJ3y-lbCFZC5fKBZZDac,138
+beautiful_traceback-0.3.0.dist-info/METADATA,sha256=Z5pu8bStps0bEkS8f53AJ5I7krXVHpu2WVdibKPco_s,8558
+beautiful_traceback-0.3.0.dist-info/RECORD,,

{beautiful_traceback-0.1.0.dist-info → beautiful_traceback-0.3.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.8.17
+Generator: uv 0.9.26
 Root-Is-Purelib: true
-Tag: py3-none-any
+Tag: py3-none-any

beautiful_traceback-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+beautiful-traceback = beautiful_traceback.cli:main
+
+[pytest11]
+beautiful_traceback = beautiful_traceback.pytest_plugin
+

beautiful_traceback-0.1.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-beautiful_traceback/__init__.py,sha256=XW0PVUTOPa6qFDhvE8oPWikOcL8Xbfgv_BLuFdkVhCI,462
-beautiful_traceback/_extension.py,sha256=klyo3XL4q3-Wdy4Lt6JYdh-Cfh_SkRCI7jCcQCwfWTM,311
-beautiful_traceback/common.py,sha256=IIg46wUk5e0syCrkI2HfLPwv8zi8mQ5AIPgb1998lAY,585
-beautiful_traceback/formatting.py,sha256=FilxU_holFyBvVKd2VHTtqQ4sRfUlfxSIYwHLtadR3M,15105
-beautiful_traceback/hook.py,sha256=6vYpqA-mD4G32HkX5WSyCMzkvMwB4RXP6wbVEIU6oaY,2078
-beautiful_traceback/parsing.py,sha256=lVqOty6X9MqTfo-lTIQjI_zVxUqRhYEVjyGhkW8wps8,2954
-beautiful_traceback/pytest_plugin.py,sha256=vdRgvycWeG9wwh9tK4921ugW9aHx0Zib1Or7mU9Khw0,2315
-beautiful_traceback-0.1.0.dist-info/WHEEL,sha256=Pi5uDq5Fdo_Rr-HD5h9BiPn9Et29Y9Sh8NhcJNnFU1c,79
-beautiful_traceback-0.1.0.dist-info/entry_points.txt,sha256=m99Hs6ia_rvyRu-ruwKwVCjob50f-wvLVtztWyi47a8,68
-beautiful_traceback-0.1.0.dist-info/METADATA,sha256=w0nVy_HVr836OK_I1jY1fosVLAXM_3MOgm5992CvmQc,8020
-beautiful_traceback-0.1.0.dist-info/RECORD,,

beautiful_traceback-0.1.0.dist-info/entry_points.txt

@@ -1,3 +0,0 @@
-[pytest11]
-beautiful_traceback = beautiful_traceback.pytest_plugin
-