For a big application with several views, it can be hard to keep the view
configuration details in your head, even if you defined all the views yourself.
You can use the pviews command in a terminal window to print a summary of
matching routes and views for a given URL in your application. The pviews
command accepts two arguments. The first argument to pviews is the path to
your application's .ini file and section name inside the .ini file
which points to your application. This should be of the format
config_file#section_name. The second argument is the URL to test for
matching views. The section_name may be omitted; if it is, it's considered
to be main.

The output always has the requested URL at the top and below that all the views
that matched with their view configuration details. In this example only one
view matches, so there is just a single View section. For each matching view,
the full code path to the associated view callable is shown, along with any
permissions and predicates that are part of that view configuration.

In this case, we are dealing with a URL dispatch application. This
specific URL has two matching routes. The matching route information is
displayed first, followed by any views that are associated with that route. As
you can see from the second matching route output, a route can be associated
with more than one view.

For a URL that doesn't match any views, pviews will simply print out a Not
found message.

Once you've installed your program for development using pipinstall-e.,
you can use an interactive Python shell to execute expressions in a Python
environment exactly like the one that will be used when your application runs
"for real". To do so, use the pshell command line utility.

The argument to pshell follows the format config_file#section_name
where config_file is the path to your application's .ini file and
section_name is the app section name inside the .ini file which
points to your application. For example, your application .ini file might
have an [app:main] section that looks like so:

The WSGI application that is loaded will be available in the shell as the
app global. Also, if the application that is loaded is the Pyramid
app with no surrounding middleware, the root object returned by the
default root factory, registry, and request will be available.

You can also simply rely on the main default section name by omitting any
hash after the filename:

It is convenient when using the interactive shell often to have some variables
significant to your application already loaded as globals when you start the
pshell. To facilitate this, pshell will look for a special [pshell]
section in your INI file and expose the subsequent key/value pairs to the
shell. Each key is a variable name that will be global within the pshell
session; each value is a dotted Python name. If specified, the special
key setup should be a dotted Python name pointing to a callable
that accepts the dictionary of globals that will be loaded into the shell. This
allows for some custom initializing code to be executed each time the
pshell is run. The setup callable can also be specified from the
commandline using the --setup option which will override the key in the INI
file.

For example, you want to expose your model to the shell along with the database
session so that you can mutate the model on an actual database. Here, we'll
assume your model is stored in the myapp.models package.

By defining the setup callable, we will create the module
myapp.lib.pshell containing a callable named setup that will receive
the global environment before it is exposed to the shell. Here we mutate the
environment's request as well as add a new value containing a WebTest version
of the application to which we can easily submit requests.

When this INI file is loaded, the extra variables m, session and t
will be available for use immediately. Since a setup callable was also
specified, it is executed and a new variable testapp is exposed, and the
request is configured to generate urls from the host
http://www.example.com. For example:

The pshell command can be easily extended with alternate REPLs if the
default python REPL is not satisfactory. Assuming you have a binding
installed such as pyramid_ipython it will normally be auto-selected and
used. You may also specifically invoke your choice with the -pchoice or
--python-shellchoice option.

You can use the proutes command in a terminal window to print a summary of
routes related to your application. Much like the pshell command (see
The Interactive Shell), the proutes command accepts one argument with
the format config_file#section_name. The config_file is the path to
your application's .ini file, and section_name is the app section
name inside the .ini file which points to your application. By default,
the section_name is main and can be omitted.

proutes generates a table with four columns: Name, Pattern, View, and
Method. The items listed in the Name column are route names, the items
listed in the Pattern column are route patterns, the items listed in the View
column are representations of the view callable that will be invoked when a
request matches the associated route pattern, and the items listed in the
Method column are the request methods that are associated with the route name.
The View column may show <unknown> if no associated view callable could be
found. The Method column, for the route name, may show either <routemismatch> if the view callable does not accept any of the route's request
methods, or * if the view callable will accept any of the route's request
methods. If no routes are configured within your application, nothing will be
printed to the console when proutes is executed.

It is convenient when using the proutes command often to configure which
columns and the order you would like to view them. To facilitate this,
proutes will look for a special [proutes] section in your .ini file
and use those as defaults.

For example you may remove the request method and place the view first:

If you want to temporarily configure the columns and order, there is the
argument --format, which is a comma separated list of columns you want to
include. The current available formats are name, pattern, view, and
method.

A tween is a bit of code that sits between the main Pyramid application
request handler and the WSGI application which calls it. A user can get a
representation of both the implicit tween ordering (the ordering specified by
calls to pyramid.config.Configurator.add_tween()) and the explicit tween
ordering (specified by the pyramid.tweens configuration setting) using the
ptweens command. Tween factories will show up represented by their
standard Python dotted name in the ptweens output.

For example, here's the ptweens command run against a system configured
without any explicit tweens:

You can use the prequest command-line utility to send a request to your
application and see the response body without starting a server.

There are two required arguments to prequest:

The config file/section: follows the format config_file#section_name,
where config_file is the path to your application's .ini file and
section_name is the app section name inside the .ini file. The
section_name is optional; it defaults to main. For example:
development.ini.

The path: this should be the non-URL-quoted path element of the URL to the
resource you'd like to be rendered on the server. For example, /.

For example:

$ $VENV/bin/prequest development.ini /

This will print the body of the response to the console on which it was
invoked.

Several options are supported by prequest. These should precede any config
file name or URL.

prequest has a -d (i.e., --display-headers) option which prints the
status and headers returned by the server before the output:

$ $VENV/bin/prequest -d development.ini /

This will print the status, headers, and the body of the response to the
console.

You can add request header values by using the --header option:

$ $VENV/bin/prequest --header=Host:example.com development.ini /

Headers are added to the WSGI environment by converting them to their CGI/WSGI
equivalents (e.g., Host=example.com will insert the HTTP_HOST header
variable as the value example.com). Multiple --header options can be
supplied. The special header value content-type sets the CONTENT_TYPE
in the WSGI environment.

By default, prequest sends a GET request. You can change this by using
the -m (aka --method) option. GET, HEAD, POST, and
DELETE are currently supported. When you use POST, the standard input
of the prequest process is used as the POST body:

pdistreport takes no options. Its output is useful to paste into a
pastebin when you are having problems and need someone with more familiarity
with Python packaging and distribution than you have to look at your
environment.

All web applications are, at their hearts, systems which accept a request and
return a response. When a request is accepted by a Pyramid application,
the system receives state from the request which is later relied on by your
application code. For example, one view callable may assume it's
working against a request that has a request.matchdict of a particular
composition, while another assumes a different composition of the matchdict.

In the meantime, it's convenient to be able to write a Python script that can
work "in a Pyramid environment", for instance to update database tables used by
your Pyramid application. But a "real" Pyramid environment doesn't have
a completely static state independent of a request; your application (and
Pyramid itself) is almost always reliant on being able to obtain information
from a request. When you run a Python script that simply imports code from
your application and tries to run it, there just is no request data, because
there isn't any real web request. Therefore some parts of your application and
some Pyramid APIs will not work.

For this reason, Pyramid makes it possible to run a script in an
environment much like the environment produced when a particular
request reaches your Pyramid application. This is achieved by
using the pyramid.paster.bootstrap() command in the body of your script.

The configuration loaded by the above bootstrap example will use the
configuration implied by the [pipeline:main] section of your configuration
file by default. Specifying /path/to/my/development.ini is logically
equivalent to specifying /path/to/my/development.ini#main. In this case,
we'll be using a configuration that includes an app object which is wrapped
in the Paste "translogger" middleware (which logs requests to the
console).

You can also specify a particular section of the PasteDeploy .ini file to
load instead of main:

The above example specifies the anotherapp, pipeline, or
composite section of your PasteDeploy configuration file. The app
object present in the env dictionary returned by
pyramid.paster.bootstrap() will be a Pyramidrouter.

By default, Pyramid will generate a request object in the env dictionary
for the URL http://localhost:80/. This means that any URLs generated by
Pyramid during the execution of your script will be anchored here. This is
generally not what you want.

So how do we make Pyramid generate the correct URLs?

Assuming that you have a route configured in your application like so:

config.add_route('verify','/verify/{code}')

You need to inform the Pyramid environment that the WSGI application is
handling requests from a certain base. For example, we want to simulate
mounting our application at https://example.com/prefix, to ensure that the
generated URLs are correct for our deployment. This can be done by either
mutating the resulting request object, or more simply by constructing the
desired request and passing it into bootstrap():

By default, pyramid.paster.bootstrap() does not configure logging
parameters present in the configuration file. If you'd like to configure
logging based on [logger] and related sections in the configuration file,
use the following command:

A "console script" is setuptools terminology for a script that gets
installed into the bin directory of a Python virtual environment
(or "base" Python environment) when a distribution which houses that
script is installed. Because it's installed into the bin directory of a
virtual environment when the distribution is installed, it's a convenient way
to package and distribute functionality that you can call from the
command-line. It's often more convenient to create a console script than it is
to create a .py script and instruct people to call it with the "right"
Python interpreter. A console script generates a file that lives in bin,
and when it's invoked it will always use the "right" Python environment, which
means it will always be invoked in an environment where all the libraries it
needs (such as Pyramid) are available.

In general, you can make your script into a console script by doing the
following:

Use an existing distribution (such as one you've already created via
pcreate) or create a new distribution that possesses at least one package
or module. It should, within any module within the distribution, house a
callable (usually a function) that takes no arguments and which runs any of
the code you wish to run.

Add a [console_scripts] section to the entry_points argument of the
distribution which creates a mapping between a script name and a dotted name
representing the callable you added to your distribution.

Run pipinstall-e. or pipinstall. to get your distribution
reinstalled. When you reinstall your distribution, a file representing the
script that you named in the last step will be in the bin directory of
the virtual environment in which you installed the distribution. It will be
executable. Invoking it from a terminal will execute your callable.

As an example, let's create some code that can be invoked by a console script
that prints the deployment settings of a Pyramid application. To do so, we'll
pretend you have a distribution with a package in it named myproject.
Within this package, we'll pretend you've added a scripts.py module which
contains the following code:

# myproject.scripts moduleimportoptparseimportsysimporttextwrapfrompyramid.pasterimportbootstrapdefsettings_show():description="""\ Print the deployment settings for a Pyramid application. Example: 'show_settings deployment.ini' """usage="usage: %prog config_uri"parser=optparse.OptionParser(usage=usage,description=textwrap.dedent(description))parser.add_option('-o','--omit',dest='omit',metavar='PREFIX',type='string',action='append',help=("Omit settings which start with PREFIX (you can use this ""option multiple times)"))options,args=parser.parse_args(sys.argv[1:])ifnotlen(args)>=1:print('You must provide at least one argument')return2config_uri=args[0]omit=options.omitifomitisNone:omit=[]env=bootstrap(config_uri)settings,closer=env['registry'].settings,env['closer']try:fork,vinsettings.items():ifany([k.startswith(x)forxinomit]):continueprint('%-40s%-20s'%(k,v))finally:closer()

This script uses the Python optparse module to allow us to make sense out
of extra arguments passed to the script. It uses the
pyramid.paster.bootstrap() function to get information about the
application defined by a config file, and prints the deployment settings
defined in that config file.

After adding this script to the package, you'll need to tell your
distribution's setup.py about its existence. Within your distribution's
top-level directory, your setup.py file will look something like this:

We're going to change the setup.py file to add a [console_scripts]
section within the entry_points string. Within this section, you should
specify a scriptname=dotted.path.to:yourfunction line. For example:

[console_scripts]show_settings=myproject.scripts:settings_show

The show_settings name will be the name of the script that is installed
into bin. The colon (:) between myproject.scripts and
settings_show above indicates that myproject.scripts is a Python
module, and settings_show is the function in that module which contains the
code you'd like to run as the result of someone invoking the show_settings
script from their command line.

Once you've done this, invoking $VENV/bin/pipinstall-e. will install a
file named show_settings into the $somevenv/bin directory with a
small bit of Python code that points to your entry point. It will be
executable. Running it without any arguments will print an error and exit.
Running it with a single argument that is the path of a config file will print
the settings. Running it with an --omit=foo argument will omit the settings
that have keys that start with foo. Running it with two "omit" options
(e.g., --omit=foo--omit=bar) will omit all settings that have keys that
start with either foo or bar: