atex 0.7__py3-none-any.whl → 0.9__py3-none-any.whl

atex/provision/__init__.py

@@ -1,110 +1,94 @@
 import importlib as _importlib
 import pkgutil as _pkgutil
-import threading as _threading
 
 from .. import connection as _connection
 
 
 class Provisioner:
     """
-    A resource (machine/system) provider.
-
-    Any class derived from Provisioner serves as a mechanisms for requesting
-    a resource (machine/system), waiting for it to be reserved, providing ssh
-    details on how to connect to it, and releasing it when no longer useful.
-
-    The 4 main API points for this are reserve(), connection(), release() and
-    alive().
-    If necessary, these methods can share data via class instance attributes,
-    which are transparently guarded by a thread-aware mutex. For any complex
-    reads/writes, use 'self.lock' via a context manager.
-
-    Note that reserve() always runs in a separate thread (and thus may block),
-    and other functions (incl. release()) may be called at any time from
-    a different thread, even while reserve() is still running.
-    It is thus recommended for reserve() to store metadata in self.* as soon
-    as the metadata becomes available (some job ID, request UUID, Popen proc
-    object with PID, etc.) so that release() can free the resource at any time.
-
-    Once release()'d, the instance is never reused for reserve() again.
-    However connection(), release() and alive() may be called several times at
-    any time and need to handle it safely.
-    Ie. once released(), an instance must never return alive() == True.
-
-        # explicit method calls
-        res = Provisioner(...)
-        res.reserve()
-        conn = res.connection()
-        conn.connect()
-        conn.ssh('ls /')
-        conn.disconnect()
-        res.release()
-
-        # via a context manager
-        with Provisioner(...) as res:
-            with res.connection() as conn:
-                conn.ssh('ls /')
-
-    If a Provisioner class needs additional configuration, it should do so via
-    class (not instance) attributes, allowing it to be instantiated many times.
-
-        class ConfiguredProvisioner(Provisioner):
-            resource_hub = 'https://...'
-            login = 'joe'
-
-        # or dynamically
-        name = 'joe'
-        cls = type(
-            f'Provisioner_for_{name}',
-            (Provisioner,),
-            {'resource_hub': 'https://...', 'login': name},
-        )
-
-    These attributes can then be accessed from __init__ or any other function.
+    A remote resource (machine/system) provider.
+
+    The main interface is .get_remote() that returns a connected class Remote
+    instance for use by the user, to be .release()d when not needed anymore,
+    with Provisioner automatically getting a replacement for it, to be returned
+    via .get_remote() later.
+
+        p = Provisioner()
+        p.start()
+        remote = p.get_remote()
+        remote.cmd(["ls", "/"])
+        remote.release()
+        p.stop()
+
+        with Provisioner() as p:
+            remote = p.get_remote()
+            ...
+            remote.release()
+
+    TODO: mention how a Provisioner always needs to take care of release all Remotes
+          when .stop()ped or when context terminates; even the ones handed over to
+          the user
+
+    Note that .stop() or .defer_stop() may be called from a different
+    thread, asynchronously to any other functions.
     """
 
-    def __init__(self):
+    def get_remote(self, block=True):
         """
-        Initialize the provisioner instance.
-        If extending __init__, always call 'super().__init__()' at the top.
+        Get a connected class Remote instance.
+
+        If 'block' is True, wait for the remote to be available and connected,
+        otherwise return None if there is no Remote available yet.
         """
-        self.lock = _threading.RLock()
-
-#    def reserve(self):
-#        """
-#        Send a reservation request for a resource and wait for it to be
-#        reserved.
-#        """
-#        raise NotImplementedError(f"'reserve' not implemented for {self.__class__.__name__}")
-#
-#    def connection(self):
-#        """
-#        Return an atex.ssh.SSHConn instance configured for connection to
-#        the reserved resource, but not yet connected.
-#        """
-#        raise NotImplementedError(f"'connection' not implemented for {self.__class__.__name__}")
-#
-#    def release(self):
-#        """
-#        Release a reserved resource, or cancel a reservation-in-progress.
-#        """
-#        raise NotImplementedError(f"'release' not implemented for {self.__class__.__name__}")
-#
-#    def alive(self):
-#        """
-#        Return True if the resource is still reserved, False otherwise.
-#        """
-#        raise NotImplementedError(f"'alive' not implemented for {self.__class__.__name__}")
+        raise NotImplementedError(f"'get_remote' not implemented for {self.__class__.__name__}")
+
+    def start(self):
+        """
+        Start the Provisioner instance, start any provisioning-related
+        processes that lead to systems being reserved.
+        """
+        raise NotImplementedError(f"'start' not implemented for {self.__class__.__name__}")
+
+    def stop(self):
+        """
+        Stop the Provisioner instance, freeing all reserved resources,
+        calling .release() on all Remote instances that were created.
+        """
+        raise NotImplementedError(f"'stop' not implemented for {self.__class__.__name__}")
+
+    def stop_defer(self):
+        """
+        Enable an external caller to stop the Provisioner instance,
+        deferring resource deallocation to the caller.
+
+        Return an iterable of argument-free thread-safe callables that can be
+        called, possibly in parallel, to free up resources.
+        Ie. a list of 200 .release() functions, to be called in a thread pool
+        by the user, speeding up cleanup.
+        """
+        return (self.stop,)
+
+    def __enter__(self):
+        try:
+            self.start()
+            return self
+        except Exception:
+            self.stop()
+            raise
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.stop()
 
 
 class Remote(_connection.Connection):
     """
     Representation of a provisioned (reserved) remote system, providing
-    a Connection-like API in addition system management helpers.
+    a Connection-like API in addition to system management helpers.
 
-    An instance of Remote is typically prepared by a Provisioner and given
-    away for further use, to be .release()d by the user. It is not meant
-    for repeated reserve/release cycles, hence the lack of .reserve().
+    An instance of Remote is typically prepared by a Provisioner and lent out
+    for further use, to be .release()d by the user (if destroyed).
+    It is not meant for repeated reserve/release cycles, hence the lack
+    of .reserve().
 
     Also note that Remote can be used via Context Manager, but does not
     do automatic .release(), the manager only handles the built-in Connection.
@@ -114,27 +98,12 @@ class Remote(_connection.Connection):
     with a callback, or a try/finally block.
     """
 
-    # TODO: pass platform as arg ?
-    #def __init__(self, platform, *args, **kwargs):
-    #    """
-    #    Initialize a new Remote instance based on a Connection instance.
-    #    If extending __init__, always call 'super().__init__(conn)' at the top.
-    #    """
-    #    self.lock = _threading.RLock()
-    #    self.platform = platform
-
     def release(self):
         """
-        Release (de-provision) the remote resource, freeing resources.
+        Release (de-provision) the remote resource.
         """
         raise NotImplementedError(f"'release' not implemented for {self.__class__.__name__}")
 
-    def alive(self):
-        """
-        Return True if the remote resource is still valid and reserved.
-        """
-        raise NotImplementedError(f"'alive' not implemented for {self.__class__.__name__}")
-
 
 _submodules = [
     info.name for info in _pkgutil.iter_modules(__spec__.submodule_search_locations)

atex/provision/libvirt/__init__.py

@@ -1,24 +1,2 @@
-from .. import base
-from ... import util, ssh
-
-
-class LibvirtProvisioner(base.Provisioner):
-    number = 123
-
-    def reserve(self):
-        util.debug(f"reserving {self.number}")
-
-    # TODO: as simple attribute, to be guaranteed set when reserve() returns,
-    #       can be overriden by a getter function if you need to keep track
-    #       how many times it was accessed
-    def connection(self):
-        #return {"Hostname": "1.2.3.4", "User": "root", "IdentityFile": ...}
-        util.debug(f"returning ssh for {self.number}")
-        return ssh.SSHConn({"Hostname": "1.2.3.4", "User": "root"})
-
-    def release(self):
-        util.debug(f"releasing {self.number}")
-
-    def alive(self):
-        util.debug(f"always alive: {self.number}")
-        return True
+from . import locking  # noqa: F401
+from .libvirt import LibvirtCloningProvisioner, LibvirtCloningRemote  # noqa: F401