diff --git a/doc/source/devref/plugin-api.rst b/doc/source/devref/plugin-api.rst new file mode 100644 index 00000000000..fbf72abf749 --- /dev/null +++ b/doc/source/devref/plugin-api.rst @@ -0,0 +1,7 @@ +Plugin API +========== + +.. automodule:: quantum.quantum_plugin_base_v2 + +.. autoclass:: QuantumPluginBaseV2 + :members: diff --git a/doc/source/index.rst b/doc/source/index.rst index 654768d5de2..5539a78d4c5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -44,6 +44,7 @@ Development Documents .. toctree:: :maxdepth: 1 + devref/plugin-api devref/index devref/common diff --git a/quantum/quantum_plugin_base_v2.py b/quantum/quantum_plugin_base_v2.py index 35bbcf9971d..43d21f1c64c 100644 --- a/quantum/quantum_plugin_base_v2.py +++ b/quantum/quantum_plugin_base_v2.py @@ -17,7 +17,7 @@ """ v2 Quantum Plug-in API specification. -QuantumPluginBase provides the definition of minimum set of +:class:`QuantumPluginBaseV2` provides the definition of minimum set of methods that needs to be implemented by a v2 Quantum Plug-in. """ @@ -36,10 +36,12 @@ class QuantumPluginBaseV2(object): Create a subnet, which represents a range of IP addresses that can be allocated to devices - : param context: quantum api request context - : param subnet: dictionary describing the subnet, with keys - as listed in the RESOURCE_ATTRIBUTE_MAP object in - quantum/api/v2/attributes.py. All keys will be populated. + + :param context: quantum api request context + :param subnet: dictionary describing the subnet, with keys + as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP` object + in :file:`quantum/api/v2/attributes.py`. All keys will + be populated. """ pass @@ -47,12 +49,13 @@ class QuantumPluginBaseV2(object): def update_subnet(self, context, id, 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. - valid keys are those that have a value of True for 'allow_put' - as listed in the RESOURCE_ATTRIBUTE_MAP object in - quantum/api/v2/attributes.py. + :param context: quantum api request context + :param id: UUID representing the subnet to update. + :param subnet: dictionary with keys indicating fields to update. + valid keys are those that have a value of True for + 'allow_put' as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. """ pass @@ -60,12 +63,13 @@ class QuantumPluginBaseV2(object): def get_subnet(self, context, id, fields=None): """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 - subnet dictionary as listed in the RESOURCE_ATTRIBUTE_MAP - object in quantum/api/v2/attributes.py. Only these fields - will be returned. + :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 + subnet dictionary as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. Only these fields + will be returned. """ pass @@ -77,18 +81,21 @@ class QuantumPluginBaseV2(object): 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 subnet as listed in the RESOURCE_ATTRIBUTE_MAP object - in quantum/api/v2/attributes.py. Values in this dictiontary - are an iterable containing values that will be used for an exact - match comparison for that value. Each result returned by this - function will have matched one of the values for each key in - filters. - : param fields: a list of strings that are valid keys in a - subnet dictionary as listed in the RESOURCE_ATTRIBUTE_MAP - object in quantum/api/v2/attributes.py. Only these fields - will be returned. + + :param context: quantum api request context + :param filters: a dictionary with keys that are valid keys for + a subnet as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP` + object in :file:`quantum/api/v2/attributes.py`. + Values in this dictiontary are an iterable containing + values that will be used for an exact match comparison + for that value. Each result returned by this + function will have matched one of the values for each + key in filters. + :param fields: a list of strings that are valid keys in a + subnet dictionary as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. Only these fields + will be returned. """ pass @@ -98,17 +105,19 @@ class QuantumPluginBaseV2(object): 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 - in quantum/api/v2/attributes.py. Values in this dictiontary - are an iterable containing values that will be used for an exact - match comparison for that value. Each result returned by this - function will have matched one of the values for each key in - filters. - NOTE: this method is optional, as it was not part of the originally - defined plugin API. + :param context: quantum api request context + :param filters: a dictionary with keys that are valid keys for + a network as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. Values in this + dictiontary are an iterable containing values that + will be used for an exact match comparison for that + value. Each result returned by this function will + have matched one of the values for each key in filters. + + .. note:: this method is optional, as it was not part of the originally + defined plugin API. """ raise exceptions.NotImplementedError() @@ -116,8 +125,8 @@ class QuantumPluginBaseV2(object): def delete_subnet(self, context, id): """Delete a subnet. - : param context: quantum api request context - : param id: UUID representing the subnet to delete. + :param context: quantum api request context + :param id: UUID representing the subnet to delete. """ pass @@ -127,10 +136,13 @@ class QuantumPluginBaseV2(object): 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 - : param network: dictionary describing the network, with keys - as listed in the RESOURCE_ATTRIBUTE_MAP object in - quantum/api/v2/attributes.py. All keys will be populated. + + :param context: quantum api request context + :param network: dictionary describing the network, with keys + as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP` object + in :file:`quantum/api/v2/attributes.py`. All keys will + be populated. + """ pass @@ -138,12 +150,13 @@ class QuantumPluginBaseV2(object): def update_network(self, context, id, 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. - valid keys are those that have a value of True for 'allow_put' - as listed in the RESOURCE_ATTRIBUTE_MAP object in - quantum/api/v2/attributes.py. + :param context: quantum api request context + :param id: UUID representing the network to update. + :param network: dictionary with keys indicating fields to update. + valid keys are those that have a value of True for + 'allow_put' as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. """ pass @@ -151,12 +164,13 @@ class QuantumPluginBaseV2(object): def get_network(self, context, id, fields=None): """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 - network dictionary as listed in the RESOURCE_ATTRIBUTE_MAP - object in quantum/api/v2/attributes.py. Only these fields - will be returned. + :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 + network dictionary as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. Only these fields + will be returned. """ pass @@ -168,18 +182,21 @@ class QuantumPluginBaseV2(object): 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 network as listed in the RESOURCE_ATTRIBUTE_MAP object - in quantum/api/v2/attributes.py. Values in this dictiontary - are an iterable containing values that will be used for an exact - match comparison for that value. Each result returned by this - function will have matched one of the values for each key in - filters. - : param fields: a list of strings that are valid keys in a - network dictionary as listed in the RESOURCE_ATTRIBUTE_MAP - object in quantum/api/v2/attributes.py. Only these fields - will be returned. + + :param context: quantum api request context + :param filters: a dictionary with keys that are valid keys for + a network as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. Values in this + dictiontary are an iterable containing values that will + be used for an exact match comparison for that value. + Each result returned by this function will have matched + one of the values for each key in filters. + :param fields: a list of strings that are valid keys in a + network dictionary as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. Only these fields + will be returned. """ pass @@ -189,14 +206,16 @@ class QuantumPluginBaseV2(object): 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 - in quantum/api/v2/attributes.py. Values in this dictiontary - are an iterable containing values that will be used for an exact - match comparison for that value. Each result returned by this - function will have matched one of the values for each key in - filters. + + :param context: quantum api request context + :param filters: a dictionary with keys that are valid keys for + a network as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object + in :file:`quantum/api/v2/attributes.py`. Values in + this dictiontary are an iterable containing values that + will be used for an exact match comparison for that + value. Each result returned by this function will have + matched one of the values for each key in filters. NOTE: this method is optional, as it was not part of the originally defined plugin API. @@ -207,8 +226,8 @@ class QuantumPluginBaseV2(object): def delete_network(self, context, id): """Delete a network. - : param context: quantum api request context - : param id: UUID representing the network to delete. + :param context: quantum api request context + :param id: UUID representing the network to delete. """ pass @@ -218,10 +237,12 @@ class QuantumPluginBaseV2(object): 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 - : param port: dictionary describing the port, with keys - as listed in the RESOURCE_ATTRIBUTE_MAP object in - quantum/api/v2/attributes.py. All keys will be populated. + + :param context: quantum api request context + :param port: dictionary describing the port, with keys as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. All keys will be + populated. """ pass @@ -229,12 +250,12 @@ class QuantumPluginBaseV2(object): def update_port(self, context, id, 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. - valid keys are those that have a value of True for 'allow_put' - as listed in the RESOURCE_ATTRIBUTE_MAP object in - quantum/api/v2/attributes.py. + :param context: quantum api request context + :param id: UUID representing the port to update. + :param port: dictionary with keys indicating fields to update. + valid keys are those that have a value of True for + 'allow_put' as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP` + object in :file:`quantum/api/v2/attributes.py`. """ pass @@ -242,12 +263,13 @@ class QuantumPluginBaseV2(object): def get_port(self, context, id, fields=None): """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 - port dictionary as listed in the RESOURCE_ATTRIBUTE_MAP - object in quantum/api/v2/attributes.py. Only these fields - will be returned. + :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 port + dictionary as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. Only these fields + will be returned. """ pass @@ -258,18 +280,20 @@ class QuantumPluginBaseV2(object): 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 - in quantum/api/v2/attributes.py. Values in this dictiontary - are an iterable containing values that will be used for an exact - match comparison for that value. Each result returned by this - function will have matched one of the values for each key in - filters. - : param fields: a list of strings that are valid keys in a - port dictionary as listed in the RESOURCE_ATTRIBUTE_MAP - object in quantum/api/v2/attributes.py. Only these fields - will be returned. + + :param context: quantum api request context + :param filters: a dictionary with keys that are valid keys for + a port as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP` + object in :file:`quantum/api/v2/attributes.py`. Values + in this dictiontary are an iterable containing values + that will be used for an exact match comparison for + that value. Each result returned by this function will + have matched one of the values for each key in filters. + :param fields: a list of strings that are valid keys in a + port dictionary as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. Only these fields + will be returned. """ pass @@ -278,17 +302,19 @@ class QuantumPluginBaseV2(object): 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 - in quantum/api/v2/attributes.py. Values in this dictiontary - are an iterable containing values that will be used for an exact - match comparison for that value. Each result returned by this - function will have matched one of the values for each key in - filters. - NOTE: this method is optional, as it was not part of the originally - defined plugin API. + :param context: quantum api request context + :param filters: a dictionary with keys that are valid keys for + a network as listed in the + :obj:`RESOURCE_ATTRIBUTE_MAP` object in + :file:`quantum/api/v2/attributes.py`. Values in this + dictiontary are an iterable containing values that will + be used for an exact match comparison for that value. + Each result returned by this function will have matched + one of the values for each key in filters. + + .. note:: this method is optional, as it was not part of the originally + defined plugin API. """ raise exceptions.NotImplementedError() @@ -296,7 +322,7 @@ class QuantumPluginBaseV2(object): def delete_port(self, context, id): """Delete a port. - : param context: quantum api request context - : param id: UUID representing the port to delete. + :param context: quantum api request context + :param id: UUID representing the port to delete. """ pass