runtime-introspect 0.3.0

A small Python library to seamlessly introspect interpreter features at runtime

runtime_introspect

A small Python library to introspect interpreter features in a couple of portable lines of code. The core functionality is to produce diagnostics for which optional features are (un)available, the state they are in (enabled, disabled, active, or inactive), and why. It utilizes implementation specific APIs to abstract away the pain of writing portable code that runs on any configuration.

Scope and development status

This project is currently in alpha, with a flexible scope; Only CPython interpreter features (Free-threading and JIT) are supported at the moment. However, the library design leaves open the possibility to add support for other Python implementations. If you spot something missing please open a feature request or a pull request, contributions are always welcome !

Installation

python -m pip install runtime-introspect

Usage

Create diagnostics

Here's how to produce a complete diagnostic

from runtime_introspect import runtime_feature_set

fs = runtime_feature_set()
print("\n".join(fs.diagnostics()))

example output:

free-threading: unavailable (this interpreter was built without free-threading support)
JIT: disabled (envvar PYTHON_JIT is unset)
py-limited-api: available

Since runtime-introspect 0.3.0, FeatureSet.snapshot and FeatureSet.diagnostics will also accept a features list to fine-tune exactly which features to inspect and report on.

Inspect specific features

To make code conditional on the availability of a specific feature, use FeatureSet.supports. For instance

from runtime_introspect import runtime_feature_set

fs = runtime_feature_set()
if fs.supports("free-threading"):
    ... # cool multi-threading stuff
else:
    ... # also cool, but single-threaded stuff

As of runtime-introspect 0.2.0, supported feature names include 'free-threading', 'JIT' and 'py-limited-api'.

Build a pytest header

You can use this library to customize pytest so that test session headers showcase the runtime feature set at startup. For instance

# conftest.py
import sys
import textwrap
from runtime_introspect import runtime_feature_set

# ...

def pytest_report_header(config, start_path) -> list[str]:
    fs = runtime_feature_set()
    if diagnostics := fs.diagnostics():
        return [
            "Runtime optional features state (snapshot):",
            textwrap.indent("\n".join(diagnostics), "  "),
        ]
    else:
        return []

example output (truncated)

===================================== test session starts ======================================
platform darwin -- Python 3.13.6, pytest-8.4.1, pluggy-1.6.0
Runtime optional features state (snapshot):
  free-threading: unavailable (this interpreter was built without free-threading support)
  JIT: undetermined (no introspection API known for Python 3.13)
  py-limited-api: available
...

Command Line Interface (CLI) examples

Outputs may (really, should) vary depending on which python interpreter is active and how it was invoked

❯ python3.13 -m runtime_introspect
free-threading: unavailable (this interpreter was built without free-threading support)
JIT: undetermined (no introspection API known for Python 3.13)
py-limited-api: available

❯ PYTHON_JIT=1 python3.14 -m runtime_introspect
free-threading: unavailable (this interpreter was built without free-threading support)
JIT: enabled (by envvar PYTHON_JIT=1)
py-limited-api: available

❯ python3.14t -X gil=0 -m runtime_introspect
free-threading: enabled (forced by command line option -Xgil=0)
JIT: unavailable (this interpreter was built without JIT compilation support)
py-limited-api: unavailable (Python 3.14t and earlier free-threaded builds do not support py-limited-api)

Run python -m runtime_introspect --help to browse additional options.

Additional resources

Many more details can be inspected with the standard library sysconfig CLI (python -m sysconfig).

Also refer to python-introspection for a similar tool with a different approach and focus.