openstack
/
os-vif
Code Issues Proposed changes

doc: Fix arg specs and object types in docs 

The usage doc stated that plug and unplug accept a single argument of
type `os_vif.objects.VIF`, which isn't a thing, and then went on to give
an example showing that they take two.  The usage doc and the plug and
unplug docstrings also listed various objects at the wrong paths (e.g.
the `instance_info` param being of type `os_vif.objects.InstanceInfo`,
which also isn't a thing).

Fixed up the usage doc to list both arguments and correct the references
in the sample code; and fixed the plug/unplug docstrings
to list the proper paths to classes: os_vif.objects.vif.VIFBase and
os_vif.objects.instance_info.InstanceInfo.

Made everything in `single backticks` into a proper rst ``literal``.

Change-Id: I400838bbe9663917fe2c64f52975b77a370405b4
This commit is contained in:
Eric Fried 2018-06-13 10:46:16 -05:00 committed by Sean Mooney
parent 1f00350203
commit 8d7c0d548d
3 changed files with 42 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
doc/source/user/usage.rst
View File

@ -2,8 +2,8 @@
Usage
=====
The interface to the `os_vif` library is very simple. To begin using the
library, first call the `os_vif.initialize()` function. This will load all
The interface to the ``os_vif`` library is very simple. To begin using the
library, first call the ``os_vif.initialize()`` function. This will load all
installed plugins and register the object model:
.. code-block:: python
@ -12,9 +12,10 @@ installed plugins and register the object model:
os_vif.initialize()
Once the `os_vif` library is initialized, there are only two other library
functions: `os_vif.plug()` and `os_vif.unplug()`. Both methods accept a single
argument of type `os_vif.objects.VIF`:
Once the ``os_vif`` library is initialized, there are only two other library
functions: ``os_vif.plug()`` and ``os_vif.unplug()``. Both methods accept an
argument of (a subclass of) type ``os_vif.objects.vif.VIFBase`` and an argument
of type ``os_vif.objects.instance_info.InstanceInfo``:
.. code-block:: python
@ -22,31 +23,34 @@ argument of type `os_vif.objects.VIF`:
from nova import objects as nova_objects
from os_vif import exception as vif_exc
from os_vif import objects as vif_objects
from os_vif import vnic_types
from os_vif.objects import fields
from os_vif.objects import instance_info
from os_vif.objects import network
from os_vif.objects import subnet
from os_vif.objects import vif as vif_obj
instance_uuid = 'd7a730ca-3c28-49c3-8f26-4662b909fe8a'
instance = nova_objects.Instance.get_by_uuid(instance_uuid)
instance_info = vif_objects.InstanceInfo(
instance_info = instance_info.InstanceInfo(
uuid=instance.uuid,
name=instance.name,
project_id=instance.project_id)
subnet = vif_objects.Subnet(cidr='192.168.1.0/24')
subnets = vif_objects.SubnetList([subnet])
network = vif_objects.Network(label='tenantnet',
subnets=subnets,
multi_host=False,
should_provide_vlan=False,
should_provide_bridge=False)
subnet = subnet.Subnet(cidr='192.168.1.0/24')
subnets = subnet.SubnetList([subnet])
network = network.Network(label='tenantnet',
subnets=subnets,
multi_host=False,
should_provide_vlan=False,
should_provide_bridge=False)
vif_uuid = uuid.uuid4()
vif = vif_objects.VIFVHostUser(id=vif_uuid,
address=None,
network=network,
plugin='vhostuser',
path='/path/to/socket',
mode=vif_objects.fields.VIFVHostUserMode.SERVER)
vif = vif_obj.VIFVHostUser(id=vif_uuid,
address=None,
network=network,
plugin='vhostuser',
path='/path/to/socket',
mode=fields.VIFVHostUserMode.SERVER)
# Now do the actual plug operations to connect the VIF to
# the backing network interface.

16
os_vif/__init__.py
View File

@ -53,14 +53,14 @@ def plug(vif, instance_info):
"""
Given a model of a VIF, perform operations to plug the VIF properly.
:param vif: `os_vif.objects.VIF` object.
:param instance_info: `os_vif.objects.InstanceInfo` object.
:raises `exception.LibraryNotInitialized` if the user of the library
did not call os_vif.initialize(**config) before trying to
:param vif: Instance of a subclass of ``os_vif.objects.vif.VIFBase``.
:param instance_info: ``os_vif.objects.instance_info.InstanceInfo`` object.
:raises ``exception.LibraryNotInitialized`` if the user of the library
did not call ``os_vif.initialize(**config)`` before trying to
plug a VIF.
:raises `exception.NoMatchingPlugin` if there is no plugin for the
:raises ``exception.NoMatchingPlugin`` if there is no plugin for the
type of VIF supplied.
:raises `exception.PlugException` if anything fails during unplug
:raises ``exception.PlugException`` if anything fails during unplug
operations.
"""
if _EXT_MANAGER is None:
@ -86,8 +86,8 @@ def unplug(vif, instance_info):
"""
Given a model of a VIF, perform operations to unplug the VIF properly.
:param vif: `os_vif.objects.VIF` object.
:param instance_info: `os_vif.objects.InstanceInfo` object.
:param vif: Instance of a subclass of `os_vif.objects.vif.VIFBase`.
:param instance_info: `os_vif.objects.instance_info.InstanceInfo` object.
:raises `exception.LibraryNotInitialized` if the user of the library
did not call os_vif.initialize(**config) before trying to
plug a VIF.

18
os_vif/plugin.py
View File

@ -30,7 +30,7 @@ class PluginBase(object):
"""
Initialize the plugin object with the provided config
:param config: `oslo_config.ConfigOpts.GroupAttr` instance:
:param config: ``oslo_config.ConfigOpts.GroupAttr`` instance:
"""
self.config = config
@ -40,7 +40,7 @@ class PluginBase(object):
Return an object that describes the plugin's supported vif types and
the earliest/latest known VIF object versions.
:returns: A `os_vif.objects.host_info.HostPluginInfo` instance
:returns: A ``os_vif.objects.host_info.HostPluginInfo`` instance
"""
@abc.abstractmethod
@ -48,10 +48,10 @@ class PluginBase(object):
"""
Given a model of a VIF, perform operations to plug the VIF properly.
:param vif: `os_vif.objects.vif.VIFBase` object.
:param instance_info: `os_vif.objects.instance_info.InstanceInfo`
:param vif: ``os_vif.objects.vif.VIFBase`` object.
:param instance_info: ``os_vif.objects.instance_info.InstanceInfo``
object.
:raises: `processutils.ProcessExecutionError`. Plugins implementing
:raises ``processutils.ProcessExecutionError``. Plugins implementing
this method should let `processutils.ProcessExecutionError`
bubble up.
"""
@ -61,11 +61,11 @@ class PluginBase(object):
"""
Given a model of a VIF, perform operations to unplug the VIF properly.
:param vif: `os_vif.objects.vif.VIFBase` object.
:param instance_info: `os_vif.objects.instance_info.InstanceInfo`
:param vif: ``os_vif.objects.vif.VIFBase`` object.
:param instance_info: ``os_vif.objects.instance_info.InstanceInfo``
object.
:raises: `processutils.ProcessExecutionError`. Plugins implementing
this method should let `processutils.ProcessExecutionError`
:raises ``processutils.ProcessExecutionError``. Plugins implementing
this method should let ``processutils.ProcessExecutionError``
bubble up.
"""