mechanize — Documentation
Full API documentation is in the docstrings and the documentation of
urllib2. The documentation in these web pages is in need of reorganisation at the moment, after the merge of ClientCookie and ClientForm into mechanize.
Tests and examples
The front page has some introductory examples.
examples directory in the source packages contains a couple of silly, but working, scripts to demonstrate basic use of the module.
See also the forms examples (these examples use the forms API independently of
To run the tests:
There are some tests that try to fetch URLs from the internet. To include those in the test run:
python test.py discover --tag internet
mechanize exports the complete interface of
urllib2. See the
urllib2 documentation. For example:
response = mechanize.urlopen("http://www.example.com/")
These notes explain the relationship between mechanize, ClientCookie, ClientForm,
urllib2, and which to use when. If you’re just using mechanize, and not any of those other libraries, you can ignore this section.
mechanize works with Python 2.4, Python 2.5, Python 2.6, and Python 2.7.
When using mechanize, anything you would normally import from
urllib2should be imported from
Use of mechanize classes with
urllib2(and vice-versa) is no longer supported. However, existing classes implementing the
urllib2 Handlerinterface are likely to work unchanged with mechanize.
mechanize now only imports
urllib2. The rest is forked. I intend to merge fixes from Python trunk frequently.
ClientForm is no longer maintained as a separate package. The code is now part of mechanize, and its interface is now exported through module mechanize (since mechanize 0.2.0). Old code can simply be changed to
import mechanize as ClientFormand should continue to work.
ClientCookie is no longer maintained as a separate package. The code is now part of mechanize, and its interface is now exported through module mechanize (since mechanize 0.1.0). Old code can simply be changed to
import mechanize as ClientCookieand should continue to work.
The cookie handling parts of mechanize are in Python 2.4 standard library as module
cookieliband extensions to module
urllib2. mechanize does not currently use
cookielib, due to the presence of thread synchronisation code in
cookielibthat is not present in the mechanize fork of
API differences between mechanize and
mechanize provides additional features.
mechanize.urlopendiffers in its behaviour: it handles cookies, whereas
urllib2.urlopendoes not. To make a
urlopenfunction with the
handler_classes = [mechanize.ProxyHandler,
opener = mechanize.OpenerDirector()
for handler_class in handler_classes:
urlopen = opener.open
- Since Python 2.6,
Requestobjects internally. However,
urllib2.Requesthas no timeout constructor argument, and
urllib2.urlopen()ignores this parameter.
timeoutconstructor argument which is used to set the attribute of the same name, and
mechanize.urlopen()does not ignore the timeout attribute.
UserAgent vs UserAgentBase
mechanize.UserAgent is a trivial subclass of
mechanize.UserAgentBase, adding just one method,
.set_seekable_responses() (see the documentation on seekable responses).
The reason for the extra class is that
mechanize.Browser depends on seekable response objects (because response objects are used to implement the browser history).
I prefer questions and comments to be sent to the mailing list rather than direct to me.
John J. Lee, July 2010.