Switch Blade*Connection* classes to be directly context manageable

vtds_provider_gcp/api_objects.py

@@ -24,7 +24,6 @@
 and operations in the provider layer.
 
 """
-from contextlib import contextmanager
 from abc import (
     ABCMeta,
     abstractmethod
@@ -92,54 +91,68 @@ def blade_ssh_key_paths(self, blade_type):
         """
 
     @abstractmethod
-    @contextmanager
     def connect_blade(self, blade_type, instance, remote_port):
         """Establish an external connection to the specified remote
         port on the specified instance of the named Virtual Blade
-        type. Return a context manager (suitable for use in a 'with'
-        clause) yielding an APIBladeConnection object for the
-        connection. Upon leaving the 'with' context, the connection in
-        the APIBladeConnection is closed.
+        type. Return a BladeConnection object for the connection.
+
+        BladeConnections are context managed, so if this is used
+        in a 'with' clause, upon leaving the 'with' context, the
+        connection in the BladeConnection is automatically closed.
+
+        To close the connection outside of a 'with' clause call
+        the __exit__() method on the BladeConnection.
 
         """
 
-    @contextmanager
     @abstractmethod
     def connect_blades(self, remote_port, blade_types=None):
         """Establish external connections to the specified remote port
         on all the Virtual Blade instances on all the Virtual Blade
         types listed by name in 'blade_types'. If 'blade_types' is not
         provided or None, all available blade types are used. Return a
-        context manager (suitable for use in a 'with' clause) yielding
-        the list of APIBladeConnection objects representing the
-        connections. Upon leaving the 'with' context, all the
-        connections in the resulting list are closed.
+        BladeConnectionSet object representing the connections.
+
+        BladeConnectionSets are context managed, so if this is used
+        in a 'with' clause, upon leaving the 'with' context, the
+        connections in the BladeConnectionSet are automatically closed.
+
+        To close the connections outside of a 'with' clause call
+        the __exit__() method on the BladeConnectionSet.
 
         """
 
     @abstractmethod
-    @contextmanager
     def ssh_connect_blade(self, blade_type, instance, remote_port):
         """Establish an external connection to the SSH server
         port on the specified instance of the named Virtual Blade
-        type. Return a context manager (suitable for use in a 'with'
-        clause) yielding a BladeSSHConnection object for the
-        connection. Upon leaving the 'with' context, the connection in
-        the BladeSSHConnection is closed.
+        type. Return a BladeSSHConnection object for the
+        connection.
+
+        BladeSSHConnection are context managed, so if this is used
+        in a 'with' clause, upon leaving the 'with' context, the
+        connection in the BladeSSHConnection is automatically closed.
+
+        To close the connection outside of a 'with' clause call
+        the __exit__() method on the BladeSSHConnection.
 
         """
 
-    @contextmanager
     @abstractmethod
     def ssh_connect_blades(self, blade_types=None, remote_port=22):
         """Establish external connections to the specified remote port
         on all the Virtual Blade instances on all the Virtual Blade
         types listed by name in 'blade_types'. If 'blade_types' is not
         provided or None, all available blade types are used. Return a
-        context manager (suitable for use in a 'with' clause) yielding
-        the list of APIBladeConnection objects representing the
-        connections. Upon leaving the 'with' context, all the
-        connections in the resulting list are closed.
+        BladeSSHConnectionSet object representing the
+        connections.
+
+        BladeSSHConnectionSets are context managed, so if this is used
+        in a 'with' clause, upon leaving the 'with' context, the
+        connections in the BladeSSHConnectionSet are automatically closed.
+
+        To close the connections outside of a 'with' clause call
+        the __exit__() method on the BladeSSHConnectionSet.
 
         """
 
@@ -202,6 +215,29 @@ def remote_port(self):
 
         """
 
+    @abstractmethod
+    def __enter__(self):
+        """Context entry handler to make BladeConnection objects
+        usable with the 'with ... as' construct. This returns the
+        BladeConnection for use in a context.
+
+        """
+
+    @abstractmethod
+    def __exit__(
+            self,
+            exception_type=None,
+            exception_value=None,
+            traceback=None
+    ):
+        """Context exit handler to make BladeConnection
+        objects usable with the 'with ... as' construct. This cleans
+        up all resources associated with the BladeConnection on
+        exit from the 'with' block context. Not called if the object
+        is used outside a 'with' context.
+
+        """
+
 
 class BladeConnectionSet(metaclass=ABCMeta):
     """A class that contains multiple active BladeConnections to
@@ -227,6 +263,29 @@ def get_connection(self, hostname):
 
         """
 
+    @abstractmethod
+    def __enter__(self):
+        """Context entry handler to make BladeConnectionSet objects
+        usable with the 'with ... as' construct. This returns the
+        BladeConnectionSet for use in a context.
+
+        """
+
+    @abstractmethod
+    def __exit__(
+            self,
+            exception_type=None,
+            exception_value=None,
+            traceback=None
+    ):
+        """Context exit handler to make BladeConnectionSet
+        objects usable with the 'with ... as' construct. This cleans
+        up all resources associated with the BladeConnectionSet on
+        exit from the 'with' block context. Not called if the object
+        is used outside a 'with' context.
+
+        """
+
 
 class BladeSSHConnection(BladeConnection, metaclass=ABCMeta):
     """Specifically a connection to the SSH server on a blade (remote
@@ -335,6 +394,29 @@ def run_command(self, cmd, blocking=True, logfiles=None, **kwargs):
 
         """
 
+    @abstractmethod
+    def __enter__(self):
+        """Context entry handler to make BladeSSHConnection objects
+        usable with the 'with ... as' construct. This returns the
+        BladeSSHConnection for use in a context.
+
+        """
+
+    @abstractmethod
+    def __exit__(
+            self,
+            exception_type=None,
+            exception_value=None,
+            traceback=None
+    ):
+        """Context exit handler to make BladeSSHConnection objects
+        usable with the 'with ... as' construct. This cleans up all
+        resources associated with the BladeSSHConnection on exit from
+        the 'with' block context. Not called if the object is used
+        outside a 'with' context.
+
+        """
+
 
 class BladeSSHConnectionSet(BladeConnectionSet, metaclass=ABCMeta):
     """A class to wrap multiple BladeSSHConnections and provide
@@ -396,6 +478,29 @@ def run_command(self, cmd, logname=None, blade_type=None):
 
         """
 
+    @abstractmethod
+    def __enter__(self):
+        """Context entry handler to make BladeSSHConnectionSet objects
+        usable with the 'with ... as' construct. This returns the
+        BladeSSHConnectionSet for use in a context.
+
+        """
+
+    @abstractmethod
+    def __exit__(
+            self,
+            exception_type=None,
+            exception_value=None,
+            traceback=None
+    ):
+        """Context exit handler to make BladeSSHConnectionSet objects
+        usable with the 'with ... as' construct. This cleans up all
+        resources associated with the BladeSSHConnectionSet on exit
+        from the 'with' block context. Not called if the object is
+        used outside a 'with' context.
+
+        """
+
 
 class Secrets:
     """Provider Layers Secrets API object. Provides ways to populate