openstack/heat
Code Issues Proposed changes

Fix garbled docstrings

Browse Source 
The process of bringing us into compliance with the H405 pep8 rule has left
us with a lot of docstrings that either don't follow the recommendations of
PEP0257, are misleading, wrong, or nonsensical. This patch attempts to fix
them up.

Change-Id: Icfe90b5ba3102a7e13ab659038a8b2af9019e9e6
This commit is contained in:
Zane Bitter 2015-11-10 11:12:36 -05:00
parent f7edd0ba2d
commit 388ee0257f
18 changed files with 114 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
heat/engine/dependencies.py
View File

@ -104,7 +104,7 @@ class Graph(collections.defaultdict):
super(Graph, self).__init__(Node, *args)
def map(self, func):
"""A dict mapping the supplied function onto each node in the graph.
"""Map the supplied function onto each node in the graph.
Return a dictionary derived from mapping the supplied function onto
each node in the graph.
@ -172,7 +172,7 @@ class Dependencies(object):
def __init__(self, edges=None):
"""Initialise, optionally with a list of edges.
Each edge has the form of (requirer, required) tuple.
Each edge takes the form of a (requirer, required) tuple.
"""
edges = edges or []
self._graph = Graph()
@ -207,10 +207,10 @@ class Dependencies(object):
return self._graph[target].requires()
def __getitem__(self, last):
"""Partial dependency graph consisting of the specified node.
"""Return a partial dependency graph starting with the specified node.
Return a partial dependency graph consisting of the specified node and
all those that require it only.
Return a subset of the dependency graph consisting of the specified
node and all those that require it only.
"""
if last not in self._graph:
raise KeyError

15
heat/engine/environment.py
View File

@ -223,8 +223,7 @@ class ResourceRegistry(object):
def _register_info(self, path, info):
"""Place the new info in the correct location in the registry.
:param path: a list of keys ['resources', 'my_server',
'OS::Nova::Server']
:param path: a list of keys ['resources', 'my_srv', 'OS::Nova::Server']
"""
descriptive_path = '/'.join(path)
name = path[-1]
@ -517,14 +516,14 @@ class ResourceRegistry(object):
class Environment(object):
def __init__(self, env=None, user_env=True):
"""Create an Environment from a dict of varying format.
"""Create an Environment from an input dict.
Next formats are available:
1) old-school flat parameters
2) or newer {resource_registry: bla, parameters: foo}
The dict may be in one of two formats:
1) old-school flat parameters; or
2) newer {resource_registry: bla, parameters: foo}
:param env: the json environment
:param user_env: boolean, if false then we manage python resources too.
:param user_env: boolean, if False then we manage python resources too.
"""
if env is None:
env = {}
@ -612,7 +611,7 @@ def get_child_environment(parent_env, child_params, item_to_remove=None,
environment.
1. resource_registry must be merged (child env should be loaded after the
parent env to take presence).
parent env to take precedence).
2. child parameters must overwrite the parent's as they won't be relevant
in the child template.

7
heat/engine/event.py
View File

@ -27,11 +27,10 @@ class Event(object):
def __init__(self, context, stack, action, status, reason,
physical_resource_id, resource_properties, resource_name,
resource_type, uuid=None, timestamp=None, id=None):
"""Initialisation of the event.
"""Initialise from a context, stack, and event information.
Initialise from a context, stack, and event information. The timestamp
and database ID may also be initialised if the event is already in the
database.
The timestamp and database ID may also be initialised if the event is
already in the database.
"""
self.context = context
self.stack = stack

12
heat/engine/function.py
View File

@ -66,6 +66,11 @@ class Function(object):
return dependencies(self.args, '.'.join([path, self.fn_name]))
def dep_attrs(self, resource_name):
"""Return the attributes of the specified resource that are referenced.
Return an iterator over any attributes of the specified resource that
this function references.
"""
return dep_attrs(self.args, resource_name)
def __reduce__(self):
@ -179,12 +184,13 @@ def dependencies(snippet, path=''):
def dep_attrs(snippet, resource_name):
"""Iterator over dependent attrs for resource_name in a template snippet.
"""Iterator over dependent attrs of a resource in a template snippet.
The snippet should be already parsed to insert Function objects where
appropriate.
:returns: an iterator over dependent attributes for specified resource_name
in a template snippet.
:returns: an iterator over the attributes of the specified resource that
are referenced in the template snippet.
"""
if isinstance(snippet, Function):

2
heat/engine/lifecycle_plugin.py
View File

@ -33,7 +33,7 @@ class LifecyclePlugin(object):
pass
def get_ordinal(self):
"""Order class instances for pre and post operation execution.
"""Get the sort order for pre and post operation execution.
The values returned by get_ordinal are used to create a partial order
for pre and post operation method invocations. The default ordinal

6
heat/engine/parameter_groups.py
View File

@ -35,10 +35,10 @@ class ParameterGroups(object):
self.parameter_groups = tmpl.get(PARAMETER_GROUPS)
def validate(self):
"""Validate parameters in current parameter group.
"""Validate the parameter group.
Validate that a parameter belongs to only one Parameter Group
and that each parameter name references a valid parameter.
Validate that each parameter belongs to only one Parameter Group and
that each parameter name in the group references a valid parameter.
"""
LOG.debug('Validating Parameter Groups.')
LOG.debug(self.parameter_names)

15
heat/engine/parameters.py
View File

@ -202,7 +202,7 @@ class Parameter(object):
return ParamClass(name, schema, value)
def __init__(self, name, schema, value=None):
"""Initialisation of the parameter.
"""Initialise the parameter.
Initialise the Parameter with a name, schema and optional user-supplied
value.
@ -255,10 +255,9 @@ class Parameter(object):
return self.user_value is not None or self.has_default()
def hidden(self):
"""Return if parameter is hidden.
"""Return whether the parameter is hidden.
Return whether the parameter should be sanitised in any output to
the user.
Hidden parameters should be sanitised in any output to the user.
"""
return self.schema.hidden
@ -458,7 +457,7 @@ class JsonParam(ParsedParameter):
class Parameters(collections.Mapping):
"""Parameters of a stack.
The parameters of a stack, with type checking, defaults etc., specified by
The parameters of a stack, with type checking, defaults, etc. specified by
the stack's template.
"""
@ -528,10 +527,10 @@ class Parameters(collections.Mapping):
return self.params[key].value()
def map(self, func, filter_func=lambda p: True):
"""Map the supplied filter function onto each Parameter.
"""Map the supplied function onto each Parameter.
Map the supplied filter function onto each Parameter (with an
optional filter function) and return the resulting dictionary.
Map the supplied function onto each Parameter (with an optional filter
function) and return the resulting dictionary.
"""
return dict((n, func(p))
for n, p in six.iteritems(self.params) if filter_func(p))

9
heat/engine/properties.py
View File

@ -350,10 +350,10 @@ class Properties(collections.Mapping):
@staticmethod
def schema_from_params(params_snippet):
"""Convert a template snippet with parameters into a properties schema.
"""Create properties schema from the parameters section of a template.
:param params_snippet: parameter definition from a template
:returns: an equivalent properties schema for the specified params
:returns: equivalent properties schemata for the specified parameters
"""
if params_snippet:
return dict((n, Schema.from_parameter(p)) for n, p
@ -561,7 +561,10 @@ class Properties(collections.Mapping):
@classmethod
def schema_to_parameters_and_properties(cls, schema, template_type='cfn'):
"""Generates properties with params resolved for a schema.
"""Convert a schema to template parameters and properties.
This can be used to generate a provider template that matches the
given properties schemata.
:param schema: A resource type's properties_schema
:returns: A tuple of params and properties dicts

39
heat/engine/resource.py
View File

@ -468,7 +468,7 @@ class Resource(object):
return dict((k, after.get(k)) for k in changed_keys_set)
def update_template_diff_properties(self, after_props, before_props):
"""The changed Properties between the before and after properties.
"""Return changed Properties between the before and after properties.
If any property having immutable as True is updated, raises
NotSupported error.
@ -525,13 +525,12 @@ class Resource(object):
deps += (self, None)
def required_by(self):
"""List of resources' names which require the resource as dependency.
"""List of resources that require this one as a dependency.
Returns a list of resources' names which directly require this
resource as a dependency.
Returns a list of names of resources that depend on this resource
directly.
"""
return list(
[r.name for r in self.stack.dependencies.required_by(self)])
return [r.name for r in self.stack.dependencies.required_by(self)]
def client(self, name=None):
client_name = name or self.default_client_name
@ -874,12 +873,12 @@ class Resource(object):
def update_convergence(self, template_id, resource_data, engine_id,
timeout):
"""Updates the resource.
"""Update the resource synchronously.
Updates the resource by invoking the scheduler TaskRunner
and it persists the resource's current_template_id to template_id and
resource's requires to list of the required resource id from the
given resource_data and existing resource's requires.
Persist the resource's current_template_id to template_id and
resource's requires to list of the required resource ids from the given
resource_data and existing resource's requires, then updates the
resource by invoking the scheduler TaskRunner.
"""
def update_tmpl_id_and_requires():
self.current_template_id = template_id
@ -905,7 +904,7 @@ class Resource(object):
@scheduler.wrappertask
def update(self, after, before=None, prev_resource=None):
"""Update the resource.
"""Return a task to update the resource.
Subclasses should provide a handle_update() method to customise update,
the base-class handle_update will fail by default.
@ -1026,7 +1025,7 @@ class Resource(object):
raise exception.Error('; '.join(invalid_checks))
def suspend(self):
"""Suspend the resource.
"""Return a task to suspend the resource.
Subclasses should provide a handle_suspend() method to implement
suspend.
@ -1046,7 +1045,7 @@ class Resource(object):
return self._do_action(action)
def resume(self):
"""Resume the resource.
"""Return a task to resume the resource.
Subclasses should provide a handle_resume() method to implement resume.
"""
@ -1222,7 +1221,7 @@ class Resource(object):
@scheduler.wrappertask
def delete(self):
"""Delete the resource.
"""A task to delete the resource.
Subclasses should provide a handle_delete() method to customise
deletion.
@ -1260,7 +1259,7 @@ class Resource(object):
@scheduler.wrappertask
def destroy(self):
"""Delete the resource and remove it from the database."""
"""A task to delete the resource and remove it from the database."""
yield self.delete()
if self.id is None:
@ -1672,7 +1671,7 @@ class Resource(object):
@classmethod
def resource_to_template(cls, resource_type, template_type='cfn'):
"""Template where resource's properties mapped as parameters.
"""Generate a provider template that mirrors the resource.
:param resource_type: The resource type to be displayed in the template
:param template_type: the template type to generate, cfn or hot.
@ -1720,7 +1719,7 @@ class Resource(object):
return tmpl_dict
def data(self):
"""Resource data for this resource.
"""Return the resource data for this resource.
Use methods data_set and data_delete to modify the resource data
for this resource.
@ -1736,13 +1735,13 @@ class Resource(object):
return self._data or {}
def data_set(self, key, value, redact=False):
"""Save resource's key/value pair to database."""
"""Set a key in the resource data."""
resource_data_objects.ResourceData.set(self, key, value, redact)
# force fetch all resource data from the database again
self._data = None
def data_delete(self, key):
"""Remove a resource_data element associated to a resource.
"""Remove a key from the resource data.
:returns: True if the key existed to delete.
"""

7
heat/engine/rsrc_defn.py
View File

@ -27,10 +27,7 @@ __all__ = ['ResourceDefinition']
class ResourceDefinitionCore(object):
"""A definition of a resource.
Independent of any particular template format.
"""
"""A definition of a resource, independent of any template format."""
DELETION_POLICIES = (
DELETE, RETAIN, SNAPSHOT,
@ -141,7 +138,7 @@ class ResourceDefinitionCore(object):
update_policy=reparse_snippet(self._update_policy))
def dep_attrs(self, resource_name):
"""Return an iterator over dependent attributes for resource_name.
"""Iterate over attributes of a given resource that this references.
Return an iterator over dependent attributes for specified
resource_name in resources' properties and metadata fields.

26
heat/engine/scheduler.py
View File

@ -32,9 +32,9 @@ ENABLE_SLEEP = True
def task_description(task):
"""Return a human-readable string description of a task suitable.
"""Return a human-readable string description of a task.
Description is used for logging the status of the task.
The description is used to identify the task when logging its status.
"""
name = task.__name__ if hasattr(task, '__name__') else None
if isinstance(task, types.MethodType):
@ -132,9 +132,9 @@ class TaskRunner(object):
"""Wrapper for a resumable task (co-routine)."""
def __init__(self, task, *args, **kwargs):
"""Initialise with a task function.
"""Initialise with a task function and arguments.
Arguments to be passed to task when it is started.
The arguments are passed to task when it is started.
The task function may be a co-routine that yields control flow between
steps.
@ -200,7 +200,7 @@ class TaskRunner(object):
def step(self):
"""Run another step of the task.
:returns: True if the task is complete; False otherwise.
Return True if the task is complete; False otherwise.
"""
if not self.done():
assert self._runner is not None, "Task not started"
@ -336,11 +336,10 @@ class DependencyTaskGroup(object):
aggregate_exceptions=False):
"""Initialise with the task dependencies.
Optionally initialise with a task to run on each.
If no task is supplied, it is assumed that the tasks are stored
directly in the dependency tree. If a task is supplied, the object
stored in the dependency tree is passed as an argument.
A task to run on each dependency may optionally be specified. If no
task is supplied, it is assumed that the tasks are stored directly in
the dependency tree. If a task is supplied, the object stored in the
dependency tree is passed as an argument.
If an error_wait_time is specified, tasks that are already running at
the time of an error will continue to run for up to the specified
@ -415,8 +414,8 @@ class DependencyTaskGroup(object):
def _ready(self):
"""Iterate over all subtasks that are ready to start.
All subtasks' dependencies have been satisfied but they have not yet
been started.
Ready subtasks are subtasks whose dependencies have all been satisfied,
but which have not yet been started.
"""
for k, n in six.iteritems(self._graph):
if not n:
@ -427,7 +426,8 @@ class DependencyTaskGroup(object):
def _running(self):
"""Iterate over all subtasks that are currently running.
Subtasks have been started but have not yet completed.
Running subtasks are subtasks have been started but have not yet
completed.
"""
def running(k_r):

34
heat/engine/service.py
View File

@ -94,7 +94,7 @@ class ThreadGroupManager(object):
def _service_task(self):
"""Dummy task which gets queued on the service.Service threadgroup.
Without this service.Service sees nothing running i.e has nothing to
Without this, service.Service sees nothing running i.e has nothing to
wait() on, so the process exits. This could also be used to trigger
periodic non-stack-specific housekeeping tasks.
"""
@ -136,7 +136,7 @@ class ThreadGroupManager(object):
return th
def start_with_lock(self, cnxt, stack, engine_id, func, *args, **kwargs):
"""Run the method in sub-thread if acquire a stack lock is successful.
"""Run the method in sub-thread after acquiring the stack lock.
Release the lock when the thread finishes.
@ -156,7 +156,7 @@ class ThreadGroupManager(object):
return th
def start_with_acquired_lock(self, stack, lock, func, *args, **kwargs):
"""Run the given method in a sub-thread.
"""Run the given method in a sub-thread with an existing stack lock.
Release the provided lock when the thread finishes.
@ -189,7 +189,7 @@ class ThreadGroupManager(object):
def add_timer(self, stack_id, func, *args, **kwargs):
"""Define a periodic task in the stack threadgroups.
Defining is to be run in a separate thread.
The task is run in a separate greenthread.
Periodicity is cfg.CONF.periodic_interval
"""
@ -261,7 +261,7 @@ class EngineListener(service.Service):
server.start()
def listening(self, ctxt):
"""Confirm the engine performing the action is still alive.
"""Respond to a watchdog request.
Respond affirmatively to confirm that the engine performing the action
is still alive.
@ -642,7 +642,7 @@ class EngineService(service.Service):
@context.request_context
def preview_stack(self, cnxt, stack_name, template, params, files, args):
"""Simulates a new stack using the provided template.
"""Simulate a new stack using the provided template.
Note that at this stage the template has already been fetched from the
heat-api process if using a template-url.
@ -673,7 +673,7 @@ class EngineService(service.Service):
def create_stack(self, cnxt, stack_name, template, params, files, args,
owner_id=None, nested_depth=0, user_creds_id=None,
stack_user_project_id=None, parent_resource_name=None):
"""Creates a new stack using the template provided.
"""Create a new stack using the template provided.
Note that at this stage the template has already been fetched from the
heat-api process if using a template-url.
@ -741,7 +741,7 @@ class EngineService(service.Service):
def _prepare_stack_updates(self, cnxt, current_stack, template, params,
files, args):
"""Return the current and updated stack.
"""Return the current and updated stack for a given transition.
Changes *will not* be persisted, this is a helper method for
update_stack and preview_update_stack.
@ -829,7 +829,7 @@ class EngineService(service.Service):
@context.request_context
def update_stack(self, cnxt, stack_identity, template, params,
files, args):
"""Updates an existing stack based on the provided template and params.
"""Update an existing stack based on the provided template and params.
Note that at this stage the template has already been fetched from the
heat-api process if using a template-url.
@ -877,7 +877,7 @@ class EngineService(service.Service):
@context.request_context
def preview_update_stack(self, cnxt, stack_identity, template, params,
files, args):
"""Shows the resources that would be updated.
"""Show the resources that would be updated.
The preview_update_stack method shows the resources that would be
changed with an update to an existing stack based on the provided
@ -970,7 +970,11 @@ class EngineService(service.Service):
@context.request_context
def validate_template(self, cnxt, template, params=None, files=None,
show_nested=False):
"""Uses the stack parser to check the validity of a template.
"""Check the validity of a template.
Checks, so far as we can, that a template is valid, and returns
information about the parameters suitable for producing a user
interface through which to specify the parameter values.
:param cnxt: RPC context.
:param template: Template of stack you want to create.
@ -1074,7 +1078,7 @@ class EngineService(service.Service):
@context.request_context
def delete_stack(self, cnxt, stack_identity):
"""The delete_stack method deletes a given stack.
"""Delete a given stack.
:param cnxt: RPC context.
:param stack_identity: Name of the stack you want to delete.
@ -1131,7 +1135,7 @@ class EngineService(service.Service):
@context.request_context
def abandon_stack(self, cnxt, stack_identity):
"""The abandon_stack method abandons a given stack.
"""Abandon a given stack.
:param cnxt: RPC context.
:param stack_identity: Name of the stack you want to abandon.
@ -1602,7 +1606,7 @@ class EngineService(service.Service):
@context.request_context
def show_watch(self, cnxt, watch_name):
"""The show_watch method returns the attributes of one watch/alarm.
"""Return the attributes of one watch/alarm.
:param cnxt: RPC context.
:param watch_name: Name of the watch you want to see, or None to see
@ -1623,7 +1627,7 @@ class EngineService(service.Service):
@context.request_context
def show_watch_metric(self, cnxt, metric_namespace=None, metric_name=None):
"""The show_watch method returns the datapoints for a metric.
"""Return the datapoints for a metric.
:param cnxt: RPC context.
:param metric_namespace: Name of the namespace you want to see, or None

2
heat/engine/service_stack_watch.py
View File

@ -106,7 +106,7 @@ class StackWatch(object):
actions, rule.get_details())
def periodic_watcher_task(self, sid):
"""Triggers watch-rule evaluation for all rules defined for stack ID.
"""Evaluate all watch-rules defined for stack ID.
Periodic task, created for each stack, triggers watch-rule evaluation
for all rules defined for the stack sid = stack ID.

22
heat/engine/stack.py
View File

@ -98,7 +98,7 @@ class Stack(collections.Mapping):
current_traversal=None, tags=None, prev_raw_template_id=None,
current_deps=None, cache_data=None, resource_validate=True):
"""Initialisation of stack.
"""Initialise the Stack.
Initialise from a context, name, Template object and (optionally)
Environment object. The database ID may also be initialised, if the
@ -330,18 +330,18 @@ class Stack(collections.Mapping):
def _set_param_stackid(self):
"""Update self.parameters with the current ARN.
self.parameters is then provided via the Parameters class as
the StackId pseudo parameter.
The ARN is then provided via the Parameters class as the StackId pseudo
parameter.
"""
if not self.parameters.set_stack_id(self.identifier()):
LOG.warn(_LW("Unable to set parameters StackId identifier"))
@staticmethod
def get_dep_attrs(resources, outputs, resource_name):
"""Return the set of dependent attributes for specified resource name.
"""Return the attributes of the specified resource that are referenced.
Return the set of dependent attributes for specified resource name by
inspecting all resources and outputs in template.
Return an iterator over any attributes of the specified resource that
are referenced.
"""
attr_lists = itertools.chain((res.dep_attrs(resource_name)
for res in resources),
@ -599,7 +599,7 @@ class Stack(collections.Mapping):
return r
def register_access_allowed_handler(self, credential_id, handler):
"""Register a specific function.
"""Register an authorization handler function.
Register a function which determines whether the credentials with a
given ID can have access to a named resource.
@ -820,8 +820,8 @@ class Stack(collections.Mapping):
aggregate_exceptions=False, pre_completion_func=None):
"""A task to perform an action on the stack.
All of the resources in forward or reverse dependency order as
specified by reverse.
All of the resources are traversed in forward or reverse dependency
order.
:param action action that should be executed with stack resources
:param reverse defines if action on the resources need to be executed
@ -947,7 +947,7 @@ class Stack(collections.Mapping):
@profiler.trace('Stack.adopt', hide_args=False)
def adopt(self):
"""Adopt the stack (create stack with all the existing resources)."""
"""Adopt existing resources into a new stack."""
def rollback():
if not self.disable_rollback and self.state == (self.ADOPT,
self.FAILED):
@ -985,7 +985,7 @@ class Stack(collections.Mapping):
@profiler.trace('Stack.converge_stack', hide_args=False)
def converge_stack(self, template, action=UPDATE, new_stack=None):
"""Update the stack and triggers convergence for resources."""
"""Update the stack template and trigger convergence for resources."""
if action not in [self.CREATE, self.ADOPT]:
# no back-up template for create action
self.prev_raw_template_id = getattr(self.t, 'id', None)

2
heat/engine/template.py
View File

@ -262,7 +262,7 @@ class Template(collections.Mapping):
@classmethod
def create_empty_template(cls,
version=('heat_template_version', '2015-04-30')):
"""Creates an empty template.
"""Create an empty template.
Creates a new empty template with given version. If version is
not provided, a new empty HOT template of version "2015-04-30"

2
heat/engine/timestamp.py
View File

@ -18,7 +18,7 @@ class Timestamp(object):
"""A descriptor for writing a timestamp to the database."""
def __init__(self, db_fetch, attribute):
"""Initialisation of timestamp.
"""Initialise the timestamp descriptor.
Initialise with a function to fetch the database representation of an
object (given a context and ID) and the name of the attribute to

7
heat/engine/update.py
View File

@ -196,10 +196,11 @@ class StackUpdate(object):
self.existing_stack.remove_resource(res_name)
def dependencies(self):
"""Return a Dependencies object.
"""Return the Dependencies graph for the update.
Dependencies object representing the dependencies between update
operations to move from an existing stack definition to a new one.
Returns a Dependencies object representing the dependencies between
update operations to move from an existing stack definition to a new
one.
"""
existing_deps = self.existing_stack.dependencies
new_deps = self.new_stack.dependencies

3
heat/engine/watchrule.py
View File

@ -77,7 +77,8 @@ class WatchRule(object):
def load(cls, context, watch_name=None, watch=None):
"""Load the watchrule object.
Loading object either by name or via an existing DB object.
The object can be loaded either from the DB by name or from an existing
DB object.
"""
if watch is None:
try: