branches/experimental:

- A bunch of documentation additions/updates.
- Minor refactoring.
- Fix catching wrong exception in netentry.py

wicd/backend.py

@@ -44,6 +44,7 @@ class BackendManager(object):
                 be_file.endswith(".py"))
     
     def get_current_backend(self):
+        """ Returns the name of the loaded backend. """
         if self.__loaded_backend:
             return self.__loaded_backend.NAME
         else:
@@ -105,4 +106,3 @@ class BackendManager(object):
         self.__loaded_backend = backend
         print 'successfully loaded backend %s' % backend_name
         return backend
-        

wicd/backends/be-external.py

@@ -76,28 +76,34 @@ RALINK_DRIVER = 'ralink legacy'
 
 
 def SetDNS(*args, **kargs):
+    """ Call the wnettools SetDNS method. """
     return wnettools.SetDNS(*args, **kargs)
 
 def GetDefaultGateway(*args, **kargs):
+    """ Call the wnettools GetDefaultGateway method. """
     return wnettools.GetDefaultGateway(*args, **kargs)
 
 def StopDHCP(*args, **kargs):
+    """ Call the wnettools StopDHCP method. """
     return wnettools.StopDHCP(*args, **kargs)
 
 def GetWirelessInterfaces(*args, **kargs):
+    """ Call the wnettools GetWirelessInterfaces method. """
     return wnettools.GetWirelessInterfaces(*args, **kargs)
 
 def GetWiredInterfaces(*args, **kargs):
+    """ Call the wnettools GetWiredInterfaces method. """
     return wnettools.GetWiredInterfaces(*args, **kargs)
 
 def NeedsExternalCalls(*args, **kargs):
+    """ Return True, since this backend using iwconfig/ifconfig. """
     return True
 
 
 class Interface(wnettools.BaseInterface):
     """ Control a network interface. """
     def __init__(self, iface, verbose=False):
-        """ Initialise the object.
+        """ Initialize the object.
 
         Keyword arguments:
         iface -- the name of the interface

wicd/backends/be-ioctl.py

@@ -83,18 +83,23 @@ SIOCETHTOOL = 0x8946
 SIOCGIFFLAGS = 0x8913
 
 def SetDNS(*args, **kargs):
+    """ Call the wnettools SetDNS method. """
     return wnettools.SetDNS(*args, **kargs)
 
 def GetDefaultGateway(*args, **kargs):
+    """ Call the wnettools GetDefaultGateway method. """
     return wnettools.GetDefaultGateway(*args, **kargs)
 
 def StopDHCP(*args, **kargs):
+    """ Call the wnettools StopDHCP method. """
     return wnettools.StopDHCP(*args, **kargs)
 
 def GetWirelessInterfaces(*args, **kargs):
+    """ Call the wnettools GetWirelessInterfaces method. """
     return wnettools.GetWirelessInterfaces(*args, **kargs)
 
 def GetWiredInterfaces(*args, **kargs):
+    """ Call the wnettools GetWiredInterfaces method. """
     return wnettools.GetWiredInterfaces(*args, **kargs)
 
 def get_iw_ioctl_result(iface, call):
@@ -121,6 +126,7 @@ def get_iw_ioctl_result(iface, call):
     return buff.tostring()
 
 def NeedsExternalCalls(*args, **kargs):
+    """ Return False, since this backend doesn't use any external apps. """
     return False
 
 
@@ -535,4 +541,3 @@ class WirelessInterface(Interface, wnettools.BaseWirelessInterface):
             return None
 
         return buff.strip('\x00')
-

wicd/configmanager.py

@@ -43,12 +43,16 @@ class ConfigManager(ConfigParser):
         return self.config_file
     
     def get_config(self):
+        """ Returns the path to the loaded config file. """
         return self.config_file
         
     def set_option(self, section, option, value, save=False):
         """ Wrapper around ConfigParser.set
 
         Adds the option to write the config file change right away.
+        Also forces all the values being written to type str, and
+        adds the section the option should be written to if it
+        doesn't exist already.
         
         """
         if not self.has_section(section):
@@ -59,6 +63,7 @@ class ConfigManager(ConfigParser):
             self.write()
 
     def set(self, *args, **kargs):
+        """ Calls the set_option method. """
         self.set_option(*args, **kargs)
         
     def get_option(self, section, option, default=None):
@@ -90,13 +95,21 @@ class ConfigManager(ConfigParser):
         return ret
     
     def get(self, *args, **kargs):
+        """ Calls the get_option method """
         return self.get_option(*args, **kargs)
     
     def write(self):
+        """ Writes the loaded config file to disk. """
         configfile = open(self.config_file, 'w')
         ConfigParser.write(self, configfile)
         configfile.close()
         
     def remove_section(self,section):
+        """ Wrapper around the ConfigParser.remove_section() method.
+        
+        This method only calls the ConfigParser.remove_section() method
+        if the section actually exists.
+        
+        """
         if self.has_section(section):
             ConfigParser.remove_section(self, section)

wicd/gui.py

@@ -450,7 +450,12 @@ class appGui(object):
         return True
 
     def update_statusbar(self):
-        """ Updates the status bar. """
+        """ Updates the status bar
+        
+        Queries the daemon for network connection information and
+        updates the GUI status bar based on the results.
+        
+        """
         if not self.is_visible:
             return True
 
@@ -501,7 +506,12 @@ class appGui(object):
             return True
     
     def update_connect_buttons(self, state=None, x=None, force_check=False):
-        """ Updates the connect/disconnect buttons for each network entry. """
+        """ Updates the connect/disconnect buttons for each network entry.
+
+        If force_check is given, update the buttons even if the
+        current network state is the same as the previous.
+        
+        """
         if not state:
             state, x = daemon.GetConnectionStatus()
         
@@ -565,6 +575,7 @@ class appGui(object):
         self.network_list.set_sensitive(False)
         
     def refresh_clicked(self, widget=None):
+        """ Kick off an asynchronous wireless scan. """
         def dummy(x=None):pass
         wireless.Scan(reply_handler=dummy, error_handler=dummy)
 
@@ -674,6 +685,7 @@ class appGui(object):
         return True
     
     def _save_gen_settings(self, entry):
+        """ Save settings common to wired and wireless settings dialogs. """
         if entry.chkbox_static_ip.get_active():
             entry.set_net_prop("ip", noneToString(entry.txt_ip.get_text()))
             entry.set_net_prop("netmask", noneToString(entry.txt_netmask.get_text()))
@@ -704,7 +716,7 @@ class appGui(object):
             entry.set_net_prop("dns3", '')
     
     def save_wired_settings(self, entry):
-        """ Saved wired network settings. """
+        """ Save wired network settings. """
         self._save_gen_settings(entry)
         wired.SaveWiredNetworkProfile(entry.prof_name)
         return True

wicd/misc.py

@@ -302,6 +302,7 @@ def to_unicode(x):
     return ret
     
 def RenameProcess(new_name):
+    """ Renames the process calling the function to the given name. """
     if sys.platform != 'linux2':
         print 'Unsupported platform'
         return False
@@ -318,6 +319,12 @@ def RenameProcess(new_name):
         return False
     
 def detect_desktop_environment():
+    """ Try to determine which desktop environment is in use. 
+    
+    Choose between kde, gnome, or xfce based on environment
+    variables and a call to xprop.
+    
+    """
     desktop_environment = 'generic'
     if os.environ.get('KDE_FULL_SESSION') == 'true':
         desktop_environment = 'kde'
@@ -333,6 +340,7 @@ def detect_desktop_environment():
     return desktop_environment
 
 def choose_sudo_prog():
+    """ Try to intelligently decide which graphical sudo program to use. """
     desktop_env = detect_desktop_environment()
     env_path = os.environ['PATH'].split(":")
     
@@ -351,6 +359,13 @@ def choose_sudo_prog():
     raise WicdError("Couldn't find graphical sudo program.")
 
 def find_path(cmd):
+    """ Try to find a full path for a given file name. 
+    
+    Search the all the paths in the environment variable PATH for
+    the given file name, or return None if a full path for
+    the file can not be found.
+    
+    """
     paths = os.getenv("PATH", default=["/usr/bin", "/usr/local/bin"]).split(':')
     for path in paths:
         if os.access(os.path.join(path, cmd), os.F_OK):
@@ -360,7 +375,7 @@ def find_path(cmd):
 def get_language_list_gui():
     """ Returns a dict of translatable strings used by the GUI.
     
-    translations are done at http://wicd.net/translator. Please 
+    Translations are done at http://wicd.net/translator. Please 
     translate if you can.
     
     """
@@ -472,6 +487,12 @@ def get_language_list_gui():
     return language
 
 def get_language_list_tray():
+    """ Returns a dict of translatable strings used by the tray icon.
+    
+    Translations are done at http://wicd.net/translator. Please 
+    translate if you can.
+    
+    """
     _ = get_gettext()
     language = {}
     language['connected_to_wireless'] = _('Connected to $A at $B (IP: $C)')

wicd/netentry.py

@@ -813,6 +813,7 @@ class WirelessNetworkEntry(NetworkEntry):
         self.wifides = self.connect("destroy", self.destroy_called)
         
     def _escape(self, val):
+        """ Escapes special characters so they're displayed correctly. """
         return val.replace("&", "&amp;").replace("<", "&lt;").\
                replace(">","&gt;").replace("'", "&apos;").replace('"', "&quot;")
         
@@ -930,7 +931,7 @@ class WirelessNetworkEntry(NetworkEntry):
                 misc.LaunchAndWait([sudo_prog, msg_flag, msg,
                                     wpath.lib + "configscript.py", 
                                     str(self.networkID), "wireless"])
-            except IOError:
+            except misc.WicdError:
                 error(None, "Could not find a graphical sudo program." + \
                       "  Script editor could no be launched.")
         else:

wicd/networking.py

@@ -102,17 +102,15 @@ class Controller(object):
         self._wireless_interface = value
         if self.wiface:
             self.wiface.SetInterface(value)
-            
+    def get_wireless_iface(self): return self._wireless_interface
-    def get_wireless_iface(self):
+    wireless_interface = property(get_wireless_iface, set_wireless_iface)    
-        return self._wireless_interface
+    
-        
     def set_wired_iface(self, value):
         self._wired_interface = value
         if self.liface:
-            self.liface.SetInterface(value)
+            self.liface.SetInterface(value)            
-            
+    def get_wired_iface(self): return self._wired_interface
-    def get_wired_iface(self):
+    wired_interface = property(get_wired_iface, set_wired_iface)
-        return self._wired_interface
     
     def set_debug(self, value):
         self._debug = value
@@ -120,9 +118,8 @@ class Controller(object):
             self.wiface.SetDebugMode(value)
         if self.liface:
             self.liface.SetDebugMode(value)
-            
+    def get_debug(self): return self._debug
-    def get_debug(self):
+    debug = property(get_debug, set_debug)
-        return self._debug
     
     def set_dhcp_client(self, value):
         self._dhcp_client = value
@@ -132,9 +129,8 @@ class Controller(object):
         if self.liface:
             self.liface.DHCP_CLIENT = value    
             self.liface.CheckDHCP()
-
+    def get_dhcp_client(self): return self._dhcp_client
-    def get_dhcp_client(self):
+    dhcp_client = property(get_dhcp_client, set_dhcp_client)
-        return self._dhcp_client
     
     def set_flush_tool(self, value):
         self._flush_tool = value
@@ -142,15 +138,8 @@ class Controller(object):
             self.wiface.flush_tool = value
         if self.liface:
             self.liface.flush_tool = value
-            
+    def get_flush_tool(self): return self._flush_tool
-    def get_flush_tool(self):
-        return self._flush_tool
-        
-    wireless_interface = property(get_wireless_iface, set_wireless_iface)
-    wired_interface = property(get_wired_iface, set_wired_iface)
-    debug = property(get_debug, set_debug)
     flush_tool = property(get_flush_tool, set_flush_tool)
-    dhcp_client = property(get_dhcp_client, set_dhcp_client)
     
     def LoadBackend(self, backend_name):
         """ Load the given networking backend. """
@@ -225,19 +214,15 @@ class ConnectThread(threading.Thread):
         
         self.SetStatus('interface_down')
         
-    def get_should_die(self):
-        return self._should_die
-    
     def set_should_die(self, val):
         self.lock.acquire()
         try:
             self._should_die = val
         finally:
             self.lock.release()
-    
+    def get_should_die(self): return self._should_die
     should_die = property(get_should_die, set_should_die)
 
-
     def SetStatus(self, status):
         """ Set the threads current status message in a thread-safe way.
 
@@ -418,6 +403,12 @@ class Wireless(Controller):
     wpa_driver = property(get_wpa_driver, set_wpa_driver)
     
     def LoadBackend(self, backend):
+        """ Load a given backend. 
+
+        Load up a backend into the backend manager and associate with
+        the networking interface.
+        
+        """
         Controller.LoadBackend(self, backend)
         if self._backend:
             self.wiface = self._backend.WirelessInterface(self.wireless_interface,
@@ -816,9 +807,7 @@ class Wired(Controller):
         self._link_detect = value
         if self.liface:
             self.liface.link_detect = value
-        
     def get_link_detect(self): return self._link_detect
-    
     link_detect = property(get_link_detect, set_link_detect)
     
     def LoadBackend(self, backend):

wicd/prefs.py

@@ -2,7 +2,8 @@
 
 """ Wicd Preferences Dialog.
 
-Displays the main settings dialog window for wicd.
+Displays the main settings dialog window for wicd and
+handles recieving/sendings the settings from/to the daemon.
 
 """
 
@@ -45,6 +46,7 @@ def alert(parent, message):
     dialog.destroy()
 
 class PreferencesDialog(object):
+    """ Class for handling the wicd preferences dialog window. """
     def __init__(self, wTree, dbus):
         global daemon, wireless, wired
         daemon = dbus['daemon']
@@ -55,6 +57,7 @@ class PreferencesDialog(object):
         self.build_preferences_diag()
         
     def build_preferences_diag(self):
+        """ Builds the preferences dialog window. """
         def build_combobox(lbl):
             """ Sets up a ComboBox using the given widget name. """
             liststore = gtk.ListStore(gobject.TYPE_STRING)
@@ -67,6 +70,7 @@ class PreferencesDialog(object):
             return combobox
         
         def setup_label(name, lbl=""):
+            """ Sets up a label for the given widget name. """
             widget = self.wTree.get_widget(name)
             if lbl:
                 widget.set_label(language[lbl])
@@ -212,15 +216,19 @@ class PreferencesDialog(object):
         self.wTree.get_widget("notebook2").set_current_page(0)
         
     def run(self):
+        """ Runs the preferences dialog window. """
         return self.dialog.run()
     
     def hide(self):
+        """ Hides the preferences dialog window. """
         self.dialog.hide()
         
     def show_all(self):
+        """ Shows the preferences dialog window. """
         self.show_all()
     
     def save_results(self):
+        """ Pushes the selected settings to the daemon. """
         daemon.SetUseGlobalDNS(self.useGlobalDNSCheckbox.get_active())
         daemon.SetGlobalDNS(self.dns1Entry.get_text(), self.dns2Entry.get_text(),
                             self.dns3Entry.get_text(), self.searchDomEntry.get_text())

wicd/wicd-daemon.py

@@ -67,8 +67,16 @@ wireless_conf = wpath.etc + "wireless-settings.conf"
 wired_conf = wpath.etc + "wired-settings.conf"
 
 class WicdDaemon(dbus.service.Object):
+    """ The main wicd daemon class.
+    
+    This class mostly contains exported DBus methods that are not
+    associated directly with either wired or wireless actions.  There
+    are a few exceptions to this, due to architectural limitations.
+    
+    """
     def __init__(self, bus_name, object_path="/org/wicd/daemon",
                  auto_connect=True):
+        """ Initializes the daemon DBus object. """
         dbus.service.Object.__init__(self, bus_name=bus_name, 
                                      object_path=object_path)
         self.wifi = networking.Wireless()
@@ -425,7 +433,7 @@ class WicdDaemon(dbus.service.Object):
         the wicd.py is not exited properly while the GUI is open.  We should
         probably implement some kind of pid system to do it properly.
         
-        ANOTHER NOTE: This isn't implemented yet!
+        ANOTHER NOTE: This isn't used by anything yet!
         
         """
         return bool(self.gui_open)
@@ -491,6 +499,12 @@ class WicdDaemon(dbus.service.Object):
     
     @dbus.service.method('org.wicd.daemon', out_signature='(uas)')
     def GetConnectionStatus(self):
+        """ Returns the current connection state in list form. 
+        
+        See SetConnectionStatus for more information about the
+        data structure being returned.
+        
+        """
         return [self.connection_state, self.connection_info]
 
     @dbus.service.method('org.wicd.daemon')
@@ -505,10 +519,20 @@ class WicdDaemon(dbus.service.Object):
 
     @dbus.service.method('org.wicd.daemon')
     def GetDHCPClient(self):
+        """ Returns the current DHCP client constant.
+        
+        See misc.py for a definition of the constants.
+        
+        """
         return self.dhcp_client
     
     @dbus.service.method('org.wicd.daemon')
     def SetDHCPClient(self, client):
+        """ Sets the DHCP client constant.
+        
+        See misc.py for a definition of the constants.
+        
+        """
         print "Setting dhcp client to %i" % (int(client))
         self.dhcp_client = int(client)
         self.wifi.dhcp_client = int(client)
@@ -517,20 +541,38 @@ class WicdDaemon(dbus.service.Object):
 
     @dbus.service.method('org.wicd.daemon')
     def GetLinkDetectionTool(self):
+        """ Returns the current link detection tool constant. """
         return self.link_detect_tool
 
     @dbus.service.method('org.wicd.daemon')
     def SetLinkDetectionTool(self, link_tool):
+        """ Sets the link detection tool. 
+        
+        Sets the value of the tool wicd should use to detect if a
+        cable is plugged in.  If using a backend that doesn't use
+        an external call to get this information (such as ioctl)
+        it will instead use the ioctls provided by the specified
+        tool to query for link status.
+        
+        """
         self.link_detect_tool = int(link_tool)
         self.wired.link_tool = int(link_tool)
         self.config.set("Settings", "link_detect_tool", link_tool, True)
 
     @dbus.service.method('org.wicd.daemon')
     def GetFlushTool(self):
+        """ Returns the current flush tool constant. """
         return self.flush_tool
 
     @dbus.service.method('org.wicd.daemon')
     def SetFlushTool(self, flush_tool):
+        """ Sets the flush tool.
+        
+        Sets the value of the tool wicd should use to flush routing tables.
+        The value is associated with a particular tool, as specified in
+        misc.py
+        
+        """
         self.flush_tool = int(flush_tool)
         self.wired.flush_tool = int(flush_tool)
         self.wifi.flush_tool = int(flush_tool)
@@ -538,7 +580,13 @@ class WicdDaemon(dbus.service.Object):
         
     @dbus.service.method('org.wicd.daemon')
     def WriteWindowSize(self, width, height, win_name):
-        """Write the desired default window size"""
+        """ Write the desired default window size.
+        
+        win_name should be either 'main' or 'pref', and specifies
+        whether the size being given applies to the main GUI window
+        or the preferences dialog window.
+        
+        """
         if win_name == "main":
             height_str = "window_height"
             width_str = "window_width"
@@ -622,6 +670,13 @@ class WicdDaemon(dbus.service.Object):
         return True
 
     def _monitor_wired_autoconnect(self):
+        """ Monitor a wired auto-connection attempt.
+
+        Helper method called on a timer that monitors a wired
+        connection attempt and makes decisions about what to
+        do next based on the result.
+        
+        """
         wiredb = self.wired_bus
         if wiredb.CheckIfWiredConnecting():
             return True
@@ -642,6 +697,7 @@ class WicdDaemon(dbus.service.Object):
         
     @dbus.service.method('org.wicd.daemon', in_signature='uav')
     def EmitStatusChanged(self, state, info):
+        """ Calls the StatusChanged signal method. """
         self.StatusChanged(state, info)
 
     @dbus.service.signal(dbus_interface='org.wicd.daemon', signature='uav')
@@ -649,12 +705,13 @@ class WicdDaemon(dbus.service.Object):
         """ Emits a "status changed" dbus signal.
         
         This D-Bus signal is emitted when the connection status changes.
+        This signal can be hooked to monitor the network state.
         
         """
         pass
     
     def __printReturn(self, text, value):
-        """prints the specified text and value, then returns the value"""
+        """ Prints the specified text and value, then returns the value. """
         if self.debug_mode:
             print ''.join([text, " ", str(value)])
         return value
@@ -744,7 +801,9 @@ class WicdDaemon(dbus.service.Object):
 ##############################
  
 class WirelessDaemon(dbus.service.Object):
+    """ DBus interface for wireless connection operations. """
     def __init__(self, bus_name, wired=None, wifi=None, debug=False):
+        """ Intitialize the wireless DBus interface. """
         dbus.service.Object.__init__(self, bus_name=bus_name,
                                      object_path='/org/wicd/daemon/wireless')
         self.hidden_essid = None
@@ -963,17 +1022,16 @@ class WirelessDaemon(dbus.service.Object):
             print bssid_key
         
         if self.config.get(essid_key, 'use_settings_globally'):
-            return self._read_wireless_profile(cur_network, essid_key)
+            section = essid_key
         elif self.config.has_section(bssid_key):
-            return self._read_wireless_profile(cur_network, bssid_key)
+            section = bssid_key
         else:
             cur_network["has_profile"] = False
             return "500: Profile Not Found"
         
-    def _read_wireless_profile(self, cur_network, section):
         cur_network["has_profile"] = True
 
-        # Read the essid because we be needing to name those hidden
+        # Read the essid because we need to name those hidden
         # wireless networks now - but only read it if it is hidden.
         if cur_network["hidden"]:
             cur_network["essid"] = misc.Noneify(self.config.get(section, 
@@ -1080,7 +1138,9 @@ class WirelessDaemon(dbus.service.Object):
 ###########################
         
 class WiredDaemon(dbus.service.Object):
+    """ DBus interface for wired connection operations. """
     def __init__(self, bus_name, wired=None, wifi=None, debug=False):
+        """ Intitialize the wireless DBus interface. """
         dbus.service.Object.__init__(self, bus_name=bus_name,
                                      object_path="/org/wicd/daemon/wired")
         self.wired = wired

wicd/wnettools.py

@@ -881,4 +881,3 @@ class BaseWirelessInterface(BaseInterface):
 
         """
         print 'Implement this in a derived class!'
-