x/python-ganttclient
Code Issues Proposed changes

fix restructuredtext formatting in docstrings that show up in the developer guide

Browse Source 
blueprint sphinx-doc-cleanup
bug 945160

- Correct parameter declarations, list formatting, cross-references, etc.
- We don't need "let" in generate_autodoc_index.sh since we aren't doing math.
- Change conf.py to not prefix class and function names with full namespace
  in generated output to save width on the screen.

Change-Id: I9adc8681951913fd291d03e7142146e9d46841df
This commit is contained in:
Doug Hellmann
2012-03-05 14:33:40 -05:00
parent 7e6370a849
commit c74d97732d
7 changed files with 175 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
nova/auth/fakeldap.py
View File

@@ -244,9 +244,9 @@ class FakeLDAP(object):
def modify_s(self, dn, attrs):
"""Modify the object at dn using the attribute list.
Args:
dn -- a dn
attrs -- a list of tuples in the following form:
:param dn: a dn
:param attrs: a list of tuples in the following form::
([MOD_ADD | MOD_DELETE | MOD_REPACE], attribute, value)
"""

172
nova/auth/manager.py
View File

@@ -129,11 +129,17 @@ class User(AuthBase):
"""Object representing a user
The following attributes are defined:
:id: A system identifier for the user. A string (for LDAP)
:name: The user name, potentially in some more friendly format
:access: The 'username' for EC2 authentication
:secret: The 'password' for EC2 authenticatoin
:admin: ???
``id``
A system identifier for the user. A string (for LDAP)
``name``
The user name, potentially in some more friendly format
``access``
The 'username' for EC2 authentication
``secret``
The 'password' for EC2 authenticatoin
``admin``
???
"""
def __init__(self, id, name, access, secret, admin):
@@ -259,35 +265,35 @@ class AuthManager(object):
a project with the same name as the user. This way, older tools
that have no project knowledge will still work.
@type access: str
@param access: Access key for user in the form "access:project".
:type access: str
:param access: Access key for user in the form "access:project".
@type signature: str
@param signature: Signature of the request.
:type signature: str
:param signature: Signature of the request.
@type params: list of str
@param params: Web paramaters used for the signature.
:type params: list of str
:param params: Web paramaters used for the signature.
@type verb: str
@param verb: Web request verb ('GET' or 'POST').
:type verb: str
:param verb: Web request verb ('GET' or 'POST').
@type server_string: str
@param server_string: Web request server string.
:type server_string: str
:param server_string: Web request server string.
@type path: str
@param path: Web request path.
:type path: str
:param path: Web request path.
@type check_type: str
@param check_type: Type of signature to check. 'ec2' for EC2, 's3' for
:type check_type: str
:param check_type: Type of signature to check. 'ec2' for EC2, 's3' for
S3. Any other value will cause signature not to be
checked.
@type headers: list
@param headers: HTTP headers passed with the request (only needed for
:type headers: list
:param headers: HTTP headers passed with the request (only needed for
s3 signature checks)
@rtype: tuple (User, Project)
@return: User and project that the request represents.
:rtype: tuple (User, Project)
:return: User and project that the request represents.
"""
# TODO(vish): check for valid timestamp
(access_key, _sep, project_id) = access.partition(':')
@@ -365,11 +371,11 @@ class AuthManager(object):
def is_superuser(self, user):
"""Checks for superuser status, allowing user to bypass authorization
@type user: User or uid
@param user: User to check.
:type user: User or uid
:param user: User to check.
@rtype: bool
@return: True for superuser.
:rtype: bool
:return: True for superuser.
"""
if not isinstance(user, User):
user = self.get_user(user)
@@ -383,11 +389,11 @@ class AuthManager(object):
def is_admin(self, user):
"""Checks for admin status, allowing user to access all projects
@type user: User or uid
@param user: User to check.
:type user: User or uid
:param user: User to check.
@rtype: bool
@return: True for admin.
:rtype: bool
:return: True for admin.
"""
if not isinstance(user, User):
user = self.get_user(user)
@@ -429,17 +435,17 @@ class AuthManager(object):
see if the user is the project_manager of the specified project. It
is the same as calling is_project_manager(user, project).
@type user: User or uid
@param user: User to check.
:type user: User or uid
:param user: User to check.
@type role: str
@param role: Role to check.
:type role: str
:param role: Role to check.
@type project: Project or project_id
@param project: Project in which to look for local role.
:type project: Project or project_id
:param project: Project in which to look for local role.
@rtype: bool
@return: True if the user has the role.
:rtype: bool
:return: True if the user has the role.
"""
if role == 'projectmanager':
if not project:
@@ -468,14 +474,14 @@ class AuthManager(object):
The 'projectmanager' role is special and can't be added or removed.
@type user: User or uid
@param user: User to which to add role.
:type user: User or uid
:param user: User to which to add role.
@type role: str
@param role: Role to add.
:type role: str
:param role: Role to add.
@type project: Project or project_id
@param project: Project in which to add local role.
:type project: Project or project_id
:param project: Project in which to add local role.
"""
if role not in FLAGS.allowed_roles:
raise exception.UserRoleNotFound(role_id=role)
@@ -501,14 +507,14 @@ class AuthManager(object):
The 'projectmanager' role is special and can't be added or removed.
@type user: User or uid
@param user: User from which to remove role.
:type user: User or uid
:param user: User from which to remove role.
@type role: str
@param role: Role to remove.
:type role: str
:param role: Role to remove.
@type project: Project or project_id
@param project: Project in which to remove local role.
:type project: Project or project_id
:param project: Project in which to remove local role.
"""
uid = User.safe_id(user)
pid = Project.safe_id(project)
@@ -563,23 +569,23 @@ class AuthManager(object):
member_users=None):
"""Create a project
@type name: str
@param name: Name of the project to create. The name will also be
:type name: str
:param name: Name of the project to create. The name will also be
used as the project id.
@type manager_user: User or uid
@param manager_user: This user will be the project manager.
:type manager_user: User or uid
:param manager_user: This user will be the project manager.
@type description: str
@param project: Description of the project. If no description is
:type description: str
:param project: Description of the project. If no description is
specified, the name of the project will be used.
@type member_users: list of User or uid
@param: Initial project members. The project manager will always be
:type member_users: list of User or uid
:param: Initial project members. The project manager will always be
added as a member, even if he isn't specified in this list.
@rtype: Project
@return: The new project.
:rtype: Project
:return: The new project.
"""
if member_users:
member_users = [User.safe_id(u) for u in member_users]
@@ -597,14 +603,14 @@ class AuthManager(object):
def modify_project(self, project, manager_user=None, description=None):
"""Modify a project
@type name: Project or project_id
@param project: The project to modify.
:type name: Project or project_id
:param project: The project to modify.
@type manager_user: User or uid
@param manager_user: This user will be the new project manager.
:type manager_user: User or uid
:param manager_user: This user will be the new project manager.
@type description: str
@param project: This will be the new description of the project.
:type description: str
:param project: This will be the new description of the project.
"""
LOG.audit(_("modifying project %s"), Project.safe_id(project))
@@ -648,11 +654,11 @@ class AuthManager(object):
def get_project_vpn_data(project):
"""Gets vpn ip and port for project
@type project: Project or project_id
@param project: Project from which to get associated vpn data
:type project: Project or project_id
:param project: Project from which to get associated vpn data
@rvalue: tuple of (str, str)
@return: A tuple containing (ip, port) or None, None if vpn has
:rvalue: tuple of (str, str)
:return: A tuple containing (ip, port) or None, None if vpn has
not been allocated for user.
"""
@@ -699,24 +705,24 @@ class AuthManager(object):
def create_user(self, name, access=None, secret=None, admin=False):
"""Creates a user
@type name: str
@param name: Name of the user to create.
:type name: str
:param name: Name of the user to create.
@type access: str
@param access: Access Key (defaults to a random uuid)
:type access: str
:param access: Access Key (defaults to a random uuid)
@type secret: str
@param secret: Secret Key (defaults to a random uuid)
:type secret: str
:param secret: Secret Key (defaults to a random uuid)
@type admin: bool
@param admin: Whether to set the admin flag. The admin flag gives
:type admin: bool
:param admin: Whether to set the admin flag. The admin flag gives
superuser status regardless of roles specified for the user.
@type create_project: bool
@param: Whether to create a project for the user with the same name.
:type create_project: bool
:param: Whether to create a project for the user with the same name.
@rtype: User
@return: The new user.
:rtype: User
:return: The new user.
"""
if access is None:
access = str(uuid.uuid4())

37
nova/common/policy.py
View File

@@ -49,26 +49,40 @@ def enforce(match_list, target_dict, credentials_dict):
"""Enforces authorization of some rules against credentials.
:param match_list: nested tuples of data to match against
The basic brain supports three types of match lists:
1) rules
looks like: ('rule:compute:get_instance',)
looks like: ``('rule:compute:get_instance',)``
Retrieves the named rule from the rules dict and recursively
checks against the contents of the rule.
2) roles
looks like: ('role:compute:admin',)
looks like: ``('role:compute:admin',)``
Matches if the specified role is in credentials_dict['roles'].
3) generic
('tenant_id:%(tenant_id)s',)
looks like: ``('tenant_id:%(tenant_id)s',)``
Substitutes values from the target dict into the match using
the % operator and matches them against the creds dict.
Combining rules:
The brain returns True if any of the outer tuple of rules match
and also True if all of the inner tuples match. You can use this to
perform simple boolean logic. For example, the following rule would
return True if the creds contain the role 'admin' OR the if the
tenant_id matches the target dict AND the the creds contains the
role 'compute_sysadmin':
The brain returns True if any of the outer tuple of rules
match and also True if all of the inner tuples match. You
can use this to perform simple boolean logic. For
example, the following rule would return True if the creds
contain the role 'admin' OR the if the tenant_id matches
the target dict AND the the creds contains the role
'compute_sysadmin':
::
{
"rule:combined": (
@@ -77,21 +91,22 @@ def enforce(match_list, target_dict, credentials_dict):
)
}
Note that rule and role are reserved words in the credentials match, so
you can't match against properties with those names. Custom brains may
also add new reserved words. For example, the HttpBrain adds http as a
reserved word.
:param target_dict: dict of object properties
Target dicts contain as much information as we can about the object being
operated on.
:param credentials_dict: dict of actor properties
Credentials dicts contain as much information as we can about the user
performing the action.
:raises NotAuthorized if the check fails
:raises NotAuthorized: if the check fails
"""
global _BRAIN

2
nova/compat/flagfile.py
View File

@@ -169,7 +169,7 @@ def handle_flagfiles(args, tempdir=None):
def handle_flagfiles_managed(args):
'''A context manager for handle_flagfiles() which removes temp files.
For use with the 'with' statement, i.e.
For use with the 'with' statement, i.e.::
with handle_flagfiles_managed(args) as args:
# Do stuff

24
nova/notifier/api.py
View File

@@ -79,28 +79,28 @@ def publisher_id(service, host=None):
def notify(publisher_id, event_type, priority, payload):
"""
Sends a notification using the specified driver
"""Sends a notification using the specified driver
Notify parameters:
publisher_id - the source worker_type.host of the message
event_type - the literal type of event (ex. Instance Creation)
priority - patterned after the enumeration of Python logging levels in
the set (DEBUG, WARN, INFO, ERROR, CRITICAL)
payload - A python dictionary of attributes
:param publisher_id: the source worker_type.host of the message
:param event_type: the literal type of event (ex. Instance Creation)
:param priority: patterned after the enumeration of Python logging
levels in the set (DEBUG, WARN, INFO, ERROR, CRITICAL)
:param payload: A python dictionary of attributes
Outgoing message format includes the above parameters, and appends the
following:
message_id - a UUID representing the id for this notification
timestamp - the GMT timestamp the notification was sent at
message_id
a UUID representing the id for this notification
timestamp
the GMT timestamp the notification was sent at
The composite message will be constructed as a dictionary of the above
attributes, which will then be sent via the transport mechanism defined
by the driver.
Message example:
Message example::
{'message_id': str(uuid.uuid4()),
'publisher_id': 'compute.host1',

15
nova/scheduler/least_cost.py
View File

@@ -79,16 +79,19 @@ def compute_fill_first_cost_fn(host_state, weighing_properties):
def weighted_sum(weighted_fns, host_states, weighing_properties):
"""Use the weighted-sum method to compute a score for an array of objects.
Normalize the results of the objective-functions so that the weights are
meaningful regardless of objective-function's range.
host_list - [(host, HostInfo()), ...]
weighted_fns - list of weights and functions like:
[(weight, objective-functions), ...]
weighing_properties is an arbitrary dict of values that can influence
weights.
:param host_list: ``[(host, HostInfo()), ...]``
:param weighted_fns: list of weights and functions like::
Returns a single WeightedHost object which represents the best
[(weight, objective-functions), ...]
:param weighing_properties: an arbitrary dict of values that can
influence weights.
:returns: a single WeightedHost object which represents the best
candidate.
"""

6
nova/vsa/api.py
View File

@@ -19,6 +19,7 @@
Handles all requests relating to Virtual Storage Arrays (VSAs).
Experimental code. Requires special VSA image.
For assistance and guidelines pls contact
Zadara Storage Inc & Openstack community
"""
@@ -143,9 +144,8 @@ class API(base.Base):
def create(self, context, display_name='', display_description='',
vc_count=1, instance_type=None, image_name=None,
availability_zone=None, storage=[], shared=None):
"""
Provision VSA instance with corresponding compute instances
and associated volumes
"""Provision VSA instance with compute instances and volumes
:param storage: List of dictionaries with following keys:
disk_name, num_disks, size
:param shared: Specifies if storage is dedicated or shared.