openstack/neutron-lbaas
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:: .. toctree::
:maxdepth: 1 :maxdepth: 1
devref/plugin-api
devref/index devref/index
devref/common devref/common

264
quantum/quantum_plugin_base_v2.py
View File

@ -17,7 +17,7 @@
""" """
v2 Quantum Plug-in API specification. 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. 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 Create a subnet, which represents a range of IP addresses
that can be allocated to devices that can be allocated to devices
: param context: quantum api request context
: param subnet: dictionary describing the subnet, with keys :param context: quantum api request context
as listed in the RESOURCE_ATTRIBUTE_MAP object in :param subnet: dictionary describing the subnet, with keys
quantum/api/v2/attributes.py. All keys will be populated. as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP` object
in :file:`quantum/api/v2/attributes.py`. All keys will
be populated.
""" """
pass pass
@ -47,12 +49,13 @@ class QuantumPluginBaseV2(object):
def update_subnet(self, context, id, subnet): def update_subnet(self, context, id, subnet):
"""Update values of a subnet. """Update values of a subnet.
: param context: quantum api request context :param context: quantum api request context
: param id: UUID representing the subnet to update. :param id: UUID representing the subnet to update.
: param subnet: dictionary with keys indicating fields to update. :param subnet: dictionary with keys indicating fields to update.
valid keys are those that have a value of True for 'allow_put' valid keys are those that have a value of True for
as listed in the RESOURCE_ATTRIBUTE_MAP object in 'allow_put' as listed in the
quantum/api/v2/attributes.py. :obj:`RESOURCE_ATTRIBUTE_MAP` object in
:file:`quantum/api/v2/attributes.py`.
""" """
pass pass
@ -60,12 +63,13 @@ class QuantumPluginBaseV2(object):
def get_subnet(self, context, id, fields=None): def get_subnet(self, context, id, fields=None):
"""Retrieve a subnet. """Retrieve a subnet.
: param context: quantum api request context :param context: quantum api request context
: param id: UUID representing the subnet to fetch. :param id: UUID representing the subnet to fetch.
: param fields: a list of strings that are valid keys in a :param fields: a list of strings that are valid keys in a
subnet dictionary as listed in the RESOURCE_ATTRIBUTE_MAP subnet dictionary as listed in the
object in quantum/api/v2/attributes.py. Only these fields :obj:`RESOURCE_ATTRIBUTE_MAP` object in
will be returned. :file:`quantum/api/v2/attributes.py`. Only these fields
will be returned.
""" """
pass pass
@ -77,18 +81,21 @@ class QuantumPluginBaseV2(object):
The contents of the list depends on The contents of the list depends on
the identity of the user making the request (as indicated by the the identity of the user making the request (as indicated by the
context) as well as any filters. context) as well as any filters.
: param context: quantum api request context
: param filters: a dictionary with keys that are valid keys for :param context: quantum api request context
a subnet as listed in the RESOURCE_ATTRIBUTE_MAP object :param filters: a dictionary with keys that are valid keys for
in quantum/api/v2/attributes.py. Values in this dictiontary a subnet as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP`
are an iterable containing values that will be used for an exact object in :file:`quantum/api/v2/attributes.py`.
match comparison for that value. Each result returned by this Values in this dictiontary are an iterable containing
function will have matched one of the values for each key in values that will be used for an exact match comparison
filters. for that value. Each result returned by this
: param fields: a list of strings that are valid keys in a function will have matched one of the values for each
subnet dictionary as listed in the RESOURCE_ATTRIBUTE_MAP key in filters.
object in quantum/api/v2/attributes.py. Only these fields :param fields: a list of strings that are valid keys in a
will be returned. 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 pass
@ -98,17 +105,19 @@ class QuantumPluginBaseV2(object):
The result depends on the identity of The result depends on the identity of
the user making the request (as indicated by the context) as well as the user making the request (as indicated by the context) as well as
any filters. 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 :param context: quantum api request context
defined plugin API. :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() raise exceptions.NotImplementedError()
@ -116,8 +125,8 @@ class QuantumPluginBaseV2(object):
def delete_subnet(self, context, id): def delete_subnet(self, context, id):
"""Delete a subnet. """Delete a subnet.
: param context: quantum api request context :param context: quantum api request context
: param id: UUID representing the subnet to delete. :param id: UUID representing the subnet to delete.
""" """
pass pass
@ -127,10 +136,13 @@ class QuantumPluginBaseV2(object):
Create a network, which represents an L2 network segment which Create a network, which represents an L2 network segment which
can have a set of subnets and ports associated with it. 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 :param context: quantum api request context
as listed in the RESOURCE_ATTRIBUTE_MAP object in :param network: dictionary describing the network, with keys
quantum/api/v2/attributes.py. All keys will be populated. as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP` object
in :file:`quantum/api/v2/attributes.py`. All keys will
be populated.
""" """
pass pass
@ -138,12 +150,13 @@ class QuantumPluginBaseV2(object):
def update_network(self, context, id, network): def update_network(self, context, id, network):
"""Update values of a network. """Update values of a network.
: param context: quantum api request context :param context: quantum api request context
: param id: UUID representing the network to update. :param id: UUID representing the network to update.
: param network: dictionary with keys indicating fields to update. :param network: dictionary with keys indicating fields to update.
valid keys are those that have a value of True for 'allow_put' valid keys are those that have a value of True for
as listed in the RESOURCE_ATTRIBUTE_MAP object in 'allow_put' as listed in the
quantum/api/v2/attributes.py. :obj:`RESOURCE_ATTRIBUTE_MAP` object in
:file:`quantum/api/v2/attributes.py`.
""" """
pass pass
@ -151,12 +164,13 @@ class QuantumPluginBaseV2(object):
def get_network(self, context, id, fields=None): def get_network(self, context, id, fields=None):
"""Retrieve a network. """Retrieve a network.
: param context: quantum api request context :param context: quantum api request context
: param id: UUID representing the network to fetch. :param id: UUID representing the network to fetch.
: param fields: a list of strings that are valid keys in a :param fields: a list of strings that are valid keys in a
network dictionary as listed in the RESOURCE_ATTRIBUTE_MAP network dictionary as listed in the
object in quantum/api/v2/attributes.py. Only these fields :obj:`RESOURCE_ATTRIBUTE_MAP` object in
will be returned. :file:`quantum/api/v2/attributes.py`. Only these fields
will be returned.
""" """
pass pass
@ -168,18 +182,21 @@ class QuantumPluginBaseV2(object):
The contents of the list depends on The contents of the list depends on
the identity of the user making the request (as indicated by the the identity of the user making the request (as indicated by the
context) as well as any filters. context) as well as any filters.
: param context: quantum api request context
: param filters: a dictionary with keys that are valid keys for :param context: quantum api request context
a network as listed in the RESOURCE_ATTRIBUTE_MAP object :param filters: a dictionary with keys that are valid keys for
in quantum/api/v2/attributes.py. Values in this dictiontary a network as listed in the
are an iterable containing values that will be used for an exact :obj:`RESOURCE_ATTRIBUTE_MAP` object in
match comparison for that value. Each result returned by this :file:`quantum/api/v2/attributes.py`. Values in this
function will have matched one of the values for each key in dictiontary are an iterable containing values that will
filters. be used for an exact match comparison for that value.
: param fields: a list of strings that are valid keys in a Each result returned by this function will have matched
network dictionary as listed in the RESOURCE_ATTRIBUTE_MAP one of the values for each key in filters.
object in quantum/api/v2/attributes.py. Only these fields :param fields: a list of strings that are valid keys in a
will be returned. 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 pass
@ -189,14 +206,16 @@ class QuantumPluginBaseV2(object):
The result depends on the identity The result depends on the identity
of the user making the request (as indicated by the context) as well of the user making the request (as indicated by the context) as well
as any filters. as any filters.
: param context: quantum api request context
: param filters: a dictionary with keys that are valid keys for :param context: quantum api request context
a network as listed in the RESOURCE_ATTRIBUTE_MAP object :param filters: a dictionary with keys that are valid keys for
in quantum/api/v2/attributes.py. Values in this dictiontary a network as listed in the
are an iterable containing values that will be used for an exact :obj:`RESOURCE_ATTRIBUTE_MAP` object
match comparison for that value. Each result returned by this in :file:`quantum/api/v2/attributes.py`. Values in
function will have matched one of the values for each key in this dictiontary are an iterable containing values that
filters. 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 NOTE: this method is optional, as it was not part of the originally
defined plugin API. defined plugin API.
@ -207,8 +226,8 @@ class QuantumPluginBaseV2(object):
def delete_network(self, context, id): def delete_network(self, context, id):
"""Delete a network. """Delete a network.
: param context: quantum api request context :param context: quantum api request context
: param id: UUID representing the network to delete. :param id: UUID representing the network to delete.
""" """
pass pass
@ -218,10 +237,12 @@ class QuantumPluginBaseV2(object):
Create a port, which is a connection point of a device (e.g., a VM Create a port, which is a connection point of a device (e.g., a VM
NIC) to attach to a L2 Quantum network. NIC) to attach to a L2 Quantum network.
: param context: quantum api request context
: param port: dictionary describing the port, with keys :param context: quantum api request context
as listed in the RESOURCE_ATTRIBUTE_MAP object in :param port: dictionary describing the port, with keys as listed in the
quantum/api/v2/attributes.py. All keys will be populated. :obj:`RESOURCE_ATTRIBUTE_MAP` object in
:file:`quantum/api/v2/attributes.py`. All keys will be
populated.
""" """
pass pass
@ -229,12 +250,12 @@ class QuantumPluginBaseV2(object):
def update_port(self, context, id, port): def update_port(self, context, id, port):
"""Update values of a port. """Update values of a port.
: param context: quantum api request context :param context: quantum api request context
: param id: UUID representing the port to update. :param id: UUID representing the port to update.
: param port: dictionary with keys indicating fields to update. :param port: dictionary with keys indicating fields to update.
valid keys are those that have a value of True for 'allow_put' valid keys are those that have a value of True for
as listed in the RESOURCE_ATTRIBUTE_MAP object in 'allow_put' as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP`
quantum/api/v2/attributes.py. object in :file:`quantum/api/v2/attributes.py`.
""" """
pass pass
@ -242,12 +263,13 @@ class QuantumPluginBaseV2(object):
def get_port(self, context, id, fields=None): def get_port(self, context, id, fields=None):
"""Retrieve a port. """Retrieve a port.
: param context: quantum api request context :param context: quantum api request context
: param id: UUID representing the port to fetch. :param id: UUID representing the port to fetch.
: param fields: a list of strings that are valid keys in a :param fields: a list of strings that are valid keys in a port
port dictionary as listed in the RESOURCE_ATTRIBUTE_MAP dictionary as listed in the
object in quantum/api/v2/attributes.py. Only these fields :obj:`RESOURCE_ATTRIBUTE_MAP` object in
will be returned. :file:`quantum/api/v2/attributes.py`. Only these fields
will be returned.
""" """
pass pass
@ -258,18 +280,20 @@ class QuantumPluginBaseV2(object):
The contents of the list depends on the identity of the user making 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. 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 :param context: quantum api request context
a port as listed in the RESOURCE_ATTRIBUTE_MAP object :param filters: a dictionary with keys that are valid keys for
in quantum/api/v2/attributes.py. Values in this dictiontary a port as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP`
are an iterable containing values that will be used for an exact object in :file:`quantum/api/v2/attributes.py`. Values
match comparison for that value. Each result returned by this in this dictiontary are an iterable containing values
function will have matched one of the values for each key in that will be used for an exact match comparison for
filters. that value. Each result returned by this function will
: param fields: a list of strings that are valid keys in a have matched one of the values for each key in filters.
port dictionary as listed in the RESOURCE_ATTRIBUTE_MAP :param fields: a list of strings that are valid keys in a
object in quantum/api/v2/attributes.py. Only these fields port dictionary as listed in the
will be returned. :obj:`RESOURCE_ATTRIBUTE_MAP` object in
:file:`quantum/api/v2/attributes.py`. Only these fields
will be returned.
""" """
pass pass
@ -278,17 +302,19 @@ class QuantumPluginBaseV2(object):
The result depends on the identity of the user making the request The result depends on the identity of the user making the request
(as indicated by the context) as well as any filters. (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 :param context: quantum api request context
defined plugin API. :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() raise exceptions.NotImplementedError()
@ -296,7 +322,7 @@ class QuantumPluginBaseV2(object):
def delete_port(self, context, id): def delete_port(self, context, id):
"""Delete a port. """Delete a port.
: param context: quantum api request context :param context: quantum api request context
: param id: UUID representing the port to delete. :param id: UUID representing the port to delete.
""" """
pass pass