Metadata-Version: 2.4
Name: simplibs-introspection
Version: 0.1.0
Summary: Introspection and stack-walking utilities for the simplibs ecosystem.
Author-email: "Dalibor Sova (Sudip2708)" <daliborsova@seznam.cz>
License-Expression: MIT
Project-URL: Homepage, https://github.com/simplibs/simplibs-introspection
Project-URL: Repository, https://github.com/simplibs/simplibs-introspection
Project-URL: Issues, https://github.com/simplibs/simplibs-introspection/issues
Project-URL: Changelog, https://github.com/simplibs/simplibs-introspection/blob/main/CHANGELOG.md
Keywords: introspection,stack-trace,caller-info,simplibs,developer-tools,debugging
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# simplibs-introspection

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

![Python](https://img.shields.io/badge/python-3.11%2B-blue)
![Licence](https://img.shields.io/badge/licence-MIT-green)
![PyPI](https://img.shields.io/pypi/v/simplibs-introspection)

-----

## Contents

  - [Installation](https://www.google.com/search?q=%23installation)
  - [Why introspection?](https://www.google.com/search?q=%23why-introspection)
  - [Stack Frames](https://www.google.com/search?q=%23stack-frames)
      - [extract\_caller\_info](https://www.google.com/search?q=%23extract_caller_info)
  - [About the simplibs ecosystem](https://www.google.com/search?q=%23about-the-simplibs-ecosystem)

-----

## Installation

```bash
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.

```python
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).

```python
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.*
