automation-entities 0.1.0__tar.gz

automation_entities-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Renken
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

automation_entities-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: automation-entities
+Version: 0.1.0
+Summary: Automate routines in a descriptive way
+Home-page: https://github.com/SudoVim/automation-entities
+Author: Michael Renken
+Author-email: Michael Renken <michaelarenken@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SudoVim/automation-entities
+Project-URL: Issues, https://github.com/SudoVim/automation-entities/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8, <4
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Automation Entities
+
+automation-entities is a package designed to color automated routines for
+maximum debugability. The purpose is to provide the tools to wrap different
+entities (web browser, REST API, terminal, etc) such that, when they're
+interacted with, it leaves a log trail that describes each interaction in
+enough detail that the user can go in after the fact and figure out what went
+wrong - if anything.

automation_entities-0.1.0/README.md

@@ -0,0 +1,8 @@
+# Automation Entities
+
+automation-entities is a package designed to color automated routines for
+maximum debugability. The purpose is to provide the tools to wrap different
+entities (web browser, REST API, terminal, etc) such that, when they're
+interacted with, it leaves a log trail that describes each interaction in
+enough detail that the user can go in after the fact and figure out what went
+wrong - if anything.

automation_entities-0.1.0/automation_entities/__init__.py

@@ -0,0 +1,3 @@
+"""
+module designed to interact with entities in an automated way
+"""

automation_entities-0.1.0/automation_entities/context.py

@@ -0,0 +1,232 @@
+"""
+The :mod:`automation_entities.context` module is primarily concerned with the
+:class:`Context` class. It contains the basic configuration and logging logic
+that will be expanded upon in the higher up :class:`entities.Entity` class.
+"""
+
+import collections.abc
+import json
+import os
+import typing
+
+
+class Subcontext:
+    """
+    object denoting a position lower down the context stack; this object
+    shouldn't be created directly but should be used by calling
+    :meth:`Context.subcontext`
+
+    .. autoattribute:: context
+    .. autoattribute:: log_position
+    """
+
+    #: the parent context
+    context: "Context"
+
+    #: the log position to save for the parent context
+    log_position: typing.Optional[int]
+
+    already_entered: bool
+
+    def __init__(self, context: "Context"):
+        self.context = context
+        self.log_position = None
+        self.already_entered = False
+
+    def log(self, msg: str) -> None:
+        """
+        Log given *msg* as a result of an interaction with this subcontext.
+        """
+        assert (
+            self.log_position is not None
+        ), "log must only be called in conjunction with __enter__"
+        self.context.log(msg)
+
+    def __enter__(self) -> "Subcontext":
+        assert not self.already_entered, "a subcontext may only be entered once"
+
+        self.log_position = self.context.log_position
+        self.already_entered = True
+        self.context.log_position += 1
+        return self
+
+    def __exit__(self, *args, **kwds) -> None:
+        assert (
+            self.log_position is not None
+        ), "__exit__ must only be called in conjunction with __enter__"
+
+        self.context.log_position = self.log_position
+        self.log_position = None
+
+
+class Context:
+    """
+    The Context is an object that provides a common entrypoint into which
+    all information surrounding the current automated routine is sent.
+
+    :param dict config_defaults: default configuration values to give to
+        the :attr:`config` object
+
+    .. autoattribute:: CONTEXT_DEPTH
+
+    .. autoattribute:: log_position
+    .. autoattribute:: config
+
+    .. automethod:: log
+    .. automethod:: subcontext
+    .. automethod:: set_config_file
+    """
+
+    #: the number of spaces to use when logging from this context
+    CONTEXT_DEPTH: int = 4
+
+    #: the current log position
+    log_position: int
+
+    subcontext_class: typing.Type["Subcontext"]
+
+    #: the configuration represented by this context
+    config: "Config"
+
+    def __init__(
+        self,
+        config_defaults: typing.Optional[dict] = None,
+        subcontext_class: typing.Optional[typing.Type["Subcontext"]] = None,
+    ) -> None:
+        self.log_position = 0
+        self.subcontext_class = subcontext_class or Subcontext
+        self.config = Config(defaults=config_defaults)
+
+    def log(self, message: str) -> None:
+        """
+        log given *message* to the context
+        """
+        spaces = " " * (self.log_position * self.CONTEXT_DEPTH)
+        print(f"{spaces}{message}")
+
+    def subcontext(self, message: str) -> Subcontext:
+        """
+        Log the given *message* to create a new subcontext. This method
+        returns a context manager that will increment the
+        :attr:`log_position` on *__enter__* and decrement it back on
+        *__exit__*::
+
+            >>> with ctx.subcontext("sub context"):
+            ...     ctx.log("subcontext message")
+            ...
+            sub context
+                subcontext message
+
+        :rtype: Subcontext
+        :returns: subcontext object
+        """
+        self.log(message)
+        return self.subcontext_class(self)
+
+    def set_config_file(self, filepath: str) -> None:
+        """
+        set config file to the given *filepath*
+        """
+        self.config.set_filepath(filepath)
+
+
+def patch_dict(original: dict, patch: dict) -> None:
+    """
+    Patch given *original* dict with the new *patch*. This function
+    recursively iterates over all keys in the patch and applies them to
+    existing keys in the original. It does not replace a sub-dict. Rather,
+    it recursively replaces its keys.
+    """
+    for k, v in patch.items():
+        if k not in original or not isinstance(v, dict):
+            original[k] = v
+        elif isinstance(v, dict):
+            patch_dict(original[k], v)
+
+
+class Config(collections.abc.MutableMapping):
+    """
+    The Config object represents the configuration of the current context.
+    It's used as a ``dict`` object and can be instantiated with default
+    values. If the :meth:`set_filepath` method is called, the :meth:`load`
+    and :meth:`persist` methods can be used to load configuration data from
+    the filepath and persist it to the filepath, respectively.
+
+    .. attribute:: filepath
+
+        ``str`` filepath containing the configuration
+
+    .. automethod:: patch
+    .. automethod:: set_filepath
+    .. automethod:: persist
+    .. automethod:: load
+    """
+
+    filepath: typing.Optional[str]
+    defaults: typing.Optional[dict]
+    _data: dict
+
+    def __init__(self, defaults: typing.Optional[dict] = None):
+        self.filepath = None
+        self.defaults = defaults
+        self._data = {}
+
+        if self.defaults is not None:
+            self.patch(self.defaults)
+
+    def patch(self, new_vals: dict) -> None:
+        """
+        patch given original ``dict`` with new values
+        """
+        patch_dict(self._data, new_vals)
+
+    def set_filepath(self, filepath: str) -> None:
+        """
+        set persistence filepath to *filepath*
+        """
+        self.filepath = filepath
+        self.load()
+
+    def persist(self) -> None:
+        """
+        persist new config to the file
+        """
+        assert self.filepath is not None, "filepath must be set before calling persist"
+
+        with open(self.filepath, "w") as fobj:
+            json.dump(
+                self._data,
+                fobj,
+                sort_keys=True,
+                indent=4,
+            )
+
+    def load(self) -> None:
+        """
+        load config from file
+        """
+        assert self.filepath is not None, "filepath must be set before calling load"
+
+        if os.path.isfile(self.filepath):
+            with open(self.filepath) as fobj:
+                self.patch(json.load(fobj))
+
+        self.persist()
+
+    def __getitem__(self, key: typing.Any) -> typing.Any:
+        return self._data.__getitem__(key)
+
+    def __setitem__(self, key: typing.Any, val: typing.Any) -> None:
+        self._data.__setitem__(key, val)
+
+    def __delitem__(self, key: typing.Any) -> None:
+        self._data.__delitem__(key)
+
+    def __iter__(self) -> typing.Iterator:
+        return self._data.__iter__()
+
+    def __len__(self) -> int:
+        return self._data.__len__()
+
+
+background = Context()

automation_entities-0.1.0/automation_entities/entities.py

@@ -0,0 +1,139 @@
+"""
+An entity is something that can be interacted with. This abstraction will be
+used as a way to log interactions with remote components.
+"""
+
+import functools
+import time
+from typing import Any, Callable, Optional, TypeVar
+
+from .context import Context, Subcontext
+
+D = TypeVar("D", bound=Callable)
+
+
+def describe(fcn: D) -> D:
+    """
+    Decorator for :class:`Entity` instance methods that will describe the
+    method call to the entity's context on entrance and print its return
+    value on exit.
+    """
+
+    @functools.wraps(fcn)
+    def inner(self: "Entity", *args, **kwds) -> Any:
+        assert isinstance(self, Entity), "received invalid 'self' value type"
+
+        arg_toks = [repr(a) for a in args] + [f"{k}={repr(v)}" for k, v in kwds.items()]
+        arg_str = ", ".join(arg_toks)
+        if len(arg_str) > 100:
+            arg_str = arg_str[:97] + "..."
+        with self.context.subcontext(f"{fcn.__qualname__}({arg_str}):") as sctx:
+            ret = fcn(self, *args, **kwds)
+            ret_str = repr(ret)
+            if len(ret_str) > 100:
+                ret_str = ret_str[:97] + "..."
+            sctx.log(f"Return: {ret_str}")
+            return ret
+
+    return inner
+
+
+class SubInteraction(object):
+    """
+    Context manager that surrounds a sub-interaction of an entity. This
+    class shouldn't be instantiated on its own but should instead be
+    returned by calling :meth:`Entity.request` or :meth:`Entity.result`.
+
+    .. automethod:: log
+    """
+
+    context: Context
+    entity: "Entity"
+
+    def __init__(
+        self,
+        context: Context,
+        entity: "Entity",
+        delimeter: str,
+        message: Optional[str] = None,
+    ):
+        self.context = context
+        self.entity = entity
+
+        text = delimeter
+        if message:
+            text += f" {message}"
+
+        self.subcontext = self.context.subcontext(text)
+
+    def __enter__(self) -> "SubInteraction":
+        self.subcontext.__enter__()
+        return self
+
+    def __exit__(self, *args, **kwds) -> None:
+        self.subcontext.__exit__(*args, **kwds)
+
+    def log(self, msg: str) -> None:
+        """
+        log given *msg* as a result of an interaction with an entity
+        """
+        self.subcontext.log(msg)
+
+
+class Entity(object):
+    """
+    This class serves as a base for any object who's purpose is to interact
+    with an entity for automation purposes. With this class, any interaction
+    with the entity can be described in such a way where the automated
+    routine can be debugged after the fact without the need to reproduce it.
+
+    :param Context context: context to associate with this entity
+    :param str name: name of this entity to use in logging
+
+    .. autoattribute:: context
+    .. autoattribute:: name
+
+    .. automethod:: interaction
+    .. automethod:: request
+    .. automethod:: result
+    .. automethod:: sleep
+    """
+
+    #: object representing the relevant context for this entity
+    context: Context
+
+    #: name of the entity
+    name: str
+
+    def __init__(self, context: Context, name: str):
+        self.context = context
+        self.name = name
+
+    def interaction(self) -> "Subcontext":
+        """
+        log an interaction with the entity; can be used as a context manager
+        or not
+        """
+        return self.context.subcontext(f"{self.name}:")
+
+    def request(self, msg: Optional[str] = None) -> "SubInteraction":
+        """
+        log an interaction request; use as a context manager to
+        return a :class:`SubInteraction` instance
+        """
+        return SubInteraction(self.context, self, "<<<", message=msg)
+
+    def result(self, msg: Optional[str] = None) -> "SubInteraction":
+        """
+        log the result of an interaction; use as a context manager to
+        return a :class:`SubInteraction` instance
+        """
+        return SubInteraction(self.context, self, ">>>", message=msg)
+
+    def sleep(self, sleep_time: float) -> None:
+        """
+        Sleep for the given *sleep_time* amount of seconds.
+        """
+        with self.interaction():
+            self.request(f"sleep {sleep_time}")
+            time.sleep(sleep_time)

automation_entities-0.1.0/automation_entities/rest.py

@@ -0,0 +1,61 @@
+from typing import Any
+
+import requests
+
+from .context import Context
+from .entities import Entity
+
+
+class RestEntity(Entity):
+    """
+    entity for interacting with a REST API
+
+    .. attribute:: base_url
+
+        ``str`` representing the base URL of the REST API endpoint
+    """
+
+    def __init__(self, context: Context, base_url: str) -> None:
+        self.context = context
+        self.base_url = base_url
+        super().__init__(context, self.base_url)
+
+    def build_url(self, path: str) -> str:
+        """
+        build URL by appending the given *path* to the end of the
+        :attr:`base_url`
+        """
+        return self.base_url.rstrip("/") + "/" + path.lstrip("/")
+
+    def new_request(self, method: str, path: str, **kwds: Any) -> requests.Request:
+        """
+        create and return a new :class:`requests.Request` instance with the
+        given parameters
+        """
+        return requests.Request(method, self.build_url(path), **kwds)
+
+    def send_request(self, request: requests.PreparedRequest) -> requests.Response:
+        """
+        send the given :class:`requests.Request` or
+        :class:`requests.PreparedRequest`
+        """
+        with self.interaction():
+            self.request(f"{request.method} {request.url}")
+
+            session = requests.Session()
+            resp = session.send(request)
+            with self.result() as result:
+                result.log(resp.content.decode())
+                return resp
+
+    def assert_send_request(
+        self, request: requests.PreparedRequest
+    ) -> requests.Response:
+        """
+        send the given :class:`requests.Request` or
+        :class:`requests.PreparedRequest` and assert on its status code
+        """
+        resp = self.send_request(request)
+        if resp.status_code < 200 or resp.status_code >= 400:
+            raise AssertionError(f"[{resp.status_code}] {resp.text}")
+        return resp

automation_entities-0.1.0/automation_entities/utils.py

@@ -0,0 +1,105 @@
+"""
+The :mod:`utilities` module contains utilities for the automation_entities
+library - namely, the :func:`try_timeout` function.
+"""
+
+import time
+from typing import Callable, Final, Optional, Tuple, Type, TypeVar
+
+#: default value to display for a :class:`SecretString`
+SECRET_STRING_DISPLAY: Final[str] = "'" + ("*" * 10) + "'"
+
+
+class SecretString(str):
+    """
+    string that should be displayed as a sequence of asterisks. These will
+    not show up in entity logs.
+    """
+
+    def __repr__(self) -> str:
+        return SECRET_STRING_DISPLAY
+
+
+Timeout = Optional[float]
+
+#: default timeout value for :func:`try_timeout`
+DEFAULT_TIMEOUT: Final[float] = 60.0
+
+#: default step value for :func:`try_timeout`
+DEFAULT_STEP: Final[float] = 1.0
+
+#: default step backoff exponent for :func:`try_timeout`
+DEFAULT_STEP_EXP: Final[float] = 2.0
+
+
+class TryAgain(Exception):
+    pass
+
+
+class TimedOut(AssertionError):
+    pass
+
+
+#: default tuple of exceptions to ignore for :func:`try_timeout`
+DEFAULT_IGNORE_EXCEPTIONS: Final[Tuple] = (TryAgain,)
+
+R = TypeVar("R")
+
+
+def try_timeout(
+    fcn: Callable[[], R],
+    timeout: Timeout = None,
+    step: Optional[float] = None,
+    step_exp: Optional[float] = None,
+    ignore_exceptions: Optional[Tuple[Type[Exception], ...]] = None,
+    retry_action: Optional[Callable[[], None]] = None,
+) -> R:
+    """
+    Try running the given function until a timeout is reached.
+
+        * If the function returns, the return value of the function will be
+          returned.
+        * If the function raises a :class:`TryAgain` exception, it will be
+          retried. Any other exception will be raised up to the calling
+          method unless *ignore_exceptions* is specified.
+        * If the timeout is reached, a :class:`TimedOut` exception will be
+          raised.
+
+    If arguments and keywords are desired in the function call, it's
+    recommended to use the :func:`functools.partial` function to generate a
+    function that includes the desired args and keywords.
+
+    :param fcn: function to call
+    :param Timeout timeout: number of seconds (or a fraction thereof) to
+        allow for the function to complete
+    :param float step: number of seconds (or a fraction thereof) to wait
+        between the first and second calls
+    :param float step_exp: exponent to use to calculate the next step for
+        exponential backoff of retries (or 1 for no exponential backoff)
+    :param tuple ignore_exceptions: subclasses of :class:`Exception` to
+        indicate that the function should be retried; if this value is
+        specified, :class:`TryAgain` needs to be appended if it's also to
+        be used to indicate the action should be retried
+    param retry_action: function to call before subsequent retries
+    """
+    timeout = timeout or DEFAULT_TIMEOUT
+    step = step or DEFAULT_STEP
+    step_exp = step_exp or DEFAULT_STEP_EXP
+    ignore_exceptions = ignore_exceptions or (TryAgain,)
+    start_time = time.time()
+    while True:
+        try:
+            return fcn()
+
+        except Exception as e:
+            if not isinstance(e, ignore_exceptions):
+                raise
+
+            curr_time = time.time()
+            if curr_time < start_time or curr_time > start_time + timeout:
+                raise TimedOut("timeout reached")
+
+            time.sleep(min(step, (start_time + timeout) - curr_time))
+            step *= step_exp
+            if retry_action is not None:
+                retry_action()

automation_entities-0.1.0/automation_entities/web_browser/__init__.py

@@ -0,0 +1,7 @@
+"""
+Module for interacting with web page as a web browser.
+"""
+
+from .web_browser import Element, WebBrowser
+
+__all__ = ["Element", "WebBrowser"]