[wwwsearch-commits] r17633 - wwwsearch/ClientForm/trunk

[jjlee at codespeak.net]

Author: jjlee
Date: Sat Sep 17 22:56:07 2005
New Revision: 17633

Modified:
   wwwsearch/ClientForm/trunk/README.html.in
Log:
Update README

Modified: wwwsearch/ClientForm/trunk/README.html.in
==============================================================================
--- wwwsearch/ClientForm/trunk/README.html.in	(original)
+++ wwwsearch/ClientForm/trunk/README.html.in	Sat Sep 17 22:56:07 2005
@@ -51,117 +51,7 @@
 
 <p>A more complicated example:
 
-@{colorize(r"""
- import ClientForm
- import urllib2
- request = urllib2.Request("http://www.example.com/form.html")
- response = urllib2.urlopen(request)
- forms = ClientForm.ParseResponse(response)
- response.close()
- form = forms[0]
- print form  # very useful!
-
- # Indexing allows setting and retrieval of control values
- original_text = form["comments"]  # a string, NOT a Control instance
- form["comments"] = "Blah."
-
- # Controls that represent lists (checkbox, select and radio lists) are
- # ListControls.  Their values are sequences of list item names.
- # They come in two flavours: single- and multiple-selection:
- print form.possible_items("cheeses")
- form["favorite_cheese"] = ["brie"]  # single
- form["cheeses"] = ["parmesan", "leicester", "cheddar"]  # multi
- #  is the "parmesan" item of the "cheeses" control selected?
- print "parmesan" in form["cheeses"]
- #  does cheeses control have a "caerphilly" item?
- print "caerphilly" in form.possible_items("cheeses")
-
- # Sometimes one wants to set or clear individual items in a list:
- #  select the item named "gorgonzola" in the first control named "cheeses"
- form.set(True, "gorgonzola", "cheeses")
- # You can be more specific: supply at least one of name, type, kind, id
- # and nr (most other methods on HTMLForm take the same form of arguments):
- #  deselect "edam" in third CHECKBOX control
- form.set(False, "edam", type="checkbox", nr=2)
-
- # You can explicitly say that you're referring to a ListControl:
- #  set whole value (rather than just one item of) "cheeses" ListControl
- form.set_value(["gouda"], name="cheeses", kind="list")
- #  last example is almost equivalent to following (but insists that the
- #  control be a ListControl -- so it will skip any non-list controls that
- #  come before the control we want)
- form["cheeses"] = ["gouda"]
- # The kind argument can also take values "multilist", "singlelist", "text",
- # "clickable" and "file":
- #  find first control that will accept text, and scribble in it
- form.set_value("rhubarb rhubarb", kind="text")
- form.set_value([""], kind="singlelist")
-
- # Often, a single checkbox (a CHECKBOX control with a single item) is
- # present.  In that case, the name of the single item isn't of much
- # interest, so it's useful to be able to check and uncheck the box
- # without using the item name:
- form.set_single(True, "smelly")  # check
- form.set_single(False, "smelly")  # uncheck
-
- # Add files to FILE controls with .add_file().  Only call this multiple
- # times if the server is expecting multiple files.
- #  add a file, default value for MIME type, no filename sent to server
- form.add_file(open("data.dat"))
- #  add a second file, explicitly giving MIME type, and telling the server
- #   what the filename is
- form.add_file(open("data.txt"), "text/plain", "data.txt")
-
- # Many methods have a by_label argument, allowing specification of list
- # items by label instead of by name.  At the moment, only SelectControl
- # supports this argument (this will be fixed).  Sometimes labels are
- # easier to maintain than names, sometimes the other way around.
- form.set_value(["Mozzarella", "Caerphilly"], "cheeses", by_label=True)
-
- # To clear a control's value, so that it is not successful (until a
- # value is subsequently set):
-
- form.clear("cheeses")
-
- # It's also possible to get at the individual controls inside the form.
- # This is useful for calling several methods in a row on a single control,
- # and for the less common operations.  The methods are quite similar to
- # those on HTMLForm:
- control = form.find_control("cheeses", type="select")
- print control.value, control.name, control.type
- print control.possible_items()
- control.value = ["mascarpone", "curd"]
- control.set(True, "limburger")
-
- # All Controls may be disabled (equivalent of greyed-out in browser)
- control = form.find_control("comments")
- print control.disabled
- # ...or readonly
- print control.readonly
- # readonly and disabled attributes can be assigned to
- control.disabled = False
- # convenience method, used here to make all controls writable (unless
- # they're disabled):
- form.set_all_readonly(False)
- # ListControl items may also be disabled (setting a disabled item is not
- # allowed, but clearing one is allowed):
- print control.get_item_disabled("emmenthal")
- control.set_item_disabled(True, "emmenthal")
- #  enable all items in control
- control.set_all_items_disabled(False)
-
- # HTMLForm.controls is a list of all controls in the form
- for control in form.controls:
-     if control.value == "inquisition": sys.exit()
-
- request2 = form.click()  # urllib2.Request object
- response2 = urllib2.urlopen(request2)
-
- print response2.geturl()
- print response2.info()  # headers
- print response2.read()  # body
- response2.close()
-""")}
+@{colorize(" "+" ".join(open("examples/example.py").readlines()[2:]))}
 
 <p>All of the standard control types are supported: <code>TEXT</code>,
 <code>PASSWORD</code>, <code>HIDDEN</code>, <code>TEXTAREA</code>,
@@ -201,6 +91,36 @@
 <p>For installation instructions, see the INSTALL file included in the
 distribution. 
 
+<p><em>Development release.</em>.  There have been XXX two? minor
+backwards-incompatible interface changes since 0.1.x.  I recommend upgrading if
+and only if you pay attention to these incompatible changes:
+
+<ul>
+ <li>Disabled list items may no longer be deselected: AttributeError is raised
+ in 0.2.x, whereas deselection was allowed in 0.1.x.  In 0.2.x, either simply
+ set <code>item.disabled = False</code> first (or call
+ <code>control.set_all_items_disabled(False)</code>), or check if the item is
+ disabled before attempting to select or deselect it.  Note also that handling
+ of disabled list items in 0.1.x was buggy: disabled items were successful
+ (ie. disabled item names got sent back to the server).</li>
+ <li>AmbiguityError?</li>
+</ul>
+
+<p>0.2.x includes better support for labels, and a redesigned,
+simpler, interface (all the old methods are still there. but some have
+been deprecated).
+
+<ul>
+@{version = "0.2.0a"}
+@{win_version = release.win_version(version)}
+<li><a href="./src/ClientForm-@(version).tar.gz">ClientForm-@(version).tar.gz</a>
+<li><a href="./src/ClientForm-@(win_version).zip">ClientForm-@(win_version).zip</a>
+<li><a href="./src/ChangeLog.txt">Change Log</a> (included in distribution)
+<li><a href="./src/">Older releases.</a>
+</ul>
+
+<br>
+
 <p><em>Stable release.</em>.  There have been many interface changes since
 0.0.x, so I don't recommend upgrading old code from 0.0.x unless you want the
 new features.
@@ -213,19 +133,19 @@
 <li><a href="./src/ClientForm-@(version).tar.gz">ClientForm-@(version).tar.gz</a>
 <li><a href="./src/ClientForm-@(win_version).zip">ClientForm-@(win_version).zip</a>
 <li><a href="./src/ChangeLog.txt">Change Log</a> (included in distribution)
-<li><a href="./src/">Older versions.</a>
+<li><a href="./src/">Older releases.</a>
 </ul>
 
 <br>
 
-<p><em>Old release.</em>
+<p><em>Old release.</em>  No longer maintained.  You don't want this.
 <ul>
 @{version = "0.0.16"}
 @{win_version = release.win_version(version)}
 <li><a href="./src/ClientForm-@(version).tar.gz">ClientForm-@(version).tar.gz</a>
 <li><a href="./src/ClientForm-@(win_version).zip">ClientForm-@(win_version).zip</a>
 <li><a href="./src/ChangeLog.txt">Change Log</a> (included in distribution)
-<li><a href="./src/">Older versions.</a>
+<li><a href="./src/">Older releases.</a>
 </ul>