feat: add environments client (#217)

LICENSE

@@ -1,4 +1,4 @@
-                            Apache License
+                                 Apache License
                            Version 2.0, January 2004
                         https://www.apache.org/licenses/
 

dialogflow_v2/__init__.py

@@ -24,15 +24,16 @@
 from dialogflow_v2.gapic import contexts_client
 from dialogflow_v2.gapic import entity_types_client
 from dialogflow_v2.gapic import enums
+from dialogflow_v2.gapic import environments_client
 from dialogflow_v2.gapic import intents_client
 from dialogflow_v2.gapic import session_entity_types_client
 from dialogflow_v2.gapic import sessions_client
 
 
 if sys.version_info[:2] == (2, 7):
     message = (
-        "A future version of this library will drop support for Python 2.7."
-        "More details about Python 2 support for Google Cloud Client Libraries"
+        "A future version of this library will drop support for Python 2.7. "
+        "More details about Python 2 support for Google Cloud Client Libraries "
         "can be found at https://cloud.google.com/python/docs/python2-sunset/"
     )
     warnings.warn(message, DeprecationWarning)
@@ -53,6 +54,11 @@ class EntityTypesClient(entity_types_client.EntityTypesClient):
     enums = enums
 
 
+class EnvironmentsClient(environments_client.EnvironmentsClient):
+    __doc__ = environments_client.EnvironmentsClient.__doc__
+    enums = enums
+
+
 class IntentsClient(intents_client.IntentsClient):
     __doc__ = intents_client.IntentsClient.__doc__
     enums = enums
@@ -74,6 +80,7 @@ class SessionsClient(sessions_client.SessionsClient):
     "AgentsClient",
     "ContextsClient",
     "EntityTypesClient",
+    "EnvironmentsClient",
     "IntentsClient",
     "SessionEntityTypesClient",
     "SessionsClient",

dialogflow_v2/gapic/agents_client.py

@@ -50,32 +50,7 @@
 
 
 class AgentsClient(object):
-    """
-    Agents are best described as Natural Language Understanding (NLU)
-    modules that transform user requests into actionable data. You can
-    include agents in your app, product, or service to determine user intent
-    and respond to the user in a natural way.
-
-    After you create an agent, you can add ``Intents``, ``Contexts``,
-    ``Entity Types``, ``Webhooks``, and so on to manage the flow of a
-    conversation and match user input to predefined intents and actions.
-
-    You can create an agent using both Dialogflow Standard Edition and
-    Dialogflow Enterprise Edition. For details, see `Dialogflow
-    Editions <https://cloud.google.com/dialogflow/docs/editions>`__.
-
-    You can save your agent for backup or versioning by exporting the agent
-    by using the ``ExportAgent`` method. You can import a saved agent by
-    using the ``ImportAgent`` method.
-
-    Dialogflow provides several `prebuilt
-    agents <https://cloud.google.com/dialogflow/docs/agents-prebuilt>`__ for
-    common conversation scenarios such as determining a date and time,
-    converting currency, and so on.
-
-    For more information about agents, see the `Dialogflow
-    documentation <https://cloud.google.com/dialogflow/docs/agents-overview>`__.
-    """
+    """Service for managing ``Agents``."""
 
     SERVICE_ADDRESS = "dialogflow.googleapis.com:443"
     """The default address of the service."""
@@ -224,36 +199,28 @@ def __init__(
         self._inner_api_calls = {}
 
     # Service calls
-    def set_agent(
+    def get_agent(
         self,
-        agent,
-        update_mask=None,
+        parent,
         retry=google.api_core.gapic_v1.method.DEFAULT,
         timeout=google.api_core.gapic_v1.method.DEFAULT,
         metadata=None,
     ):
         """
-        Creates/updates the specified agent.
+        Retrieves the specified agent.
 
         Example:
             >>> import dialogflow_v2
             >>>
             >>> client = dialogflow_v2.AgentsClient()
             >>>
-            >>> # TODO: Initialize `agent`:
-            >>> agent = {}
+            >>> parent = client.project_path('[PROJECT]')
             >>>
-            >>> response = client.set_agent(agent)
+            >>> response = client.get_agent(parent)
 
         Args:
-            agent (Union[dict, ~google.cloud.dialogflow_v2.types.Agent]): Required. The agent to update.
-
-                If a dict is provided, it must be of the same form as the protobuf
-                message :class:`~google.cloud.dialogflow_v2.types.Agent`
-            update_mask (Union[dict, ~google.cloud.dialogflow_v2.types.FieldMask]): Optional. The mask to control which fields get updated.
-
-                If a dict is provided, it must be of the same form as the protobuf
-                message :class:`~google.cloud.dialogflow_v2.types.FieldMask`
+            parent (str): Required. The project that the agent to fetch is associated with.
+                Format: ``projects/<Project ID>``.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -274,22 +241,22 @@ def set_agent(
             ValueError: If the parameters are invalid.
         """
         # Wrap the transport method to add retry and timeout logic.
-        if "set_agent" not in self._inner_api_calls:
+        if "get_agent" not in self._inner_api_calls:
             self._inner_api_calls[
-                "set_agent"
+                "get_agent"
             ] = google.api_core.gapic_v1.method.wrap_method(
-                self.transport.set_agent,
-                default_retry=self._method_configs["SetAgent"].retry,
-                default_timeout=self._method_configs["SetAgent"].timeout,
+                self.transport.get_agent,
+                default_retry=self._method_configs["GetAgent"].retry,
+                default_timeout=self._method_configs["GetAgent"].timeout,
                 client_info=self._client_info,
             )
 
-        request = agent_pb2.SetAgentRequest(agent=agent, update_mask=update_mask)
+        request = agent_pb2.GetAgentRequest(parent=parent)
         if metadata is None:
             metadata = []
         metadata = list(metadata)
         try:
-            routing_header = [("agent.parent", agent.parent)]
+            routing_header = [("parent", parent)]
         except AttributeError:
             pass
         else:
@@ -298,32 +265,40 @@ def set_agent(
             )
             metadata.append(routing_metadata)
 
-        return self._inner_api_calls["set_agent"](
+        return self._inner_api_calls["get_agent"](
             request, retry=retry, timeout=timeout, metadata=metadata
         )
 
-    def delete_agent(
+    def set_agent(
         self,
-        parent,
+        agent,
+        update_mask=None,
         retry=google.api_core.gapic_v1.method.DEFAULT,
         timeout=google.api_core.gapic_v1.method.DEFAULT,
         metadata=None,
     ):
         """
-        Deletes the specified agent.
+        Creates/updates the specified agent.
 
         Example:
             >>> import dialogflow_v2
             >>>
             >>> client = dialogflow_v2.AgentsClient()
             >>>
-            >>> parent = client.project_path('[PROJECT]')
+            >>> # TODO: Initialize `agent`:
+            >>> agent = {}
             >>>
-            >>> client.delete_agent(parent)
+            >>> response = client.set_agent(agent)
 
         Args:
-            parent (str): Required. The project that the agent to delete is associated with.
-                Format: ``projects/<Project ID>``.
+            agent (Union[dict, ~google.cloud.dialogflow_v2.types.Agent]): Required. The agent to update.
+
+                If a dict is provided, it must be of the same form as the protobuf
+                message :class:`~google.cloud.dialogflow_v2.types.Agent`
+            update_mask (Union[dict, ~google.cloud.dialogflow_v2.types.FieldMask]): Optional. The mask to control which fields get updated.
+
+                If a dict is provided, it must be of the same form as the protobuf
+                message :class:`~google.cloud.dialogflow_v2.types.FieldMask`
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
                 be retried using a default configuration.
@@ -333,6 +308,9 @@ def delete_agent(
             metadata (Optional[Sequence[Tuple[str, str]]]): Additional metadata
                 that is provided to the method.
 
+        Returns:
+            A :class:`~google.cloud.dialogflow_v2.types.Agent` instance.
+
         Raises:
             google.api_core.exceptions.GoogleAPICallError: If the request
                     failed for any reason.
@@ -341,22 +319,22 @@ def delete_agent(
             ValueError: If the parameters are invalid.
         """
         # Wrap the transport method to add retry and timeout logic.
-        if "delete_agent" not in self._inner_api_calls:
+        if "set_agent" not in self._inner_api_calls:
             self._inner_api_calls[
-                "delete_agent"
+                "set_agent"
             ] = google.api_core.gapic_v1.method.wrap_method(
-                self.transport.delete_agent,
-                default_retry=self._method_configs["DeleteAgent"].retry,
-                default_timeout=self._method_configs["DeleteAgent"].timeout,
+                self.transport.set_agent,
+                default_retry=self._method_configs["SetAgent"].retry,
+                default_timeout=self._method_configs["SetAgent"].timeout,
                 client_info=self._client_info,
             )
 
-        request = agent_pb2.DeleteAgentRequest(parent=parent)
+        request = agent_pb2.SetAgentRequest(agent=agent, update_mask=update_mask)
         if metadata is None:
             metadata = []
         metadata = list(metadata)
         try:
-            routing_header = [("parent", parent)]
+            routing_header = [("agent.parent", agent.parent)]
         except AttributeError:
             pass
         else:
@@ -365,19 +343,19 @@ def delete_agent(
             )
             metadata.append(routing_metadata)
 
-        self._inner_api_calls["delete_agent"](
+        return self._inner_api_calls["set_agent"](
             request, retry=retry, timeout=timeout, metadata=metadata
         )
 
-    def get_agent(
+    def delete_agent(
         self,
         parent,
         retry=google.api_core.gapic_v1.method.DEFAULT,
         timeout=google.api_core.gapic_v1.method.DEFAULT,
         metadata=None,
     ):
         """
-        Retrieves the specified agent.
+        Deletes the specified agent.
 
         Example:
             >>> import dialogflow_v2
@@ -386,10 +364,10 @@ def get_agent(
             >>>
             >>> parent = client.project_path('[PROJECT]')
             >>>
-            >>> response = client.get_agent(parent)
+            >>> client.delete_agent(parent)
 
         Args:
-            parent (str): Required. The project that the agent to fetch is associated with.
+            parent (str): Required. The project that the agent to delete is associated with.
                 Format: ``projects/<Project ID>``.
             retry (Optional[google.api_core.retry.Retry]):  A retry object used
                 to retry requests. If ``None`` is specified, requests will
@@ -400,9 +378,6 @@ def get_agent(
             metadata (Optional[Sequence[Tuple[str, str]]]): Additional metadata
                 that is provided to the method.
 
-        Returns:
-            A :class:`~google.cloud.dialogflow_v2.types.Agent` instance.
-
         Raises:
             google.api_core.exceptions.GoogleAPICallError: If the request
                     failed for any reason.
@@ -411,17 +386,17 @@ def get_agent(
             ValueError: If the parameters are invalid.
         """
         # Wrap the transport method to add retry and timeout logic.
-        if "get_agent" not in self._inner_api_calls:
+        if "delete_agent" not in self._inner_api_calls:
             self._inner_api_calls[
-                "get_agent"
+                "delete_agent"
             ] = google.api_core.gapic_v1.method.wrap_method(
-                self.transport.get_agent,
-                default_retry=self._method_configs["GetAgent"].retry,
-                default_timeout=self._method_configs["GetAgent"].timeout,
+                self.transport.delete_agent,
+                default_retry=self._method_configs["DeleteAgent"].retry,
+                default_timeout=self._method_configs["DeleteAgent"].timeout,
                 client_info=self._client_info,
             )
 
-        request = agent_pb2.GetAgentRequest(parent=parent)
+        request = agent_pb2.DeleteAgentRequest(parent=parent)
         if metadata is None:
             metadata = []
         metadata = list(metadata)
@@ -435,7 +410,7 @@ def get_agent(
             )
             metadata.append(routing_metadata)
 
-        return self._inner_api_calls["get_agent"](
+        self._inner_api_calls["delete_agent"](
             request, retry=retry, timeout=timeout, metadata=metadata
         )
 
@@ -654,7 +629,10 @@ def export_agent(
             >>>
             >>> parent = client.project_path('[PROJECT]')
             >>>
-            >>> response = client.export_agent(parent)
+            >>> # TODO: Initialize `agent_uri`:
+            >>> agent_uri = ''
+            >>>
+            >>> response = client.export_agent(parent, agent_uri)
             >>>
             >>> def callback(operation_future):
             ...     # Handle result.
@@ -741,9 +719,15 @@ def import_agent(
 
         Uploads new intents and entity types without deleting the existing ones.
         Intents and entity types with the same name are replaced with the new
-        versions from ImportAgentRequest.
+        versions from ``ImportAgentRequest``. After the import, the imported
+        draft agent will be trained automatically (unless disabled in agent
+        settings). However, once the import is done, training may not be
+        completed yet. Please call ``TrainAgent`` and wait for the operation it
+        returns in order to train explicitly.
 
-        Operation <response: ``google.protobuf.Empty``>
+        Operation <response: ``google.protobuf.Empty``> An operation which
+        tracks when importing is complete. It only tracks when the draft agent
+        is updated not when it is done training.
 
         Example:
             >>> import dialogflow_v2
@@ -844,9 +828,15 @@ def restore_agent(
         Restores the specified agent from a ZIP file.
 
         Replaces the current agent version with a new one. All the intents and
-        entity types in the older version are deleted.
+        entity types in the older version are deleted. After the restore, the
+        restored draft agent will be trained automatically (unless disabled in
+        agent settings). However, once the restore is done, training may not be
+        completed yet. Please call ``TrainAgent`` and wait for the operation it
+        returns in order to train explicitly.
 
-        Operation <response: ``google.protobuf.Empty``>
+        Operation <response: ``google.protobuf.Empty``> An operation which
+        tracks when restoring is complete. It only tracks when the draft agent
+        is updated not when it is done training.
 
         Example:
             >>> import dialogflow_v2
@@ -951,13 +941,15 @@ def get_validation_result(
             >>>
             >>> client = dialogflow_v2.AgentsClient()
             >>>
-            >>> response = client.get_validation_result()
+            >>> parent = client.project_path('[PROJECT]')
+            >>>
+            >>> response = client.get_validation_result(parent)
 
         Args:
             parent (str): Required. The project that the agent is associated with. Format:
                 ``projects/<Project ID>``.
-            language_code (str): Optional. The language for which you want a validation result. If not
-                specified, the agent's default language is used. `Many
+            language_code (str): Optional. The language for which you want a validation result. If
+                not specified, the agent's default language is used. `Many
                 languages <https://cloud.google.com/dialogflow/docs/reference/language>`__
                 are supported. Note: languages must be enabled in the agent before they
                 can be used.