1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
.. _commands:
.. |argparse| replace:: ``argparse``
.. _argparse: http://docs.python.org/dev/library/argparse.html
Command Line Pecan
==================
Any Pecan application can be controlled and inspected from the command line
using the built-in ``pecan`` command. The usage examples of the ``pecan``
command in this document are intended to be invoked from your project's root
directory.
Serving a Pecan App For Development
-----------------------------------
Pecan comes bundled with a lightweight WSGI development server based on
Python's ``wsgiref.simpleserver`` module.
Serving your Pecan app is as simple as invoking the ``pecan serve`` command::
$ pecan serve config.py
Starting server in PID 000.
serving on 0.0.0.0:8080, view at http://127.0.0.1:8080
...and then visiting it in your browser.
The server ``host`` and ``port`` in your configuration file can be changed as
described in :ref:`server_configuration`.
.. include:: reload.rst
:start-after: #reload
The Interactive Shell
---------------------
Pecan applications also come with an interactive Python shell which can be used
to execute expressions in an environment very similar to the one your
application runs in. To invoke an interactive shell, use the ``pecan shell``
command::
$ pecan shell config.py
Pecan Interactive Shell
Python 2.7.1 (r271:86832, Jul 31 2011, 19:30:53)
[GCC 4.2.1 (Based on Apple Inc. build 5658)
The following objects are available:
wsgiapp - This project's WSGI App instance
conf - The current configuration
app - webtest.TestApp wrapped around wsgiapp
>>> conf
Config({
'app': Config({
'root': 'myapp.controllers.root.RootController',
'modules': ['myapp'],
'static_root': '/Users/somebody/myapp/public',
'template_path': '/Users/somebody/myapp/project/templates',
'errors': {'404': '/error/404'},
'debug': True
}),
'server': Config({
'host': '0.0.0.0',
'port': '8080'
})
})
>>> app
<webtest.app.TestApp object at 0x101a830>
>>> app.get('/')
<200 OK text/html body='<html>\n ...\n\n'/936>
Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).
Using an Alternative Shell
++++++++++++++++++++++++++
``pecan shell`` has optional support for the `IPython <http://ipython.org/>`_
and `bpython <http://bpython-interpreter.org/>`_ alternative shells, each of
which can be specified with the ``--shell`` flag (or its abbreviated alias,
``-s``), e.g.,
::
$ pecan shell --shell=ipython config.py
$ pecan shell -s bpython config.py
.. _env_config:
Configuration from an environment variable
------------------------------------------
In all the examples shown, you will see that the `pecan` commands were
accepting a file path to the configuration file. An alternative to this is to
specify the configuration file in an environment variable (``PECAN_CONFIG``).
This is completely optional; if a file path is passed in explicitly, Pecan will
honor that before looking for an environment variable.
For example, to ``serve`` a Pecan application, a variable could be exported and
subsequently be re-used when no path is passed in::
$ export PECAN_CONFIG=/path/to/app/config.py
$ pecan serve
Starting server in PID 000.
serving on 0.0.0.0:8080, view at http://127.0.0.1:8080
Note that the path needs to reference a valid pecan configuration file,
otherwise the command will error out with a meaningful message indicating that
the path is invalid (for example, if a directory is passed in).
If ``PECAN_CONFIG`` is not set and no configuration is passed in, the command
will error out because it will not be able to locate a configuration file.
Extending ``pecan`` with Custom Commands
----------------------------------------
While the commands packaged with Pecan are useful, the real utility of its
command line toolset lies in its extensibility. It's convenient to be able to
write a Python script that can work "in a Pecan environment" with access to
things like your application's parsed configuration file or a simulated
instance of your application itself (like the one provided in the ``pecan
shell`` command).
Writing a Custom Pecan Command
++++++++++++++++++++++++++++++
As an example, let's create a command that can be used to issue a simulated
HTTP GET to your application and print the result. Its invocation from the
command line might look something like this::
$ pecan wget config.py /path/to/some/resource
Let's say you have a distribution with a package in it named ``myapp``, and
that within this package is a ``wget.py`` module::
# myapp/myapp/wget.py
import pecan
from webtest import TestApp
class GetCommand(pecan.commands.BaseCommand):
'''
Issues a (simulated) HTTP GET and returns the request body.
'''
arguments = pecan.commands.BaseCommand.arguments + ({
'name': 'path',
'help': 'the URI path of the resource to request'
},)
def run(self, args):
super(GetCommand, self).run(args)
app = TestApp(self.load_app())
print app.get(args.path).body
Let's analyze this piece-by-piece.
Overriding the ``run`` Method
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
First, we're subclassing ``pecan.commands.BaseCommand`` and extending
the ``run`` method to:
* Load a Pecan application - ``self.load_app()``
* Wrap it in a fake WGSI environment - ``webtest.TestApp()``
* Issue an HTTP GET request against it - ``app.get(args.path)``
Defining Custom Arguments
,,,,,,,,,,,,,,,,,,,,,,,,,
The ``arguments`` class attribute is used to define command line arguments
specific to your custom command. You'll notice in this example that we're
*adding* to the arguments list provided by ``pecan.commands.BaseCommand``
(which already provides an argument for the ``config_file``), rather
than overriding it entirely.
The format of the ``arguments`` class attribute is a *tuple* of dictionaries,
with each dictionary representing an argument definition in the
same format accepted by Python's |argparse|_ module (more specifically,
``argparse.ArgumentParser.add_argument``). By providing a list of arguments in
this format, the ``pecan`` command can include your custom commands in the help
and usage output it provides::
$ pecan -h
usage: pecan [-h] command ...
positional arguments:
command
wget Issues a (simulated) HTTP GET and returns the request body
serve Open an interactive shell with the Pecan app loaded
...
::
$ pecan wget -h
usage: pecan wget [-h] config_file path
$ pecan wget config.py /path/to/some/resource
Additionally, you'll notice that the first line of ``GetCommand``'s docstring
- ``Issues a (simulated) HTTP GET and returns the request body`` - is
automatically used to describe the ``wget`` command in the output for ``$ pecan
-h``. Following this convention allows you to easily integrate a summary for
your command into the Pecan command line tool.
Registering a Custom Command
++++++++++++++++++++++++++++
Now that you've written your custom command, you’ll need to tell your
distribution’s ``setup.py`` about its existence and reinstall. Within your
distribution’s ``setup.py`` file, you'll find a call to ``setuptools.setup()``,
e.g., ::
# myapp/setup.py
...
setup(
name='myapp',
version='0.1',
author='Joe Somebody',
...
)
Assuming it doesn't exist already, we'll add the ``entry_points`` argument
to the ``setup()`` call, and define a ``[pecan.command]`` definition for your custom
command::
# myapp/setup.py
...
setup(
name='myapp',
version='0.1',
author='Joe Somebody',
...
entry_points="""
[pecan.command]
wget = myapp.wget:GetCommand
"""
)
Once you've done this, reinstall your project in development to register the
new entry point::
$ python setup.py develop
...and give it a try::
$ pecan wget config.py /path/to/some/resource
|
