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
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
<title>twill's Python API</title>
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="twill-s-python-api">
<h1 class="title">twill's Python API</h1>
<p>Using TwillBrowser
Making extensions</p>
<p>twill is essentially a thin shell around the <a class="reference" href="http://wwwsearch.sf.net/">mechanize</a> package. All
twill commands are implemented in the <tt class="docutils literal"><span class="pre">commands.py</span></tt> file, and
<a class="reference" href="http://pyparsing.sourceforge.net/">pyparsing</a> does the work of parsing the input and converting it into
Python commands (see <tt class="docutils literal"><span class="pre">parse.py</span></tt>). Interactive shell work and
readline support is implemented via the <a class="reference" href="http://docs.python.org/lib/module-cmd.html">cmd</a> module (from the
standard Python library).</p>
<div class="section" id="using-twill-from-python">
<h1><a name="using-twill-from-python">Using twill from Python</a></h1>
<p>There are two fairly simple ways to use twill from Python. (They are
compatible with each other, so you don't need to choose between them;
just use whichever is appropriate.)</p>
<p>The first is to simply import all of the commands in <tt class="docutils literal"><span class="pre">commands.py</span></tt> and
use them directly from Python. For example,</p>
<pre class="literal-block">
from twill.commands import *
go("http://www.python.org/")
showforms()
</pre>
<p>This has the advantage of being very simple, as well as being tied
directly to the documented set of commands in <a class="reference" href="commands.html">the commands
reference</a>.</p>
<p>However, the functions in <tt class="docutils literal"><span class="pre">commands.py</span></tt> are too simple for some situations.
In particular, they do not have any return values, so in order to e.g. get
the HTML for a particular page, you will need to talk to the actual "Web
browser" object that twill uses.</p>
<p>To talk to the Web browser directly, call the <tt class="docutils literal"><span class="pre">get_browser</span></tt> function:</p>
<pre class="literal-block">
from twill import get_browser
b = get_browser()
b.go("http://www.python.org/")
b.showforms()
</pre>
<p>This is the second way to use twill from Python, and it is much more flexible.
All of the functions in <tt class="docutils literal"><span class="pre">commands.py</span></tt> use this same browser object, so
you can mix and match:</p>
<pre class="literal-block">
from twill import get_browser
b = get_browser()
from twill.commands import *
go("http://www.python.org/")
b.showforms()
</pre>
<p>The basic difference is that functions available through the browser object
are intended for use from Python, while <tt class="docutils literal"><span class="pre">commands.py</span></tt> functions define
the twill <em>language</em>. In fact, all of the functions in <tt class="docutils literal"><span class="pre">commands.py</span></tt>
are small snippets of code wrapped around the browser object.</p>
<p>For more information on the functions exposed by the browser object,
see the <strong>TwillBrowser</strong> section below.</p>
</div>
<div class="section" id="twillbrowser">
<h1><a name="twillbrowser">TwillBrowser</a></h1>
<p>...</p>
</div>
<div class="section" id="extending-twill">
<h1><a name="extending-twill">Extending twill</a></h1>
<p>Right now twill is very easy to extend: just build a Python module
that exports the functions you want to call, place it in the
PYTHONPATH, and run <tt class="docutils literal"><span class="pre">extend_with</span> <span class="pre"><modulename></span></tt>. See
<tt class="docutils literal"><span class="pre">extensions/mailman_sf.py</span></tt> for an extension that helps deal
with mailman lists on SourceForge; this extension is used by
<tt class="docutils literal"><span class="pre">examples/discard-sf-mailman-msgs</span></tt>.</p>
<p>Notes:</p>
<blockquote>
<ul class="simple">
<li>If your extension raises <tt class="docutils literal"><span class="pre">SystemExit</span></tt>, twill will stop
processing the script. This is a useful way to build in
conditionals, e.g. see the <tt class="docutils literal"><span class="pre">discard-sf-mailman-msgs</span></tt> example
script.</li>
</ul>
</blockquote>
</div>
<div class="section" id="passing-variables-from-python-into-twill">
<h1><a name="passing-variables-from-python-into-twill">Passing variables from Python into twill</a></h1>
<p>Suppose you write an extension function, and you want to return some
values from that extension function for later use in filling out forms.
How do you do this?</p>
<p>The simplest way is to simply insert them into the global or local
dictionary, like so:</p>
<pre class="literal-block">
from twill.namespaces import get_twill_glocals
global_dict, local_dict = get_twill_glocals()
global_dict['varname'] = value
</pre>
<p>You can then use the usual variable access methods to substitute for
varname, e.g.</p>
<pre class="literal-block">
formvalue 1 field $varname
</pre>
</div>
<div class="section" id="using-twill-in-other-python-programs">
<h1><a name="using-twill-in-other-python-programs">Using twill in other Python programs</a></h1>
<p>All of the commands available in twill are implemented as top-level functions
in the <cite>twill.commands</cite> module. For example, to use twill functionality from
another Python program, you can do:</p>
<pre class="literal-block">
from twill.commands import go, showforms, formclear, fv, submit
go('http://issola.caltech.edu/~t/qwsgi/qwsgi-demo.cgi/')
go('./widgets')
showforms()
formclear('1')
fv("1", "name", "test")
fv("1", "password", "testpass")
fv("1", "confirm", "yes")
showforms()
submit('0')
</pre>
<p>Note that all arguments need to be strings, at least for the moment.</p>
<p>You can capture command output by passing any write-enabled file handle
to twill.set_output, e.g.</p>
<pre class="literal-block">
twill.set_output(StringIO())
</pre>
<p>will send all non-error output into a StringIO() object.</p>
<p>twill also provides a simple wrapper for <a class="reference" href="http://wwwsearch.sf.net/">mechanize</a> functionality, in
the <cite>browser.py</cite> module. This may be useful for twill extensions as
well as for other toolkits, but the API is still unstable.</p>
</div>
</div>
</body>
</html>
|
