[twill] A word of thanks and a suggestion, inc. tiny bit of code

[Titus Brown]

Hi Wilmer,

-> First of all I must say that I have discovered Twill only about one hour 
-> ago, but I believe I have already fallen in love with it!
-> 
-> Why? It's straightforward and simple to use, and it just helped me code 
-> something I had on my to-do list for a few months now.. but for which I 
-> simply could not find the time. I'm very thankful!

I'm glad to hear it ;)

-> I have used Twill for a use case that has not been mentioned yet, namely a 
-> small webspider to connect to a website, fill in a few forms, and return 
-> some values.

You're one of several people using it for this, I think; I must admit that
initially I was focused on Web testing, and I ignored the more general
application of scripted Web browsing.

-> Now, I really hope that the following is not a foolish suggestion for 
-> something that already existed in some form (perhaps I have overlooked 
-> something very obvious :O)

No worries ;)

-> Because I needed some more logic and a connection to a back-end database, I 
-> was very happy that I could use Twill from/via Python. However, at one 
-> point I really needed to have the contents/'raw html' from the page 
-> accessed using the 'go' command.
-> 
-> So I have added the command 'get_page()' (sorry, no time right now to dive 
-> into Darcs):
-> 
-> def get_page():
->    """
->    >> get_page
-> 
->    Return the HTML of the current page.
->    """
->    return browser.get_html()
-> 
-> 
-> It's basically the same thing as 'show()', but it returns the browser html 
-> so that it can be used by Python, e.g.:  page_data = get_page()   ; 
-> doSomethingWith(page_data)

So, of course I understand the utility of functions like this.  The
question is, why not just use 'browser.get_html()' in your code?

I'm probably over-analyzing the situation, but there are pros and cons
to making the commands.py functions return stuff to Python:

First, I'm committed to providing a simple, well-documented API to the
twill scripting language.  I don't want to clutter up that API with
information useful only to Python programmers; since your get_page
function is a no-op for someone using from the twill shell, I don't
want to add it into commands.py.  (Every function in commands.py is
available from the shell.)

On the other hand, using twill.commands directly from Python code is one
of the growing use cases for twill, and it seems silly to have every
function return nothing!  People have requested that 'find' and 'show'
return things, in particular.

What I've been planning to do is make the 'browser' object/TwillBrowser
class interface documented and stable.  Would this answer the needs of
people who want to use twill as a Python-accessible Web browser?

This has multiple advantages:

 * commands.py will serve as "instant documentation" on how to use the
   interface for many tasks;

 * you could instantiate a new Web browser just by asking for a new
   TwillBrowser(), and have multiple Web browser instances running at
   the same time;
   
 * you could subclass TwillBrowser in your own code to add new
   functions;

 * documentation for TwillBrowser functions could be more technical than
   documentation for commands.py functions.

The downside is that the interface is likely to be a bit more *complex*
than the commands.py functions.

Does anyone have any thoughts on this approach?

cheers,
--titus