Commit c41eea6e authored by Iustin Pop's avatar Iustin Pop

Fix epydoc format warnings

This patch should fix all outstanding epydoc parsing errors; as such, we
switch epydoc into verbose mode so that any new errors will be visible.

Reviewed-by: imsnah
parent 16f323ce
......@@ -344,7 +344,7 @@ apidoc:
CDIR=`pwd` && \
cd $$TMPDIR && \
mv lib ganeti && \
epydoc --conf $$CDIR/epydoc.conf -o $$CDIR/doc/api \
epydoc -v --conf $$CDIR/epydoc.conf -o $$CDIR/doc/api \
) ; \
rm -rf $$TMPDIR ; \
}
......
......@@ -89,9 +89,8 @@ class IOServer(SocketServer.UnixStreamServer):
def __init__(self, address, rqhandler):
"""IOServer constructor
Args:
address: the address to bind this IOServer to
rqhandler: RequestHandler type object
@param address: the address to bind this IOServer to
@param rqhandler: RequestHandler type object
"""
SocketServer.UnixStreamServer.__init__(self, address, rqhandler)
......@@ -348,8 +347,7 @@ class GanetiContext(object):
def ParseOptions():
"""Parse the command line options.
Returns:
(options, args) as from OptionParser.parse_args()
@return: (options, args) as from OptionParser.parse_args()
"""
parser = OptionParser(description="Ganeti master daemon",
......
......@@ -647,8 +647,7 @@ class NodeHttpServer(http.server.HttpServer):
def ParseOptions():
"""Parse the command line options.
Returns:
(options, args) as from OptionParser.parse_args()
@return: (options, args) as from OptionParser.parse_args()
"""
parser = OptionParser(description="Ganeti node daemon",
......
......@@ -75,8 +75,7 @@ class RemoteApiHttpServer(http.server.HttpServer):
def ParseOptions():
"""Parse the command line options.
Returns:
(options, args) as from OptionParser.parse_args()
@return: (options, args) as from OptionParser.parse_args()
"""
parser = optparse.OptionParser(description="Ganeti Remote API",
......
......@@ -62,9 +62,8 @@ class NotMasterError(errors.GenericError):
def Indent(s, prefix='| '):
"""Indent a piece of text with a given prefix before each line.
Args:
s: The string to indent
prefix: The string to prepend each line.
@param s: the string to indent
@param prefix: the string to prepend each line
"""
return "%s%s\n" % (prefix, ('\n' + prefix).join(s.splitlines()))
......@@ -158,8 +157,8 @@ class WatcherState(object):
def NumberOfRestartAttempts(self, instance):
"""Returns number of previous restart attempts.
Args:
instance - the instance to look up.
@type instance: L{Instance}
@param instance: the instance to look up
"""
idata = self._data["instance"]
......@@ -172,8 +171,8 @@ class WatcherState(object):
def RecordRestartAttempt(self, instance):
"""Record a restart attempt.
Args:
instance - the instance being restarted
@type instance: L{Instance}
@param instance: the instance being restarted
"""
idata = self._data["instance"]
......@@ -187,12 +186,13 @@ class WatcherState(object):
inst[KEY_RESTART_COUNT] = inst.get(KEY_RESTART_COUNT, 0) + 1
def RemoveInstance(self, instance):
"""Update state to reflect that a machine is running, i.e. remove record.
"""Update state to reflect that a machine is running.
Args:
instance - the instance to remove from books
This method removes the record for a named instance (as we only
track down instances).
This method removes the record for a named instance.
@type instance: L{Instance}
@param instance: the instance to remove from books
"""
idata = self._data["instance"]
......@@ -204,9 +204,6 @@ class WatcherState(object):
class Instance(object):
"""Abstraction for a Virtual Machine instance.
Methods:
Restart(): issue a command to restart the represented machine.
"""
def __init__(self, name, state, autostart):
self.name = name
......@@ -399,8 +396,7 @@ class Watcher(object):
def ParseOptions():
"""Parse the command line options.
Returns:
(options, args) as from OptionParser.parse_args()
@return: (options, args) as from OptionParser.parse_args()
"""
parser = OptionParser(description="Ganeti cluster watcher",
......
......@@ -279,7 +279,7 @@ def LeaveCluster():
from the cluster.
If processing is successful, then it raises an
L{errors.GanetiQuitException} which is used as a special case to
L{errors.QuitGanetiException} which is used as a special case to
shutdown the node daemon.
"""
......@@ -970,7 +970,7 @@ def RemoveBlockDevice(disk):
@note: This is intended to be called recursively.
@type disk: L{objects.disk}
@type disk: L{objects.Disk}
@param disk: the disk object we should remove
@rtype: boolean
@return: the success of the operation
......@@ -1069,8 +1069,9 @@ def AssembleBlockDevice(disk, owner, as_primary):
def ShutdownBlockDevice(disk):
"""Shut down a block device.
First, if the device is assembled (can L{Attach()}), then the device
is shutdown. Then the children of the device are shutdown.
First, if the device is assembled (Attach() is successfull), then
the device is shutdown. Then the children of the device are
shutdown.
This function is called recursively. Note that we don't cache the
children or such, as oppossed to assemble, shutdown of different
......@@ -1161,7 +1162,7 @@ def GetMirrorStatus(disks):
@rtype: disk
@return:
a list of (mirror_done, estimated_time) tuples, which
are the result of L{bdev.BlockDevice.CombinedSyncStatus}
are the result of L{bdev.BlockDev.CombinedSyncStatus}
@raise errors.BlockDeviceError: if any of the disks cannot be
found
......@@ -1981,7 +1982,7 @@ def JobQueueUpdate(file_name, content):
def JobQueueRename(old, new):
"""Renames a job queue file.
This is just a wrapper over L{os.rename} with proper checking.
This is just a wrapper over os.rename with proper checking.
@type old: str
@param old: the old (actual) file name
......@@ -2305,7 +2306,7 @@ class DevCacheManager(object):
node nor not
@type iv_name: str
@param iv_name: the instance-visible name of the
device, as in L{objects.Disk.iv_name}
device, as in objects.Disk.iv_name
@rtype: None
......
......@@ -202,9 +202,6 @@ class BlockDev(object):
If this device is a mirroring device, this function returns the
status of the mirror.
Returns:
(sync_percent, estimated_time, is_degraded, ldisk)
If sync_percent is None, it means the device is not syncing.
If estimated_time is None, it means we can't estimate
......@@ -218,6 +215,9 @@ class BlockDev(object):
data. This is only valid for some devices, the rest will always
return False (not degraded).
@rtype: tuple
@return: (sync_percent, estimated_time, is_degraded, ldisk)
"""
return None, None, False, False
......@@ -259,10 +259,7 @@ class BlockDev(object):
def Grow(self, amount):
"""Grow the block device.
Arguments:
amount: the amount (in mebibytes) to grow with
Returns: None
@param amount: the amount (in mebibytes) to grow with
"""
raise NotImplementedError
......@@ -326,11 +323,10 @@ class LogicalVolume(BlockDev):
def GetPVInfo(vg_name):
"""Get the free space info for PVs in a volume group.
Args:
vg_name: the volume group name
@param vg_name: the volume group name
Returns:
list of (free_space, name) with free_space in mebibytes
@rtype: list
@return: list of tuples (free_space, name) with free_space in mebibytes
"""
command = ["pvs", "--noheadings", "--nosuffix", "--units=m",
......@@ -456,9 +452,6 @@ class LogicalVolume(BlockDev):
If this device is a mirroring device, this function returns the
status of the mirror.
Returns:
(sync_percent, estimated_time, is_degraded, ldisk)
For logical volumes, sync_percent and estimated_time are always
None (no recovery in progress, as we don't handle the mirrored LV
case). The is_degraded parameter is the inverse of the ldisk
......@@ -472,6 +465,9 @@ class LogicalVolume(BlockDev):
The status was already read in Attach, so we just return it.
@rtype: tuple
@return: (sync_percent, estimated_time, is_degraded, ldisk)
"""
return None, None, self._degraded, self._degraded
......@@ -642,8 +638,8 @@ class BaseDRBD(BlockDev):
def _MassageProcData(data):
"""Transform the output of _GetProdData into a nicer form.
Returns:
a dictionary of minor: joined lines from /proc/drbd for that minor
@return: a dictionary of minor: joined lines from /proc/drbd
for that minor
"""
lmatch = re.compile("^ *([0-9]+):.*$")
......@@ -669,12 +665,12 @@ class BaseDRBD(BlockDev):
"""Return the DRBD version.
This will return a dict with keys:
k_major,
k_minor,
k_point,
api,
proto,
proto2 (only on drbd > 8.2.X)
- k_major
- k_minor
- k_point
- api
- proto
- proto2 (only on drbd > 8.2.X)
"""
proc_data = cls._GetProcData()
......@@ -1176,8 +1172,6 @@ class DRBD8(BaseDRBD):
def GetSyncStatus(self):
"""Returns the sync status of the device.
Returns:
(sync_percent, estimated_time, is_degraded)
If sync_percent is None, it means all is ok
If estimated_time is None, it means we can't esimate
......@@ -1190,6 +1184,9 @@ class DRBD8(BaseDRBD):
We compute the ldisk parameter based on wheter we have a local
disk or not.
@rtype: tuple
@return: (sync_percent, estimated_time, is_degraded, ldisk)
"""
if self.minor is None and not self.Attach():
raise errors.BlockDeviceError("Can't attach to device in GetSyncStatus")
......@@ -1504,8 +1501,8 @@ class FileStorage(BlockDev):
def Remove(self):
"""Remove the file backing the block device.
Returns:
boolean indicating wheter removal of file was successful or not.
@rtype: boolean
@return: True if the removal was successful
"""
if not os.path.exists(self.dev_path):
......@@ -1522,8 +1519,8 @@ class FileStorage(BlockDev):
Check if this file already exists.
Returns:
boolean indicating if file exists or not.
@rtype: boolean
@return: True if file exists
"""
self.attached = os.path.exists(self.dev_path)
......@@ -1533,12 +1530,10 @@ class FileStorage(BlockDev):
def Create(cls, unique_id, children, size):
"""Create a new file.
Args:
children:
size: integer size of file in MiB
@param size: the size of file in MiB
Returns:
A ganeti.bdev.FileStorage object.
@rtype: L{bdev.FileStorage}
@return: an instance of FileStorage
"""
if not isinstance(unique_id, (tuple, list)) or len(unique_id) != 2:
......
......@@ -41,12 +41,10 @@ from ganeti import ssconf
def _InitSSHSetup(node):
"""Setup the SSH configuration for the cluster.
This generates a dsa keypair for root, adds the pub key to the
permitted hosts and adds the hostkey to its own known hosts.
Args:
node: the name of this host as a fqdn
@param node: the name of this host as an FQDN
"""
priv_key, pub_key, auth_keys = ssh.GetUserFiles(constants.GANETI_RUNAS)
......@@ -243,16 +241,16 @@ def InitConfig(version, cluster_config, master_node_config,
node, and no instances.
@type version: int
@param version: Configuration version
@type cluster_config: objects.Cluster
@param cluster_config: Cluster configuration
@type master_node_config: objects.Node
@param master_node_config: Master node configuration
@type file_name: string
@param file_name: Configuration file path
@rtype: ssconf.SimpleConfigWriter
@returns: Initialized config instance
@param version: configuration version
@type cluster_config: L{objects.Cluster}
@param cluster_config: cluster configuration
@type master_node_config: L{objects.Node}
@param master_node_config: master node configuration
@type cfg_file: string
@param cfg_file: configuration file path
@rtype: L{ssconf.SimpleConfigWriter}
@returns: initialized config instance
"""
nodes = {
......
......@@ -314,15 +314,15 @@ keyval_option = KeyValOption
def _ParseArgs(argv, commands, aliases):
"""Parses the command line and return the function which must be
executed together with its arguments
"""Parser for the command line arguments.
Arguments:
argv: the command line
This function parses the arguements and returns the function which
must be executed together with its (modified) arguments.
commands: dictionary with special contents, see the design doc for
cmdline handling
aliases: dictionary with command aliases {'alias': 'target, ...}
@param argv: the command line
@param commands: dictionary with special contents, see the design
doc for cmdline handling
@param aliases: dictionary with command aliases {'alias': 'target, ...}
"""
if len(argv) == 0:
......@@ -439,17 +439,16 @@ def UsesRPC(fn):
def AskUser(text, choices=None):
"""Ask the user a question.
Args:
text - the question to ask.
@param text: the question to ask
choices - list with elements tuples (input_char, return_value,
description); if not given, it will default to: [('y', True,
'Perform the operation'), ('n', False, 'Do no do the operation')];
note that the '?' char is reserved for help
@param choices: list with elements tuples (input_char, return_value,
description); if not given, it will default to: [('y', True,
'Perform the operation'), ('n', False, 'Do no do the operation')];
note that the '?' char is reserved for help
Returns: one of the return values from the choices list; if input is
not possible (i.e. not running with a tty, we return the last entry
from the list
@return: one of the return values from the choices list; if input is
not possible (i.e. not running with a tty, we return the last
entry from the list
"""
if choices is None:
......
......@@ -49,6 +49,14 @@ _config_lock = locking.SharedLock()
def _ValidateConfig(data):
"""Verifies that a configuration objects looks valid.
This only verifies the version of the configuration.
@raise errors.ConfigurationError: if the version differs from what
we expect
"""
if data.version != constants.CONFIG_VERSION:
raise errors.ConfigurationError("Cluster configuration version"
" mismatch, got %s instead of %s" %
......@@ -155,13 +163,13 @@ class ConfigWriter:
This checks the current node, instances and disk names for
duplicates.
Args:
- exceptions: a list with some other names which should be checked
for uniqueness (used for example when you want to get
more than one id at one time without adding each one in
turn to the config file
@param exceptions: a list with some other names which should be checked
for uniqueness (used for example when you want to get
more than one id at one time without adding each one in
turn to the config file)
Returns: the unique id as a string
@rtype: string
@return: the unique id
"""
existing = set()
......@@ -185,6 +193,9 @@ class ConfigWriter:
def _AllMACs(self):
"""Return all MACs present in the config.
@rtype: list
@return: the list of all MACs
"""
result = []
for instance in self._config_data.instances.values():
......@@ -196,6 +207,9 @@ class ConfigWriter:
def _AllDRBDSecrets(self):
"""Return all DRBD secrets present in the config.
@rtype: list
@return: the list of all DRBD secrets
"""
def helper(disk, result):
"""Recursively gather secrets from this disk."""
......@@ -377,9 +391,9 @@ class ConfigWriter:
def _ComputeDRBDMap(self, instance):
"""Compute the used DRBD minor/nodes.
Return: dictionary of node_name: dict of minor: instance_name. The
returned dict will have all the nodes in it (even if with an empty
list).
@return: dictionary of node_name: dict of minor: instance_name;
the returned dict will have all the nodes in it (even if with
an empty list).
"""
def _AppendUsedPorts(instance_name, disk, used):
......@@ -521,9 +535,9 @@ class ConfigWriter:
def GetHostKey(self):
"""Return the rsa hostkey from the config.
Args: None
@rtype: string
@return: the rsa hostkey
Returns: rsa hostkey
"""
return self._config_data.cluster.rsahostkeypub
......@@ -533,8 +547,9 @@ class ConfigWriter:
This should be used after creating a new instance.
Args:
instance: the instance object
@type instance: L{objects.Instance}
@param instance: the instance object
"""
if not isinstance(instance, objects.Instance):
raise errors.ProgrammerError("Invalid type passed to AddInstance")
......@@ -628,9 +643,8 @@ class ConfigWriter:
def GetInstanceList(self):
"""Get the list of instances.
Returns:
array of instances, ex. ['instance2.example.com','instance1.example.com']
these contains all the instances, also the ones in Admin_down state
@return: array of instances, ex. ['instance2.example.com',
'instance1.example.com']
"""
return self._UnlockedGetInstanceList()
......@@ -661,11 +675,11 @@ class ConfigWriter:
It takes the information from the configuration file. Other informations of
an instance are taken from the live systems.
Args:
instance: name of the instance, ex instance1.example.com
@param instance_name: name of the instance, e.g.
I{instance1.example.com}
Returns:
the instance object
@rtype: L{objects.Instance}
@return: the instance object
"""
return self._UnlockedGetInstanceInfo(instance_name)
......@@ -687,8 +701,8 @@ class ConfigWriter:
def AddNode(self, node):
"""Add a node to the configuration.
Args:
node: an object.Node instance
@type node: L{objects.Node}
@param node: a Node instance
"""
logging.info("Adding node %s to configuration" % node.name)
......@@ -723,11 +737,13 @@ class ConfigWriter:
def _UnlockedGetNodeInfo(self, node_name):
"""Get the configuration of a node, as stored in the config.
This function is for internal use, when the config lock is already held.
This function is for internal use, when the config lock is already
held.
Args: node: nodename (tuple) of the node
@param node_name: the node name, e.g. I{node1.example.com}
Returns: the node object
@rtype: L{objects.Node}
@return: the node object
"""
if node_name not in self._config_data.nodes:
......@@ -740,9 +756,12 @@ class ConfigWriter:
def GetNodeInfo(self, node_name):
"""Get the configuration of a node, as stored in the config.
Args: node: nodename (tuple) of the node
This is just a locked wrapper over L{_UnlockedGetNodeInfo}.
Returns: the node object
@param node_name: the node name, e.g. I{node1.example.com}
@rtype: L{objects.Node}
@return: the node object
"""
return self._UnlockedGetNodeInfo(node_name)
......@@ -750,7 +769,10 @@ class ConfigWriter:
def _UnlockedGetNodeList(self):
"""Return the list of nodes which are in the configuration.
This function is for internal use, when the config lock is already held.
This function is for internal use, when the config lock is already
held.
@rtype: list
"""
return self._config_data.nodes.keys()
......@@ -846,10 +868,6 @@ class ConfigWriter:
def _OpenConfig(self):
"""Read the config data from disk.
In case we already have configuration data and the config file has
the same mtime as when we read it, we skip the parsing of the
file, since de-serialisation could be slow.
"""
f = open(self._cfg_file, 'r')
try:
......@@ -1026,8 +1044,8 @@ class ConfigWriter:
def GetClusterInfo(self):
"""Returns informations about the cluster
Returns:
the cluster object
@rtype: L{objects.Cluster}
@return: the cluster object
"""
return self._config_data.cluster
......@@ -1042,6 +1060,10 @@ class ConfigWriter:
that all modified objects will be saved, but the target argument
is the one the caller wants to ensure that it's saved.
@param target: an instance of either L{objects.Cluster},
L{objects.Node} or L{objects.Instance} which is existing in
the cluster
"""
if self._config_data is None:
raise errors.ProgrammerError("Configuration file not read,"
......
......@@ -228,7 +228,8 @@ class QuitGanetiException(Exception):
error should returned to the caller, and the second one will be the returned
result (either as an error or as a normal result).
Examples:
Examples::
# Return a result of "True" to the caller, but quit ganeti afterwards
raise QuitGanetiException(False, True)
# Send an error to the caller, and quit ganeti
......
......@@ -393,7 +393,7 @@ class HttpServer(http.HttpSocketBase):
@type mainloop: ganeti.daemon.Mainloop
@param mainloop: Mainloop used to poll for I/O events
@type local_addess: string
@type local_address: string
@param local_address: Local IP address to bind to
@type port: int
@param port: TCP port to listen on
......
......@@ -57,11 +57,9 @@ class BaseHypervisor(object):
def GetInstanceInfo(self, instance_name):
"""Get instance properties.
Args:
instance_name: the instance name
@param instance_name: the instance name
Returns:
(name, id, memory, vcpus, state, times)
@return: tuple (name, id, memory, vcpus, state, times)
"""
raise NotImplementedError
......@@ -69,19 +67,18 @@ class BaseHypervisor(object):
def GetAllInstancesInfo(self):
"""Get properties of all instances.
Returns:
[(name, id, memory, vcpus, stat, times),...]
@return: list of tuples (name, id, memory, vcpus, stat, times)
"""
raise NotImplementedError
def GetNodeInfo(self):
"""Return information about the node.
The return value is a dict, which has to have the following items:
(all values in MiB)
- memory_total: the total memory size on the node
- memory_free: the available memory on the node for instances
- memory_dom0: the memory used by the node itself, if available
@return: a dict with the following keys (values in MiB):
- memory_total: the total memory size on the node
- memory_free: the available memory on the node for instances
- memory_dom0: the memory used by the node itself, if available
"""
raise NotImplementedError
......
......@@ -56,11 +56,10 @@ class FakeHypervisor(hv_base.BaseHypervisor):