localstack-core 4.6.1.dev60__py3-none-any.whl → 4.10.1.dev12__py3-none-any.whl

localstack/utils/scheduler.py

@@ -1,8 +1,9 @@
 import queue
 import threading
 import time
+from collections.abc import Callable, Mapping
 from concurrent.futures import Executor
-from typing import Any, Callable, List, Mapping, Optional, Tuple, Union
+from typing import Any
 
 
 class ScheduledTask:
@@ -13,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
@@ -26,8 +27,8 @@ class ScheduledTask:
         self.period = period
         self.start = start
         self.on_error = on_error
-        self.args = args or tuple()
-        self.kwargs = kwargs or dict()
+        self.args = args or ()
+        self.kwargs = kwargs or {}
 
         self.deadline = None
         self.error = None
@@ -75,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
@@ -93,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()
@@ -44,9 +43,9 @@ class Server(abc.ABC):
 
     @property
     def url(self):
-        return "%s://%s:%s" % (self.protocol, self.host, self.port)
+        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 Dict, List, 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
@@ -42,7 +41,7 @@ def to_bytes(obj: Union[str, bytes], encoding: str = DEFAULT_ENCODING, errors="s
 
 def truncate(data: str, max_length: int = 100) -> str:
     data = str(data or "")
-    return ("%s..." % data[:max_length]) if len(data) > max_length else data
+    return (f"{data[:max_length]}...") if len(data) > max_length else data
 
 
 def is_string(s, include_unicode=True, exclude_binary=False):
@@ -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
 
@@ -104,11 +103,11 @@ def convert_to_printable_chars(value: Union[List, Dict, str]) -> str:
 
 
 def first_char_to_lower(s: str) -> str:
-    return s and "%s%s" % (s[0].lower(), s[1:])
+    return s and f"{s[0].lower()}{s[1:]}"
 
 
 def first_char_to_upper(s: str) -> str:
-    return s and "%s%s" % (s[0].upper(), s[1:])
+    return s and f"{s[0].upper()}{s[1:]}"
 
 
 def str_to_bool(value):
@@ -121,13 +120,13 @@ def str_to_bool(value):
 
 def str_insert(string, index, content):
     """Insert a substring into an existing string at a certain index."""
-    return "%s%s%s" % (string[:index], content, string[index:])
+    return f"{string[:index]}{content}{string[index:]}"
 
 
 def str_remove(string, index, end_index=None):
     """Remove a substring from an existing string at a certain from-to index range."""
     end_index = end_index or (index + 1)
-    return "%s%s" % (string[:index], string[end_index:])
+    return f"{string[:index]}{string[end_index:]}"
 
 
 def str_startswith_ignore_case(value: str, prefix: str) -> bool:
@@ -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,18 +1,20 @@
-from typing import Dict, List, Optional
+class TaggingService:
+    key_field: str
+    value_field: str
 
+    tags: dict[str, dict[str, str]]
 
-class TaggingService:
-    def __init__(self, key_field: str = None, value_field: str = None):
+    def __init__(self, key_field: str = "Key", value_field: str = "Value"):
         """
         :param key_field: the field name representing the tag key as used by botocore specs
         :param value_field: the field name representing the tag value as used by botocore specs
         """
-        self.key_field = key_field or "Key"
-        self.value_field = value_field or "Value"
+        self.key_field = key_field
+        self.value_field = value_field
 
         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 = []
@@ -21,7 +23,7 @@ class TaggingService:
                 result.append({self.key_field: k, self.value_field: v})
         return {root_name: result}
 
-    def tag_resource(self, arn: str, tags: List[Dict[str, str]]):
+    def tag_resource(self, arn: str, tags: list[dict[str, str]]):
         if not tags:
             return
         if arn not in self.tags:
@@ -29,7 +31,7 @@ class TaggingService:
         for t in tags:
             self.tags[arn][t[self.key_field]] = t[self.value_field]
 
-    def untag_resource(self, arn: str, tag_names: List[str]):
+    def untag_resource(self, arn: str, tag_names: list[str]):
         tags = self.tags.get(arn, {})
         for name in tag_names:
             tags.pop(name, None)

localstack/utils/testutil.py

@@ -7,7 +7,8 @@ import re
 import shutil
 import tempfile
 import time
-from typing import Any, Callable, Dict, List, 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
@@ -71,7 +72,7 @@ def is_local_test_mode():
 def create_lambda_archive(
     script: str,
     get_content: bool = False,
-    libs: List[str] = None,
+    libs: list[str] = None,
     runtime: str = None,
     file_name: str = None,
     exclude_func: Callable[[str], bool] = None,
@@ -94,7 +95,7 @@ def create_lambda_archive(
         chmod_r(script_file, 0o777)
         # copy libs
         for lib in libs:
-            paths = [lib, "%s.py" % lib]
+            paths = [lib, f"{lib}.py"]
             try:
                 module = importlib.import_module(lib)
                 paths.append(module.__file__)
@@ -255,7 +256,7 @@ def create_lambda_function(
         "Role": role or LAMBDA_TEST_ROLE.format(account_id=TEST_AWS_ACCOUNT_ID),
         "Code": lambda_code,
         "Timeout": timeout or LAMBDA_TIMEOUT_SEC,
-        "Environment": dict(Variables=envvars),
+        "Environment": {"Variables": envvars},
         "Tags": tags,
     }
     kwargs.update(additional_kwargs)
@@ -382,7 +383,7 @@ def assert_object(expected_object, all_objects):
         all_objects = [all_objects]
     found = find_object(expected_object, all_objects)
     if not found:
-        raise Exception("Expected object not found: %s in list %s" % (expected_object, all_objects))
+        raise Exception(f"Expected object not found: {expected_object} in list {all_objects}")
 
 
 def find_object(expected_object, object_list):
@@ -425,7 +426,7 @@ def list_all_s3_objects(s3_client):
     return map_all_s3_objects(s3_client=s3_client).values()
 
 
-def delete_all_s3_objects(s3_client, buckets: str | List[str]):
+def delete_all_s3_objects(s3_client, buckets: str | list[str]):
     buckets = ensure_list(buckets)
     for bucket in buckets:
         keys = all_s3_object_keys(s3_client, bucket)
@@ -444,15 +445,15 @@ def download_s3_object(s3_client, bucket, path):
     return result
 
 
-def all_s3_object_keys(s3_client, bucket: str) -> List[str]:
+def all_s3_object_keys(s3_client, bucket: str) -> list[str]:
     response = s3_client.list_objects_v2(Bucket=bucket)
     keys = [obj["Key"] for obj in response.get("Contents", [])]
     return keys
 
 
 def map_all_s3_objects(
-    s3_client, to_json: bool = True, buckets: str | List[str] = None
-) -> Dict[str, Any]:
+    s3_client, to_json: bool = True, buckets: str | list[str] = None
+) -> dict[str, Any]:
     result = {}
     buckets = ensure_list(buckets)
     if not buckets:
@@ -499,7 +500,7 @@ def send_update_dynamodb_ttl_request(table_name, ttl_status):
 def send_dynamodb_request(path, action, request_body):
     headers = {
         "Host": "dynamodb.amazonaws.com",
-        "x-amz-target": "DynamoDB_20120810.{}".format(action),
+        "x-amz-target": f"DynamoDB_20120810.{action}",
         "Authorization": mock_aws_request_headers(
             "dynamodb", aws_access_key_id=TEST_AWS_ACCESS_KEY_ID, region_name=TEST_AWS_REGION_NAME
         )["Authorization"],
@@ -509,7 +510,7 @@ def send_dynamodb_request(path, action, request_body):
 
 
 def get_lambda_log_group_name(function_name):
-    return "/aws/lambda/{}".format(function_name)
+    return f"/aws/lambda/{function_name}"
 
 
 # TODO: make logs_client mandatory
@@ -522,8 +523,7 @@ def check_expected_lambda_log_events_length(
     events = [line for line in events if line not in ["\x1b[0m", "\\x1b[0m"]]
     if len(events) != expected_length:
         print(
-            "Invalid # of Lambda %s log events: %s / %s: %s"
-            % (
+            "Invalid # of Lambda {} log events: {} / {}: {}".format(
                 function_name,
                 len(events),
                 expected_length,
@@ -537,7 +537,7 @@ def check_expected_lambda_log_events_length(
     return events
 
 
-def list_all_log_events(log_group_name: str, logs_client=None) -> List[Dict]:
+def list_all_log_events(log_group_name: str, logs_client=None) -> list[dict]:
     logs = logs_client or connect_to().logs
     return list_all_resources(
         lambda kwargs: logs.filter_log_events(logGroupName=log_group_name, **kwargs),
@@ -549,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,
 ):
@@ -597,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, List, 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
@@ -153,7 +153,7 @@ def cleanup_threads_and_processes(quiet=True):
     TMP_PROCESSES.clear()
 
 
-def parallelize(func: Callable, arr: List, size: int = None):
+def parallelize(func: Callable, arr: list, size: int = None):
     if not size:
         size = len(arr)
     if size <= 0:

localstack/utils/time.py

@@ -1,6 +1,6 @@
 import time
 from datetime import date, datetime, timezone, tzinfo
-from typing import Optional
+from zoneinfo import ZoneInfo
 
 TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S"
 TIMESTAMP_FORMAT_TZ = "%Y-%m-%dT%H:%M:%SZ"
@@ -42,6 +42,11 @@ def epoch_timestamp() -> float:
 
 
 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,
@@ -49,13 +54,16 @@ def parse_timestamp(ts_str: str) -> datetime:
         TIMESTAMP_READABLE_FORMAT,
     ]:
         try:
-            return datetime.strptime(ts_str, ts_format)
+            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("Unable to parse timestamp string with any known formats: %s" % ts_str)
+    raise Exception(f"Unable to parse timestamp string with any known formats: {ts_str}")
 
 
-def now(millis: bool = False, tz: Optional[tzinfo] = None) -> int:
+def now(millis: bool = False, tz: tzinfo | None = None) -> int:
     return mktime(datetime.now(tz=tz), millis=millis)
 
 

localstack/utils/urls.py

@@ -1,5 +1,3 @@
-from typing import Optional
-
 from localstack import config
 from localstack.config import HostAndPort
 
@@ -12,7 +10,7 @@ def hostname_from_url(url: str) -> str:
     return url.split("://")[-1].split("/")[0].split(":")[0]
 
 
-def localstack_host(custom_port: Optional[int] = None) -> HostAndPort:
+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)

localstack/utils/xml.py

@@ -9,7 +9,7 @@ def obj_to_xml(obj: Any) -> str:
     if isinstance(obj, list):
         return "".join([obj_to_xml(o) for o in obj])
     if isinstance(obj, dict):
-        return "".join(["<{k}>{v}</{k}>".format(k=k, v=obj_to_xml(v)) for (k, v) in obj.items()])
+        return "".join([f"<{k}>{obj_to_xml(v)}</{k}>" for (k, v) in obj.items()])
     return str(obj)
 
 

localstack/utils/xray/traceid.py

@@ -29,7 +29,7 @@ class TraceId:
         """
         Convert TraceId object to a string.
         """
-        return "%s%s%s%s%s" % (
+        return "{}{}{}{}{}".format(
             TraceId.VERSION,
             TraceId.DELIMITER,
             format(self.start_time, "x"),