playground-ls-cli 4.14.1.dev8__py3-none-any.whl

localstack_cli/utils/sync.py

@@ -0,0 +1,267 @@
+"""Concurrency synchronization utilities"""
+
+import functools
+import threading
+import time
+from collections import defaultdict
+from collections.abc import Callable
+from typing import Literal, TypeVar
+
+
+class ShortCircuitWaitException(Exception):
+    """raise to immediately stop waiting, e.g. when an operation permanently failed"""
+
+    pass
+
+
+def wait_until(
+    fn: Callable[[], bool],
+    wait: float = 1.0,
+    max_retries: int = 10,
+    strategy: Literal["exponential", "static", "linear"] = "exponential",
+    _retries: int = 1,
+    _max_wait: float = 240,
+) -> bool:
+    """waits until a given condition is true, rechecking it periodically"""
+    assert _retries > 0
+    if max_retries < _retries:
+        return False
+    try:
+        completed = fn()
+    except ShortCircuitWaitException:
+        return False
+    except Exception:
+        completed = False
+
+    if completed:
+        return True
+    else:
+        if wait > _max_wait:
+            return False
+        time.sleep(wait)
+        next_wait = wait  # default: static
+        if strategy == "linear":
+            next_wait = (wait / _retries) * (_retries + 1)
+        elif strategy == "exponential":
+            next_wait = wait * 2
+        return wait_until(fn, next_wait, max_retries, strategy, _retries + 1, _max_wait)
+
+
+T = TypeVar("T")
+
+
+def retry(function: Callable[..., T], retries=3, sleep=1.0, sleep_before=0, **kwargs) -> T:
+    raise_error = None
+    if sleep_before > 0:
+        time.sleep(sleep_before)
+    retries = int(retries)
+    for i in range(0, retries + 1):
+        try:
+            return function(**kwargs)
+        except Exception as error:
+            raise_error = error
+            time.sleep(sleep)
+    raise raise_error
+
+
+def poll_condition(condition, timeout: float = None, interval: float = 0.5) -> bool:
+    """
+    Poll evaluates the given condition until a truthy value is returned. It does this every `interval` seconds
+    (0.5 by default), until the timeout (in seconds, if any) is reached.
+
+    Poll returns True once `condition()` returns a truthy value, or False if the timeout is reached.
+    """
+    remaining = 0
+    if timeout is not None:
+        remaining = timeout
+
+    while not condition():
+        if timeout is not None:
+            remaining -= interval
+
+            if remaining <= 0:
+                return False
+
+        time.sleep(interval)
+
+    return True
+
+
+def synchronized(lock=None):
+    """
+    Synchronization decorator as described in
+    http://blog.dscpl.com.au/2014/01/the-missing-synchronized-decorator.html.
+    """
+
+    def _decorator(wrapped):
+        @functools.wraps(wrapped)
+        def _wrapper(*args, **kwargs):
+            with lock:
+                return wrapped(*args, **kwargs)
+
+        return _wrapper
+
+    return _decorator
+
+
+def sleep_forever():
+    while True:
+        time.sleep(1)
+
+
+class SynchronizedDefaultDict(defaultdict):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._lock = threading.RLock()
+
+    def fromkeys(self, keys, value=None):
+        with self._lock:
+            return super().fromkeys(keys, value)
+
+    def __getitem__(self, key):
+        with self._lock:
+            return super().__getitem__(key)
+
+    def __setitem__(self, key, value):
+        with self._lock:
+            super().__setitem__(key, value)
+
+    def __delitem__(self, key):
+        with self._lock:
+            super().__delitem__(key)
+
+    def __iter__(self):
+        with self._lock:
+            return super().__iter__()
+
+    def __len__(self):
+        with self._lock:
+            return super().__len__()
+
+    def __str__(self):
+        with self._lock:
+            return super().__str__()
+
+
+class Once:
+    """
+    An object that will perform an action exactly once.
+    Inspired by Golang's [sync.Once](https://pkg.go.dev/sync#Once) operation.
+
+
+    ### Example 1
+
+    Multiple threads using `Once::do` to ensure only 1 line is printed.
+
+    ```python
+    import threading
+    import time
+    import random
+
+    greet_once = Once()
+    def greet():
+        print("This should happen only once.")
+
+    greet_threads = []
+    for _ in range(10):
+        t = threading.Thread(target=lambda: greet_once.do(greet))
+        greet_threads.append(t)
+        t.start()
+
+    for t in greet_threads:
+        t.join()
+    ```
+
+
+    ### Example 2
+
+    Ensuring idemponent calling to prevent exceptions on multiple calls.
+
+    ```python
+    import os
+
+    class Service:
+        close_once: sync.Once
+
+    def start(self):
+        with open("my-service.txt) as f:
+            myfile.write("Started service")
+
+    def close(self):
+        # Ensure we only ever delete the file once on close
+        self.close_once.do(lambda: os.remove("my-service.txt"))
+
+    ```
+
+
+    """
+
+    _is_done: bool = False
+    _mu: threading.Lock = threading.Lock()
+
+    def do(self, fn: Callable[[], None]):
+        """
+        `do` calls the function `fn()` if-and-only-if `do` has never been called before.
+
+        This ensures idempotent and thread-safe execution.
+
+        If the function raises an exception, `do` considers `fn` as done, where subsequent calls are still no-ops.
+        """
+        if self._is_done:
+            return
+
+        with self._mu:
+            if not self._is_done:
+                try:
+                    fn()
+                finally:
+                    self._is_done = True
+
+
+def once_func(fn: Callable[..., T]) -> Callable[..., T | None]:
+    """
+    Wraps and returns a function that can only ever execute once.
+
+    The first call to the returned function will permanently set the result.
+    If the wrapped function raises an exception, this will be re-raised on each subsequent call.
+
+    This function can be used either as a decorator or called directly.
+
+    Direct usage:
+    ```python
+    delete_file = once_func(os.remove)
+
+    delete_file("myfile.txt")  # deletes the file
+    delete_file("myfile.txt")  # does nothing
+    ```
+
+    As a decorator:
+    ```python
+    @once_func
+    def delete_file():
+        os.remove("myfile.txt")
+
+    delete_file()  # deletes the file
+    delete_file()  # does nothing
+    ```
+    """
+    once = Once()
+
+    result, exception = None, None
+
+    def _do(*args, **kwargs):
+        nonlocal result, exception
+        try:
+            result = fn(*args, **kwargs)
+        except Exception as e:
+            exception = e
+            raise
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        once.do(lambda: _do(*args, **kwargs))
+        if exception is not None:
+            raise exception
+        return result
+
+    return wrapper

localstack_cli/utils/threads.py

@@ -0,0 +1,163 @@
+import concurrent.futures
+import inspect
+import logging
+import threading
+import traceback
+from collections.abc import Callable
+from concurrent.futures import Future
+from multiprocessing.dummy import Pool
+
+LOG = logging.getLogger(__name__)
+
+# arrays for temporary threads and resources
+TMP_THREADS = []
+TMP_PROCESSES = []
+
+counter_lock = threading.Lock()
+counter = 0
+
+
+class FuncThread(threading.Thread):
+    """Helper class to run a Python function in a background thread."""
+
+    def __init__(
+        self,
+        func,
+        params=None,
+        quiet=False,
+        on_stop: Callable[["FuncThread"], None] = None,
+        name: str | None = None,
+        daemon=True,
+    ):
+        global counter
+        global counter_lock
+
+        if name:
+            with counter_lock:
+                counter += 1
+                thread_counter_current = counter
+
+            threading.Thread.__init__(
+                self, name=f"{name}-functhread{thread_counter_current}", daemon=daemon
+            )
+        else:
+            threading.Thread.__init__(self, daemon=daemon)
+
+        self.params = params
+        self.func = func
+        self.quiet = quiet
+        self.result_future = Future()
+        self._stop_event = threading.Event()
+        self.on_stop = on_stop
+
+    def run(self):
+        result = None
+        try:
+            kwargs = {}
+            argspec = inspect.getfullargspec(self.func)
+            if argspec.varkw or "_thread" in (argspec.args or []) + (argspec.kwonlyargs or []):
+                kwargs["_thread"] = self
+            result = self.func(self.params, **kwargs)
+        except Exception as e:
+            self.result_future.set_exception(e)
+            result = e
+            if not self.quiet:
+                LOG.info(
+                    "Thread run method %s(%s) failed: %s %s",
+                    self.func,
+                    self.params,
+                    e,
+                    traceback.format_exc(),
+                )
+        finally:
+            try:
+                self.result_future.set_result(result)
+                pass
+            except concurrent.futures.InvalidStateError as e:
+                # this can happen on shutdown if the task is already canceled
+                LOG.debug(e)
+
+    @property
+    def running(self):
+        return not self._stop_event.is_set()
+
+    def stop(self, quiet: bool = False) -> None:
+        self._stop_event.set()
+
+        if self.on_stop:
+            try:
+                self.on_stop(self)
+            except Exception as e:
+                LOG.warning("error while calling on_stop callback: %s", e)
+
+
+def start_thread(method, *args, **kwargs) -> FuncThread:  # TODO: find all usages and add names...
+    """Start the given method in a background thread, and add the thread to the TMP_THREADS shutdown hook"""
+    _shutdown_hook = kwargs.pop("_shutdown_hook", True)
+    if not kwargs.get("name"):
+        LOG.debug(
+            "start_thread called without providing a custom name"
+        )  # technically we should add a new level here for *internal* warnings
+    kwargs.setdefault("name", method.__name__)
+    thread = FuncThread(method, *args, **kwargs)
+    thread.start()
+    if _shutdown_hook:
+        TMP_THREADS.append(thread)
+    return thread
+
+
+def start_worker_thread(method, *args, **kwargs):
+    kwargs.setdefault("name", "start_worker_thread")
+    return start_thread(method, *args, _shutdown_hook=False, **kwargs)
+
+
+def cleanup_threads_and_processes(quiet=True):
+    from localstack_cli.utils.run import kill_process_tree
+
+    for thread in TMP_THREADS:
+        if thread:
+            try:
+                if hasattr(thread, "shutdown"):
+                    thread.shutdown()
+                    continue
+                if hasattr(thread, "kill"):
+                    thread.kill()
+                    continue
+                thread.stop(quiet=quiet)
+            except Exception as e:
+                LOG.debug("[shutdown] Error stopping thread %s: %s", thread, e)
+                if not thread.daemon:
+                    LOG.warning(
+                        "[shutdown] Non-daemon thread %s may block localstack shutdown", thread
+                    )
+    for proc in TMP_PROCESSES:
+        try:
+            kill_process_tree(proc.pid)
+            # proc.terminate()
+        except Exception as e:
+            LOG.debug("[shutdown] Error cleaning up process tree %s: %s", proc, e)
+    # clean up async tasks
+    try:
+        import asyncio
+
+        for task in asyncio.all_tasks():
+            try:
+                task.cancel()
+            except Exception as e:
+                LOG.debug("[shutdown] Error cancelling asyncio task %s: %s", task, e)
+    except Exception:
+        pass
+    LOG.debug("[shutdown] Done cleaning up threads / processes / tasks")
+    # clear lists
+    TMP_THREADS.clear()
+    TMP_PROCESSES.clear()
+
+
+def parallelize(func: Callable, arr: list, size: int = None):
+    if not size:
+        size = len(arr)
+    if size <= 0:
+        return None
+
+    with Pool(size) as pool:
+        return pool.map(func, arr)

localstack_cli/utils/time.py

@@ -0,0 +1,81 @@
+import time
+from datetime import date, datetime, timezone, tzinfo
+from zoneinfo import ZoneInfo
+
+TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S"
+TIMESTAMP_FORMAT_TZ = "%Y-%m-%dT%H:%M:%SZ"
+TIMESTAMP_FORMAT_MICROS = "%Y-%m-%dT%H:%M:%S.%fZ"
+TIMESTAMP_READABLE_FORMAT = "%d/%b/%Y:%H:%M:%S %z"
+
+
+def isoformat_milliseconds(t) -> str:
+    try:
+        return t.isoformat(timespec="milliseconds")
+    except TypeError:
+        return t.isoformat()[:-3]
+
+
+def timestamp(time=None, format: str = TIMESTAMP_FORMAT) -> str:
+    if not time:
+        time = datetime.utcnow()
+    if isinstance(time, (int, float)):
+        time = datetime.fromtimestamp(time)
+    return time.strftime(format)
+
+
+def timestamp_millis(time=None) -> str:
+    microsecond_time = timestamp(time=time, format=TIMESTAMP_FORMAT_MICROS)
+    # truncating microseconds to milliseconds, while leaving the "Z" indicator
+    return microsecond_time[:-4] + microsecond_time[-1]
+
+
+def iso1806_to_epoch(t: str) -> float:
+    return datetime.fromisoformat(t).timestamp()
+
+
+def epoch_to_iso1806(ts: int) -> str:
+    return datetime.utcfromtimestamp(ts).isoformat()
+
+
+def epoch_timestamp() -> float:
+    return time.time()
+
+
+def parse_timestamp(ts_str: str) -> datetime:
+    """
+    Parse the incoming date string into a timezone aware datetime object
+    :param ts_str:
+    :return:
+    """
+    for ts_format in [
+        TIMESTAMP_FORMAT,
+        TIMESTAMP_FORMAT_TZ,
+        TIMESTAMP_FORMAT_MICROS,
+        TIMESTAMP_READABLE_FORMAT,
+    ]:
+        try:
+            value = datetime.strptime(ts_str, ts_format)
+            if value.tzinfo is None:
+                value = value.replace(tzinfo=ZoneInfo("UTC"))
+            return value
+        except ValueError:
+            pass
+    raise Exception(f"Unable to parse timestamp string with any known formats: {ts_str}")
+
+
+def now(millis: bool = False, tz: tzinfo | None = None) -> int:
+    return mktime(datetime.now(tz=tz), millis=millis)
+
+
+def now_utc(millis: bool = False) -> int:
+    return now(millis, timezone.utc)
+
+
+def today_no_time() -> int:
+    return mktime(datetime.combine(date.today(), datetime.min.time()))
+
+
+def mktime(ts: datetime, millis: bool = False) -> int:
+    if millis:
+        return int(ts.timestamp() * 1000)
+    return int(ts.timestamp())

localstack_cli/utils/urls.py

@@ -0,0 +1,21 @@
+from localstack_cli import config
+from localstack_cli.config import HostAndPort
+
+
+def path_from_url(url: str) -> str:
+    return f"/{url.partition('://')[2].partition('/')[2]}" if "://" in url else url
+
+
+def hostname_from_url(url: str) -> str:
+    return url.split("://")[-1].split("/")[0].split(":")[0]
+
+
+def localstack_host(custom_port: int | None = None) -> HostAndPort:
+    """
+    Determine the host and port to return to the user based on:
+    - the user's configuration (e.g environment variable overrides)
+    - the defaults of the system
+    """
+    port = custom_port or config.LOCALSTACK_HOST.port
+    host = config.LOCALSTACK_HOST.host
+    return HostAndPort(host=host, port=port)

localstack_cli/utils/venv.py

@@ -0,0 +1,100 @@
+import io
+import os
+import sys
+from functools import cached_property
+from pathlib import Path
+from typing import Union
+
+
+class VirtualEnvironment:
+    """
+    Encapsulates methods to operate and navigate on a python virtual environment.
+    """
+
+    def __init__(self, venv_dir: Union[str, os.PathLike]):
+        self._venv_dir = venv_dir
+
+    def create(self) -> None:
+        """
+        Uses the virtualenv cli to create the virtual environment.
+        :return:
+        """
+        self.venv_dir.mkdir(parents=True, exist_ok=True)
+        from venv import main
+
+        main([str(self.venv_dir)])
+
+    @property
+    def exists(self) -> bool:
+        """
+        Checks whether the virtual environment exists by checking whether the site-package directory of the venv exists.
+        :return: the if the venv exists
+        :raises NotADirectoryError: if the venv path exists but is not a directory
+        """
+        try:
+            return True if self.site_dir else False
+        except FileNotFoundError:
+            return False
+
+    @cached_property
+    def venv_dir(self) -> Path:
+        """
+        Returns the path of the virtual environment directory
+        :return: the path to the venv
+        """
+        return Path(self._venv_dir).absolute()
+
+    @cached_property
+    def site_dir(self) -> Path:
+        """
+        Resolves and returns the site-packages directory of the virtual environment. Once resolved successfully the
+        result is cached.
+
+        :return: the path to the site-packages dir.
+        :raise FileNotFoundError: if the venv does not exist or the site-packages could not be found, or there are
+         multiple lib/python* directories.
+        :raise NotADirectoryError: if the venv is not a directory
+        """
+        venv = self.venv_dir
+
+        if not venv.exists():
+            raise FileNotFoundError(f"expected venv directory to exist at {venv}")
+
+        if not venv.is_dir():
+            raise NotADirectoryError(f"expected {venv} to be a directory")
+
+        matches = list(venv.glob("lib/python*/site-packages"))
+
+        if not matches:
+            raise FileNotFoundError(f"could not find site-packages directory in {venv}")
+
+        if len(matches) > 1:
+            raise FileNotFoundError(f"multiple python versions found in {venv}: {matches}")
+
+        return matches[0]
+
+    def inject_to_sys_path(self) -> None:
+        path = str(self.site_dir)
+        if path and path not in sys.path:
+            sys.path.append(path)
+
+    def add_pth(self, name, path: Union[str, os.PathLike, "VirtualEnvironment"]) -> None:
+        """
+        Add a <name>.pth file into the virtual environment and append the given path to it. Does nothing if the path
+        is already in the file.
+
+        :param name: the name of the path file (without the .pth extensions)
+        :param path: the path to be appended
+        """
+        pth_file = self.site_dir / f"{name}.pth"
+
+        if isinstance(path, VirtualEnvironment):
+            path = path.site_dir
+
+        line = io.text_encoding(str(path)) + "\n"
+
+        if pth_file.exists() and line in pth_file.read_text():
+            return
+
+        with open(pth_file, "a") as fd:
+            fd.write(line)

localstack_cli/utils/xml.py

@@ -0,0 +1,41 @@
+import xml.etree.ElementTree as ET
+from typing import Any
+
+
+def obj_to_xml(obj: Any) -> str:
+    """Return an XML representation of the given object (dict, list, or primitive).
+    Does NOT add a common root element if the given obj is a list.
+    Does NOT work for nested dict structures."""
+    if isinstance(obj, list):
+        return "".join([obj_to_xml(o) for o in obj])
+    if isinstance(obj, dict):
+        return "".join([f"<{k}>{obj_to_xml(v)}</{k}>" for (k, v) in obj.items()])
+    return str(obj)
+
+
+def strip_xmlns(obj: Any) -> Any:
+    """Strip xmlns attributes from a dict returned by xmltodict.parse."""
+    if isinstance(obj, list):
+        return [strip_xmlns(item) for item in obj]
+    if isinstance(obj, dict):
+        # Remove xmlns attribute.
+        obj.pop("@xmlns", None)
+        if len(obj) == 1 and "#text" in obj:
+            # If the only remaining key is the #text key, elide the dict
+            # entirely, to match the structure that xmltodict.parse would have
+            # returned if the xmlns namespace hadn't been present.
+            return obj["#text"]
+        return {k: strip_xmlns(v) for k, v in obj.items()}
+    return obj
+
+
+def is_valid_xml(xml_string: str) -> bool:
+    """
+    Check if the given string is a valid XML document.
+    """
+    try:
+        # Attempt to parse the XML string
+        ET.fromstring(xml_string.encode("utf-8"))
+        return True
+    except ET.ParseError:
+        return False

localstack_cli/version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '4.14.1.dev8'
+__version_tuple__ = version_tuple = (4, 14, 1, 'dev8')
+
+__commit_id__ = commit_id = None