pyramid-introspector

Extract route and view metadata from Pyramid applications, with an extension system that handles library-specific introspection for Cornice and pycornmarsh.

Why

Pyramid's introspectable registry holds rich metadata about routes and views, but extracting it -- especially when libraries like Cornice and pycornmarsh layer their own conventions on top -- requires non-trivial, repetitive code. This library provides a single, tested entry point for that work.

Installation

pip install pyramid-introspector

With Cornice/Marshmallow support:

pip install pyramid-introspector[cornice]

Quick start

from pyramid.config import Configurator
from pyramid_introspector import PyramidIntrospector

config = Configurator()
# ... add routes, views, include cornice, etc.
config.commit()

introspector = PyramidIntrospector(config.registry)
routes = introspector.introspect()

for route in routes:
    for view in route.views:
        print(f"{view.method:6} {route.pattern}")
        if view.request_schema:
            print(f"       body: {view.request_schema.name}")
        if view.response_schema:
            print(f"       resp: {view.response_schema.name}")

What you get

Each RouteInfo contains:

Each ViewInfo contains:

Extensions

Extensions enrich the base route/view data with library-specific metadata. Built-in extensions are loaded automatically when their dependencies are installed.

Cornice

Activated when cornice is installed. Discovers Cornice services, matches them to routes by path, and extracts Marshmallow schemas from service definitions -- both composite schemas (body/querystring/path as nested fields) and flat schemas with location detection from validators.

pycornmarsh

Activated when cornice is installed. Reads pycornmarsh predicates (pcm_request, pcm_responses, pcm_tags, pcm_summary, pcm_description, pcm_security, pcm_show) from Cornice service definition args and populates the corresponding ViewInfo fields.

Writing custom extensions

Any class that satisfies the IntrospectionExtension protocol can be used:

from pyramid_introspector.extensions import IntrospectionExtension
from pyramid_introspector.models import RouteInfo

class MyExtension:
    name = "my_library"

    def is_available(self) -> bool:
        try:
            import my_library
            return True
        except ImportError:
            return False

    def enrich(self, registry, routes: list[RouteInfo]) -> list[RouteInfo]:
        # Mutate views with library-specific metadata
        return routes

Pass it directly:

introspector = PyramidIntrospector(registry, extensions=[MyExtension()])

Or register it via entry points for automatic discovery:

[project.entry-points."pyramid_introspector.extensions"]
my_library = "my_package:MyExtension"

Development

git clone https://github.com/your-org/pyramid-introspector.git
cd pyramid-introspector
uv sync --group dev

Run tests:

uv run pytest

Lint and format:

uv run ruff check src/ tests/
uv run black src/ tests/

License

MIT