libcloud.compute.base: Add some more missing docstrings, use consistent docstring format and fix some broken class references.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/f941c9df Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/f941c9df Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/f941c9df Branch: refs/heads/trunk Commit: f941c9dfdafa649a978601bba06026973d48b09a Parents: 0d27fce Author: Tomaz Muraus <[email protected]> Authored: Thu Nov 14 16:02:42 2013 +0100 Committer: Tomaz Muraus <[email protected]> Committed: Thu Nov 14 16:02:42 2013 +0100 ---------------------------------------------------------------------- libcloud/compute/base.py | 107 ++++++++++++++++++++++++++++-------------- 1 file changed, 72 insertions(+), 35 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/f941c9df/libcloud/compute/base.py ---------------------------------------------------------------------- diff --git a/libcloud/compute/base.py b/libcloud/compute/base.py index 155a017..2172e6b 100644 --- a/libcloud/compute/base.py +++ b/libcloud/compute/base.py @@ -387,6 +387,19 @@ class NodeLocation(object): """ def __init__(self, id, name, country, driver): + """ + :param id: Location ID. + :type id: ``str`` + + :param name: Location name. + :type name: ``str`` + + :param country: Location country. + :type country : ``str`` + + :param driver: Driver this location belongs to. + :type driver: :class:`.NodeDriver` + """ self.id = str(id) self.name = name self.country = country @@ -412,6 +425,10 @@ class NodeAuthSSHKey(object): """ def __init__(self, pubkey): + """ + :param pubkey: Public key matetiral. + :type pubkey: ``str`` + """ self.pubkey = pubkey def __repr__(self): @@ -423,6 +440,13 @@ class NodeAuthPassword(object): A password to be used for authentication to a node. """ def __init__(self, password, generated=False): + """ + :param password: Password. + :type password: ``str`` + + :type generated: ``True`` if this password was automatically generated, + ``False`` otherwise. + """ self.password = password self.generated = generated @@ -464,12 +488,13 @@ class StorageVolume(UuidMixin): Attach this volume to a node. :param node: Node to attach volume to - :type node: :class:`Node` + :type node: :class:`.Node` :param device: Where the device is exposed, e.g. '/dev/sdb (optional) :type device: ``str`` + :return: ``True`` if attach was successful, ``False`` otherwise. :rtype: ``bool`` """ @@ -479,6 +504,7 @@ class StorageVolume(UuidMixin): """ Detach this volume from its node + :return: ``True`` if detach was successful, ``False`` otherwise. :rtype: ``bool`` """ @@ -494,6 +520,7 @@ class StorageVolume(UuidMixin): """ Creates a snapshot of this volume. + :return: Created snapshot. :rtype: ``VolumeSnapshot`` """ return self.driver.create_volume_snapshot(volume=self, name=name) @@ -502,6 +529,7 @@ class StorageVolume(UuidMixin): """ Destroy this storage volume. + :return: ``True`` if destroy was successful, ``False`` otherwise. :rtype: ``bool`` """ @@ -558,12 +586,14 @@ class NodeDriver(BaseDriver): type = None port = None features = {"create_node": []} + """ List of available features for a driver. - - :class:`create_node` - - ssh_key: Supports :class:`NodeAuthSSHKey` as an authentication + - :meth:`libcloud.compute.base.NodeDriver.create_node` + - ssh_key: Supports :class:`.NodeAuthSSHKey` as an authentication method for nodes. - - password: Supports :class:`NodeAuthPassword` as an authentication + - password: Supports :class:`.NodeAuthPassword` as an + authentication method for nodes. - generates_password: Returns a password attribute on the Node object returned from creation. @@ -579,13 +609,13 @@ class NodeDriver(BaseDriver): def _get_and_check_auth(self, auth): """ - Helper function for providers supporting :class:`NodeAuthPassword` or - :class:`NodeAuthSSHKey` + Helper function for providers supporting :class:`.NodeAuthPassword` or + :class:`.NodeAuthSSHKey` Validates that only a supported object type is passed to the auth parameter and raises an exception if it is not. - If no :class:`NodeAuthPassword` object is provided but one is expected + If no :class:`.NodeAuthPassword` object is provided but one is expected then a password is automatically generated. """ @@ -668,8 +698,8 @@ class NodeDriver(BaseDriver): actually provided to the driver API by the hosting provider rather than generated by libcloud. - You can only pass a :class:`NodeAuthPassword` or - :class:`NodeAuthSSHKey` to ``create_node`` via the auth parameter if + You can only pass a :class:`.NodeAuthPassword` or + :class:`.NodeAuthSSHKey` to ``create_node`` via the auth parameter if has the corresponding feature flag. :param name: String with a name for this new node (required) @@ -677,21 +707,21 @@ class NodeDriver(BaseDriver): :param size: The size of resources allocated to this node. (required) - :type size: :class:`NodeSize` + :type size: :class:`.NodeSize` :param image: OS Image to boot on node. (required) - :type image: :class:`NodeImage` + :type image: :class:`.NodeImage` :param location: Which data center to create a node in. If empty, undefined behavoir will be selected. (optional) - :type location: :class:`NodeLocation` + :type location: :class:`.NodeLocation` :param auth: Initial authentication information for the node (optional) - :type auth: :class:`NodeAuthSSHKey` or :class:`NodeAuthPassword` + :type auth: :class:`.NodeAuthSSHKey` or :class:`NodeAuthPassword` :return: The newly created node. - :rtype: :class:`Node` + :rtype: :class:`.Node` """ raise NotImplementedError( 'create_node not implemented for this driver') @@ -703,9 +733,9 @@ class NodeDriver(BaseDriver): the node, including backups. :param node: The node to be destroyed - :type node: :class:`Node` + :type node: :class:`.Node` - :return: True if the destroy was successful, otherwise False + :return: True if the destroy was successful, False otherwise. :rtype: ``bool`` """ raise NotImplementedError( @@ -716,7 +746,7 @@ class NodeDriver(BaseDriver): Reboot a node. :param node: The node to be rebooted - :type node: :class:`Node` + :type node: :class:`.Node` :return: True if the reboot was successful, otherwise False :rtype: ``bool`` @@ -728,7 +758,7 @@ class NodeDriver(BaseDriver): """ List all nodes :return: list of node objects - :rtype: ``list`` of :class:`Node` + :rtype: ``list`` of :class:`.Node` """ raise NotImplementedError( 'list_nodes not implemented for this driver') @@ -738,10 +768,10 @@ class NodeDriver(BaseDriver): List images on a provider :param location: The location at which to list images - :type location: :class:`NodeLocation` + :type location: :class:`.NodeLocation` :return: list of node image objects - :rtype: ``list`` of :class:`NodeImage` + :rtype: ``list`` of :class:`.NodeImage` """ raise NotImplementedError( 'list_images not implemented for this driver') @@ -751,10 +781,10 @@ class NodeDriver(BaseDriver): List sizes on a provider :param location: The location at which to list sizes - :type location: :class:`NodeLocation` + :type location: :class:`.NodeLocation` :return: list of node size objects - :rtype: ``list`` of :class:`NodeSize` + :rtype: ``list`` of :class:`.NodeSize` """ raise NotImplementedError( 'list_sizes not implemented for this driver') @@ -764,7 +794,7 @@ class NodeDriver(BaseDriver): List data centers for a provider :return: list of node location objects - :rtype: ``list`` of :class:`NodeLocation` + :rtype: ``list`` of :class:`.NodeLocation` """ raise NotImplementedError( 'list_locations not implemented for this driver') @@ -776,8 +806,8 @@ class NodeDriver(BaseDriver): In order to be able to SSH into a created node access credentials are required. - A user can pass either a :class:`NodeAuthPassword` or - :class:`NodeAuthSSHKey` to the ``auth`` argument. If the + A user can pass either a :class:`.NodeAuthPassword` or + :class:`.NodeAuthSSHKey` to the ``auth`` argument. If the ``create_node`` implementation supports that kind if credential (as declared in ``self.features['create_node']``) then it is passed on to ``create_node``. Otherwise it is not passed on to ``create_node`` and @@ -837,7 +867,7 @@ class NodeDriver(BaseDriver): :param auth: Initial authentication information for the node (optional) - :type auth: :class:`NodeAuthSSHKey` or :class:`NodeAuthPassword` + :type auth: :class:`.NodeAuthSSHKey` or :class:`NodeAuthPassword` :param ssh_key: A path (or paths) to an SSH private key with which to attempt to authenticate. (optional) @@ -947,7 +977,7 @@ class NodeDriver(BaseDriver): :param location: Which data center to create a volume in. If empty, undefined behavoir will be selected. (optional) - :type location: :class:`NodeLocation` + :type location: :class:`.NodeLocation` :param snapshot: Name of snapshot from which to create the new volume. (optional) @@ -976,11 +1006,16 @@ class NodeDriver(BaseDriver): """ Attaches volume to node. - :param Node node: Node to attach volume to. - :param StorageVolume volume: Volume to attach. - :param str device: Where the device is exposed, e.g. '/dev/sdb' + :param node: Node to attach volume to. + :type node: :class:`.Node` + + :param volume: Volume to attach. + :type volume: :class:`.StorageVolume` - :return bool: + :param device: Where the device is exposed, e.g. '/dev/sdb' + :type device: ``str`` + + :rytpe: ``bool`` """ raise NotImplementedError('attach not implemented for this driver') @@ -988,8 +1023,10 @@ class NodeDriver(BaseDriver): """ Detaches a volume from a node. - :param StorageVolume volume: Volume to be detached - :return bool: + :param volume: Volume to be detached + :type volume: :class:`.StorageVolume` + + :rtype: ``bool`` """ raise NotImplementedError('detach not implemented for this driver') @@ -998,7 +1035,7 @@ class NodeDriver(BaseDriver): """ List storage volumes. - :return [StorageVolume]: + :rtype: ``list`` of :class:`.StorageVolume` """ raise NotImplementedError( 'list_volumes not implemented for this driver') @@ -1046,7 +1083,7 @@ class NodeDriver(BaseDriver): assigned. :param nodes: list of node instances. - :type nodes: ``List`` of :class:`Node` + :type nodes: ``List`` of :class:`.Node` :param wait_period: How many seconds to between each loop iteration (default is 3)
