[PATCH master] Use Sphinx documentation format in nm.py.

[Radek Vykydal]

..as I promised

---
 pyanaconda/nm.py | 307 ++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 216 insertions(+), 91 deletions(-)

diff --git a/pyanaconda/nm.py b/pyanaconda/nm.py
index 880c9df..3c587dc 100644
--- a/pyanaconda/nm.py
+++ b/pyanaconda/nm.py
@@ -104,7 +104,11 @@ def _get_property(object_path, prop, interface_name_suffix=""):
     return prop.unpack()[0]

def nm_state():
-    """Return state of NetworkManager"""
+    """Return state of NetworkManager
+
+    :return: state of NetworkManager
+    :rtype: integer
+    """
     return _get_property("/org/freedesktop/NetworkManager", "State")

# FIXME - use just GLOBAL? There is some connectivity checking
@@ -112,17 +116,29 @@ def nm_state():
 # and how it is implemented.
 # Also see Gio g_network_monitor_can_reach.
 def nm_is_connected():
-    """Is NetworkManager connected?"""
+    """Is NetworkManager connected?
+
+    :return: True if NM is connected, False otherwise.
+    :rtype: bool
+    """
     return nm_state() in (NetworkManager.State.CONNECTED_GLOBAL,
                           NetworkManager.State.CONNECTED_SITE,
                           NetworkManager.State.CONNECTED_LOCAL)

def nm_is_connecting():
-    """Is NetworkManager connecting?"""
+    """Is NetworkManager connecting?
+
+    :return: True if NM is in CONNECTING state, False otherwise.
+    :rtype: bool
+    """
     return nm_state() == NetworkManager.State.CONNECTING

def nm_devices():
-    """Return list of network device names supported in installer"""
+    """Return names of network devices supported in installer.
+
+    :return: names of network devices supported in installer
+    :rtype: list of strings
+    """

interfaces = []

@@ -145,7 +161,11 @@ def nm_devices():
     return interfaces

def nm_activated_devices():
-    """Return list of names of activated network devices"""
+    """Return names of activated network devices.
+
+    :return: names of activated network devices
+    :rtype: list of strings
+    """

interfaces = []

@@ -185,9 +205,14 @@ def _device_type_specific_interface(device):
 def nm_device_property(name, prop):
     """Return value of device NM property

-       Exceptions:
-       UnknownDeviceError if device is not found
-       PropertyNotFoundError if property is not found
+       :param name: name of device
+       :type name: str
+       :param prop: property
+       :type name: str
+       :return: value of device's property
+       :rtype: unpacked GDBus value
+       :raise UnknownDeviceError if device is not found
+       :raise PropertyNotFoundError if property is not found
     """

retval = None
@@ -223,75 +248,100 @@ def nm_device_property(name, prop):
 def nm_device_type_is_wifi(name):
     """Is the type of device wifi?

-       Exceptions:
-       UnknownDeviceError if device is not found
-       PropertyNotFoundError if type is not found
+       :param name: name of device
+       :type name: str
+       :return: True if type of device is WIFI, False otherwise
+       :rtype: bool
+       :raise UnknownDeviceError if device is not found
+       :raise PropertyNotFoundError if property is not found
     """
     return nm_device_type(name) == NetworkManager.DeviceType.WIFI

def nm_device_type_is_ethernet(name):
     """Is the type of device ethernet?

-       Exceptions:
-       UnknownDeviceError if device is not found
-       PropertyNotFoundError if type is not found
+       :param name: name of device
+       :type name: str
+       :return: True if type of device is ETHERNET, False otherwise
+       :rtype: bool
+       :raise UnknownDeviceError if device is not found
+       :raise PropertyNotFoundError if property is not found
     """
     return nm_device_type(name) == NetworkManager.DeviceType.ETHERNET

def nm_device_type_is_bond(name):
     """Is the type of device bond?

-       Exceptions:
-       UnknownDeviceError if device is not found
-       PropertyNotFoundError if type is not found
+       :param name: name of device
+       :type name: str
+       :return: True if type of device is BOND, False otherwise
+       :rtype: bool
+       :raise UnknownDeviceError if device is not found
+       :raise PropertyNotFoundError if property is not found
     """
     return nm_device_type(name) == NetworkManager.DeviceType.BOND

def nm_device_type_is_vlan(name):
     """Is the type of device vlan?

-       Exceptions:
-       UnknownDeviceError if device is not found
-       PropertyNotFoundError if type is not found
+       :param name: name of device
+       :type name: str
+       :return: True if type of device is VLAN, False otherwise
+       :rtype: bool
+       :raise UnknownDeviceError if device is not found
+       :raise PropertyNotFoundError if property is not found
     """
     return nm_device_type(name) == NetworkManager.DeviceType.VLAN

def nm_device_hwaddress(name):
-    """Return device's 'HwAddress' property
+    """Return active hardware address of device ('HwAddress' property)

-       Exceptions:
-       UnknownDeviceError if device is not found
-       PropertyNotFoundError if property is not found
+       :param name: name of device
+       :type name: str
+       :return: active hardware address of device ('HwAddress' property)
+       :rtype: str
+       :raise UnknownDeviceError if device is not found
+       :raise PropertyNotFoundError if 'HwAddress' property is not found
     """
     return nm_device_property(name, "HwAddress")

def nm_device_type(name):
-    """Return device's 'DeviceType' property
+    """Return device's type ('DeviceType' property).

-       Exceptions:
-       UnknownDeviceError if device is not found
-       PropertyNotFoundError if property is not found
+       :param name: name of device
+       :type name: str
+       :return: device type
+       :rtype: integer
+       :raise UnknownDeviceError if device is not found
+       :raise PropertyNotFoundError if 'DeviceType' property is not found
     """
     return nm_device_property(name, "DeviceType")

def nm_device_carrier(name):
-    """Return device's 'Carrier' property
+    """Return whether physical carrier of device is found.
+       ('Carrier' property)

-       Exceptions:
-       UnknownDeviceError if device is not found
-       PropertyNotFoundError if property is not found
+       :param name: name of device
+       :type name: str
+       :return: True if physical carrier is found, False otherwise
+       :rtype: bool
+       :raise UnknownDeviceError if device is not found
+       :raise PropertyNotFoundError if 'Carrier' property is not found
     """
     return nm_device_property(name, "Carrier")

def nm_device_ip_addresses(name, version=4):
-    """Return list of devices's IP addresses
+    """Return IP addresses of device in ACTIVATED state.

-       version=4 - ipv4 addresses
-       version=6 - ipv6 addresses
-
-       Exceptions:
-       UnknownDeviceError if device is not found
-       PropertyNotFoundError if ip configuration is not found
+       :param name: name of device
+       :type name: str
+       :param version: version of IP protocol (value 4 or 6)
+       :type version: int
+       :return: IP addresses of device, empty list if device is not
+                in ACTIVATED state
+       :rtype: list of strings
+       :raise UnknownDeviceError if device is not found
+       :raise PropertyNotFoundError if IP configuration is not found
     """
     retval = []
     config = nm_device_ip_config(name, version)
@@ -303,8 +353,11 @@ def nm_device_ip_addresses(name, version=4):
 def nm_device_active_ssid(name):
     """Return ssid of device's active access point.

-       Exceptions:
-       UnknownDeviceError if device is not found
+       :param name: name of device
+       :type name: str
+       :return ssid of active access point, None if device has no active AP
+       :rtype: str
+       :raise UnknownDeviceError if device is not found
     """

try:
@@ -321,25 +374,20 @@ def nm_device_active_ssid(name):
     return ssid

def nm_device_ip_config(name, version=4):
-    """Return list of devices's IP config.
+    """Return IP configurations of device in ACTIVATED state.

:param name: name of device
        :type name: str
-
        :param version: version of IP protocol (value 4 or 6)
        :type version: int
-
-       :returns:  
-
-       Returns:
-       [[[address1, prefix1, gateway1], [address2, prefix2, gateway2], ...], [nameserver1, nameserver2]]
-       addressX, gatewayX: string
-       prefixX: int
-       [] if device is not in ACTIVATED state
-
-       Exceptions:
-       UnknownDeviceError if device is not found
-       PropertyNotFoundError if ip configuration is not found
+       :return: IP configuration of device, empty list if device is not
+                in ACTIVATED state
+       :rtype: [[[address1, prefix1, gateway1], [address2, prefix2, gateway2], ...],
+                [nameserver1, nameserver2]]
+               addressX, gatewayX: string
+               prefixX: int
+       :raise UnknownDeviceError if device is not found
+       :raise PropertyNotFoundError if ip configuration is not found
     """
     state = nm_device_property(name, "State")
     if state != NetworkManager.DeviceState.ACTIVATED:
@@ -393,10 +441,10 @@ def nm_device_ip_config(name, version=4):
     return [addr_list, ns_list]

def nm_ntp_servers_from_dhcp():
-    """Return a list of NTP servers that were specified the reply of the
-       DHCP server or empty list if no NTP servers were returned.
-       The return_hostnames  parameter specifies if the NTP server IP
-       addresses from the DHCP reply should be converted to hostnames.
+    """Return NTP servers obtained by DHCP.
+
+       return: NTP servers obtained by DHCP
+       rtype: list of str
     """
     ntp_servers = []
     # get paths for all actively connected interfaces
@@ -419,12 +467,13 @@ def nm_ntp_servers_from_dhcp():
     return ntp_servers

def _device_settings(name):
-    """Return object path of device setting
-
-       Returns None if settings were not found.
+    """Return object path of device setting.

-       Exceptions:
-       UnknownDeviceError - device was not found
+       :param name: name of device
+       :type name: str
+       :return: path of settings, None if not found
+       :rtype: str or None
+       :raise UnknownDeviceError if device is not found
     """
     devtype = nm_device_type(name)
     if devtype == NetworkManager.DeviceType.BOND:
@@ -444,7 +493,10 @@ def _device_settings(name):
 def _settings_for_ap(ssid):
     """Return object path of wireless access point settings.

-       Returns None if settings were not found.
+       :param ssid: ssid of access point
+       :type ssid: str
+       :return: path of settings, None if not found
+       :rtype: str or None
 `   """
     return _find_settings(ssid, '802-11-wireless', 'ssid',
             format_value=lambda ba: "".join(chr(b) for b in ba))
@@ -452,7 +504,10 @@ def _settings_for_ap(ssid):
 def _settings_for_hwaddr(hwaddr):
     """Return object path of settings of device specified by hw address.

-       Returns None if settings were not found.
+       :param hwaddr: hardware address (uppercase)
+       :type hwaddr: str
+       :return: path of settings, None if not found
+       :rtype: str or None
     """
     return _find_settings(hwaddr, '802-3-ethernet', 'mac-address',
             format_value=lambda ba: ":".join("%02X" % b for b in ba))
@@ -460,7 +515,17 @@ def _settings_for_hwaddr(hwaddr):
 def _find_settings(value, key1, key2, format_value=lambda x:x):
     """Return object path of settings having given value of key1, key2 setting

-       Returns None if settings were not found.
+       :param value: required value of setting
+       :type value: corresponds to dbus type of setting
+       :param key1: first-level key of setting (eg "connection")
+       :type key1: str
+       :param key2: second-level key of setting (eg "uuid")
+       :type key2: str
+       :param format_value: function to be called on setting value before
+                            comparing
+       :type format_value: function taking one argument (setting value)
+       :return: path of settings, None if not found
+       :rtype: str or None
     """
     retval = None

@@ -495,16 +560,19 @@ def _find_settings(value, key1, key2, format_value=lambda x:x):
 def nm_device_setting_value(name, key1, key2):
     """Return value of device's setting specified by key1 and key2.

-       Return None if the setting is not found which means NM will use
-       default value for the setting.  We can't validate that keys
-       actually correspond to a setting (see "connection" "autoconnect"
-       setting).
-
-       Caller should handle None as default value.
-
-       Exceptions:
-       UnknownDeviceError - device was not found
-       DeviceSettingsNotFoundError - settings were not found (eg for "wlan0")
+       :param name: name of device
+       :type name: str
+       :param key1: first-level key of setting (eg "connection")
+       :type key1: str
+       :param key2: second-level key of setting (eg "uuid")
+       :type key2: str
+       :return: value of setting or None if the setting was not found
+                which means it does not exist or default value is used
+                by NM
+       :rtype: unpacked GDBus variant or None
+       :raise UnknownDeviceError if device is not found
+       :raise DeviceSettingsNotFoundError if settings were not found
+                                          (eg for "wlan0")
     """
     settings_path = _device_settings(name)
     if not settings_path:
@@ -527,9 +595,13 @@ def nm_device_setting_value(name, key1, key2):
 def nm_activate_device_connection(dev_name, con_uuid):
     """Activate device with specified connection.

-       Exceptions:
-       UnknownDeviceError - device was not found
-
+       :param dev_name: name of device
+       :type dev_name: str
+       :param con_uuid: uuid of connection to be activated on device
+       :type con_uuid: str
+       :raise UnknownDeviceError if device is not found
+       :raise UnmanagedDeviceError if device is not managed by NM
+              or unavailable
     """

proxy = _get_proxy()
@@ -565,15 +637,29 @@ def nm_activate_device_connection(dev_name, con_uuid):
 def nm_update_settings_of_device(name, new_values):
     """Update setting of device.

-       new_values: list of settings to be modified [[key1, key2, value, default_type_str], ...]
-
        The type of value is determined from existing settings of device.
        If setting for key1, key2 does not exist, default_type_str is used or
        if None, the type is inferred from the value supplied (string and bool only).

-       Exceptions:
-       UnknownDeviceError - device was not found
-       DeviceSettingsNotFoundError - settings were not found (eg for "wlan0")
+       :param name: name of device
+       :type name: str
+       :param new_values: list of settings with new values and its types
+                          [[key1, key2, value, default_type_str]]
+                          key1: first-level key of setting (eg "connection")
+                          key2: second-level key of setting (eg "uuid")
+                          value: new value
+                          default_type_str: dbus type of new value to be used
+                                            if the setting does not already exist;
+                                            if None, the type is inferred from
+                                            value (string and bool only)
+       :type new_values: [[key1, key2, value, default_type_str], ...]
+                         key1: str
+                         key2: str
+                         value:
+                         default_type_str: str
+       :raise UnknownDeviceError if device is not found
+       :raise DeviceSettingsNotFoundError if settings were not found
+                                          (eg for "wlan0")
     """
     settings_path = _device_settings(name)
     if not settings_path:
@@ -583,11 +669,26 @@ def nm_update_settings_of_device(name, new_values):
 def _update_settings(settings_path, new_values):
     """Update setting of object specified by settings_path with value.

-       new_values: list of settings to be modified [[key1, key2, value, default_type_str], ...]
-
        The type of value is determined from existing setting.
        If setting for key1, key2 does not exist, default_type_str is used or
        if None, the type is inferred from the value supplied (string and bool only).
+
+       :param settings_path: path of settings object
+       :type settings_path: str
+       :param new_values: list of settings with new values and its types
+                          [[key1, key2, value, default_type_str]]
+                          key1: first-level key of setting (eg "connection")
+                          key2: second-level key of setting (eg "uuid")
+                          value: new value
+                          default_type_str: dbus type of new value to be used
+                                            if the setting does not already exist;
+                                            if None, the type is inferred from
+                                            value (string and bool only)
+       :type new_values: [[key1, key2, value, default_type_str], ...]
+                         key1: str
+                         key2: str
+                         value:
+                         default_type_str: str
     """
     proxy = _get_proxy(object_path=settings_path, interface_name="org.freedesktop.NetworkManager.Settings.Connection")
     args = None
@@ -656,19 +757,43 @@ def _gvariant_settings(settings, updated_key1, updated_key2, value, default_type
     return GLib.Variant(settings.get_type_string(), (new_settings,))

def nm_ipv6_to_dbus_ay(address):
-    """Convert ipv6 address from string to list of bytes (ay) for dbus."""
+    """Convert ipv6 address from string to list of bytes 'ay' for dbus
+
+    :param address: IPv6 address
+    :type address: str
+    :return: address in format 'ay' for NM dbus setting
+    :rtype: list of bytes
+    """
     return [int(byte, 16) for byte in re.findall('.{1,2}', IPy.IP(address).strFullsize().replace(':', ''))]

def nm_ipv4_to_dbus_int(address):
-    """Convert ipv4 address from string to int for dbus (switched endianess)."""
+    """Convert ipv4 address from string to int for dbus (switched endianess).
+
+    :param address: IPv4 address
+    :type address: str
+    :return: IPv4 address as an integer 'u' for NM dbus setting
+    :rtype: integer
+    """
     return struct.unpack("=L", socket.inet_aton(address))[0]

def nm_dbus_ay_to_ipv6(bytelist):
-    """Convert ipv6 address from list of bytes (dbus ay) to string."""
+    """Convert ipv6 address from list of bytes (dbus 'ay') to string.
+
+    :param address: IPv6 address as list of bytes returned by dbus ('ay')
+    :type address: list of bytes - dbus 'ay'
+    :return: IPv6 address
+    :rtype: str
+    """
     return socket.inet_ntop(socket.AF_INET6, "".join(chr(byte) for byte in bytelist))

def nm_dbus_int_to_ipv4(address):
-    """Convert ipv4 address from int from dbus (switched endianess) to string."""
+    """Convert ipv4 address from dus int 'u' (switched endianess) to string.
+
+    :param address: IPv4 address as integer returned by dbus ('u')
+    :type address: integer - dbus 'u'
+    :return: IPv6 address
+    :rtype: str
+    """
     return socket.inet_ntop(socket.AF_INET, struct.pack('=L', address))

def test():

[Vratislav Podzimek]

On Fri, 2013-09-20 at 17:07 +0200, Radek Vykydal wrote:
> ..as I promised
>
> pyanaconda/nm.py | 307 ++++++++++++++++++++++++++++++++++++++-----------------
>  1 file changed, 216 insertions(+), 91 deletions(-)
>
> diff --git a/pyanaconda/nm.py b/pyanaconda/nm.py
> index 880c9df..3c587dc 100644
> --- a/pyanaconda/nm.py
> +++ b/pyanaconda/nm.py
> @@ -104,7 +104,11 @@ def _get_property(object_path, prop, interface_name_suffix=""):
>      return prop.unpack()[0]
>
> def nm_state():
> """Return state of NetworkManager"""
> """Return state of NetworkManager
> :return: state of NetworkManager
> :rtype: integer
> """
> return _get_property("/org/freedesktop/NetworkManager", "State")
>
> # FIXME - use just GLOBAL? There is some connectivity checking
> @@ -112,17 +116,29 @@ def nm_state():
>  # and how it is implemented.
>  # Also see Gio g_network_monitor_can_reach.
>  def nm_is_connected():
> """Is NetworkManager connected?"""
> """Is NetworkManager connected?
> :return: True if NM is connected, False otherwise.
> :rtype: bool
> """
> return nm_state() in (NetworkManager.State.CONNECTED_GLOBAL,
>                       NetworkManager.State.CONNECTED_SITE,
>                       NetworkManager.State.CONNECTED_LOCAL)
>
> def nm_is_connecting():
> """Is NetworkManager connecting?"""
> """Is NetworkManager connecting?
> :return: True if NM is in CONNECTING state, False otherwise.
> :rtype: bool
> """
> return nm_state() == NetworkManager.State.CONNECTING
>
> def nm_devices():
> """Return list of network device names supported in installer"""
>
> """Return names of network devices supported in installer.
>
> :return: names of network devices supported in installer
>
> :rtype: list of strings
>
> """
>
> interfaces = []
>
> @@ -145,7 +161,11 @@ def nm_devices():
>      return interfaces
>
> def nm_activated_devices():
> """Return list of names of activated network devices"""
>
> """Return names of activated network devices.
>
> :return: names of activated network devices
>
> :rtype: list of strings
>
> """
>
> interfaces = []
>
> @@ -185,9 +205,14 @@ def _device_type_specific_interface(device):
>  def nm_device_property(name, prop):
>      """Return value of device NM property
>   Exceptions:
>   UnknownDeviceError if device is not found
>   PropertyNotFoundError if property is not found
>   :param name: name of device
>   :type name: str
>   :param prop: property
>   :type name: str
>   :return: value of device's property
>   :rtype: unpacked GDBus value
>   :raise UnknownDeviceError if device is not found
>   :raise PropertyNotFoundError if property is not found
> """

I think the above should be 
:raise PropertyNotFoundError: if property is not found

with the colon after the exception type which applies to a bunch of
other places from the patch. Otherwise this looks good to me, nice!