simplibs-introspection 0.1.0

Introspection and stack-walking utilities for the simplibs ecosystem.

simplibs-introspection

Diagnostic and structural inspection tools for the simplibs ecosystem — safe, non-crashing tools for understanding the runtime state.

---

Contents

• Installation
• Why introspection?
• Stack Frames
  • extract_caller_info
• About the simplibs ecosystem

---

Installation

pip install simplibs-introspection

---

Why introspection?

In complex systems, a function often needs to know who called it or from which file execution originated — typically for logging, defensive error handling, or dynamic configuration.

Python's inspect module is powerful but can be heavy and prone to raising exceptions if the stack is not as expected. simplibs-introspection provides a defensive wrapper that prioritises stability: it either gives you the data you need or returns None, but it never crashes your program.

---

Stack Frames

Tools for examining the Python call stack and execution frames.

extract_caller_info

Walks the call stack and returns info about the first relevant frame. It automatically skips internal Python frames and allows you to filter out specific parts of your own codebase.

from simplibs.introspection import extract_caller_info

# Basic usage
info = extract_caller_info()

if info:
    print(f"Called from {info['function']} in {info['file']} at line {info['line']}")
    # Output: Called from my_function in logic.py at line 42

Advanced filtering

You can skip a specific number of frames or exclude files whose paths contain certain strings (e.g., when building a wrapper library where you want to skip the wrapper's own frames).

info = extract_caller_info(
    skip_frames=1, 
    excluded_patterns=("my_internal_tool", "decorators")
)

Key features:

• Performance: Uses context=0 to avoid reading source files from disk.
• Cleanliness: Automatically filters out dynamic frames like <string> or <frozen importlib>.
• Safety: Wrapped in a total try/except block — guaranteed not to raise.

---

About the simplibs ecosystem

simplibs-introspection is part of the simplibs ecosystem — a collection of small, self-contained Python libraries. Each one solves exactly one thing — but all of them share a common philosophy:

Dyslexia-friendly — minimise mental load. Atomise code into self-contained units, name files after the logic they contain, write explanations that describe why — not just what.

Programmer's zen — nothing should be missing and nothing should be superfluous. The journey is the destination: code should be fully understood; better to go slowly and correctly than quickly and with mistakes. The crystallisation approach — not perfection on the first try, but gradual refinement towards it.

Defensive style — anticipate all possible failure modes so that only safe paths remain. Never raise unexpected errors; degrade gracefully.

Minimalism — find the path to the goal in as few steps as possible, but leave nothing out. Each file has one responsibility.

Code as craft — code should be pleasant to look at and evoke a sense of harmony. Treat code as a small work of art — like a carpenter carving a sculpture. Optimise for the user: everything should make sense without having to study the documentation at length.

These are aspirations — a sense of direction. And that is exactly what the note about the journey becoming the destination is all about. 🙂

---

The library is covered by tests across all modules. Tests are part of the repository and serve as living documentation of the expected behaviour.