updated outdated comments in base v2 plugin class

bug 1011841

Change-Id: Iddcb1cb365391b3c3e8b8f06cbf714baa3e64a02

diff --git a/quantum/quantum_plugin_base_v2.py b/quantum/quantum_plugin_base_v2.py
index f503b1e5cb61d3cca693bb1821780e0d614f9793..2dae8911d2ba770fd2f41514c4bfa3d00e31e72b 100644 (file)
--- a/quantum/quantum_plugin_base_v2.py
+++ b/quantum/quantum_plugin_base_v2.py
@@ -33,164 +33,201 @@ class QuantumPluginBaseV2(object):
         """
         Create a subnet, which represents a range of IP addresses
         that can be allocated to devices
-        : param subnet_data: data describing the prefix
-          {
-            "network_id": UUID of the network to which this subnet
-                          is bound.
-            "ip_version": integer indicating IP protocol version.
-                          example: 4
-            "cidr": string indicating IP prefix indicating addresses
-                    that can be allocated for devices on this subnet.
-                    example: "10.0.0.0/24"
-            "gateway_ip": string indicating the default gateway
-                          for devices on this subnet. example: "10.0.0.1"
-            "dns_nameservers": list of strings stricting indication the
-                               DNS name servers for devices on this
-                               subnet.  example: [ "8.8.8.8", "8.8.4.4" ]
-            "reserved_ranges" : list of dicts indicating pairs of IPs that
-                                should not be automatically allocated from
-                                the prefix.
-                                example: [ { "start" : "10.0.0.2",
-                                             "end" : "10.0.0.5" } ]
-            "additional_host_routes": list of dicts indicating routes beyond
-                                 the default gateway and local prefix route
-                                 that should be injected into the device.
-                                 example: [{"destination": "192.168.0.0/16",
-                                              "nexthop": "10.0.0.5" } ]
-          }
+        : 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.
         """
         pass
 
     @abstractmethod
     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.
+        """
         pass
 
     @abstractmethod
     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.
+        """
         pass
 
     @abstractmethod
-    def delete_subnet(self, context, id):
+    def get_subnets(self, context, filters=None, fields=None):
+        """
+        Retrieve a list of subnets.  The contents of the list depends on
+        the identify 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.
+        """
         pass
 
     @abstractmethod
-    def get_subnets(self, context, filters=None, fields=None):
+    def delete_subnet(self, context, id):
+        """
+        Delete a subnet.
+        : param context: quantum api request context
+        : param id: UUID representing the subnet to delete.
+        """
         pass
 
     @abstractmethod
     def create_network(self, context, network):
         """
-        Creates a new Virtual Network, assigns a name and associates
-
-        :param net_data:
-          {
-           'name': a human-readable name associated
-                   with network referenced by net-id
-                   example: "net-1"
-           'admin-state-up': indicates whether this network should
-                             be operational.
-           'subnets': list of subnet uuids associated with this
-                      network.
-          }
-        :raises:
+        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.
         """
         pass
 
     @abstractmethod
     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.
+        """
         pass
 
     @abstractmethod
-    def delete_network(self, context, id):
+    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.
+        """
         pass
 
     @abstractmethod
-    def get_network(self, context, id, fields=None):
+    def get_networks(self, context, filters=None, fields=None):
+        """
+        Retrieve a list of networks.  The contents of the list depends on
+        the identify 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.
+        """
         pass
 
     @abstractmethod
-    def get_networks(self, context, filters=None, fields=None):
+    def delete_network(self, context, id):
+        """
+        Delete a network.
+        : param context: quantum api request context
+        : param id: UUID representing the network to delete.
+        """
         pass
 
     @abstractmethod
     def create_port(self, context, port):
         """
-        Creates a port on the specified Virtual Network. Optionally
-        specify customization of port IP-related attributes, otherwise
-        the port gets the default values of these attributes associated with
-        the subnet.
-
-        :param port_data:
-          {"network_id" : UUID of network that this port is attached to.
-           "admin-state-up" : boolean indicating whether this port should be
-                              operational.
-           "mac_address" : (optional) mac address used on this port.  If no
-                           value is specified, the plugin will generate a
-                           MAC address based on internal configuration.
-           "fixed_ips" : (optional) list of dictionaries describing the
-                         fixed IPs to be allocated for use by the device on
-                         this port. If not specified, the plugin will
-                         attempt to find a v4 and v6 subnet associated
-                         with the network and allocate an IP for that
-                         subnet.
-                         Note: "address" is optional, in which case an
-                               address from the specified subnet is
-                               selected.
-                         example: [{"subnet": "<uuid>",
-                                    "address": "10.0.0.9"}]
-           "routes" : (optional) list of routes to be injected into this
-                      device. If not specified, the port will get a
-                      route for its local subnet, a route for the default
-                      gateway, and each of the routes in the
-                      'additional_routes' field of the subnet.
-                      example: [ { "destination" : "192.168.0.0/16",
-                                   "nexthop" : "10.0.0.5" } ]
-          }
-        :raises: exception.NetworkNotFound
-        :raises: exception.RequestedFixedIPNotAvailable
-        :raises: exception.FixedIPNotAvailable
-        :raises: exception.RouteInvalid
+        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.
         """
         pass
 
     @abstractmethod
     def update_port(self, context, id, port):
         """
-        Updates the attributes of a specific port on the
-        specified Virtual Network.
-
-        :returns: a mapping sequence with the following signature:
-                    {'port-id': uuid representing the
-                                 updated port on specified quantum network
-                     'port-state': update port state( ACTIVE or DOWN)
-                    }
-        :raises: exception.StateInvalid
-        :raises: exception.PortNotFound
+        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.
         """
         pass
 
     @abstractmethod
-    def delete_port(self, context, id):
+    def get_port(self, context, id, fields=None):
         """
-        Deletes a port on a specified Virtual Network,
-        if the port contains a remote interface attachment,
-        the remote interface is first un-plugged and then the port
-        is deleted.
-
-        :returns: a mapping sequence with the following signature:
-                    {'port-id': uuid representing the deleted port
-                                 on specified quantum network
-                    }
-        :raises: exception.PortInUse
-        :raises: exception.PortNotFound
-        :raises: exception.NetworkNotFound
+        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.
         """
         pass
 
     @abstractmethod
-    def get_port(self, context, id, fields=None):
+    def get_ports(self, context, filters=None, fields=None):
+        """
+        Retrieve a list of ports.  The contents of the list depends on
+        the identify 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.
+        """
         pass
 
     @abstractmethod
-    def get_ports(self, context, filters=None, fields=None):
+    def delete_port(self, context, id):
+        """
+        Delete a port.
+        : param context: quantum api request context
+        : param id: UUID representing the port to delete.
+        """
         pass