biotite 1.5.0__cp314-cp314-macosx_11_0_arm64.whl

biotite/__init__.py

@@ -0,0 +1,18 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+This is the top-level package of *Biotite*.
+Although it does not provide useful functionality for most users,
+it does provide utilities and base classes used by a lot of *Biotite*'s
+modules.
+"""
+
+__name__ = "biotite"
+__author__ = "Patrick Kunzmann"
+
+from .copyable import *
+from .file import *
+from .version import __version__, __version_tuple__  # noqa: F401
+from .visualize import *

biotite/application/__init__.py

@@ -0,0 +1,69 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+A subpackage that provides interfaces for external software in case
+*Biotite*’s integrated functionality is not sufficient for your tasks.
+These interfaces range from locally installed software
+(e.g. MSA software) to web services (e.g. BLAST).
+The interfaces are seamless:
+Writing input files and reading output files is handled internally.
+The user only needs to provide objects like a :class:`Sequence`
+and will receive objects like an :class:`Alignment`.
+
+Note that in order to use an interface in :mod:`biotite.application`
+the corresponding software must be installed or the web server must be
+reachable, respectively.
+These programs are not shipped with the *Biotite* package.
+
+Each application is represented by its respective :class:`Application`
+class.
+Each :class:`Application` instance has a life cycle, starting with its
+creation and ending with the result extraction.
+Each state in this life cycle is described by the value of the
+*enum* :class:`AppState`, that each :class:`Application` contains:
+Directly after its instantiation the app is in the ``CREATED`` state.
+In this state further parameters can be set for the application run.
+After the user calls the :func:`Application.start()` method, the app
+state is set to ``RUNNING`` and the app performs the calculations.
+When the application finishes the AppState
+changes to ``FINISHED``.
+The user can now call the :func:`Application.join()` method, concluding
+the application in the ``JOINED`` state and making the results of the
+application accessible.
+Furthermore, this may trigger cleanup actions in some applications.
+:func:`Application.join()` can even be called in the ``RUNNING`` state:
+This will constantly check if the application has finished and will
+directly go into the ``JOINED`` state as soon as the application reaches
+the ``FINISHED`` state.
+Calling the :func:`Application.cancel()` method while the application is
+``RUNNING`` or ``FINISHED`` leaves the application in the ``CANCELLED``
+state.
+This triggers cleanup, too, but there are no accessible results.
+If a method is called in an unsuitable app state, an
+:class:`AppStateError` is called.
+At each state in the life cycle, :class:`Application` type specific
+methods are called, as shown in the following diagram.
+
+.. figure:: /static/assets/figures/app_lifecycle.png
+    :alt: Application life cycle
+    :scale: 50%
+
+    Taken from
+    `Kunzmann & Hamacher 2018 <https://doi.org/10.1186/s12859-018-2367-z>`_
+    licensed under `CC BY 4.0 <https://creativecommons.org/licenses/by/4.0/>`_.
+
+The execution of an :class:`Application` can run in parallel:
+The time between starting the run and collecting the results can be
+used to run other code, similar to the *Python* :class:`Thread` or
+:class:`Process` classes.
+"""
+
+__name__ = "biotite.application"
+__author__ = "Patrick Kunzmann"
+
+from .application import *
+from .localapp import *
+from .msaapp import *
+from .webapp import *

biotite/application/application.py

@@ -0,0 +1,276 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.application"
+__author__ = "Patrick Kunzmann"
+__all__ = [
+    "Application",
+    "AppStateError",
+    "TimeoutError",
+    "VersionError",
+    "AppState",
+    "requires_state",
+]
+
+import abc
+import time
+from enum import Flag, auto
+from functools import wraps
+
+
+class AppState(Flag):
+    """
+    This enum type represents the app states of an application.
+    """
+
+    CREATED = auto()
+    RUNNING = auto()
+    FINISHED = auto()
+    JOINED = auto()
+    CANCELLED = auto()
+
+
+def requires_state(app_state):
+    """
+    A decorator for methods of :class:`Application` subclasses that
+    raises an :class:`AppStateError` in case the method is called, when
+    the :class:`Application` is not in the specified :class:`AppState`
+    `app_state`.
+
+    Parameters
+    ----------
+    app_state : AppState
+        The required app state.
+
+    Examples
+    --------
+    Raises :class:`AppStateError` when `function` is called,
+    if :class:`Application` is not in one of the specified states:
+
+    >>> @requires_state(AppState.RUNNING | AppState.FINISHED)
+    ... def function(self):
+    ...     pass
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # First parameter of method is always 'self'
+            try:
+                instance = args[0]
+            except IndexError:
+                raise TypeError("This method must be called from a class instance")
+            if not instance._state & app_state:
+                raise AppStateError(
+                    f"The application is in {instance.get_app_state()} state, "
+                    f"but {app_state} state is required"
+                )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+class Application(metaclass=abc.ABCMeta):
+    """
+    This class is a wrapper around an external piece of runnable
+    software in any sense. Subclasses of this abstract base class
+    specify the respective kind of software and the way of interacting
+    with it.
+
+    Every :class:`Application` runs through a different app states
+    (instances of enum :class:`AppState`) from its creation until its
+    termination.
+
+    Directly after its instantiation the app is in the *CREATED* state.
+    In this state further parameters can be set for the application run.
+    After the user calls the :func:`start()` method, the app state is
+    set to *RUNNING* and the :class:`Application` type specific
+    :func:`run()` method is called.
+    When the application finishes the AppState changes to *FINISHED*.
+    This is checked via the :class:`Application` type specific
+    :func:`is_finished()` method.
+    The user can now call the :func:`join()` method, concluding the
+    application in the *JOINED* state and making the results of the
+    application accessible by executing the :class:`Application`
+    type specific :func:`evaluate()` method.
+    Furthermore this executes the :class:`Application` type specific
+    :func:`clean_up()` method.
+    :func:`join()` can even be called in the *RUNNING* state:
+    This will constantly check :func:`is_finished()` and will directly
+    go into the *JOINED* state as soon as the application reaches the
+    *FINISHED* state.
+    Calling the :func:`cancel()` method while the application is
+    *RUNNING* or *FINISHED* leaves the application in the *CANCELLED*
+    state.
+    This triggers the :func:`clean_up()` method, too, but there are no
+    accessible results.
+    If a method is called in an unsuitable app state, an
+    :class:`AppStateError` is called.
+
+    The application run behaves like an additional thread: Between the
+    call of :func:`start()` and :func:`join()` other Python code can be
+    executed, while the application runs in the background.
+    """
+
+    def __init__(self):
+        self._state = AppState.CREATED
+
+    @requires_state(AppState.CREATED)
+    def start(self):
+        """
+        Start the application run and set its state to *RUNNING*.
+        This can only be done from the *CREATED* state.
+        """
+        self.run()
+        self._start_time = time.time()
+        self._state = AppState.RUNNING
+
+    @requires_state(AppState.RUNNING | AppState.FINISHED)
+    def join(self, timeout=None):
+        """
+        Conclude the application run and set its state to *JOINED*.
+        This can only be done from the *RUNNING* or *FINISHED* state.
+
+        If the application is *FINISHED* the joining process happens
+        immediately, if otherwise the application is *RUNNING*, this
+        method waits until the application is *FINISHED*.
+
+        Parameters
+        ----------
+        timeout : float, optional
+            If this parameter is specified, the :class:`Application`
+            only waits for finishing until this value (in seconds) runs
+            out.
+            After this time is exceeded a :class:`TimeoutError` is
+            raised and the application is cancelled.
+
+        Raises
+        ------
+        TimeoutError
+            If the joining process exceeds the `timeout` value.
+        """
+        time.sleep(self.wait_interval())
+        while self.get_app_state() != AppState.FINISHED:
+            if timeout is not None and time.time() - self._start_time > timeout:
+                self.cancel()
+                raise TimeoutError(
+                    f"The application expired its timeout ({timeout:.1f} s)"
+                )
+            else:
+                time.sleep(self.wait_interval())
+        time.sleep(self.wait_interval())
+        try:
+            self.evaluate()
+        except AppStateError:
+            raise
+        except:
+            self._state = AppState.CANCELLED
+            raise
+        else:
+            self._state = AppState.JOINED
+        self.clean_up()
+
+    @requires_state(AppState.RUNNING | AppState.FINISHED)
+    def cancel(self):
+        """
+        Cancel the application when in *RUNNING* or *FINISHED* state.
+        """
+        self._state = AppState.CANCELLED
+        self.clean_up()
+
+    def get_app_state(self):
+        """
+        Get the current app state.
+
+        Returns
+        -------
+        app_state : AppState
+            The current app state.
+        """
+        if self._state == AppState.RUNNING:
+            if self.is_finished():
+                self._state = AppState.FINISHED
+        return self._state
+
+    @abc.abstractmethod
+    def run(self):
+        """
+        Commence the application run. Called in :func:`start()`.
+
+        PROTECTED: Override when inheriting.
+        """
+        pass
+
+    @abc.abstractmethod
+    def is_finished(self):
+        """
+        Check if the application has finished.
+
+        PROTECTED: Override when inheriting.
+
+        Returns
+        -------
+        finished : bool
+            True of the application has finished, false otherwise.
+        """
+        pass
+
+    @abc.abstractmethod
+    def wait_interval(self):
+        """
+        The time interval of :func:`is_finished()` calls in the joining
+        process.
+
+        PROTECTED: Override when inheriting.
+
+        Returns
+        -------
+        interval : float
+            Time (in seconds) between calls of :func:`is_finished()` in
+            :func:`join()`.
+        """
+        pass
+
+    @abc.abstractmethod
+    def evaluate(self):
+        """
+        Evaluate application results. Called in :func:`join()`.
+
+        PROTECTED: Override when inheriting.
+        """
+        pass
+
+    def clean_up(self):
+        """
+        Do clean up work after the application terminates.
+
+        PROTECTED: Optionally override when inheriting.
+        """
+        pass
+
+
+class AppStateError(Exception):
+    """
+    Indicate that the application lifecycle was violated.
+    """
+
+    pass
+
+
+class TimeoutError(Exception):
+    """
+    Indicate that the application's timeout expired.
+    """
+
+    pass
+
+
+class VersionError(Exception):
+    """
+    Indicate that the application's version is invalid.
+    """
+
+    pass

biotite/application/autodock/__init__.py

@@ -0,0 +1,12 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+A subpackage for static ligand docking with *Autodock*.
+"""
+
+__name__ = "biotite.application.autodock"
+__author__ = "Patrick Kunzmann"
+
+from .app import *