From ecc0e7a9de9b0384c485b2dff60ef3acfa371fdc Mon Sep 17 00:00:00 2001 From: Sergey Skripnick Date: Wed, 15 May 2013 10:48:33 +0300 Subject: [PATCH] Docstrings formatted according to pep257 Bug #1020184 quantum/* Change-Id: I771e0f0d6121b7c03cecd82583e9a6c1915f891d --- quantum/context.py | 3 +- quantum/manager.py | 3 +- quantum/quantum_plugin_base_v2.py | 81 +++++++++++++++++-------------- quantum/quota.py | 12 ++--- quantum/rootwrap/wrapper.py | 8 ++- quantum/wsgi.py | 57 ++++++++++------------ 6 files changed, 83 insertions(+), 81 deletions(-) diff --git a/quantum/context.py b/quantum/context.py index 01c1d377b..fa6166dd9 100644 --- a/quantum/context.py +++ b/quantum/context.py @@ -39,7 +39,8 @@ class ContextBase(common_context.RequestContext): def __init__(self, user_id, tenant_id, is_admin=None, read_deleted="no", roles=None, timestamp=None, **kwargs): - """ + """Object initialization. + :param read_deleted: 'no' indicates deleted records are hidden, 'yes' indicates deleted records are visible, 'only' indicates that *only* deleted records are visible. diff --git a/quantum/manager.py b/quantum/manager.py index d014b7dd3..5573ab19e 100644 --- a/quantum/manager.py +++ b/quantum/manager.py @@ -60,7 +60,8 @@ class Manager(periodic_task.PeriodicTasks): class QuantumManager(object): - """ + """Quantum's Manager class. + Quantum's Manager class is responsible for parsing a config file and instantiating the correct plugin that concretely implement quantum_plugin_base class. diff --git a/quantum/quantum_plugin_base_v2.py b/quantum/quantum_plugin_base_v2.py index 406d248d8..35bbcf997 100644 --- a/quantum/quantum_plugin_base_v2.py +++ b/quantum/quantum_plugin_base_v2.py @@ -32,7 +32,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def create_subnet(self, context, subnet): - """ + """Create a subnet. + Create a subnet, which represents a range of IP addresses that can be allocated to devices : param context: quantum api request context @@ -44,8 +45,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def update_subnet(self, context, id, subnet): - """ - Update values of a subnet. + """Update values of a subnet. + : param context: quantum api request context : param id: UUID representing the subnet to update. : param subnet: dictionary with keys indicating fields to update. @@ -57,8 +58,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def get_subnet(self, context, id, fields=None): - """ - Retrieve a subnet. + """Retrieve a subnet. + : param context: quantum api request context : param id: UUID representing the subnet to fetch. : param fields: a list of strings that are valid keys in a @@ -71,8 +72,9 @@ class QuantumPluginBaseV2(object): @abstractmethod def get_subnets(self, context, filters=None, fields=None, sorts=None, limit=None, marker=None, page_reverse=False): - """ - Retrieve a list of subnets. The contents of the list depends on + """Retrieve a list of subnets. + + The contents of the list depends on the identity of the user making the request (as indicated by the context) as well as any filters. : param context: quantum api request context @@ -91,8 +93,9 @@ class QuantumPluginBaseV2(object): pass def get_subnets_count(self, context, filters=None): - """ - Return the number of subnets. The result depends on the identity of + """Return the number of subnets. + + The result depends on the identity of the user making the request (as indicated by the context) as well as any filters. : param context: quantum api request context @@ -111,8 +114,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def delete_subnet(self, context, id): - """ - Delete a subnet. + """Delete a subnet. + : param context: quantum api request context : param id: UUID representing the subnet to delete. """ @@ -120,7 +123,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def create_network(self, context, network): - """ + """Create a network. + Create a network, which represents an L2 network segment which can have a set of subnets and ports associated with it. : param context: quantum api request context @@ -132,8 +136,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def update_network(self, context, id, network): - """ - Update values of a network. + """Update values of a network. + : param context: quantum api request context : param id: UUID representing the network to update. : param network: dictionary with keys indicating fields to update. @@ -145,8 +149,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def get_network(self, context, id, fields=None): - """ - Retrieve a network. + """Retrieve a network. + : param context: quantum api request context : param id: UUID representing the network to fetch. : param fields: a list of strings that are valid keys in a @@ -159,8 +163,9 @@ class QuantumPluginBaseV2(object): @abstractmethod def get_networks(self, context, filters=None, fields=None, sorts=None, limit=None, marker=None, page_reverse=False): - """ - Retrieve a list of networks. The contents of the list depends on + """Retrieve a list of networks. + + The contents of the list depends on the identity of the user making the request (as indicated by the context) as well as any filters. : param context: quantum api request context @@ -179,8 +184,9 @@ class QuantumPluginBaseV2(object): pass def get_networks_count(self, context, filters=None): - """ - Return the number of networks. The result depends on the identity + """Return the number of networks. + + The result depends on the identity of the user making the request (as indicated by the context) as well as any filters. : param context: quantum api request context @@ -199,8 +205,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def delete_network(self, context, id): - """ - Delete a network. + """Delete a network. + : param context: quantum api request context : param id: UUID representing the network to delete. """ @@ -208,7 +214,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def create_port(self, context, port): - """ + """Create a port. + Create a port, which is a connection point of a device (e.g., a VM NIC) to attach to a L2 Quantum network. : param context: quantum api request context @@ -220,8 +227,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def update_port(self, context, id, port): - """ - Update values of a port. + """Update values of a port. + : param context: quantum api request context : param id: UUID representing the port to update. : param port: dictionary with keys indicating fields to update. @@ -233,8 +240,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def get_port(self, context, id, fields=None): - """ - Retrieve a port. + """Retrieve a port. + : param context: quantum api request context : param id: UUID representing the port to fetch. : param fields: a list of strings that are valid keys in a @@ -247,10 +254,10 @@ class QuantumPluginBaseV2(object): @abstractmethod def get_ports(self, context, filters=None, fields=None, sorts=None, limit=None, marker=None, page_reverse=False): - """ - Retrieve a list of ports. The contents of the list depends on - the identity of the user making the request (as indicated by the - context) as well as any filters. + """Retrieve a list of ports. + + The contents of the list depends on the identity of the user making + the request (as indicated by the context) as well as any filters. : param context: quantum api request context : param filters: a dictionary with keys that are valid keys for a port as listed in the RESOURCE_ATTRIBUTE_MAP object @@ -267,10 +274,10 @@ class QuantumPluginBaseV2(object): pass def get_ports_count(self, context, filters=None): - """ - Return the number of ports. The result depends on the identity of - the user making the request (as indicated by the context) as well as - any filters. + """Return the number of ports. + + The result depends on the identity of the user making the request + (as indicated by the context) as well as any filters. : param context: quantum api request context : param filters: a dictionary with keys that are valid keys for a network as listed in the RESOURCE_ATTRIBUTE_MAP object @@ -287,8 +294,8 @@ class QuantumPluginBaseV2(object): @abstractmethod def delete_port(self, context, id): - """ - Delete a port. + """Delete a port. + : param context: quantum api request context : param id: UUID representing the port to delete. """ diff --git a/quantum/quota.py b/quantum/quota.py index 3d229eaff..5896ec401 100644 --- a/quantum/quota.py +++ b/quantum/quota.py @@ -54,14 +54,16 @@ cfg.CONF.register_opts(quota_opts, 'QUOTAS') class ConfDriver(object): - """ + """Configuration driver. + Driver to perform necessary checks to enforce quotas and obtain quota information. The default driver utilizes the default values in quantum.conf. """ def _get_quotas(self, context, resources, keys): - """ + """Get quotas. + A helper method which retrieves the quotas for the specific resources identified by keys, and which apply to the current context. @@ -150,8 +152,7 @@ class BaseResource(object): """Describe a single resource for quota checking.""" def __init__(self, name, flag): - """ - Initializes a Resource. + """Initializes a resource. :param name: The name of the resource, i.e., "instances". :param flag: The name of the flag or configuration option @@ -169,8 +170,7 @@ class BaseResource(object): class CountableResource(BaseResource): - """Describe a resource where the counts are determined by a function. - """ + """Describe a resource where the counts are determined by a function.""" def __init__(self, name, count, flag=None): """Initializes a CountableResource. diff --git a/quantum/rootwrap/wrapper.py b/quantum/rootwrap/wrapper.py index c7d0999dd..ebf10cf3b 100644 --- a/quantum/rootwrap/wrapper.py +++ b/quantum/rootwrap/wrapper.py @@ -31,10 +31,7 @@ class NoFilterMatched(Exception): class FilterMatchNotExecutable(Exception): - """ - This exception is raised when a filter matched but no executable was - found. - """ + """Raised when a filter matched but no executable was found.""" def __init__(self, match=None, **kwargs): self.match = match @@ -122,7 +119,8 @@ def load_filters(filters_path): def match_filter(filter_list, userargs, exec_dirs=[]): - """ + """Return first matched filter from command filters. + Checks user command and arguments through command filters and returns the first matching filter. Raises NoFilterMatched if no filter matched. diff --git a/quantum/wsgi.py b/quantum/wsgi.py index b68eb984f..39c82b77c 100644 --- a/quantum/wsgi.py +++ b/quantum/wsgi.py @@ -202,11 +202,11 @@ class Server(object): class Middleware(object): - """ - Base WSGI middleware wrapper. These classes require an application to be - initialized that will be called next. By default the middleware will - simply call its wrapped app, or you can override __call__ to customize its - behavior. + """Base WSGI middleware wrapper. + + These classes require an application to be initialized that will be called + next. By default the middleware will simply call its wrapped app, or you + can override __call__ to customize its behavior. """ @classmethod @@ -240,8 +240,7 @@ class Middleware(object): self.application = application def process_request(self, req): - """ - Called on each request. + """Called on each request. If this returns None, the next application down the stack will be executed. If it returns a response then that response will be returned @@ -342,7 +341,8 @@ class JSONDictSerializer(DictSerializer): class XMLDictSerializer(DictSerializer): def __init__(self, metadata=None, xmlns=None): - """ + """Object initialization. + :param metadata: information needed to deserialize xml into a dictionary. :param xmlns: XML namespace to include with serialized xml @@ -356,7 +356,8 @@ class XMLDictSerializer(DictSerializer): self.xmlns = xmlns def default(self, data): - """ + """Return data as XML string. + :param data: expect data to contain a single key as XML root, or contain another '*_links' key as atom links. Other case will use 'VIRTUAL_ROOT_KEY' as XML root. @@ -571,7 +572,8 @@ class ProtectedXMLParser(etree.XMLParser): class XMLDeserializer(TextDeserializer): def __init__(self, metadata=None): - """ + """Object initialization. + :param metadata: information needed to deserialize xml into a dictionary. """ @@ -865,7 +867,8 @@ class Application(object): class Debug(Middleware): - """ + """Middleware for debugging. + Helper class that can be inserted into any WSGI application chain to get information about the request and response. """ @@ -889,10 +892,7 @@ class Debug(Middleware): @staticmethod def print_generator(app_iter): - """ - Iterator that prints the contents of a wrapper string iterator - when iterated. - """ + """Print contents of a wrapper string iterator when iterated.""" print ("*" * 40) + " BODY" for part in app_iter: sys.stdout.write(part) @@ -902,20 +902,15 @@ class Debug(Middleware): class Router(object): - """ - WSGI middleware that maps incoming requests to WSGI apps. - """ + """WSGI middleware that maps incoming requests to WSGI apps.""" @classmethod def factory(cls, global_config, **local_config): - """ - Returns an instance of the WSGI Router class - """ + """Return an instance of the WSGI Router class.""" return cls() def __init__(self, mapper): - """ - Create a router for the given routes.Mapper. + """Create a router for the given routes.Mapper. Each route in `mapper` must specify a 'controller', which is a WSGI app to call. You'll probably want to specify an 'action' as @@ -943,8 +938,8 @@ class Router(object): @webob.dec.wsgify def __call__(self, req): - """ - Route the incoming request to a controller based on self.map. + """Route the incoming request to a controller based on self.map. + If no match, return a 404. """ return self._router @@ -952,9 +947,10 @@ class Router(object): @staticmethod @webob.dec.wsgify def _dispatch(req): - """ + """Dispatch a Request. + Called by self._router after matching the incoming request to a route - and putting the information into req.environ. Either returns 404 + and putting the information into req.environ. Either returns 404 or the routed WSGI app's response. """ match = req.environ['wsgiorg.routing_args'][1] @@ -979,7 +975,8 @@ class Resource(Application): def __init__(self, controller, fault_body_function, deserializer=None, serializer=None): - """ + """Object initialization. + :param controller: object that implement methods created by routes lib :param deserializer: object that can serialize the output of a controller into a webob response @@ -1118,9 +1115,7 @@ class Controller(object): @webob.dec.wsgify(RequestClass=Request) def __call__(self, req): - """ - Call the method specified in req.environ by RoutesMiddleware. - """ + """Call the method specified in req.environ by RoutesMiddleware.""" arg_dict = req.environ['wsgiorg.routing_args'][1] action = arg_dict['action'] method = getattr(self, action)