From 3f9083df27385e4b8a484f8d6d90e2c3db9d8f39 Mon Sep 17 00:00:00 2001
From: Romain Bignon <romain@peerfuse.org>
Date: Fri, 16 Apr 2010 20:11:36 +0200
Subject: [PATCH] documentation

---
 weboob/tools/browser.py          | 51 +++++++++++++++++++++++++++++++-
 weboob/tools/parsers/__init__.py |  2 +-
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/weboob/tools/browser.py b/weboob/tools/browser.py
index 5feac9ea..6f762996 100644
--- a/weboob/tools/browser.py
+++ b/weboob/tools/browser.py
@@ -104,12 +104,18 @@ class BaseBrowser(mechanize.Browser):
     def login(self):
         """
         Login to the website.
+
+        This function is called when is_logged() returns False and the password
+        attribute is not None.
         """
         raise NotImplementedError()
 
     def is_logged(self):
         """
-        Return True if we are loggen on website.
+        Return True if we are logged on website. When Browser tries to access
+        to a page, if this method returns False, it calls login().
+
+        It is never called if the password attribute is None.
         """
         raise NotImplementedError()
 
@@ -117,6 +123,17 @@ class BaseBrowser(mechanize.Browser):
 
     def __init__(self, username=None, password=None, firefox_cookies=None,
                  parser=None, history=NoHistory()):
+        """
+        Constructor of Browser.
+
+        @param username [str] username on website.
+        @param password [str] password on website. If it is None, Browser will
+                              not try to login.
+        @param filefox_cookies [str] Path to cookies' sqlite file.
+        @param parser [IParser]  parser to use on HTML files.
+        @param hisory [object]  History manager. Default value is an object
+                                which does not keep history.
+        """
         mechanize.Browser.__init__(self, history=history)
         self.addheaders = [
                 ['User-agent', self.USER_AGENT]
@@ -132,6 +149,8 @@ class BaseBrowser(mechanize.Browser):
 
         if parser is None:
             parser = get_parser()()
+        elif isinstance(parser, (tuple,list)):
+            parser = get_parser(parser)()
         self.parser = parser
         self.page = None
         self.last_update = 0.0
@@ -166,6 +185,9 @@ class BaseBrowser(mechanize.Browser):
 
     @change_location
     def openurl(self, *args, **kwargs):
+        """
+        Open an URL but do not create a Page object.
+        """
         try:
             return mechanize.Browser.open(self, *args, **kwargs)
         except (mechanize.response_seek_wrapper, urllib2.HTTPError, urllib2.URLError), e:
@@ -176,6 +198,9 @@ class BaseBrowser(mechanize.Browser):
             return mechanize.Browser.open(self, *args, **kwargs)
 
     def submit(self, *args, **kwargs):
+        """
+        Submit the selected form.
+        """
         try:
             self._change_location(mechanize.Browser.submit(self, *args, **kwargs))
         except (mechanize.response_seek_wrapper, urllib2.HTTPError, urllib2.URLError), e:
@@ -202,6 +227,16 @@ class BaseBrowser(mechanize.Browser):
 
     @change_location
     def location(self, *args, **kwargs):
+        """
+        Change location of browser on an URL.
+
+        When the page is loaded, it looks up PAGES to find a regexp which
+        matches, and create the object. Then, the 'on_loaded' method of
+        this object is called.
+
+        If a password is set, and is_logged() returns False, it tries to login
+        with login() and reload the page.
+        """
         keep_args = copy(args)
         keep_kwargs = kwargs.copy()
 
@@ -219,6 +254,11 @@ class BaseBrowser(mechanize.Browser):
             self.location(*keep_args, **keep_kwargs)
 
     def _change_location(self, result):
+        """
+        This function is called when we have moved to a page, to load a Page
+        object.
+        """
+
         # Find page from url
         pageCls = None
         for key, value in self.PAGES.items():
@@ -259,6 +299,15 @@ class BaseBrowser(mechanize.Browser):
         return s
 
     def set_field(self, args, label, field=None, value=None, is_list=False):
+        """
+        Set a value to a form field.
+
+        @param args [dict]  arguments where to look for value.
+        @param label [str]  label in args.
+        @param field [str]  field name. If None, use label instead.
+        @param value [str]  value to give on field.
+        @param is_list [bool]  the field is a list.
+        """
         try:
             if not field:
                 field = label
diff --git a/weboob/tools/parsers/__init__.py b/weboob/tools/parsers/__init__.py
index 837b538e..ebb6591a 100644
--- a/weboob/tools/parsers/__init__.py
+++ b/weboob/tools/parsers/__init__.py
@@ -42,7 +42,7 @@ def load_buildtin():
     from .htmlparser import HTMLParser
     return HTMLParser
 
-def get_parser(preference_order=['lxml', 'html5lib', 'elementtidy', 'builtin']):
+def get_parser(preference_order=('lxml', 'html5lib', 'elementtidy', 'builtin')):
     """
     Get a parser from a preference order list.
     This allows Weboob to run on systems without lxml, which is the default parser.