# Developing twill

twill is entirely written in Python. You will need Python 2.3 or later to develop it.

# Package tests

twill comes with several unit tests. They depend on nose and Quixote 2.3. To run them, type 'python setup.py test' in the top package directory.

# Licensing

twill 0.8 and above are licensed under the MIT license. All code currently contained in twill is Copyright (C) 2005, 2006, 2007 C. Titus Brown <titus@idyll.org>.

In plain English: I own the code, but you're welcome to use it, subsume it into other projects, and distribute it freely. However, you must retain copyright attribution.

pyparsing, BeautifulSoup, and mechanize are all included with twill, but are under their own licenses.

# Developer releases

"Developer releases" incorporating all recent significant changes are made available at http://darcs.idyll.org/~t/projects/twill-latest.tar.gz

You can install them with easy_install by typing

    easy_install -f http://darcs.idyll.org/~t/projects/twill-latest.tar.gz

# Obtaining twill with darcs

darcs is a distributed version control system that allows users to maintain their own versions of various programs. It's a convenient way for me to make the latest source code available quickly, and it also is a dandy way to submit patches.

To obtain twill using darcs, install darcs and then type

    darcs get http://darcs.idyll.org/~t/projects/twill/

To propose a change to the lead developer, make the changes and then do a 'send':

    darcs record -am "explanation of change"
    darcs send -a

To pull in changes made by the lead developer some time later:

    darcs pull

# Advanced documentation

twill uses a melange of different packages. Here are some potentially useful links:

> - urllib2.py: the missing manual -- a detailed discussion of urllib2 functionality that can be directly applied to twill.

## Future Plans

TODO:

for 9.0 (beta).

> 1. RECORDING.
> 2. execute directories/directory trees.
> 3. expose 'browser' & document re Grig; regexp esp.; make source docs.
> 4. twill-fork: make file writing stuff optional; test massive fork fn.
> 5. add config directives for socket timeout.
> 6. directory stuff: import from specific place, access script location.

Misc fixes & cleanups:

> 1. Paul McGuire's pyparsing suggestions.
> 2. cookie "1" vs 1, in cookielib.
> 3. extend_with etc. -- module namespaces, e.g. extmodule.fn?
> 4. implement more complex proxy support. proxies proxies proxies.
> 5. 'history' to show command history...
> 6. record commands to script
> 7. command line option for stdout -> file

Random ideas:

> 1. Build twill interfaces for zope.testbrowser and mechanoid and pycurl.

>    (This shouldn't be too difficult, since both are based on mechanize...)

> 2. Develop twill-like languages for PAMIE and PyXPCOM. Note that the hard work, at least for PAMIE, is already done; check out the PAMIE examples page.

Contributions are welcome & will be duly acknowledged!