From f9b06e89375ca54e04890cc0ac26a80c320e777e Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Wed, 5 Jul 2017 08:52:27 +0900 Subject: [PATCH] Enable module reference Also fixes sphinx warnings in existing docstrings. Change-Id: Iccccd782ff8b80a3fd2764e7ef9cc3dde46e32ee --- .gitignore | 1 + doc/source/index.rst | 4 + doc/source/reference/index.rst | 5 +- neutron_lib/api/attributes.py | 26 ++--- neutron_lib/api/converters.py | 35 +++--- neutron_lib/api/validators/__init__.py | 131 +++++++++++----------- neutron_lib/api/validators/dns.py | 6 +- neutron_lib/callbacks/events.py | 4 +- neutron_lib/callbacks/exceptions.py | 4 +- neutron_lib/callbacks/manager.py | 12 +- neutron_lib/db/utils.py | 4 +- neutron_lib/exceptions/__init__.py | 14 +-- neutron_lib/hacking/checks.py | 32 +++--- neutron_lib/hacking/translation_checks.py | 12 +- neutron_lib/plugins/ml2/api.py | 44 ++++---- neutron_lib/utils/file.py | 2 +- neutron_lib/utils/helpers.py | 8 +- neutron_lib/utils/host.py | 2 +- neutron_lib/utils/net.py | 2 +- neutron_lib/utils/runtime.py | 2 +- neutron_lib/worker.py | 3 + setup.cfg | 10 ++ 22 files changed, 191 insertions(+), 172 deletions(-) diff --git a/.gitignore b/.gitignore index 1e6c1af..127cafc 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ cover/ covhtml/ dist/ doc/build +doc/source/reference/modules/ *.DS_Store *.pyc neutron_lib.egg-info/ diff --git a/doc/source/index.rst b/doc/source/index.rst index 652bb05..1ea28fb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -45,4 +45,8 @@ Enjoy! install/index user/index contributor/index + +.. toctree:: + :maxdepth: 1 + reference/index diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 93aa723..9d1af1c 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -25,10 +25,9 @@ Module Reference .. toctree:: :maxdepth: 1 + :glob: -.. todo:: - - Add in all the big modules as automodule indexes. + modules/* * :ref:`genindex` * :ref:`search` diff --git a/neutron_lib/api/attributes.py b/neutron_lib/api/attributes.py index 3576827..6d33fb1 100644 --- a/neutron_lib/api/attributes.py +++ b/neutron_lib/api/attributes.py @@ -40,10 +40,10 @@ def populate_project_info(attributes): If neither are present then attributes is not updated. :param attributes: A dictionary of resource/API attributes - or API request/response dict. + or API request/response dict. :returns: attributes (updated with project_id if applicable). :raises: HTTPBadRequest if the attributes project_id and tenant_id - don't match. + don't match. """ if 'tenant_id' in attributes and 'project_id' not in attributes: attributes['project_id'] = attributes['tenant_id'] @@ -70,9 +70,9 @@ class AttributeInfo(object): """Create a new instance that wraps the given resource attributes. :param resource_attrs: The resource's attributes that can be any - of the following types: an instance of AttributeInfo, an API definition - that contains a RESOURCE_ATTRIBUTE_MAP attribute or a dict of - attributes for the resource. + of the following types: an instance of AttributeInfo, an API + definition that contains a RESOURCE_ATTRIBUTE_MAP attribute or + a dict of attributes for the resource. """ if isinstance(resource_attrs, AttributeInfo): resource_attrs = resource_attrs.attributes @@ -102,11 +102,11 @@ class AttributeInfo(object): :param res_dict: The resource attributes from the request. :param exc_cls: Exception to be raised on error that must take - a single error message as it's only constructor arg. + a single error message as it's only constructor arg. :param check_allow_post: Raises an exception if a non-POST-able - attribute is specified. + attribute is specified. :raises: exc_cls If check_allow_post is True and this instance of - ResourceAttributes doesn't support POST. + ResourceAttributes doesn't support POST. """ for attr, attr_vals in self.attributes.items(): if attr_vals['allow_post']: @@ -128,9 +128,9 @@ class AttributeInfo(object): :param res_dict: The resource attributes from the request. :param exc_cls: Exception to be raised on error that must take - a single error message as it's only constructor arg. + a single error message as it's only constructor arg. :raises: exc_cls If any errors occur converting/validating the - res_dict. + res_dict. """ for attr, attr_vals in self.attributes.items(): if (attr not in res_dict or @@ -165,7 +165,7 @@ class AttributeInfo(object): :param attr_info: The attribute map for the resource. :param is_create: Is this a create request? :raises: HTTPBadRequest If neither the project_id nor tenant_id - are specified in the res_dict. + are specified in the res_dict. """ populate_project_info(res_dict) @@ -190,9 +190,9 @@ class AttributeInfo(object): attrs_to_verify before calling this method. :param attrs_to_verify: The attributes to verify against this - resource attributes. + resource attributes. :raises: HTTPBadRequest: If attrs_to_verify contains any unrecognized - for this resource attributes instance. + for this resource attributes instance. """ extra_keys = set(attrs_to_verify.keys()) - set(self.attributes.keys()) if extra_keys: diff --git a/neutron_lib/api/converters.py b/neutron_lib/api/converters.py index cc433d8..af39291 100644 --- a/neutron_lib/api/converters.py +++ b/neutron_lib/api/converters.py @@ -24,8 +24,8 @@ def convert_to_boolean(data): """Convert a data value into a python bool. :param data: The data value to convert to a python bool. This function - supports string types, bools, and ints for conversion of representation - to python bool. + supports string types, bools, and ints for conversion of representation + to python bool. :returns: The bool value of 'data' if it can be coerced. :raises InvalidInput: If the value can't be coerced to a python bool. """ @@ -41,7 +41,7 @@ def convert_to_boolean_if_not_none(data): :param data: The data value to convert. :returns: The 'data' returned from convert_to_boolean() if 'data' is not - None. None is returned if data is None. + None. None is returned if data is None. """ if data is not None: return convert_to_boolean(data) @@ -51,7 +51,7 @@ def convert_to_int(data): """Convert a data value to a python int. :param data: The data value to convert to a python int via python's - built-in int() constructor. + built-in int() constructor. :returns: The int value of the data. :raises InvalidInput: If the value can't be converted to an int. """ @@ -67,7 +67,7 @@ def convert_to_int_if_not_none(data): :param data: The data value to convert. :returns: The 'data' returned from convert_to_int() if 'data' is not None. - None is returned if data is None. + None is returned if data is None. """ if data is not None: return convert_to_int(data) @@ -79,10 +79,10 @@ def convert_to_positive_float_or_none(val): :param val: The value to convert to a positive python float. :returns: The value as a python float. If the val is None, None is - returned. + returned. :raises ValueError, InvalidInput: A ValueError is raised if the 'val' - is a float, but is negative. InvalidInput is raised if 'val' can't be - converted to a python float. + is a float, but is negative. InvalidInput is raised if 'val' can't be + converted to a python float. """ # NOTE(salv-orlando): This conversion function is currently used by # a vendor specific extension only at the moment It is used for @@ -119,7 +119,7 @@ def convert_kvp_list_to_dict(kvp_list): """Convert a list of 'key=value' strings to a dict. :param kvp_list: A list of key value pair strings. For more info on the - format see; convert_kvp_str_to_list(). + format see; convert_kvp_str_to_list(). :returns: A dict who's key value pairs are populated by parsing 'kvp_list'. :raises InvalidInput: If any of the key value strings are malformed. """ @@ -157,7 +157,7 @@ def convert_to_list(data): :param data: The value to convert. :return: A new list wrapped around 'data' whereupon the list is empty - if 'data' is None. + if 'data' is None. """ if data is None: return [] @@ -175,6 +175,7 @@ def convert_ip_to_canonical_format(value): - 'value' if 'value' is IPv4 address, - 'value' if 'value' is not an IP Address - canonical IPv6 address if 'value' is IPv6 address. + """ try: ip = netaddr.IPAddress(value) @@ -191,8 +192,8 @@ def convert_cidr_to_canonical_format(value): :param value: The CIDR which needs to be checked. :returns: - 'value' if 'value' is CIDR with IPv4 address, - CIDR with canonical IPv6 address if 'value' is IPv6 CIDR. - :raises: - InvalidInput if 'value' is None, not a valid CIDR or - invalid IP Format. + :raises: InvalidInput if 'value' is None, not a valid CIDR or + invalid IP Format. """ error_message = _("%s is not in a CIDR format") % value try: @@ -210,7 +211,7 @@ def convert_string_to_case_insensitive(data): :param data: The value to convert. :return: The lower-cased string representation of the value, or None is - 'data' is None. + 'data' is None. :raises InvalidInput: If the value is not a string. """ try: @@ -228,11 +229,11 @@ def convert_to_protocol(data): :param data: The value to verify is an IP protocol. :returns: If data is an int between 0 and 255 or None, return that; if - data is a string then return it lower-cased if it matches one of the - allowed protocol names. + data is a string then return it lower-cased if it matches one of the + allowed protocol names. :raises exceptions.InvalidInput: If data is an int < 0, an - int > 255, or a string that does not match one of the allowed protocol - names. + int > 255, or a string that does not match one of the allowed protocol + names. """ if data is None: diff --git a/neutron_lib/api/validators/__init__.py b/neutron_lib/api/validators/__init__.py index fabc21d..1a4086b 100644 --- a/neutron_lib/api/validators/__init__.py +++ b/neutron_lib/api/validators/__init__.py @@ -44,7 +44,7 @@ def _verify_dict_keys(expected_keys, target_dict, strict=True): :param target_dict: The dictionary which should be verified. :param strict: Specifies whether additional keys are allowed to be present. :returns: None if the expected keys are found. Otherwise a human readable - message indicating why the validation failed. + message indicating why the validation failed. """ if not isinstance(target_dict, dict): msg = (_("Invalid input. '%(target_dict)s' must be a dictionary " @@ -72,9 +72,9 @@ def _collect_duplicates(data_list): """Collects duplicate items from a list and returns them. :param data_list: A list of items to check for duplicates. The list may - include dict items. + include dict items. :returns: A set of items that are duplicates in data_list. If no - duplicates are found, the returned set is empty. + duplicates are found, the returned set is empty. """ seen = [] dups = set() @@ -91,7 +91,7 @@ def is_attr_set(attribute): :param attribute: The attribute value to check. :returns: False if the attribute value is None or ATTR_NOT_SPECIFIED, - otherwise True. + otherwise True. """ return not (attribute is None or attribute is constants.ATTR_NOT_SPECIFIED) @@ -167,7 +167,8 @@ def validate_not_empty_string_or_none(data, max_len=None): :param data: The data to validate. :param max_len: An optional cap on the str length to validate. :returns: None if the data string is not None and is not an empty string, - otherwise a human readable message as to why the string data is invalid. + otherwise a human readable message as to why the string data is + invalid. """ if data is not None: return validate_not_empty_string(data, max_len=max_len) @@ -179,7 +180,7 @@ def validate_not_empty_string(data, max_len=None): :param data: The data to validate. :param max_len: An optional cap on the length of the string data. :returns: None if the data is non-empty/non-blank, otherwise a human - readable string message indicating why validation failed. + readable string message indicating why validation failed. """ msg = validate_string(data, max_len=max_len) if msg: @@ -196,7 +197,7 @@ def validate_string_or_none(data, max_len=None): :param data: The data to validate. :param max_len: An optional cap on the length of the string data. :returns: None if the data is None or a valid string, otherwise a human - readable message indicating why validation failed. + readable message indicating why validation failed. """ if data is not None: return validate_string(data, max_len=max_len) @@ -208,8 +209,8 @@ def validate_string(data, max_len=None): :param data: The data to validate. :param max_len: An optional cap on the length of the string. :returns: None if the data is a valid string type and (optionally) within - the given max_len. Otherwise a human readable message indicating why - the data is invalid. + the given max_len. Otherwise a human readable message indicating why + the data is invalid. """ if not isinstance(data, six.string_types): msg = _("'%s' is not a valid string") % data @@ -234,7 +235,7 @@ def validate_list_of_unique_strings(data, max_len=None): :param data: The data to validate. :param max_len: An optional cap on the length of the string. :returns: None if the data is a list of non-empty/non-blank strings, - otherwise a human readable message indicating why validation failed. + otherwise a human readable message indicating why validation failed. """ return _validate_list_of_unique_strings(data, max_len=max_len) @@ -245,7 +246,7 @@ def validate_boolean(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :return: None if the value can be converted to a bool, otherwise a - human readable message indicating why data is invalid. + human readable message indicating why data is invalid. """ try: strutils.bool_from_string(data, strict=True) @@ -264,7 +265,7 @@ def validate_integer(data, valid_values=None): :param data: The string or number to validate as integer. :param valid_values: values to limit the 'data' to. :returns: None if data is an integer, otherwise a human readable message - indicating why validation failed.. + indicating why validation failed.. """ if valid_values is not None: @@ -300,9 +301,9 @@ def validate_range(data, valid_values=None): :param data: The data to validate. :param valid_values: A list of 2 elements where element 0 is the min - value the int data can have and element 1 is the max. + value the int data can have and element 1 is the max. :returns: None if the data is a valid int in the given range, otherwise - a human readable message as to why validation failed. + a human readable message as to why validation failed. """ min_value = valid_values[0] @@ -329,7 +330,7 @@ def validate_no_whitespace(data): """Validates that input has no whitespace. :param data: The data to validate. Must be a python string type suitable - for searching via regex. + for searching via regex. :returns: The data itself. :raises InvalidInput: If the data contains whitespace. """ @@ -346,7 +347,7 @@ def validate_mac_address(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if the data is a valid MAC address, otherwise a human - readable message as to why validation failed. + readable message as to why validation failed. """ try: valid_mac = netaddr.valid_mac(validate_no_whitespace(data)) @@ -371,7 +372,7 @@ def validate_mac_address_or_none(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if the data is None or a valid MAC address, otherwise - a human readable message indicating why validation failed. + a human readable message indicating why validation failed. """ if data is not None: return validate_mac_address(data, valid_values) @@ -383,7 +384,7 @@ def validate_ip_address(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if data is an IP address, otherwise a human readable - message indicating why data isn't an IP address. + message indicating why data isn't an IP address. """ msg = None try: @@ -425,10 +426,10 @@ def _validate_any_key_spec(data, key_specs=None): :param data: The dict to validate. :param key_specs: An iterable collection of key spec dicts used to validate - data. + data. :returns: None if at least 1 of the key_specs matches data, otherwise - a message is returned indicating data could not be matched with any - of the key_specs. + a message is returned indicating data could not be matched with any + of the key_specs. """ for spec in key_specs: if validate_dict(data, spec) is None: @@ -443,10 +444,10 @@ def validate_any_key_specs_or_none(data, key_specs=None): :param data: The list of dicts to validate. :param key_specs: An iterable collection of key spec dicts that is used - to check each dict in data. + to check each dict in data. :returns: None. :raises InvalidInput: If any of the dicts in data do not match at least - 1 of the key_specs given. + 1 of the key_specs given. """ if data is None: return @@ -467,10 +468,10 @@ def validate_ip_pools(data, valid_values=None): In addition to this the IP addresses will also be validated. :param data: The data to validate. Must be a list-like structure of - IP pool dicts that each have a 'start' and 'end' key value. + IP pool dicts that each have a 'start' and 'end' key value. :param valid_values: Not used! :returns: None if data is a valid list of IP pools, otherwise a message - indicating why the data is invalid. + indicating why the data is invalid. """ if not isinstance(data, list): msg = _("Invalid data format for IP pool: '%s'") % data @@ -497,7 +498,7 @@ def validate_fixed_ips(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if data is a valid list of fixed IP dicts. Otherwise a - human readable message is returned indicating why validation failed. + human readable message is returned indicating why validation failed. """ if not isinstance(data, list): msg = _("Invalid data format for fixed IP: '%s'") % data @@ -534,7 +535,7 @@ def validate_nameservers(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if data is a list of valid IP addresses, otherwise - a human readable message is returned indicating why validation failed. + a human readable message is returned indicating why validation failed. """ if not hasattr(data, '__iter__'): msg = _("Invalid data format for nameserver: '%s'") % data @@ -561,11 +562,11 @@ def validate_hostroutes(data, valid_values=None): """Validate a list of unique host route dicts. :param data: The data to validate. To be valid it must be a list like - structure of host route dicts, each containing 'destination' and 'nexthop' - key values. + structure of host route dicts, each containing 'destination' and + 'nexthop' key values. :param valid_values: Not used! :returns: None if data is a valid list of unique host route dicts, - otherwise a human readable message indicating why validation failed. + otherwise a human readable message indicating why validation failed. """ if not isinstance(data, list): msg = _("Invalid data format for hostroute: '%s'") % data @@ -597,7 +598,7 @@ def validate_ip_address_or_none(data, valid_values=None): :param data: The data to validate. :param valid_values: An optional list of values data may take on. :return: None if data is None or a valid IP address, otherwise a - human readable message indicating why the data is invalid. + human readable message indicating why the data is invalid. """ if data is not None: return validate_ip_address(data, valid_values) @@ -609,8 +610,8 @@ def validate_ip_or_subnet_or_none(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :return: None if data is None or a valid IP address or a valid IP subnet, - otherwise a human readable message indicating why the data is neither an - IP address nor IP subnet. + otherwise a human readable message indicating why the data is neither + an IP address nor IP subnet. """ msg_ip = validate_ip_address_or_none(data) msg_subnet = validate_subnet_or_none(data) @@ -625,7 +626,7 @@ def validate_subnet(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if data is valid IP network address. Otherwise a human - readable message as to why data is invalid. + readable message as to why data is invalid. """ msg = None try: @@ -649,7 +650,7 @@ def validate_subnet_or_none(data, valid_values=None): :param data: The data to validate. :param valid_values: The optional list of values data may take on. :returns: None if data is None or a valid subnet, otherwise a human - readable message as to why data is invalid. + readable message as to why data is invalid. """ if data is not None: return validate_subnet(data, valid_values) @@ -666,7 +667,7 @@ def validate_subnet_list(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if data is a valid list of subnet dicts, otherwise a human - readable message as to why the data is invalid. + readable message as to why the data is invalid. """ return _validate_subnet_list(data, valid_values) @@ -676,9 +677,9 @@ def validate_regex(data, valid_values=None): :param data: The data to validate. :param valid_values: The regular expression to use with re.match on - the data. + the data. :returns: None if data contains matches for valid_values, otherwise a - human readable message as to why data is invalid. + human readable message as to why data is invalid. """ try: if re.match(valid_values, data): @@ -696,9 +697,9 @@ def validate_regex_or_none(data, valid_values=None): :param data: The data to validate. :param valid_values: The regular expression to use with re.match on - the data. + the data. :returns: None if data is None or contains matches for valid_values, - otherwise a human readable message as to why data is invalid. + otherwise a human readable message as to why data is invalid. """ if data is not None: return validate_regex(data, valid_values) @@ -709,9 +710,9 @@ def validate_list_of_regex_or_none(data, valid_values=None): :param data: A list of data to validate. :param valid_values: The regular expression to use with re.match on - each element of the data. + each element of the data. :returns: None if data is None or contains matches for valid_values, - otherwise a human readable message as to why data is invalid. + otherwise a human readable message as to why data is invalid. """ if data is not None: return _validate_list_of_items(validate_regex, data, valid_values) @@ -723,7 +724,7 @@ def validate_subnetpool_id(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if data is a valid subnet pool ID, otherwise a - human readable message as to why it's invalid. + human readable message as to why it's invalid. """ if data != constants.IPV6_PD_POOL_ID: return validate_uuid_or_none(data, valid_values) @@ -735,7 +736,7 @@ def validate_subnetpool_id_or_none(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if data is a valid subnet pool ID or None, otherwise a - human readable message as to why it's invalid. + human readable message as to why it's invalid. """ if data is not None: return validate_subnetpool_id(data, valid_values) @@ -747,7 +748,7 @@ def validate_uuid(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if data is UUID like in form, otherwise a human readable - message indicating why data is invalid. + message indicating why data is invalid. """ if not uuidutils.is_uuid_like(data): msg = _("'%s' is not a valid UUID") % data @@ -761,7 +762,7 @@ def validate_uuid_or_none(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if data is UUID like in form or None, otherwise a human - readable message indicating why data is invalid. + readable message indicating why data is invalid. """ if data is not None: return validate_uuid(data) @@ -778,7 +779,7 @@ def validate_uuid_list(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if data is an iterable that contains valid UUID values, - otherwise a message is returned indicating why validation failed. + otherwise a message is returned indicating why validation failed. """ return _validate_uuid_list(data, valid_values) @@ -813,10 +814,10 @@ def validate_dict(data, key_specs=None): :param data: The data to validate. :param key_specs: The optional list of keys that must be contained in - data. + data. :returns: None if data is a dict and (optionally) contains only key_specs. - Otherwise a human readable message is returned indicating why data is not - valid. + Otherwise a human readable message is returned indicating why data is + not valid. """ if not isinstance(data, dict): msg = _("'%s' is not a dictionary") % data @@ -856,10 +857,10 @@ def validate_dict_or_none(data, key_specs=None): :param data: The data to validate. :param key_specs: The optional list of keys that must be contained in - data. + data. :returns: None if data is None or a dict that (optionally) contains - all key_specs. Otherwise a human readable message is returned indicating - why data is not valid. + all key_specs. Otherwise a human readable message is returned + indicating why data is not valid. """ if data is not None: return validate_dict(data, key_specs) @@ -870,10 +871,10 @@ def validate_dict_or_empty(data, key_specs=None): :param data: The data to validate. :param key_specs: The optional list of keys that must be contained in - data. + data. :returns: None if data is {} or a dict (optionally) containing - only key_specs. Otherwise a human readable message is returned indicating - why data is not valid. + only key_specs. Otherwise a human readable message is returned + indicating why data is not valid. """ if data != {}: return validate_dict(data, key_specs) @@ -884,10 +885,10 @@ def validate_dict_or_nodata(data, key_specs=None): :param data: The data to validate. May be None. :param key_specs: The optional list of keys that must be contained in - data. + data. :returns: None if no data/empty dict or a dict and (optionally) contains - all key_specs. Otherwise a human readable message is returned indicating - why data is not valid. + all key_specs. Otherwise a human readable message is returned + indicating why data is not valid. """ if data: return validate_dict(data, key_specs) @@ -899,7 +900,7 @@ def validate_non_negative(data, valid_values=None): :param data: The data to validate :param valid_values: Not used! :returns: None if data is an int and is positive, otherwise a human - readable message as to why data is invalid. + readable message as to why data is invalid. """ try: data = int(data) @@ -920,8 +921,8 @@ def validate_port_range_or_none(data, valid_values=None): :param data: The data to validate :param valid_values: Not used! :returns: None if data is an int between 0 and 65535, or two ints between 0 - and 65535 with a colon between them, otherwise a human readable message as - to why data is invalid. + and 65535 with a colon between them, otherwise a human readable message + as to why data is invalid. """ if data is None: return @@ -953,8 +954,8 @@ def validate_subports(data, valid_values=None): :param data: The data to validate. :param valid_values: Not used! :returns: None if data is a list of subport dicts each with a unique valid - port_id, segmentation_id and segmentation_type. Otherwise a human readable - message is returned indicating why the data is invalid. + port_id, segmentation_id and segmentation_type. Otherwise a human + readable message is returned indicating why the data is invalid. """ if not isinstance(data, list): msg = _("Invalid data format for subports: '%s' is not a list") % data @@ -1060,7 +1061,7 @@ def get_validator(validation_type, default=None): :param validation_type: The type to retrieve the validator for. :param default: A default value to return if the validator is - not registered. + not registered. :return: The validator if registered, otherwise the default value. """ return validators.get(_to_validation_type(validation_type), default) diff --git a/neutron_lib/api/validators/dns.py b/neutron_lib/api/validators/dns.py index a2b16fd..db22c0f 100644 --- a/neutron_lib/api/validators/dns.py +++ b/neutron_lib/api/validators/dns.py @@ -118,7 +118,7 @@ def validate_dns_name(data, max_len=db_constants.FQDN_FIELD_SIZE): :param data: The data to validate. :param max_len: An optional cap on the length of the string. :returns: None if data is valid, otherwise a human readable message - indicating why validation failed. + indicating why validation failed. """ msg = _validate_dns_format(data, max_len) if msg: @@ -138,7 +138,7 @@ def validate_fip_dns_name(data, max_len=db_constants.FQDN_FIELD_SIZE): :param data: The data to validate. :param max_len: An optional cap on the length of the string. :returns: None if data is valid, otherwise a human readable message - indicating why validation failed. + indicating why validation failed. """ msg = validators.validate_string(data) if msg: @@ -167,7 +167,7 @@ def validate_dns_domain(data, max_len=db_constants.FQDN_FIELD_SIZE): :param data: The data to validate. :param max_len: An optional cap on the length of the string. :returns: None if data is valid, otherwise a human readable message - indicating why validation failed. + indicating why validation failed. """ msg = validators.validate_string(data) if msg: diff --git a/neutron_lib/callbacks/events.py b/neutron_lib/callbacks/events.py index dfbfcc1..4185655 100644 --- a/neutron_lib/callbacks/events.py +++ b/neutron_lib/callbacks/events.py @@ -117,7 +117,7 @@ class DBEventPayload(EventPayload): """Determine if the resource for this event payload is persisted. :returns: True if this payload's resource is persisted, otherwise - False. + False. """ return self.resource_id is not None and self.has_states @@ -134,7 +134,7 @@ class DBEventPayload(EventPayload): """Returns the latest state for the event payload resource. :returns: If this payload has a desired_state its returned, otherwise - latest_state is returned. + latest_state is returned. """ return (self.desired_state or super(DBEventPayload, self).latest_state) diff --git a/neutron_lib/callbacks/exceptions.py b/neutron_lib/callbacks/exceptions.py index b055371..f2bea0d 100644 --- a/neutron_lib/callbacks/exceptions.py +++ b/neutron_lib/callbacks/exceptions.py @@ -34,8 +34,8 @@ class CallbackFailure(exceptions.MultipleExceptions): """The list of unpacked errors for this exception. :return: A list of unpacked errors for this exception. An unpacked - error is the Exception's 'error' attribute if it inherits from - NotificationError, otherwise it's the exception itself. + error is the Exception's 'error' attribute if it inherits from + NotificationError, otherwise it's the exception itself. """ if isinstance(self.errors, list): return [self._unpack_if_notification_error(e) for e in self.errors] diff --git a/neutron_lib/callbacks/manager.py b/neutron_lib/callbacks/manager.py index ee06bcc..9f129d7 100644 --- a/neutron_lib/callbacks/manager.py +++ b/neutron_lib/callbacks/manager.py @@ -115,10 +115,10 @@ class CallbacksManager(object): :param event: The event. :param trigger: The trigger. A reference to the sender of the event. :param payload: The optional event object to send to subscribers. If - passed this must be an instance of BaseEvent. - :raises Invalid, CallbackFailure: The Invalid exception is raised if - the payload object is not an instance of BaseEvent. CallbackFailure - is raise if the underlying callback has errors. + passed this must be an instance of BaseEvent. + :raises neutron_lib.callbacks.exceptions.Invalid: if + the payload object is not an instance of BaseEvent. + :raises CallbackFailure: if the underlying callback has errors. """ if payload: if not isinstance(payload, events.EventPayload): @@ -138,9 +138,9 @@ class CallbacksManager(object): :param event: The event. :param trigger: The trigger. A reference to the sender of the event. :param kwargs: (deprecated) Unstructured key/value pairs to invoke - the callback with. Using event objects with publish() is preferred. + the callback with. Using event objects with publish() is preferred. :raises CallbackFailure: CallbackFailure is raised if the underlying - callback has errors. + callback has errors. """ errors = self._notify_loop(resource, event, trigger, **kwargs) if errors: diff --git a/neutron_lib/db/utils.py b/neutron_lib/db/utils.py index 3722f8d..f9f8d84 100644 --- a/neutron_lib/db/utils.py +++ b/neutron_lib/db/utils.py @@ -28,7 +28,7 @@ def get_and_validate_sort_keys(sorts, model): :param model: A sqlalchemy ORM model class. :returns: A list of the extracted sort keys. :raises BadRequest: If a sort key attribute references another resource - and cannot be used in the sort. + and cannot be used in the sort. """ sort_keys = [s[0] for s in sorts] @@ -91,7 +91,7 @@ def reraise_as_retryrequest(function): :param function: The function to wrap/decorate. :returns: The 'function' wrapped in a try block that will reraise any - Exception's as a RetryRequest. + Exception's as a RetryRequest. :raises RetryRequest: If the wrapped function raises retriable exception. """ @six.wraps(function) diff --git a/neutron_lib/exceptions/__init__.py b/neutron_lib/exceptions/__init__.py index eaaa74f..7be8240 100644 --- a/neutron_lib/exceptions/__init__.py +++ b/neutron_lib/exceptions/__init__.py @@ -96,7 +96,7 @@ class AdminRequired(NotAuthorized): is required to carry out the operation or access a resource. :param reason: A message indicating additional details on why admin is - required for the operation access. + required for the operation access. """ message = _("User does not have admin privileges: %(reason)s.") @@ -195,8 +195,8 @@ class SubnetInUse(InUse): :param subnet_id: The UUID of the subnet requested. :param reason: Details on why the operation failed. If None, a default - reason is used indicating one or more ports still have IP allocations - on the subnet. + reason is used indicating one or more ports still have IP allocations + on the subnet. """ message = _("Unable to complete operation on subnet %(subnet_id)s: " "%(reason)s.") @@ -216,7 +216,7 @@ class SubnetPoolInUse(InUse): :param subnet_pool_id: The UUID of the subnet pool requested. :param reason: Details on why the operation failed. If None a default - reason is used indicating two or more concurrent subnets are allocated. + reason is used indicating two or more concurrent subnets are allocated. """ message = _("Unable to complete operation on subnet pool " "%(subnet_pool_id)s. %(reason)s.") @@ -390,7 +390,7 @@ class InvalidInput(BadRequest): specified. :param error_message: Details on the operation that failed due to bad - input. + input. """ message = _("Invalid input for operation: %(error_message)s.") @@ -454,7 +454,7 @@ class InvalidConfigurationOption(NeutronException): """An error due to an invalid configuration option value. :param opt_name: The name of the configuration option that has an invalid - value. + value. :param opt_value: The value that's invalid for the configuration option. """ message = _("An invalid value was provided for %(opt_name)s: " @@ -467,7 +467,7 @@ class NetworkTunnelRangeError(NeutronException): An exception indicating an invalid network tunnel range was specified. :param tunnel_range: The invalid tunnel range. If specified in the - start:end' format, they will be converted automatically. + start:end' format, they will be converted automatically. :param error: Additional details on why the range is invalid. """ message = _("Invalid network tunnel range: " diff --git a/neutron_lib/hacking/checks.py b/neutron_lib/hacking/checks.py index 6b01332..affd51d 100644 --- a/neutron_lib/hacking/checks.py +++ b/neutron_lib/hacking/checks.py @@ -47,8 +47,8 @@ def use_jsonutils(logical_line, filename): :param logical_line: The logical line to check. :param filename: The file name where the logical line exists. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line and a + message describe the check validation failure. """ msg = "N521: jsonutils.%(fun)s must be used instead of json.%(fun)s" @@ -111,8 +111,8 @@ def check_no_contextlib_nested(logical_line, filename): :param logical_line: The logical line to check. :param filename: The file name where the logical line exists. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line and a + message describe the check validation failure. """ msg = ("N524: contextlib.nested is deprecated. With Python 2.7 and later " "the with-statement supports multiple nested objects. See https://" @@ -128,8 +128,8 @@ def check_python3_xrange(logical_line): :param logical_line: The logical line to check. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line and a + message describe the check validation failure. """ if re.search(r"\bxrange\s*\(", logical_line): yield(0, "N525: Do not use xrange. Use range, or six.moves.range for " @@ -141,8 +141,8 @@ def check_no_basestring(logical_line): :param logical_line: The logical line to check. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line and a + message describe the check validation failure. """ if re.search(r"\bbasestring\b", logical_line): msg = ("N526: basestring is not Python3-compatible, use " @@ -155,8 +155,8 @@ def check_python3_no_iteritems(logical_line): :param logical_line: The logical line to check. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line and a + message describe the check validation failure. """ if re.search(r".*\.iteritems\(\)", logical_line): msg = ("N527: Use dict.items() instead of dict.iteritems() to be " @@ -172,8 +172,8 @@ def no_mutable_default_args(logical_line): :param logical_line: The logical line to check. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line and a + message describe the check validation failure. """ msg = "N529: Method's default argument shouldn't be mutable!" if mutable_default_args.match(logical_line): @@ -188,8 +188,8 @@ def check_neutron_namespace_imports(logical_line): :param logical_line: The logical line to check. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line and a + message describe the check validation failure. """ x = _check_namespace_imports( 'N530', 'neutron', 'neutron_lib.', logical_line, @@ -203,8 +203,8 @@ def check_no_eventlet_imports(logical_line): :param logical_line: The logical line to check. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line and a + message describe the check validation failure. """ if re.match(r'(import|from)\s+[(]?eventlet', logical_line): msg = 'N535: Usage of Python eventlet module not allowed' diff --git a/neutron_lib/hacking/translation_checks.py b/neutron_lib/hacking/translation_checks.py index e90694e..47a6114 100644 --- a/neutron_lib/hacking/translation_checks.py +++ b/neutron_lib/hacking/translation_checks.py @@ -41,8 +41,8 @@ def check_log_warn_deprecated(logical_line, filename): :param logical_line: The logical line to check. :param filename: The file name where the logical line exists. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line and a + message describe the check validation failure. """ msg = "N532: Use LOG.warning due to compatibility with py3" if _log_warn.match(logical_line): @@ -55,8 +55,8 @@ def check_raised_localized_exceptions(logical_line, filename): :param logical_line: The logical line to check. :param filename: The file name where the logical line exists. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line and a + message describe the check validation failure. """ if _translation_checks_not_enforced(filename): return @@ -84,8 +84,8 @@ def no_translate_logs(logical_line, filename): :param logical_line: The logical line to check. :param filename: The file name where the logical line exists. :returns: None if the logical line passes the check, otherwise a tuple - is yielded that contains the offending index in logical line and a - message describe the check validation failure. + is yielded that contains the offending index in logical line and a + message describe the check validation failure. """ if _translation_checks_not_enforced(filename): return diff --git a/neutron_lib/plugins/ml2/api.py b/neutron_lib/plugins/ml2/api.py index 5fa6513..2dd5210 100644 --- a/neutron_lib/plugins/ml2/api.py +++ b/neutron_lib/plugins/ml2/api.py @@ -68,7 +68,7 @@ class MechanismDriver(object): """Allocate resources for a new network. :param context: NetworkContext instance describing the new - network. + network. Create a new network, allocating resources as necessary in the database. Called inside transaction context on session. Call @@ -81,7 +81,7 @@ class MechanismDriver(object): """Create a network. :param context: NetworkContext instance describing the new - network. + network. Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not @@ -94,8 +94,8 @@ class MechanismDriver(object): """Update resources of a network. :param context: NetworkContext instance describing the new - state of the network, as well as the original state prior - to the update_network call. + state of the network, as well as the original state prior + to the update_network call. Update values of a network, updating the associated resources in the database. Called inside transaction context on session. @@ -112,8 +112,8 @@ class MechanismDriver(object): """Update a network. :param context: NetworkContext instance describing the new - state of the network, as well as the original state prior - to the update_network call. + state of the network, as well as the original state prior + to the update_network call. Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not @@ -130,7 +130,7 @@ class MechanismDriver(object): """Delete resources for a network. :param context: NetworkContext instance describing the current - state of the network, prior to the call to delete it. + state of the network, prior to the call to delete it. Delete network resources previously allocated by this mechanism driver for a network. Called inside transaction @@ -144,7 +144,7 @@ class MechanismDriver(object): """Delete a network. :param context: NetworkContext instance describing the current - state of the network, prior to the call to delete it. + state of the network, prior to the call to delete it. Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not @@ -158,7 +158,7 @@ class MechanismDriver(object): """Allocate resources for a new subnet. :param context: SubnetContext instance describing the new - subnet. + subnet. Create a new subnet, allocating resources as necessary in the database. Called inside transaction context on session. Call @@ -171,7 +171,7 @@ class MechanismDriver(object): """Create a subnet. :param context: SubnetContext instance describing the new - subnet. + subnet. Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not @@ -184,8 +184,8 @@ class MechanismDriver(object): """Update resources of a subnet. :param context: SubnetContext instance describing the new - state of the subnet, as well as the original state prior - to the update_subnet call. + state of the subnet, as well as the original state prior + to the update_subnet call. Update values of a subnet, updating the associated resources in the database. Called inside transaction context on session. @@ -202,8 +202,8 @@ class MechanismDriver(object): """Update a subnet. :param context: SubnetContext instance describing the new - state of the subnet, as well as the original state prior - to the update_subnet call. + state of the subnet, as well as the original state prior + to the update_subnet call. Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not @@ -220,7 +220,7 @@ class MechanismDriver(object): """Delete resources for a subnet. :param context: SubnetContext instance describing the current - state of the subnet, prior to the call to delete it. + state of the subnet, prior to the call to delete it. Delete subnet resources previously allocated by this mechanism driver for a subnet. Called inside transaction @@ -234,7 +234,7 @@ class MechanismDriver(object): """Delete a subnet. :param context: SubnetContext instance describing the current - state of the subnet, prior to the call to delete it. + state of the subnet, prior to the call to delete it. Called after the transaction commits. Call can block, though will block the entire process so care should be taken to not @@ -272,8 +272,8 @@ class MechanismDriver(object): """Update resources of a port. :param context: PortContext instance describing the new - state of the port, as well as the original state prior - to the update_port call. + state of the port, as well as the original state prior + to the update_port call. Called inside transaction context on session to complete a port update as defined by this mechanism driver. Raising an @@ -289,8 +289,8 @@ class MechanismDriver(object): """Update a port. :param context: PortContext instance describing the new - state of the port, as well as the original state prior - to the update_port call. + state of the port, as well as the original state prior + to the update_port call. Called after the transaction completes. Call can block, though will block the entire process so care should be taken to not @@ -307,7 +307,7 @@ class MechanismDriver(object): """Delete resources of a port. :param context: PortContext instance describing the current - state of the port, prior to the call to delete it. + state of the port, prior to the call to delete it. Called inside transaction context on session. Runtime errors are not expected, but raising an exception will result in @@ -319,7 +319,7 @@ class MechanismDriver(object): """Delete a port. :param context: PortContext instance describing the current - state of the port, prior to the call to delete it. + state of the port, prior to the call to delete it. Called after the transaction completes. Call can block, though will block the entire process so care should be taken to not diff --git a/neutron_lib/utils/file.py b/neutron_lib/utils/file.py index e69d910..5f056eb 100644 --- a/neutron_lib/utils/file.py +++ b/neutron_lib/utils/file.py @@ -30,7 +30,7 @@ def ensure_dir(dir_path): :param dir_path: The directory path to ensure. :returns: None. :raises OSError: If the underlying call to makedirs raises an OSError - other than EEXIST. + other than EEXIST. """ try: os.makedirs(dir_path, 0o755) diff --git a/neutron_lib/utils/helpers.py b/neutron_lib/utils/helpers.py index bbd6557..65ccb2b 100644 --- a/neutron_lib/utils/helpers.py +++ b/neutron_lib/utils/helpers.py @@ -26,7 +26,7 @@ def parse_mappings(mapping_list, unique_values=True, unique_keys=True): :param mapping_list: A list of strings of the form ':'. :param unique_values: Values must be unique if True. :param unique_keys: Keys must be unique if True, else implies that keys - and values are not unique. + and values are not unique. :returns: A dict mapping keys to values or to list of values. :raises ValueError: Upon malformed data or duplicate keys. """ @@ -89,7 +89,7 @@ def dict2str(dic): :param dic: The dict to build a str representation for. :returns: The dict in str representation that is a k=v command list for - each item in dic. + each item in dic. """ return ','.join("%s=%s" % (key, val) for key, val in sorted(dic.items())) @@ -127,7 +127,7 @@ def diff_list_of_dict(old_list, new_list): :param old_list: The old list of dicts to diff. :param new_list: The new list of dicts to diff. :returns: A tuple where the first item is a list of the added dicts in - the diff and the second item is the removed dicts. + the diff and the second item is the removed dicts. """ new_set = set([dict2str(l) for l in new_list]) old_set = set([dict2str(l) for l in old_list]) @@ -149,7 +149,7 @@ def camelize(s): """Camelize a str that uses _ as a camelize token. :param s: The str to camelize that contains a _ at each index where a new - camelized word starts. + camelized word starts. :returns: The camelized str. """ return ''.join(s.replace('_', ' ').title().split()) diff --git a/neutron_lib/utils/host.py b/neutron_lib/utils/host.py index a447a0b..07e4004 100644 --- a/neutron_lib/utils/host.py +++ b/neutron_lib/utils/host.py @@ -18,7 +18,7 @@ def cpu_count(): """Get the system CPU count. :returns: The number of CPUs on the system as an int. If there's an issue - fetching the CPU count on the system, a default value of 1 is returned. + fetching the CPU count on the system, a default value of 1 is returned. """ try: return multiprocessing.cpu_count() diff --git a/neutron_lib/utils/net.py b/neutron_lib/utils/net.py index 319adfd..b30ae28 100644 --- a/neutron_lib/utils/net.py +++ b/neutron_lib/utils/net.py @@ -48,7 +48,7 @@ def is_port_trusted(port): :param port: The port dict to inspect the 'device_owner' for. :returns: True if the port dict's 'device_owner' value starts with the - networking prefix. False otherwise. + networking prefix. False otherwise. """ return port['device_owner'].startswith( constants.DEVICE_OWNER_NETWORK_PREFIX) diff --git a/neutron_lib/utils/runtime.py b/neutron_lib/utils/runtime.py index ea91874..98ffaf8 100644 --- a/neutron_lib/utils/runtime.py +++ b/neutron_lib/utils/runtime.py @@ -34,7 +34,7 @@ def load_class_by_alias_or_classname(namespace, name): :param namespace: The namespace where the alias is defined. :param name: The alias or class name of the class to be loaded. :returns: Class if it can be loaded. - :raises ImportError if class cannot be loaded. + :raises ImportError: if class cannot be loaded. """ if not name: diff --git a/neutron_lib/worker.py b/neutron_lib/worker.py index 2f97cf7..1f4975f 100644 --- a/neutron_lib/worker.py +++ b/neutron_lib/worker.py @@ -29,6 +29,9 @@ class BaseWorker(service.ServiceBase): do this only once instead of in every API worker, for instance, it would define a BaseWorker class and the plugin would have get_workers return an array of BaseWorker instances. For example: + + .. code-block:: python + class MyPlugin(...): def get_workers(self): return [MyPluginWorker()] diff --git a/setup.cfg b/setup.cfg index f64a17d..5bb1287 100644 --- a/setup.cfg +++ b/setup.cfg @@ -44,3 +44,13 @@ input_file = neutron_lib/locale/neutron_lib.pot keywords = _ gettext ngettext l_ lazy_gettext mapping_file = babel.cfg output_file = neutron_lib/locale/neutron_lib.pot + +[pbr] +autodoc_tree_index_modules = True +autodoc_tree_excludes = + setup.py + neutron_lib/tests + # In case neutron_lib.legacy has no actual content, this causes + # an error in sphinx autodoc, so let's exclude it. + neutron_lib/legacy +api_doc_dir = reference/modules