From df0ebdb92f143c8a95fcfccd9a4ae1fe523ce8f7 Mon Sep 17 00:00:00 2001 From: imdano <> Date: Thu, 25 Sep 2008 20:17:35 +0000 Subject: [PATCH] branches/experimental: - A bunch of documentation additions/updates. - Minor refactoring. - Fix catching wrong exception in netentry.py --- wicd/backend.py | 2 +- wicd/backends/be-external.py | 8 +++- wicd/backends/be-ioctl.py | 7 +++- wicd/configmanager.py | 13 +++++++ wicd/gui.py | 18 +++++++-- wicd/misc.py | 23 ++++++++++- wicd/netentry.py | 3 +- wicd/networking.py | 47 +++++++++-------------- wicd/prefs.py | 10 ++++- wicd/wicd-daemon.py | 74 ++++++++++++++++++++++++++++++++---- wicd/wnettools.py | 1 - 11 files changed, 160 insertions(+), 46 deletions(-) diff --git a/wicd/backend.py b/wicd/backend.py index ac4cab3..b9d0894 100644 --- a/wicd/backend.py +++ b/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 - diff --git a/wicd/backends/be-external.py b/wicd/backends/be-external.py index 525637a..ed4625c 100644 --- a/wicd/backends/be-external.py +++ b/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 diff --git a/wicd/backends/be-ioctl.py b/wicd/backends/be-ioctl.py index 784d96f..6829470 100644 --- a/wicd/backends/be-ioctl.py +++ b/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') - diff --git a/wicd/configmanager.py b/wicd/configmanager.py index 1627abc..d688506 100644 --- a/wicd/configmanager.py +++ b/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) diff --git a/wicd/gui.py b/wicd/gui.py index 0e1a9f4..564b46e 100644 --- a/wicd/gui.py +++ b/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 diff --git a/wicd/misc.py b/wicd/misc.py index a430eb1..3737008 100644 --- a/wicd/misc.py +++ b/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)') diff --git a/wicd/netentry.py b/wicd/netentry.py index 820b3e5..b986859 100644 --- a/wicd/netentry.py +++ b/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("&", "&").replace("<", "<").\ replace(">",">").replace("'", "'").replace('"', """) @@ -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: diff --git a/wicd/networking.py b/wicd/networking.py index 67eafd7..a3fda92 100644 --- a/wicd/networking.py +++ b/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): return self._wireless_interface + wireless_interface = property(get_wireless_iface, set_wireless_iface) + def set_wired_iface(self, value): self._wired_interface = value if self.liface: - self.liface.SetInterface(value) - - def get_wired_iface(self): - return self._wired_interface + self.liface.SetInterface(value) + def get_wired_iface(self): return self._wired_interface + wired_interface = property(get_wired_iface, set_wired_iface) 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): return self._debug + debug = property(get_debug, set_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): return self._dhcp_client + dhcp_client = property(get_dhcp_client, set_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 - - wireless_interface = property(get_wireless_iface, set_wireless_iface) - wired_interface = property(get_wired_iface, set_wired_iface) - debug = property(get_debug, set_debug) + def get_flush_tool(self): return self._flush_tool 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): diff --git a/wicd/prefs.py b/wicd/prefs.py index 724604e..60d964c 100644 --- a/wicd/prefs.py +++ b/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()) diff --git a/wicd/wicd-daemon.py b/wicd/wicd-daemon.py index e5d05fa..d48d595 100644 --- a/wicd/wicd-daemon.py +++ b/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 diff --git a/wicd/wnettools.py b/wicd/wnettools.py index 313a147..aebb6b3 100644 --- a/wicd/wnettools.py +++ b/wicd/wnettools.py @@ -881,4 +881,3 @@ class BaseWirelessInterface(BaseInterface): """ print 'Implement this in a derived class!' -