Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 94 lines (67 sloc) 3.372 kb
e71a5ff @mitsuhiko Started work on new request dispatching. Unittests not yet updated
authored
1 .. _shell:
2
ef0dc18 @mitsuhiko Added interactive Python docs, fixed part style.
authored
3 Working with the Shell
4 ======================
5
ce6e4cb @mitsuhiko 0.5 is 0.3 now, why skip numbers?
authored
6 .. versionadded:: 0.3
ef0dc18 @mitsuhiko Added interactive Python docs, fixed part style.
authored
7
8 One of the reasons everybody loves Python is the interactive shell. It
9 basically allows you to execute Python commands in real time and
10 immediately get results back. Flask itself does not come with an
11 interactive shell, because it does not require any specific setup upfront,
12 just import your application and start playing around.
13
14 There are however some handy helpers to make playing around in the shell a
15 more pleasant experience. The main issue with interactive console
16 sessions is that you're not triggering a request like a browser does which
17 means that :data:`~flask.g`, :data:`~flask.request` and others are not
18 available. But the code you want to test might depend on them, so what
19 can you do?
20
21 This is where some helper functions come in handy. Keep in mind however
22 that these functions are not only there for interactive shell usage, but
23 also for unittesting and other situations that require a faked request
24 context.
25
e71a5ff @mitsuhiko Started work on new request dispatching. Unittests not yet updated
authored
26 Generally it's recommended that you read the :ref:`request-context`
27 chapter of the documentation first.
ef0dc18 @mitsuhiko Added interactive Python docs, fixed part style.
authored
28
e71a5ff @mitsuhiko Started work on new request dispatching. Unittests not yet updated
authored
29 Creating a Request Context
30 --------------------------
ef0dc18 @mitsuhiko Added interactive Python docs, fixed part style.
authored
31
e71a5ff @mitsuhiko Started work on new request dispatching. Unittests not yet updated
authored
32 The easiest way to create a proper request context from the shell is by
33 using the :attr:`~flask.Flask.test_request_context` method which creates
34 us a :class:`~flask.ctx.RequestContext`:
ef0dc18 @mitsuhiko Added interactive Python docs, fixed part style.
authored
35
e71a5ff @mitsuhiko Started work on new request dispatching. Unittests not yet updated
authored
36 >>> ctx = app.test_request_context()
ef0dc18 @mitsuhiko Added interactive Python docs, fixed part style.
authored
37
e71a5ff @mitsuhiko Started work on new request dispatching. Unittests not yet updated
authored
38 Normally you would use the `with` statement to make this request object
39 active, but in the shell it's easier to use the
40 :meth:`~flask.ctx.RequestContext.push` and
41 :meth:`~flask.ctx.RequestContext.pop` methods by hand:
ef0dc18 @mitsuhiko Added interactive Python docs, fixed part style.
authored
42
43 >>> ctx.push()
44
e71a5ff @mitsuhiko Started work on new request dispatching. Unittests not yet updated
authored
45 From that point onwards you can work with the request object until you
46 call `pop`:
ef0dc18 @mitsuhiko Added interactive Python docs, fixed part style.
authored
47
48 >>> ctx.pop()
49
50 Firing Before/After Request
51 ---------------------------
52
53 By just creating a request context, you still don't have run the code that
e71a5ff @mitsuhiko Started work on new request dispatching. Unittests not yet updated
authored
54 is normally run before a request. This might result in your database
55 being unavailable if you are connecting to the database in a
56 before-request callback or the current user not being stored on the
ef0dc18 @mitsuhiko Added interactive Python docs, fixed part style.
authored
57 :data:`~flask.g` object etc.
58
59 This however can easily be done yourself. Just call
60 :meth:`~flask.Flask.preprocess_request`:
61
62 >>> ctx = app.test_request_context()
63 >>> ctx.push()
64 >>> app.preprocess_request()
65
66 Keep in mind that the :meth:`~flask.Flask.preprocess_request` function
67 might return a response object, in that case just ignore it.
68
69 To shutdown a request, you need to trick a bit before the after request
70 functions (triggered by :meth:`~flask.Flask.process_response`) operate on
71 a response object:
72
73 >>> app.process_response(app.response_class())
74 <Response 0 bytes [200 OK]>
75 >>> ctx.pop()
76
e71a5ff @mitsuhiko Started work on new request dispatching. Unittests not yet updated
authored
77 The functions registered as :meth:`~flask.Flask.teardown_request` are
78 automatically called when the context is popped. So this is the perfect
79 place to automatically tear down resources that were needed by the request
80 context (such as database connections).
81
ef0dc18 @mitsuhiko Added interactive Python docs, fixed part style.
authored
82
83 Further Improving the Shell Experience
84 --------------------------------------
85
86 If you like the idea of experimenting in a shell, create yourself a module
87 with stuff you want to star import into your interactive session. There
88 you could also define some more helper methods for common things such as
89 initializing the database, dropping tables etc.
90
91 Just put them into a module (like `shelltools` and import from there):
92
93 >>> from shelltools import *
Something went wrong with that request. Please try again.