nui-python-shared-utils 2.0__py3-none-any.whl → 2.2__py3-none-any.whl

{nui_python_shared_utils-2.0.dist-info → nui_python_shared_utils-2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-python-shared-utils
-Version: 2.0
+Version: 2.2
 Summary: Shared Python utilities for AWS Lambda, CLI tools, and agents with Slack, Elasticsearch, and monitoring integrations
 Home-page: https://github.com/nuimarkets/nui-python-shared-utils
 Author: NUI Markets
@@ -49,11 +49,11 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: boto3>=1.20.0
-Requires-Dist: pytz>=2021.3
 Requires-Dist: click>=8.0.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: tzdata>=2023.3; platform_system == "Windows"
 Provides-Extra: elasticsearch
-Requires-Dist: elasticsearch<8.0.0,>=7.17.0; extra == "elasticsearch"
+Requires-Dist: elasticsearch<10.0.0,>=7.17.0; extra == "elasticsearch"
 Provides-Extra: database
 Requires-Dist: pymysql>=1.0.0; extra == "database"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "database"
@@ -64,12 +64,14 @@ Requires-Dist: aws-lambda-powertools<4.0.0,>=3.6.0; extra == "powertools"
 Requires-Dist: coloredlogs>=15.0; extra == "powertools"
 Provides-Extra: jwt
 Requires-Dist: rsa>=4.9; extra == "jwt"
+Provides-Extra: timezone
+Requires-Dist: tzdata>=2023.3; extra == "timezone"
 Provides-Extra: snowflake
 Requires-Dist: snowflake-sql-api<0.2.0,>=0.1.1; extra == "snowflake"
 Provides-Extra: llm
 Requires-Dist: anthropic[bedrock]<1.0.0,>=0.45.0; extra == "llm"
 Provides-Extra: all
-Requires-Dist: elasticsearch<8.0.0,>=7.17.0; extra == "all"
+Requires-Dist: elasticsearch<10.0.0,>=7.17.0; extra == "all"
 Requires-Dist: pymysql>=1.0.0; extra == "all"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
 Requires-Dist: slack-sdk>=3.19.0; extra == "all"
@@ -85,11 +87,11 @@ Requires-Dist: black>=22.0.0; extra == "dev"
 Requires-Dist: mypy>=0.990; extra == "dev"
 Requires-Dist: boto3-stubs[essential]>=1.20.0; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
-Requires-Dist: types-pytz>=2021.3.0; extra == "dev"
 Requires-Dist: twine>=4.0.0; extra == "dev"
 Requires-Dist: build>=0.8.0; extra == "dev"
 Requires-Dist: rsa>=4.9; extra == "dev"
 Requires-Dist: cryptography>=41.0.0; extra == "dev"
+Requires-Dist: tzdata>=2023.3; extra == "dev"
 Requires-Dist: snowflake-sql-api<0.2.0,>=0.1.1; extra == "dev"
 Requires-Dist: anthropic[bedrock]<1.0.0,>=0.45.0; extra == "dev"
 Dynamic: author

{nui_python_shared_utils-2.0.dist-info → nui_python_shared_utils-2.2.dist-info}/RECORD

@@ -1,12 +1,12 @@
-nui_python_shared_utils-2.0.dist-info/licenses/LICENSE,sha256=vGe2mC5yLUb8toYlY3T36ZwCB5zQUW5hlCtEMiqokhM,1071
-nui_shared_utils/__init__.py,sha256=vFS5oaw7_iHgHnLRifDYYyb7au6G2nYJ6ztqMs-hrQs,13289
+nui_python_shared_utils-2.2.dist-info/licenses/LICENSE,sha256=vGe2mC5yLUb8toYlY3T36ZwCB5zQUW5hlCtEMiqokhM,1071
+nui_shared_utils/__init__.py,sha256=wbm10x7THNbrCBGClWiWSVkTNxcBKcHZ-HjYpRQBFrk,13354
 nui_shared_utils/base_client.py,sha256=I1lKQGhrKyvujV2zps0TrtEdPDqMCwRQaIh6ceGONXQ,11016
 nui_shared_utils/cli.py,sha256=JJpSoQWKvAz4b8cO30yFNi5vY9jmqrCHzbFpvrVTkbU,8747
 nui_shared_utils/cloudwatch_metrics.py,sha256=p0J-s63UJDGK14TRGt0k8yoj7aWSSM55UKdgcuaT1dU,12098
 nui_shared_utils/config.py,sha256=ZbkUKDxnHMJiHNv-TlWKjotmf2mH1Vz3GaIXgGfWg7E,4524
 nui_shared_utils/db_client.py,sha256=HyVKJ1Su0dVPV1QI2MU5UtT8myDRCjKgV60xRL4SEdE,21726
 nui_shared_utils/error_handler.py,sha256=pJ6b_mI0Ait8QRbs9UmLzYUN-Ft0l_dnpudVO_6LRSE,12171
-nui_shared_utils/es_client.py,sha256=rLyexuL6_RXQpuMC4A2SeJDk30medx2qxOgWIG3A_7o,15765
+nui_shared_utils/es_client.py,sha256=3MlrbddTrRN2mEH1b3TNzcmwYycLdujoIq_5_j-Cyfc,16714
 nui_shared_utils/es_query_builder.py,sha256=UuheQf8b2UXaOiJlYCKYIfKfVERDZ3ag1P0OOOWm9do,12158
 nui_shared_utils/jwt_auth.py,sha256=2Ag1zZKxd2R8QBz3aQA4h8OtKHQvUVKrjUp6lXpJxJU,9143
 nui_shared_utils/lambda_helpers.py,sha256=psHVotpmOfnmyQCoOt4MSIEj7VwWcy6gZM3vYSZwjOk,3041
@@ -14,10 +14,10 @@ nui_shared_utils/llm.py,sha256=adNUO8Qbeb3__GvpROxWSUERkpiazKiGJFE5xzU5eZ0,8351
 nui_shared_utils/log_processors.py,sha256=x5gz1LEkbmoMCZ3ZB6q-mbn26dSzwh1trz4wSkBGxqk,5538
 nui_shared_utils/powertools_helpers.py,sha256=qc-lYLfY-QX20gALfPOJcihrtJhiCU-fJW8rsPT7LJE,11037
 nui_shared_utils/secrets_helper.py,sha256=_jQkMWzjayZ8vvyHG2yuuxur-SQYUUONfcsZ0MF8qOw,7025
-nui_shared_utils/slack_client.py,sha256=wXE0D4T4FWt1giz9Xmp71RustpaJYeLAZo6JxulDVko,25550
-nui_shared_utils/slack_formatter.py,sha256=95g6XfAJst7RVhd0M0ahiF3gWWW5j96WYkCg5tLS6Zg,10894
+nui_shared_utils/slack_client.py,sha256=jvkLeBMA8WHOqdRzCEpG42FfBlMeWue8bZ1g1ZxF-UI,40304
+nui_shared_utils/slack_formatter.py,sha256=QT9VXApE0q09n_PmEVvaLCSfLW24vmowlCXF3Dzimfk,10850
 nui_shared_utils/snowflake_client.py,sha256=e3jH6_2mMqbtP1TE8-mUFFYrfGW9eqUPT5tlcgeCqx8,16181
-nui_shared_utils/timezone.py,sha256=TvtSZV7w3Vvz3NbMTcJSNbUf0ZxPwpFS-xfgye1h-4Q,3583
+nui_shared_utils/timezone.py,sha256=gTiSK5NUG0Z8UY_AsB4ktIzLrZ0wwTXtdTUH-Npdvik,3837
 nui_shared_utils/utils.py,sha256=gOpw80tZGC24QsyesR8EySRODY-TFXG8cXUvggPBsRI,8184
 nui_shared_utils/logging/__init__.py,sha256=gVC853q3ja4RhcBVbf5jKO10lFX4upfsTvkKZx4wu54,1805
 nui_shared_utils/logging/binding.py,sha256=I5VNmtf4U2yt54aS4F0Djw4u22mfjwCpWvORUnJNkPU,13577
@@ -27,8 +27,8 @@ nui_shared_utils/slack_setup/__init__.py,sha256=OElyS3xk4F_YKH5uUUTDpN0ah1dOO3e5
 nui_shared_utils/slack_setup/channel_creator.py,sha256=0gyCBIS0EC96SVn1Z2dD4Fpzk0xNdHSWyiCxoUQIUe8,10667
 nui_shared_utils/slack_setup/channel_definitions.py,sha256=atfz5ZhpqefOeLh1gShbWd-TLzgjPmhv95bfuTdmZog,5676
 nui_shared_utils/slack_setup/setup_helpers.py,sha256=pzzXMs12GI9sdZttWeYzgLPgC0xqPz7ZLHM1GUPNNXc,7219
-nui_python_shared_utils-2.0.dist-info/METADATA,sha256=bK7P8bMGhOLpSyVQsZ3gwrWRZ6KZksIoAJIlj6V-qHM,22584
-nui_python_shared_utils-2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-nui_python_shared_utils-2.0.dist-info/entry_points.txt,sha256=TrJ3Z4kz3oXfy6InXn20jHu7rnTwo-4EA0KRFX3fkL0,66
-nui_python_shared_utils-2.0.dist-info/top_level.txt,sha256=YMRu5cnn3hxHoYq9wNvaI9atVHnTNVdswO5_cQSfnJI,17
-nui_python_shared_utils-2.0.dist-info/RECORD,,
+nui_python_shared_utils-2.2.dist-info/METADATA,sha256=QsygJarXaIbwKBA4-jRoTNQdsUHPvdgA0vtiVHWGsBw,22688
+nui_python_shared_utils-2.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+nui_python_shared_utils-2.2.dist-info/entry_points.txt,sha256=TrJ3Z4kz3oXfy6InXn20jHu7rnTwo-4EA0KRFX3fkL0,66
+nui_python_shared_utils-2.2.dist-info/top_level.txt,sha256=YMRu5cnn3hxHoYq9wNvaI9atVHnTNVdswO5_cQSfnJI,17
+nui_python_shared_utils-2.2.dist-info/RECORD,,

{nui_python_shared_utils-2.0.dist-info → nui_python_shared_utils-2.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (83.0.0)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

nui_shared_utils/__init__.py

@@ -87,6 +87,7 @@ _LAZY_EXPORTS = {
     "get_lambda_environment_info": ("lambda_helpers", "get_lambda_environment_info"),
     # Optional: Slack client (slack-sdk)
     "SlackClient": ("slack_client", "SlackClient"),
+    "SentMessage": ("slack_client", "SentMessage"),
     # Optional: Elasticsearch client + query builder
     "ElasticsearchClient": ("es_client", "ElasticsearchClient"),
     "ESQueryBuilder": ("es_query_builder", "ESQueryBuilder"),
@@ -265,7 +266,7 @@ if TYPE_CHECKING:
         extract_cloudwatch_logs_from_kinesis,
     )
     from .lambda_helpers import get_lambda_environment_info
-    from .slack_client import SlackClient
+    from .slack_client import SentMessage, SlackClient
     from .es_client import ElasticsearchClient
     from .es_query_builder import (
         ESQueryBuilder,

nui_shared_utils/es_client.py

@@ -97,24 +97,37 @@ class ElasticsearchClient(BaseClient, ServiceHealthMixin):
             retry_on_timeout=self.client_config.get("retry_on_timeout", True),
         )
 
+    @staticmethod
+    def _body_with_size(body: Dict, size: int) -> Dict:
+        """Return a copy of ``body`` carrying ``size``.
+
+        ``size`` travels inside the request body rather than as a sibling keyword
+        argument, which is the one call shape every supported client major accepts.
+        On elasticsearch-py 8.x/9.x, passing ``body=`` alongside a body field as a
+        keyword folds that keyword into the caller's dict (mutating it) and raises
+        ``ValueError`` if the key is already there, so reusing a body dict for two
+        searches breaks. A body that carries its own ``size`` is accepted unchanged
+        by 7.17, 8.x and 9.x, and leaves the caller's dict alone.
+        """
+        return {**body, "size": size}
+
     @handle_client_errors(default_return=[])
     def search(self, index: str, body: Dict, size: int = 100) -> List[Dict]:
         """
         Execute search query with error handling.
-        
+
         Args:
             index: Index pattern to search
             body: Elasticsearch query body
-            size: Maximum results to return
-            
+            size: Maximum results to return (overrides any ``size`` in ``body``)
+
         Returns:
             List of hit documents
         """
         def _search_operation():
             response = self._service_client.search(
                 index=index,
-                body=body,
-                size=size,
+                body=self._body_with_size(body, size),
                 ignore_unavailable=True
             )
             return [hit["_source"] for hit in response["hits"]["hits"]]
@@ -141,8 +154,7 @@ class ElasticsearchClient(BaseClient, ServiceHealthMixin):
         def _aggregate_operation():
             response = self._service_client.search(
                 index=index,
-                body=body,
-                size=0,  # Only need aggregations
+                body=self._body_with_size(body, 0),  # Only need aggregations
                 ignore_unavailable=True
             )
             return response.get("aggregations", {})
@@ -374,7 +386,9 @@ class ElasticsearchClient(BaseClient, ServiceHealthMixin):
                 format="json",
                 h="index,health,status,docs.count,store.size"
             )
-            return response or []
+            # 8.x/9.x return a response wrapper around the JSON array; normalise to
+            # a plain list so callers get the same type on every client major.
+            return list(response) if response else []
 
         return self._execute_with_error_handling(
             "get_indices_info",

nui_shared_utils/slack_client.py

@@ -4,10 +4,12 @@ Refactored Slack client using BaseClient for DRY code patterns.
 
 import os
 import logging
-from typing import Any, List, Dict, Optional
+from dataclasses import dataclass
+from typing import Any, List, Dict, Optional, Union
 from pathlib import Path
 from slack_sdk import WebClient
 from slack_sdk.errors import SlackApiError
+from slack_sdk.web.slack_response import SlackResponse
 from datetime import datetime
 
 try:
@@ -30,9 +32,60 @@ DEFAULT_ACCOUNT_NAMES = {
 }
 
 
+@dataclass(frozen=True)
+class SentMessage:
+    """Slack's answer to a ``chat.postMessage`` call.
+
+    ``ts`` is the handle Slack addresses a message by. Keep it to reply under
+    the message (:meth:`SlackClient.send_thread_reply`), edit it in place
+    (:meth:`SlackClient.update_message`) or annotate it
+    (:meth:`SlackClient.add_reaction`). Without it those three are unreachable,
+    which is why :meth:`SlackClient.post_message` exists alongside the
+    bool-returning :meth:`SlackClient.send_message`.
+
+    Truthiness follows ``ok``. Note that a SentMessage returned by
+    :meth:`SlackClient.post_message` against a real client is always ``ok``,
+    because ``slack_sdk`` raises on a rejection rather than returning one, so
+    ``if sent:`` is not a failure guard there. ``ok`` earns its place for a
+    client that does not validate, and for :meth:`SlackClient.send_message`,
+    which converts this type into its bool.
+
+    Attributes:
+        ok: Whether Slack accepted the message.
+        ts: Message timestamp, or None when Slack did not return one.
+        channel: Channel Slack recorded the message against. Worth keeping
+            rather than reusing the channel you passed: posting to a user ID
+            or channel name resolves to a different id than the one you sent.
+        response: The underlying ``slack_sdk`` response, for fields this type
+            does not name.
+    """
+
+    ok: bool
+    ts: Optional[str] = None
+    channel: Optional[str] = None
+    response: Any = None
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+
 class SlackClient(BaseClient, ServiceHealthMixin):
     """
     Refactored Slack client with standardized patterns and reduced duplication.
+
+    Two families of write method, differing only in what they give back:
+
+    - ``send_message`` / ``send_thread_reply`` / ``update_message`` /
+      ``send_file`` / ``add_reaction`` return a bool and swallow every error.
+    - ``post_message`` / ``post_thread_reply`` / ``post_update`` / ``post_file``
+      return Slack's answer and **raise** on every failure, rejections included.
+      The shared ``post_`` prefix marks that return contract, not the Slack call:
+      ``post_update`` edits a message in place rather than posting a new one.
+
+    Reach for a ``post_*`` method when you need the message's ``ts`` (the only
+    handle an edit, reaction or thread reply accepts) or the error detail behind
+    a failure. Reach for the others when a failed notification should not take
+    the caller down with it. Each method's docstring names its counterpart.
     """
 
     def __init__(
@@ -380,6 +433,145 @@ class SlackClient(BaseClient, ServiceHealthMixin):
             }]
         }]
 
+    def _blocks_with_header(
+        self,
+        blocks: Optional[List[Dict]],
+        include_lambda_header: bool,
+        event_type: Optional[str],
+    ) -> Optional[List[Dict]]:
+        """Prepend the standard context header to ``blocks`` when requested.
+
+        Shared by send_message and post_message so both head a message the same
+        way. Consumers used to rebuild this by calling the private header
+        builders directly; call post_message instead.
+        """
+        if not include_lambda_header:
+            return blocks
+
+        if self._lambda_context["function_name"] != "Unknown":
+            header_blocks = self._create_lambda_header_block(event_type=event_type)
+        else:
+            header_blocks = self._create_local_header_block(event_type=event_type)
+
+        return header_blocks + (blocks or [])
+
+    def _chat_post(
+        self,
+        channel: str,
+        text: str,
+        blocks: Optional[List[Dict]],
+        attachments: Optional[List[Dict]],
+        include_lambda_header: bool,
+        event_type: Optional[str],
+        unfurl_links: Optional[bool],
+        unfurl_media: Optional[bool],
+    ) -> SentMessage:
+        """Build the payload, post it, log the outcome, return Slack's answer."""
+        kwargs: Dict[str, Any] = dict(
+            channel=channel,
+            text=text,
+            blocks=self._blocks_with_header(blocks, include_lambda_header, event_type),
+            attachments=attachments,
+        )
+        # Forward unfurl controls only when explicitly set, so existing callers
+        # keep Slack's default behavior (and their call assertions stay unchanged).
+        if unfurl_links is not None:
+            kwargs["unfurl_links"] = unfurl_links
+        if unfurl_media is not None:
+            kwargs["unfurl_media"] = unfurl_media
+
+        response = self._service_client.chat_postMessage(**kwargs)
+
+        sent = SentMessage(
+            ok=bool(response.get("ok", False)),
+            ts=response.get("ts"),
+            channel=response.get("channel"),
+            response=response,
+        )
+
+        if sent.ok:
+            log.info("Slack message sent successfully", extra={"channel": channel, "ts": sent.ts})
+        else:
+            log.error("Slack API returned error", extra={"error": response.get("error", "Unknown error")})
+        return sent
+
+    @handle_client_errors(reraise=True)
+    def post_message(
+        self,
+        channel: str,
+        text: str,
+        blocks: Optional[List[Dict]] = None,
+        attachments: Optional[List[Dict]] = None,
+        include_lambda_header: bool = True,
+        event_type: Optional[str] = None,
+        unfurl_links: Optional[bool] = None,
+        unfurl_media: Optional[bool] = None,
+    ) -> SentMessage:
+        """
+        Send a message and return Slack's response, including the ``ts``. Raises.
+
+        **Like every ``post_*`` method here, it raises rather than swallowing.**
+        The ``send_*`` / ``update_message`` family logs and returns a default
+        instead; this one lets the exception reach you, because a caller holding
+        a ``ts`` generally needs the rejection code, HTTP status and retry headers
+        that a bare False cannot express. Wrap the call accordingly, or use
+        send_message if you want the swallowing behaviour.
+
+        **It returns on success and raises on every failure**, Slack's own
+        rejections included: ``slack_sdk`` validates each response before handing
+        it back, so ``{"ok": false, "error": ...}`` arrives as a ``SlackApiError``
+        carrying that detail on ``err.response``, never as a returned value. So do
+        not write ``if sent:`` as a failure guard, because it never runs; catch
+        instead. (``SentMessage.ok`` stays for defensive handling of a client that
+        does not validate, such as a test double returning a plain dict; against a
+        real client a returned SentMessage is always ``ok``.)
+
+        Otherwise it is send_message: same arguments, same standard header. The
+        difference is what comes back. send_message answers True/False and
+        discards the ``ts``, which is the only handle send_thread_reply,
+        update_message and add_reaction accept, so a caller that may later thread
+        under, edit or react to its own message wants this one.
+
+        Args:
+            channel: Channel ID
+            text: Fallback text
+            blocks: Rich formatted blocks
+            attachments: Legacy attachment objects (supports color sidebars)
+            include_lambda_header: Whether to include context header
+            event_type: Optional event type label for header (e.g., "Scheduled", "API", "SQS")
+            unfurl_links: Override Slack link unfurling. None leaves Slack's default;
+                False suppresses link preview cards (links stay clickable)
+            unfurl_media: Override Slack media unfurling. None leaves Slack's default;
+                False suppresses media preview cards
+
+        Returns:
+            SentMessage carrying ok, ts, channel and the raw response.
+
+        Raises:
+            slack_sdk.errors.SlackApiError: Slack rejected the call, at the
+                transport layer or by answering ``ok: false``. ``err.response``
+                carries the error code, status and any retry headers. Any other
+                exception raised by the underlying client propagates too.
+
+        Example:
+            sent = client.post_message("C123", "Build started")
+            client.send_thread_reply(sent.channel, sent.ts, "Build finished")
+        """
+        return self._execute_with_error_handling(
+            "post_message",
+            lambda: self._chat_post(
+                channel=channel,
+                text=text,
+                blocks=blocks,
+                attachments=attachments,
+                include_lambda_header=include_lambda_header,
+                event_type=event_type,
+                unfurl_links=unfurl_links,
+                unfurl_media=unfurl_media,
+            ),
+            channel=channel,
+        )
+
     @handle_client_errors(default_return=False)
     def send_message(
         self,
@@ -409,103 +601,181 @@ class SlackClient(BaseClient, ServiceHealthMixin):
 
         Returns:
             True if successful, False otherwise
-        """
-        def _send_operation():
-            # Add context header if requested
-            if include_lambda_header:
-                if self._lambda_context["function_name"] != "Unknown":
-                    header_blocks = self._create_lambda_header_block(event_type=event_type)
-                else:
-                    header_blocks = self._create_local_header_block(event_type=event_type)
 
-                if blocks:
-                    blocks_with_header = header_blocks + blocks
-                else:
-                    blocks_with_header = header_blocks
-            else:
-                blocks_with_header = blocks
-
-            kwargs = dict(
+        See Also:
+            post_message: same arguments, returns Slack's response (with the
+            ``ts``) instead of a bool, and raises rather than swallowing.
+        """
+        sent = self._execute_with_error_handling(
+            "send_message",
+            lambda: self._chat_post(
                 channel=channel,
                 text=text,
-                blocks=blocks_with_header,
+                blocks=blocks,
                 attachments=attachments,
-            )
-            # Forward unfurl controls only when explicitly set, so existing callers
-            # keep Slack's default behavior (and their call assertions stay unchanged).
-            if unfurl_links is not None:
-                kwargs["unfurl_links"] = unfurl_links
-            if unfurl_media is not None:
-                kwargs["unfurl_media"] = unfurl_media
-            response = self._service_client.chat_postMessage(**kwargs)
-
-            if response["ok"]:
-                log.info(
-                    "Slack message sent successfully",
-                    extra={"channel": channel, "ts": response["ts"]}
-                )
-                return True
-            else:
-                log.error(
-                    "Slack API returned error",
-                    extra={"error": response.get("error", "Unknown error")}
-                )
-                return False
+                include_lambda_header=include_lambda_header,
+                event_type=event_type,
+                unfurl_links=unfurl_links,
+                unfurl_media=unfurl_media,
+            ),
+            channel=channel,
+        )
+        return bool(sent)
 
-        return self._execute_with_error_handling(
-            "send_message",
-            _send_operation,
-            channel=channel
+    def _upload_file(
+        self,
+        channel: str,
+        content: Union[str, bytes],
+        filename: str,
+        title: Optional[str],
+        thread_ts: Optional[str],
+    ) -> SlackResponse:
+        """Upload a file and log the outcome, returning Slack's raw response.
+
+        Shared by send_file and post_file. Unlike the message helpers this does
+        not build a SentMessage: an upload has no single message ``ts``, so one
+        would have to be invented.
+        """
+        kwargs: Dict[str, Any] = dict(
+            channel=channel,
+            content=content,
+            filename=filename,
+            title=title or filename,
         )
+        if thread_ts is not None:
+            kwargs["thread_ts"] = thread_ts
+
+        response = self._service_client.files_upload_v2(**kwargs)
+
+        if response.get("ok", False):
+            log.info("File uploaded successfully", extra={"channel": channel, "file_name": filename})
+        else:
+            log.error("Slack file upload failed", extra={"error": response.get("error", "Unknown error")})
+        return response
 
     @handle_client_errors(default_return=False)
     def send_file(
         self,
         channel: str,
-        content: str,
+        content: Union[str, bytes],
         filename: str,
-        title: Optional[str] = None
+        title: Optional[str] = None,
+        thread_ts: Optional[str] = None,
     ) -> bool:
         """
         Upload file to Slack channel.
-        
+
         Args:
-            channel: Channel ID
-            content: File content
+            channel: Channel ID. A name will not do: the SDK forwards this as
+                ``channel_id`` to ``files.completeUploadExternal``, so a name
+                uploads the bytes and then fails to share them.
+            content: File content (str or bytes)
             filename: File name
             title: Optional title
-            
+            thread_ts: Optional parent message timestamp, to upload into a thread
+
         Returns:
             True if successful, False otherwise
+
+        See Also:
+            post_file: same arguments, returns Slack's response and raises.
         """
-        def _upload_operation():
-            response = self._service_client.files_upload_v2(
-                channel=channel,
-                content=content,
-                filename=filename,
-                title=title or filename
-            )
+        response = self._execute_with_error_handling(
+            "send_file",
+            lambda: self._upload_file(channel, content, filename, title, thread_ts),
+            channel=channel,
+            # not `filename`: logging reserves it on LogRecord, and passing it
+            # raises a KeyError that replaces whatever error we were reporting.
+            file_name=filename,
+        )
+        return bool(response.get("ok", False))
 
-            if response["ok"]:
-                log.info(
-                    "File uploaded successfully",
-                    extra={"channel": channel, "file_name": filename}
-                )
-                return True
-            else:
-                log.error(
-                    "Slack file upload failed",
-                    extra={"error": response.get("error", "Unknown error")}
-                )
-                return False
+    @handle_client_errors(reraise=True)
+    def post_file(
+        self,
+        channel: str,
+        content: Union[str, bytes],
+        filename: str,
+        title: Optional[str] = None,
+        thread_ts: Optional[str] = None,
+    ) -> SlackResponse:
+        """
+        Upload a file and return Slack's response. Raises.
+
+        Response-returning counterpart of send_file, following the same rule as
+        post_message: it returns on success and raises on every failure. The
+        return is ``files_upload_v2``'s completion response rather than a
+        SentMessage, because an upload has no single message ``ts``; read
+        ``response["files"]`` for what was created.
+
+        Args:
+            channel: Channel ID. A name will not do: the SDK forwards this as
+                ``channel_id`` to ``files.completeUploadExternal``, so a name
+                uploads the bytes and then fails to share them.
+            content: File content (str or bytes)
+            filename: File name
+            title: Optional title
+            thread_ts: Optional parent message timestamp, to upload into a thread
 
+        Returns:
+            ``files_upload_v2``'s completion response.
+
+        Raises:
+            slack_sdk.errors.SlackApiError: Slack rejected the upload. Any other
+                exception from the underlying client propagates too.
+        """
         return self._execute_with_error_handling(
-            "send_file",
-            _upload_operation,
+            "post_file",
+            lambda: self._upload_file(channel, content, filename, title, thread_ts),
             channel=channel,
-            filename=filename
+            # not `filename`: logging reserves it on LogRecord, and passing it
+            # raises a KeyError that replaces whatever error we were reporting.
+            file_name=filename,
         )
 
+    def _chat_post_thread_reply(
+        self,
+        channel: str,
+        thread_ts: str,
+        text: str,
+        blocks: Optional[List[Dict]],
+        include_lambda_header: bool,
+        event_type: Optional[str],
+    ) -> SentMessage:
+        """Post a thread reply, log the outcome, return Slack's answer.
+
+        Shared by send_thread_reply and post_thread_reply. Note this heads a
+        reply only inside Lambda: unlike a top-level post it has never added the
+        local header, and that is preserved rather than unified.
+        """
+        blocks_with_header = blocks
+        if include_lambda_header and self._lambda_context["function_name"] != "Unknown":
+            header_blocks = self._create_lambda_header_block(event_type=event_type)
+            blocks_with_header = header_blocks + (blocks or [])
+
+        response = self._service_client.chat_postMessage(
+            channel=channel,
+            thread_ts=thread_ts,
+            text=text,
+            blocks=blocks_with_header,
+        )
+
+        sent = SentMessage(
+            ok=bool(response.get("ok", False)),
+            ts=response.get("ts"),
+            channel=response.get("channel"),
+            response=response,
+        )
+
+        if sent.ok:
+            log.info(
+                "Thread reply sent successfully",
+                extra={"channel": channel, "thread_ts": thread_ts, "reply_ts": sent.ts},
+            )
+        else:
+            log.error("Failed to send thread reply", extra={"error": response.get("error", "Unknown error")})
+        return sent
+
     @handle_client_errors(default_return=False)
     def send_thread_reply(
         self,
@@ -529,48 +799,99 @@ class SlackClient(BaseClient, ServiceHealthMixin):
 
         Returns:
             True if successful, False otherwise
-        """
-        def _reply_operation():
-            # Add header if requested (uncommon for thread replies)
-            blocks_with_header = blocks
-            if include_lambda_header and self._lambda_context["function_name"] != "Unknown":
-                header_blocks = self._create_lambda_header_block(event_type=event_type)
-                if blocks:
-                    blocks_with_header = header_blocks + blocks
-                else:
-                    blocks_with_header = header_blocks
 
-            response = self._service_client.chat_postMessage(
+        See Also:
+            post_thread_reply: same arguments, returns Slack's response (with the
+            reply's own ``ts``) instead of a bool, and raises rather than swallowing.
+        """
+        sent = self._execute_with_error_handling(
+            "send_thread_reply",
+            lambda: self._chat_post_thread_reply(
                 channel=channel,
                 thread_ts=thread_ts,
                 text=text,
-                blocks=blocks_with_header
-            )
+                blocks=blocks,
+                include_lambda_header=include_lambda_header,
+                event_type=event_type,
+            ),
+            channel=channel,
+            thread_ts=thread_ts,
+        )
+        return bool(sent)
 
-            if response["ok"]:
-                log.info(
-                    "Thread reply sent successfully",
-                    extra={
-                        "channel": channel,
-                        "thread_ts": thread_ts,
-                        "reply_ts": response["ts"]
-                    }
-                )
-                return True
-            else:
-                log.error(
-                    "Failed to send thread reply",
-                    extra={"error": response.get("error", "Unknown error")}
-                )
-                return False
+    @handle_client_errors(reraise=True)
+    def post_thread_reply(
+        self,
+        channel: str,
+        thread_ts: str,
+        text: str,
+        blocks: Optional[List[Dict]] = None,
+        include_lambda_header: bool = False,
+        event_type: Optional[str] = None,
+    ) -> SentMessage:
+        """
+        Send a thread reply and return Slack's response, including its own ``ts``.
+
+        Response-returning counterpart of send_thread_reply, following the same
+        rule as post_message: it returns on success and raises on every failure,
+        Slack's rejections included. A reply has a ``ts`` of its own, so this is
+        what you want when a later call edits or reacts to the reply itself.
+
+        Args:
+            channel: Channel ID
+            thread_ts: Parent message timestamp
+            text: Reply text
+            blocks: Optional blocks
+            include_lambda_header: Whether to include header
+            event_type: Optional event type label for header (e.g., "Scheduled", "API", "SQS")
+
+        Returns:
+            SentMessage for the reply, whose ``ts`` is the reply's, not the parent's.
 
+        Raises:
+            slack_sdk.errors.SlackApiError: Slack rejected the call. Any other
+                exception from the underlying client propagates too.
+        """
         return self._execute_with_error_handling(
-            "send_thread_reply",
-            _reply_operation,
+            "post_thread_reply",
+            lambda: self._chat_post_thread_reply(
+                channel=channel,
+                thread_ts=thread_ts,
+                text=text,
+                blocks=blocks,
+                include_lambda_header=include_lambda_header,
+                event_type=event_type,
+            ),
             channel=channel,
-            thread_ts=thread_ts
+            thread_ts=thread_ts,
         )
 
+    def _chat_update(
+        self,
+        channel: str,
+        ts: str,
+        text: str,
+        blocks: Optional[List[Dict]],
+    ) -> SentMessage:
+        """Edit a message, log the outcome, return Slack's answer.
+
+        Shared by update_message and post_update.
+        """
+        response = self._service_client.chat_update(channel=channel, ts=ts, text=text, blocks=blocks)
+
+        sent = SentMessage(
+            ok=bool(response.get("ok", False)),
+            ts=response.get("ts"),
+            channel=response.get("channel"),
+            response=response,
+        )
+
+        if sent.ok:
+            log.info("Message updated successfully", extra={"channel": channel, "ts": ts})
+        else:
+            log.error("Failed to update message", extra={"error": response.get("error", "Unknown error")})
+        return sent
+
     @handle_client_errors(default_return=False)
     def update_message(
         self,
@@ -581,36 +902,65 @@ class SlackClient(BaseClient, ServiceHealthMixin):
     ) -> bool:
         """
         Update existing message.
-        
+
         Args:
             channel: Channel ID
             ts: Message timestamp
             text: New text
             blocks: New blocks
-            
+
         Returns:
             True if successful, False otherwise
+
+        See Also:
+            post_update: same arguments, returns Slack's response instead of a
+            bool, and raises rather than swallowing.
         """
-        def _update_operation():
-            response = self._service_client.chat_update(
-                channel=channel,
-                ts=ts,
-                text=text,
-                blocks=blocks
-            )
+        sent = self._execute_with_error_handling(
+            "update_message",
+            lambda: self._chat_update(channel=channel, ts=ts, text=text, blocks=blocks),
+            channel=channel,
+            ts=ts,
+        )
+        return bool(sent)
 
-            if response["ok"]:
-                log.info("Message updated successfully", extra={"channel": channel, "ts": ts})
-                return True
-            else:
-                log.error("Failed to update message", extra={"error": response.get("error", "Unknown error")})
-                return False
+    @handle_client_errors(reraise=True)
+    def post_update(
+        self,
+        channel: str,
+        ts: str,
+        text: str,
+        blocks: Optional[List[Dict]] = None,
+    ) -> SentMessage:
+        """
+        Edit an existing message in place and return Slack's response. Raises.
+
+        This edits; it does not post anything new, despite the ``post_`` prefix
+        the response-returning family shares. It is the counterpart of
+        update_message and follows the same rule as post_message: it returns on
+        success and raises on every failure. Use it when an edit failing silently
+        would be wrong, or when you need the edited message's fields back.
+
+        Args:
+            channel: Channel ID. Pass the ``channel`` from the original post's
+                SentMessage, not the name you posted to: ``chat.update`` wants
+                the id.
+            ts: Message timestamp
+            text: New text
+            blocks: New blocks
+
+        Returns:
+            SentMessage for the edited message.
 
+        Raises:
+            slack_sdk.errors.SlackApiError: Slack rejected the edit. Any other
+                exception from the underlying client propagates too.
+        """
         return self._execute_with_error_handling(
-            "update_message",
-            _update_operation,
+            "post_update",
+            lambda: self._chat_update(channel=channel, ts=ts, text=text, blocks=blocks),
             channel=channel,
-            ts=ts
+            ts=ts,
         )
 
     @handle_client_errors(default_return=False)

nui_shared_utils/slack_formatter.py

@@ -4,8 +4,9 @@ Provides a builder pattern for creating Slack Block Kit messages.
 """
 
 from typing import Dict, List, Any, Optional, Union
-from datetime import datetime, timedelta
-import pytz
+from datetime import datetime, timedelta, timezone
+
+from .timezone import NZ_TZ
 
 # Severity emoji mapping
 SEVERITY_EMOJI = {"critical": "🚨", "warning": "⚠️", "info": "ℹ️", "success": "✅", "error": "❌"}
@@ -42,25 +43,23 @@ def format_number(value: Union[int, float], decimals: int = 0) -> str:
 def format_nz_time(dt: Optional[datetime] = None) -> str:
     """Format datetime in NZ timezone."""
     if dt is None:
-        dt = datetime.utcnow()
+        dt = datetime.now(timezone.utc)
     elif not dt.tzinfo:
-        dt = dt.replace(tzinfo=pytz.UTC)
+        dt = dt.replace(tzinfo=timezone.utc)
 
-    nz_tz = pytz.timezone("Pacific/Auckland")
-    nz_time = dt.astimezone(nz_tz)
+    nz_time = dt.astimezone(NZ_TZ)
     return nz_time.strftime("%I:%M %p %Z")
 
 
 def format_date_range(start: datetime, end: datetime) -> str:
     """Format a date range in NZ timezone."""
-    nz_tz = pytz.timezone("Pacific/Auckland")
     if not start.tzinfo:
-        start = start.replace(tzinfo=pytz.UTC)
+        start = start.replace(tzinfo=timezone.utc)
     if not end.tzinfo:
-        end = end.replace(tzinfo=pytz.UTC)
+        end = end.replace(tzinfo=timezone.utc)
 
-    start_nz = start.astimezone(nz_tz)
-    end_nz = end.astimezone(nz_tz)
+    start_nz = start.astimezone(NZ_TZ)
+    end_nz = end.astimezone(NZ_TZ)
 
     if start_nz.date() == end_nz.date():
         return f"{start_nz.strftime('%b %d')} {start_nz.strftime('%I:%M %p')} - {end_nz.strftime('%I:%M %p %Z')}"

nui_shared_utils/timezone.py

@@ -1,17 +1,21 @@
 """
 Timezone utilities for multi-timezone handling (NZ primary, AUS/US/EUR secondary).
+
+Zone data comes from the standard library's ``zoneinfo``, which reads the system
+IANA database. Environments without one (Windows, minimal images such as Alpine)
+need the ``tzdata`` package: `pip install nui-python-shared-utils[timezone]`.
 """
 
 from datetime import datetime, timezone
-import pytz
-from typing import List, Tuple, Optional
+from typing import List, Optional, Tuple
+from zoneinfo import ZoneInfo
 
 # Supported timezones
-NZ_TZ = pytz.timezone("Pacific/Auckland")  # Primary timezone
-AUS_TZ = pytz.timezone("Australia/Sydney")
-US_EAST_TZ = pytz.timezone("US/Eastern")
-US_WEST_TZ = pytz.timezone("US/Pacific")
-EUR_TZ = pytz.timezone("Europe/London")
+NZ_TZ = ZoneInfo("Pacific/Auckland")  # Primary timezone
+AUS_TZ = ZoneInfo("Australia/Sydney")
+US_EAST_TZ = ZoneInfo("US/Eastern")
+US_WEST_TZ = ZoneInfo("US/Pacific")
+EUR_TZ = ZoneInfo("Europe/London")
 
 
 def nz_time(utc_dt: Optional[datetime] = None) -> datetime:
@@ -28,7 +32,7 @@ def nz_time(utc_dt: Optional[datetime] = None) -> datetime:
         utc_dt = datetime.now(timezone.utc)
 
     if utc_dt.tzinfo is None:
-        utc_dt = pytz.UTC.localize(utc_dt)
+        utc_dt = utc_dt.replace(tzinfo=timezone.utc)
 
     return utc_dt.astimezone(NZ_TZ)
 
@@ -66,7 +70,7 @@ def format_multi_timezone(dt: Optional[datetime] = None, primary_tz: str = "nz",
         dt = datetime.now(timezone.utc)
 
     if dt.tzinfo is None:
-        dt = pytz.UTC.localize(dt)
+        dt = dt.replace(tzinfo=timezone.utc)
 
     # Timezone mapping
     tz_map = {"nz": NZ_TZ, "aus": AUS_TZ, "us_east": US_EAST_TZ, "us_west": US_WEST_TZ, "eur": EUR_TZ}