openstack/neutron-vpnaas
Code Issues Proposed changes

Sphinx-ify QuantumPluginBaseV2 docstrings

Browse Source 
The quantum.quantum_plugin_base_v2 module had some good docstrings,
but there was no corresponding sphinx code that would generate
docs from them. There were also some syntax issues with the
sphinx markup in the docstrings.

This change adds sphinx directives so these docs will be auto-
generated. It also modifies the docstrings in the QuantumPluginBaseV2
methods so they are parsed by the Sphinx documentation generator
without any errors.

If this patch is accepted, a "Plugin API" link to these docs
will appear at

http://docs.openstack.org/developer/quantum/

Fixes bug 1186255

Change-Id: I96eddcc516d109766d7f4c52edd595748696b595
This commit is contained in:
Lorin Hochstein 2013-05-26 16:42:21 -04:00
parent b8960ea393
commit 28884ffaa4
3 changed files with 153 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
doc/source/devref/plugin-api.rst Normal file
View File

@ -0,0 +1,7 @@
Plugin API
==========
.. automodule:: quantum.quantum_plugin_base_v2
.. autoclass:: QuantumPluginBaseV2
:members:

1
doc/source/index.rst
View File

@ -44,6 +44,7 @@ Development Documents
.. toctree::
:maxdepth: 1
devref/plugin-api
devref/index
devref/common

264
quantum/quantum_plugin_base_v2.py
View File

@ -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