A pyramid plugin that describes a pyramid application URL hierarchy via inspection.
Project description
A pyramid plugin that describes a pyramid application URL hierarchy, either by responding to an HTTP request or on the command line, via application inspection and reflection. It has built-in support for plain-text hierachies, reStructuredText, HTML, PDF, JSON, YAML, WADL, and XML, however other custom formats can be added easily.
Exposing an application’s structure via HTTP is useful to dynamically generate an API description (via WADL, JSON, or YAML) or to create documentation directly from source code.
On the command-line it is useful to get visibility into an application’s URL structure and hierarchy so that it can be understood and maintained.
TL;DR
Install:
$ pip install pyramid-describeCommand-line example:
$ pdescribe example.ini --format txt
/ # The application root.
├── contact/ # Contact manager.
│ ├── <POST> # Creates a new 'contact' object.
│ └── {CONTACTID} # RESTful access to a specific contact.
│ ├── <DELETE> # Delete this contact.
│ ├── <GET> # Get this contact's details.
│ └── <PUT> # Update this contact's details.
├── login # Authenticate against the server.
└── logout # Remove authentication tokens.Examples of the above application in all other formats with built-in support are available at: text (pure-ASCII), reStructuredText, HTML, PDF, JSON, YAML, WADL, and XML.
Configuration
When pyramid-describe is integrated via inclusion (e.g. config.include('pyramid_describe')), the module will auto-create DescribeController’s as defined in the application’s settings. The following configurations can be specified there (note that the first one controls the prefix set on the others):
describe.prefixes : list(str), default: ‘describe’
Defines the prefix or the list of prefixes that pyramid-describe settings will be searched for in the configuration. For each prefix, a separate DescribeController will be created and attached to the application router. The following example attaches two controllers at /desc-one and /desc-two:
[app:main] describe.prefixes =describe-one describe-twodescribe-one.attach =/desc-one# other `describe-one` options... describe-two.attach =/desc-two# other `describe-two` options...describe.class : resolve-spec, default: pyramid_describe.DescribeController
Sets the global default Controller class that will be instantiated for each of the stanzas defined in describe.prefixes. Note that this option can be overriden on a per-stanza basis.
{PREFIX}.class : resolve-spec, default: describe.class
Sets the Controller class that will be instantiated for this PREFIX stanza, overriding describe.class.
{PREFIX}.attach : str, default: /describe
Specifies the path to attach the controller to the current application’s router. Note that this uses the add_controller directive, and ensures that pyramid-controllers has already been added via an explicit call to config.include(). This path will serve the default format: to request alternate formats, use “PATH/FILENAME.EXT” (where FILENAME is controlled by the {PREFIX}.filename configuration and EXT specifies the format) or use the “format=EXT” query-string. Examples using the default settings:
http://localhost:8080/describe/application.txt http://localhost:8080/describe/application.json http://localhost:8080/describe?format=json
