localstack-core 4.7.1.dev139__py3-none-any.whl → 4.10.1.dev7__py3-none-any.whl

localstack/utils/json.py

@@ -5,7 +5,7 @@ import logging
 import os
 from datetime import date, datetime
 from json import JSONDecodeError
-from typing import Any, Union
+from typing import Any
 
 from localstack.config import HostAndPort
 
@@ -63,9 +63,9 @@ class FileMappedDocument(dict):
     concurrent writes, run load(). To save and overwrite the current document on disk, run save().
     """
 
-    path: Union[str, os.PathLike]
+    path: str | os.PathLike
 
-    def __init__(self, path: Union[str, os.PathLike], mode=0o664):
+    def __init__(self, path: str | os.PathLike, mode=0o664):
         super().__init__()
         self.path = path
         self.mode = mode
@@ -169,10 +169,24 @@ def extract_jsonpath(value, path):
     return result
 
 
-def assign_to_path(target, path: str, value, delimiter: str = "."):
+def assign_to_path(target: dict, path: str, value: any, delimiter: str = ".") -> dict:
+    """Assign the given value to a dict. If the path doesn't exist in the target dict, it will be created.
+    The delimiter can be used to provide a path with a different delimiter.
+
+    Examples:
+     - assign_to_path({}, "a", "b") => {"a": "b"}
+     - assign_to_path({}, "a.b.c", "d") => {"a": {"b": {"c": "d"}}}
+     - assign_to_path({}, "a.b/c", "d", delimiter="/") => {"a.b": {"c": "d"}}
+
+    """
     parts = path.strip(delimiter).split(delimiter)
+
+    if len(parts) == 1:
+        target[parts[0]] = value
+        return target
+
     path_to_parent = delimiter.join(parts[:-1])
-    parent = extract_from_jsonpointer_path(target, path_to_parent, auto_create=True)
+    parent = extract_from_jsonpointer_path(target, path_to_parent, delimiter, auto_create=True)
     if not isinstance(parent, dict):
         LOG.debug(
             'Unable to find parent (type %s) for path "%s" in object: %s',

localstack/utils/kinesis/kinesis_connector.py

@@ -6,7 +6,8 @@ import re
 import socket
 import tempfile
 import threading
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 from amazon_kclpy import kcl
 from amazon_kclpy.v2 import processor

localstack/utils/net.py

@@ -5,7 +5,7 @@ import socket
 import threading
 from collections.abc import MutableMapping
 from contextlib import closing
-from typing import Any, NamedTuple, Optional, Union
+from typing import Any, NamedTuple
 from urllib.parse import urlparse
 
 import dns.resolver
@@ -50,14 +50,14 @@ class Port(NamedTuple):
 
 
 # simple helper type to encapsulate int/Port argument types
-IntOrPort = Union[int, Port]
+IntOrPort = int | Port
 
 
 def is_port_open(
-    port_or_url: Union[int, str],
+    port_or_url: int | str,
     http_path: str = None,
     expect_success: bool = True,
-    protocols: Optional[Union[str, list[str]]] = None,
+    protocols: str | list[str] | None = None,
     quiet: bool = True,
 ):
     from localstack.utils.http import safe_requests
@@ -275,7 +275,7 @@ def get_free_tcp_port_range(num_ports: int, max_attempts: int = 50) -> "PortRang
     raise PortNotAvailableException("reached max_attempts when trying to find port range")
 
 
-def resolve_hostname(hostname: str) -> Optional[str]:
+def resolve_hostname(hostname: str) -> str | None:
     """Resolve the given hostname and return its IP address, or None if it cannot be resolved."""
     try:
         return socket.gethostbyname(hostname)
@@ -362,7 +362,7 @@ class PortRange:
         """
         return range(self.start, self.end + 1)
 
-    def reserve_port(self, port: Optional[IntOrPort] = None, duration: Optional[int] = None) -> int:
+    def reserve_port(self, port: IntOrPort | None = None, duration: int | None = None) -> int:
         """
         Reserves the given port (if it is still free). If the given port is None, it reserves a free port from the
         configured port range for external services. If a port is given, it has to be within the configured

localstack/utils/no_exit_argument_parser.py

@@ -1,6 +1,6 @@
 import argparse
 import logging
-from typing import NoReturn, Optional
+from typing import NoReturn
 
 LOG = logging.getLogger(__name__)
 
@@ -12,7 +12,7 @@ class NoExitArgumentParser(argparse.ArgumentParser):
     * ArgumentParser subclassing example: https://stackoverflow.com/a/59072378/6875981
     """
 
-    def exit(self, status: int = ..., message: Optional[str] = ...) -> NoReturn:
+    def exit(self, status: int = ..., message: str | None = ...) -> NoReturn:
         LOG.warning("Error in argument parser but preventing exit: %s", message)
 
     def error(self, message: str) -> NoReturn:

localstack/utils/numbers.py

@@ -1,4 +1,4 @@
-from typing import Any, Union
+from typing import Any
 
 
 def format_number(number: float, decimals: int = 2):
@@ -11,6 +11,13 @@ def format_number(number: float, decimals: int = 2):
 
 
 def is_number(s: Any) -> bool:
+    # booleans inherit from int
+    #
+    # >>> a.__class__.__mro__
+    # (<class 'bool'>, <class 'int'>, <class 'object'>)
+    if s is False or s is True:
+        return False
+
     try:
         float(s)  # for int, long and float
         return True
@@ -18,7 +25,7 @@ def is_number(s: Any) -> bool:
         return False
 
 
-def to_number(s: Any) -> Union[int, float]:
+def to_number(s: Any) -> int | float:
     """Cast the string representation of the given object to a number (int or float), or raise ValueError."""
     try:
         return int(str(s))

localstack/utils/objects.py

@@ -1,12 +1,13 @@
 import functools
 import re
 import threading
-from typing import Any, Callable, Generic, Optional, TypeVar, Union
+from collections.abc import Callable
+from typing import Any, Generic, TypeVar
 
 from .collections import ensure_list
 from .strings import first_char_to_lower, first_char_to_upper
 
-ComplexType = Union[list, dict, object]
+ComplexType = list | dict | object
 
 _T = TypeVar("_T")
 
@@ -16,7 +17,7 @@ class Value(Generic[_T]):
     Simple value container.
     """
 
-    value: Optional[_T]
+    value: _T | None
 
     def __init__(self, value: _T = None) -> None:
         self.value = value
@@ -30,7 +31,7 @@ class Value(Generic[_T]):
     def is_set(self) -> bool:
         return self.value is not None
 
-    def get(self) -> Optional[_T]:
+    def get(self) -> _T | None:
         return self.value
 
     def __bool__(self):
@@ -136,7 +137,7 @@ def fully_qualified_class_name(klass: type) -> str:
     return f"{klass.__module__}.{klass.__name__}"
 
 
-def not_none_or(value: Optional[Any], alternative: Any) -> Any:
+def not_none_or(value: Any | None, alternative: Any) -> Any:
     """Return 'value' if it is not None, or 'alternative' otherwise."""
     return value if value is not None else alternative
 

localstack/utils/patch.py

@@ -1,7 +1,8 @@
 import functools
 import inspect
 import types
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 
 def get_defining_object(method):

localstack/utils/run.py

@@ -7,9 +7,10 @@ import subprocess
 import sys
 import threading
 import time
+from collections.abc import Callable
 from functools import lru_cache
 from queue import Queue
-from typing import Any, AnyStr, Callable, Optional, Union
+from typing import Any, AnyStr
 
 from localstack import config
 
@@ -23,19 +24,19 @@ LOG = logging.getLogger(__name__)
 
 
 def run(
-    cmd: Union[str, list[str]],
+    cmd: str | list[str],
     print_error=True,
     asynchronous=False,
     stdin=False,
     stderr=subprocess.STDOUT,
     outfile=None,
-    env_vars: Optional[dict[AnyStr, AnyStr]] = None,
+    env_vars: dict[AnyStr, AnyStr] | None = None,
     inherit_cwd=False,
     inherit_env=True,
     tty=False,
     shell=True,
     cwd: str = None,
-) -> Union[str, subprocess.Popen]:
+) -> str | subprocess.Popen:
     LOG.debug("Executing command: %s", cmd)
     env_dict = os.environ.copy() if inherit_env else {}
     if env_vars:
@@ -202,7 +203,7 @@ def get_os_user() -> str:
     return run("whoami").strip()
 
 
-def to_str(obj: Union[str, bytes], errors="strict"):
+def to_str(obj: str | bytes, errors="strict"):
     return obj.decode(config.DEFAULT_ENCODING, errors) if isinstance(obj, bytes) else obj
 
 
@@ -211,9 +212,9 @@ class ShellCommandThread(FuncThread):
 
     def __init__(
         self,
-        cmd: Union[str, list[str]],
+        cmd: str | list[str],
         params: Any = None,
-        outfile: Union[str, int] = None,
+        outfile: str | int = None,
         env_vars: dict[str, str] = None,
         stdin: bool = False,
         auto_restart: bool = False,
@@ -223,8 +224,8 @@ class ShellCommandThread(FuncThread):
         log_listener: Callable = None,
         stop_listener: Callable = None,
         strip_color: bool = False,
-        name: Optional[str] = None,
-        cwd: Optional[str] = None,
+        name: str | None = None,
+        cwd: str | None = None,
     ):
         params = params if params is not None else {}
         env_vars = env_vars if env_vars is not None else {}

localstack/utils/scheduler.py

@@ -1,9 +1,9 @@
 import queue
 import threading
 import time
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from concurrent.futures import Executor
-from typing import Any, Callable, Optional, Union
+from typing import Any
 
 
 class ScheduledTask:
@@ -14,12 +14,12 @@ class ScheduledTask:
     def __init__(
         self,
         task: Callable,
-        period: Optional[float] = None,
+        period: float | None = None,
         fixed_rate: bool = True,
-        start: Optional[float] = None,
+        start: float | None = None,
         on_error: Callable[[Exception], None] = None,
-        args: Optional[Union[tuple, list]] = None,
-        kwargs: Optional[Mapping[str, Any]] = None,
+        args: tuple | list | None = None,
+        kwargs: Mapping[str, Any] | None = None,
     ) -> None:
         super().__init__()
         self.task = task
@@ -76,7 +76,7 @@ class Scheduler:
 
     POISON = (-1, "__POISON__")
 
-    def __init__(self, executor: Optional[Executor] = None) -> None:
+    def __init__(self, executor: Executor | None = None) -> None:
         """
         Creates a new Scheduler. If an executor is passed, then that executor will be used to run the scheduled tasks
         asynchronously, otherwise they will be executed synchronously inside the event loop. Running tasks
@@ -94,12 +94,12 @@ class Scheduler:
     def schedule(
         self,
         func: Callable,
-        period: Optional[float] = None,
+        period: float | None = None,
         fixed_rate: bool = True,
-        start: Optional[float] = None,
+        start: float | None = None,
         on_error: Callable[[Exception], None] = None,
-        args: Optional[Union[tuple, list[Any]]] = None,
-        kwargs: Optional[Mapping[str, Any]] = None,
+        args: tuple | list[Any] | None = None,
+        kwargs: Mapping[str, Any] | None = None,
     ) -> ScheduledTask:
         """
         Schedules a given task (function call).

localstack/utils/server/tcp_proxy.py

@@ -1,8 +1,8 @@
 import logging
 import select
 import socket
+from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor
-from typing import Callable
 
 from localstack.utils.serving import Server
 
@@ -93,7 +93,7 @@ class TCPProxy(Server):
                 try:
                     src_socket, _ = self._server_socket.accept()
                     self._thread_pool.submit(self._handle_request, src_socket)
-                except socket.timeout:
+                except TimeoutError:
                     pass
                 except OSError as e:
                     # avoid creating an error message if OSError is thrown due to socket closing

localstack/utils/serving.py

@@ -1,7 +1,6 @@
 import abc
 import logging
 import threading
-from typing import Optional
 
 from localstack.utils.net import is_port_open
 from localstack.utils.sync import poll_condition
@@ -21,7 +20,7 @@ class Server(abc.ABC):
 
     def __init__(self, port: int, host: str = "localhost") -> None:
         super().__init__()
-        self._thread: Optional[FuncThread] = None
+        self._thread: FuncThread | None = None
 
         self._lifecycle_lock = threading.RLock()
         self._stopped = threading.Event()
@@ -46,7 +45,7 @@ class Server(abc.ABC):
     def url(self):
         return f"{self.protocol}://{self.host}:{self.port}"
 
-    def get_error(self) -> Optional[Exception]:
+    def get_error(self) -> Exception | None:
         """
         If the thread running the server returned with an Exception, then this function will return that exception.
         """

localstack/utils/strings.py

@@ -7,7 +7,6 @@ import re
 import string
 import uuid
 import zlib
-from typing import Union
 
 from localstack.config import DEFAULT_ENCODING
 
@@ -28,13 +27,13 @@ REGEX_UNPRINTABLE_CHARS = re.compile(
 )
 
 
-def to_str(obj: Union[str, bytes], encoding: str = DEFAULT_ENCODING, errors="strict") -> str:
+def to_str(obj: str | bytes, encoding: str = DEFAULT_ENCODING, errors="strict") -> str:
     """If ``obj`` is an instance of ``binary_type``, return
     ``obj.decode(encoding, errors)``, otherwise return ``obj``"""
     return obj.decode(encoding, errors) if isinstance(obj, bytes) else obj
 
 
-def to_bytes(obj: Union[str, bytes], encoding: str = DEFAULT_ENCODING, errors="strict") -> bytes:
+def to_bytes(obj: str | bytes, encoding: str = DEFAULT_ENCODING, errors="strict") -> bytes:
     """If ``obj`` is an instance of ``text_type``, return
     ``obj.encode(encoding, errors)``, otherwise return ``obj``"""
     return obj.encode(encoding, errors) if isinstance(obj, str) else obj
@@ -86,7 +85,7 @@ def canonicalize_bool_to_str(val: bool) -> str:
     return "true" if str(val).lower() == "true" else "false"
 
 
-def convert_to_printable_chars(value: Union[list, dict, str]) -> str:
+def convert_to_printable_chars(value: list | dict | str) -> str:
     """Removes all unprintable characters from the given string."""
     from localstack.utils.objects import recurse_object
 
@@ -148,19 +147,19 @@ def long_uid() -> str:
     return str(uuid.uuid4())
 
 
-def md5(string: Union[str, bytes]) -> str:
+def md5(string: str | bytes) -> str:
     m = hashlib.md5()
     m.update(to_bytes(string))
     return m.hexdigest()
 
 
-def checksum_crc32(string: Union[str, bytes]) -> str:
+def checksum_crc32(string: str | bytes) -> str:
     bytes = to_bytes(string)
     checksum = zlib.crc32(bytes)
     return base64.b64encode(checksum.to_bytes(4, "big")).decode()
 
 
-def checksum_crc32c(string: Union[str, bytes]):
+def checksum_crc32c(string: str | bytes):
     # import botocore locally here to avoid a dependency of the CLI to botocore
     from botocore.httpchecksum import CrtCrc32cChecksum
 
@@ -169,7 +168,7 @@ def checksum_crc32c(string: Union[str, bytes]):
     return base64.b64encode(checksum.digest()).decode()
 
 
-def checksum_crc64nvme(string: Union[str, bytes]):
+def checksum_crc64nvme(string: str | bytes):
     # import botocore locally here to avoid a dependency of the CLI to botocore
     from botocore.httpchecksum import CrtCrc64NvmeChecksum
 
@@ -178,12 +177,12 @@ def checksum_crc64nvme(string: Union[str, bytes]):
     return base64.b64encode(checksum.digest()).decode()
 
 
-def hash_sha1(string: Union[str, bytes]) -> str:
+def hash_sha1(string: str | bytes) -> str:
     digest = hashlib.sha1(to_bytes(string)).digest()
     return base64.b64encode(digest).decode()
 
 
-def hash_sha256(string: Union[str, bytes]) -> str:
+def hash_sha256(string: str | bytes) -> str:
     digest = hashlib.sha256(to_bytes(string)).digest()
     return base64.b64encode(digest).decode()
 
@@ -192,7 +191,7 @@ def base64_to_hex(b64_string: str) -> bytes:
     return binascii.hexlify(base64.b64decode(b64_string))
 
 
-def base64_decode(data: Union[str, bytes]) -> bytes:
+def base64_decode(data: str | bytes) -> bytes:
     """Decode base64 data - with optional padding, and able to handle urlsafe encoding (containing -/_)."""
     data = to_str(data)
     missing_padding = len(data) % 4

localstack/utils/sync.py

@@ -4,7 +4,8 @@ import functools
 import threading
 import time
 from collections import defaultdict
-from typing import Callable, Literal, TypeVar
+from collections.abc import Callable
+from typing import Literal, TypeVar
 
 
 class ShortCircuitWaitException(Exception):
@@ -140,3 +141,127 @@ class SynchronizedDefaultDict(defaultdict):
     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/utils/tagging.py

@@ -1,6 +1,3 @@
-from typing import Optional
-
-
 class TaggingService:
     key_field: str
     value_field: str
@@ -17,7 +14,7 @@ class TaggingService:
 
         self.tags = {}
 
-    def list_tags_for_resource(self, arn: str, root_name: Optional[str] = None):
+    def list_tags_for_resource(self, arn: str, root_name: str | None = None):
         root_name = root_name or "Tags"
 
         result = []

localstack/utils/testutil.py

@@ -7,7 +7,8 @@ import re
 import shutil
 import tempfile
 import time
-from typing import Any, Callable, Optional
+from collections.abc import Callable
+from typing import Any
 
 from localstack.aws.api.lambda_ import Runtime
 from localstack.aws.connect import connect_externally_to, connect_to
@@ -20,7 +21,7 @@ from localstack.utils.urls import localstack_host
 try:
     from typing import Literal
 except ImportError:
-    from typing_extensions import Literal
+    from typing import Literal
 
 import boto3
 import requests
@@ -548,7 +549,7 @@ def list_all_log_events(log_group_name: str, logs_client=None) -> list[dict]:
 def get_lambda_log_events(
     function_name,
     delay_time=DEFAULT_GET_LOG_EVENTS_DELAY,
-    regex_filter: Optional[str] = None,
+    regex_filter: str | None = None,
     log_group=None,
     logs_client=None,
 ):
@@ -596,7 +597,7 @@ def list_all_resources(
     page_function: Callable[[dict], Any],
     last_token_attr_name: str,
     list_attr_name: str,
-    next_token_attr_name: Optional[str] = None,
+    next_token_attr_name: str | None = None,
 ) -> list:
     """
     List all available resources by loading all available pages using `page_function`.

localstack/utils/threads.py

@@ -3,9 +3,9 @@ import inspect
 import logging
 import threading
 import traceback
+from collections.abc import Callable
 from concurrent.futures import Future
 from multiprocessing.dummy import Pool
-from typing import Callable, Optional
 
 LOG = logging.getLogger(__name__)
 
@@ -26,7 +26,7 @@ class FuncThread(threading.Thread):
         params=None,
         quiet=False,
         on_stop: Callable[["FuncThread"], None] = None,
-        name: Optional[str] = None,
+        name: str | None = None,
         daemon=True,
     ):
         global counter