Commit a7399f66 authored by Iustin Pop's avatar Iustin Pop
Browse files

Documentation updates

Reviewed-by: imsnah
parent a47f574c
......@@ -21,3 +21,5 @@ docformat: epytext
imports: yes
include-log: no
inheritance: listed
......@@ -40,11 +40,18 @@ class BaseOpCode(object):
This object serves as a parent class for OpCode without any custom
field handling.
"""
__slots__ = []
def __init__(self, **kwargs):
"""Constructor for BaseOpCode.
The constructor takes only keyword arguments and will set
attributes on this object based on the passed arguments. As such,
it means that you should not pass arguments which are not in the
__slots__ attribute for this class.
"""
for key in kwargs:
if key not in self.__slots__:
raise TypeError("Object %s doesn't support the parameter '%s'" %
......@@ -52,6 +59,15 @@ class BaseOpCode(object):
setattr(self, key, kwargs[key])
def __getstate__(self):
"""Generic serializer.
This method just returns the contents of the instance as a
dictionary.
@rtype: C{dict}
@return: the instance attributes and their values
"""
state = {}
for name in self.__slots__:
if hasattr(self, name):
......@@ -59,6 +75,15 @@ class BaseOpCode(object):
return state
def __setstate__(self, state):
"""Generic unserializer.
This method just restores from the serialized state the attributes
of the current instance.
@param state: the serialized opcode data
@type state: C{dict}
"""
if not isinstance(state, dict):
raise ValueError("Invalid data to __setstate__: expected dict, got %s" %
type(state))
......@@ -72,13 +97,28 @@ class BaseOpCode(object):
class OpCode(BaseOpCode):
"""Abstract OpCode"""
"""Abstract OpCode.
This is the root of the actual OpCode hierarchy. All clases derived
from this class should override OP_ID.
@cvar OP_ID: The ID of this opcode. This should be unique amongst all
childre of this class.
"""
OP_ID = "OP_ABSTRACT"
__slots__ = []
def __getstate__(self):
"""Specialized getstate for opcodes.
This method adds to the state dictionary the OP_ID of the class,
so that on unload we can identify the correct class for
instantiating the opcode.
@rtype: C{dict}
@return: the state as a dictionary
"""
data = BaseOpCode.__getstate__(self)
data["OP_ID"] = self.OP_ID
......@@ -88,6 +128,13 @@ class OpCode(BaseOpCode):
def LoadOpCode(cls, data):
"""Generic load opcode method.
The method identifies the correct opcode class from the dict-form
by looking for a OP_ID key, if this is not found, or its value is
not available in this module as a child of this class, we fail.
@type data: C{dict}
@param data: the serialized opcode
"""
if not isinstance(data, dict):
raise ValueError("Invalid data to LoadOpCode (%s)" % type(data))
......@@ -113,7 +160,12 @@ class OpCode(BaseOpCode):
class OpDestroyCluster(OpCode):
"""Destroy the cluster."""
"""Destroy the cluster.
This opcode has no other parameters. All the state is irreversibly
lost after the execution of this opcode.
"""
OP_ID = "OP_CLUSTER_DESTROY"
__slots__ = []
......@@ -125,7 +177,15 @@ class OpQueryClusterInfo(OpCode):
class OpVerifyCluster(OpCode):
"""Verify the cluster state."""
"""Verify the cluster state.
@type skip_checks: C{list}
@ivar skip_checks: steps to be skipped from the verify process; this
needs to be a subset of
L{constants.VERIFY_OPTIONAL_CHECKS}; currently
only L{constants.VERIFY_NPLUSONE_MEM} can be passed
"""
OP_ID = "OP_CLUSTER_VERIFY"
__slots__ = ["skip_checks"]
......@@ -137,7 +197,7 @@ class OpVerifyDisks(OpCode):
Result: two lists:
- list of node names with bad data returned (unreachable, etc.)
- dist of node names with broken volume groups (values: error msg)
- dict of node names with broken volume groups (values: error msg)
- list of instances with degraded disks (that should be activated)
- dict of instances with missing logical volumes (values: (node, vol)
pairs with details about the missing volumes)
......@@ -168,13 +228,25 @@ class OpDumpClusterConfig(OpCode):
class OpRenameCluster(OpCode):
"""Rename the cluster."""
"""Rename the cluster.
@type name: C{str}
@ivar name: The new name of the cluster. The name and/or the master IP
address will be changed to match the new name and its IP
address.
"""
OP_ID = "OP_CLUSTER_RENAME"
__slots__ = ["name"]
class OpSetClusterParams(OpCode):
"""Change the parameters of the cluster."""
"""Change the parameters of the cluster.
@type vg_name: C{str} or C{None}
@ivar vg_name: The new volume group name or None to disable LVM usage.
"""
OP_ID = "OP_CLUSTER_SET_PARAMS"
__slots__ = ["vg_name"]
......@@ -182,13 +254,39 @@ class OpSetClusterParams(OpCode):
# node opcodes
class OpRemoveNode(OpCode):
"""Remove a node."""
"""Remove a node.
@type node_name: C{str}
@ivar node_name: The name of the node to remove. If the node still has
instances on it, the operation will fail.
"""
OP_ID = "OP_NODE_REMOVE"
__slots__ = ["node_name"]
class OpAddNode(OpCode):
"""Add a node."""
"""Add a node to the cluster.
@type node_name: C{str}
@ivar node_name: The name of the node to add. This can be a short name,
but it will be expanded to the FQDN.
@type primary_ip: IP address
@ivar primary_ip: The primary IP of the node. This will be ignored when the
opcode is submitted, but will be filled during the node
add (so it will be visible in the job query).
@type secondary_ip: IP address
@ivar secondary_ip: The secondary IP of the node. This needs to be passed
if the cluster has been initialized in 'dual-network'
mode, otherwise it must not be given.
@type readd: C{bool}
@ivar readd: Whether to re-add an existing node to the cluster. If
this is not passed, then the operation will abort if the node
name is already in the cluster; use this parameter to 'repair'
a node that had its configuration broken, or was reinstalled
without removal from the cluster.
"""
OP_ID = "OP_NODE_ADD"
__slots__ = ["node_name", "primary_ip", "secondary_ip", "readd"]
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment