nui-python-shared-utils 1.3.2__py3-none-any.whl → 1.3.3__py3-none-any.whl

nui_lambda_shared_utils/__init__.py

@@ -4,15 +4,21 @@ Backwards-compatibility shim for nui-lambda-shared-utils.
 This package has been renamed to nui-python-shared-utils.
 The import name has changed from nui_lambda_shared_utils to nui_shared_utils.
 
-This shim re-exports everything from nui_shared_utils so existing consumers
+This shim forwards attribute access to nui_shared_utils so existing consumers
 continue to work without changes. New code should use:
 
     from nui_shared_utils import ...
 
 This shim will be removed in the next major version (2.0.0).
+
+Forwarding is lazy (PEP 562 ``__getattr__``) to preserve the cold-start
+optimisation in the underlying package: ``from nui_lambda_shared_utils.jwt_auth
+import check_auth`` only imports ``jwt_auth`` and its dependencies, not the
+full slack/es/db client surface.
 """
 
 import warnings
+from typing import Any, List
 
 warnings.warn(
     "nui_lambda_shared_utils is deprecated. Use nui_shared_utils instead. "
@@ -21,5 +27,18 @@ warnings.warn(
     stacklevel=2,
 )
 
-from nui_shared_utils import *  # noqa: F401,F403
-from nui_shared_utils import __all__  # noqa: F401
+import nui_shared_utils as _target
+
+__all__ = list(_target.__all__)
+
+
+def __getattr__(name: str) -> Any:
+    # Delegate to the new package's lazy resolver. Cache on this module so
+    # subsequent accesses avoid the round-trip.
+    value = getattr(_target, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> List[str]:
+    return sorted(set(globals()) | set(__all__))

{nui_python_shared_utils-1.3.2.dist-info → nui_python_shared_utils-1.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-python-shared-utils
-Version: 1.3.2
+Version: 1.3.3
 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

{nui_python_shared_utils-1.3.2.dist-info → nui_python_shared_utils-1.3.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-nui_lambda_shared_utils/__init__.py,sha256=5hyn9xyUmLXov5Ej5i2CHFQgSNNoOkwCHuQjdKySG8E,741
+nui_lambda_shared_utils/__init__.py,sha256=FaaYBqgNxSQ0x7jlf5fw2pQoMh8Pbmw7uZiVfavI_IY,1320
 nui_lambda_shared_utils/base_client.py,sha256=c7t2_IfISQ39Y1AY6MOj-SlX2tkpzNpp47RRMfu5xqY,135
 nui_lambda_shared_utils/cli.py,sha256=3TtfQy0x3P0QKiNDiz0j3kze7Hs26CMeQE8X_948OEQ,127
 nui_lambda_shared_utils/cloudwatch_metrics.py,sha256=Qwj52AIVrxg7HEEMjmgvDptCJ5Csr_w3NJBI1v34sFw,142
@@ -20,11 +20,11 @@ nui_lambda_shared_utils/slack_setup/__init__.py,sha256=q78NzSznsSd3ri5OUohWxQt7r
 nui_lambda_shared_utils/slack_setup/channel_creator.py,sha256=xaeqzyEAqVqYj2EhN69UvcyZQ6LdFKYODPPCwxHInLA,172
 nui_lambda_shared_utils/slack_setup/channel_definitions.py,sha256=3TkdLzWvEMBMDy5jqOPMUGRgKQ3z9TN58D43V7O7LpE,180
 nui_lambda_shared_utils/slack_setup/setup_helpers.py,sha256=ex_RiUfiZqH9qGLQwmedezMbfp35uI-VQPevducfbBk,168
-nui_python_shared_utils-1.3.2.dist-info/licenses/LICENSE,sha256=vGe2mC5yLUb8toYlY3T36ZwCB5zQUW5hlCtEMiqokhM,1071
-nui_shared_utils/__init__.py,sha256=0yYLzo2zggr43W2zdybp7PBc5oPsU-kwh1M1r7CuFv4,6617
+nui_python_shared_utils-1.3.3.dist-info/licenses/LICENSE,sha256=vGe2mC5yLUb8toYlY3T36ZwCB5zQUW5hlCtEMiqokhM,1071
+nui_shared_utils/__init__.py,sha256=Myt_55yTIZO71iyz2wkM9wySd7xhOCCky4EBOs-aI0A,10964
 nui_shared_utils/base_client.py,sha256=I1lKQGhrKyvujV2zps0TrtEdPDqMCwRQaIh6ceGONXQ,11016
 nui_shared_utils/cli.py,sha256=JJpSoQWKvAz4b8cO30yFNi5vY9jmqrCHzbFpvrVTkbU,8747
-nui_shared_utils/cloudwatch_metrics.py,sha256=Rdyfy-3zAQqZkPL2krzjyB3FXYgrh7Hx56nVeT6eDIw,11836
+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
@@ -33,18 +33,18 @@ nui_shared_utils/es_query_builder.py,sha256=UuheQf8b2UXaOiJlYCKYIfKfVERDZ3ag1P0O
 nui_shared_utils/jwt_auth.py,sha256=2Ag1zZKxd2R8QBz3aQA4h8OtKHQvUVKrjUp6lXpJxJU,9143
 nui_shared_utils/lambda_helpers.py,sha256=psHVotpmOfnmyQCoOt4MSIEj7VwWcy6gZM3vYSZwjOk,3041
 nui_shared_utils/log_processors.py,sha256=x5gz1LEkbmoMCZ3ZB6q-mbn26dSzwh1trz4wSkBGxqk,5538
-nui_shared_utils/powertools_helpers.py,sha256=pVu9MVBC6PEirHBbMC-9nKreP9jk8wd0fQt6OWekzdk,10126
-nui_shared_utils/secrets_helper.py,sha256=KoEKplGjfxc8HnhRXvxCRAqLKOOBN9oxKABjTlZvy4I,6806
+nui_shared_utils/powertools_helpers.py,sha256=qc-lYLfY-QX20gALfPOJcihrtJhiCU-fJW8rsPT7LJE,11037
+nui_shared_utils/secrets_helper.py,sha256=jtQZSbghNTyWYylGxFiHWeL28Q1JUpLTrnGIICU4R3k,6815
 nui_shared_utils/slack_client.py,sha256=_qR7Q1GU7gvYhUxiaBxEohhoEYznqr8kz9enGfeDtn8,24759
 nui_shared_utils/slack_formatter.py,sha256=95g6XfAJst7RVhd0M0ahiF3gWWW5j96WYkCg5tLS6Zg,10894
 nui_shared_utils/timezone.py,sha256=TvtSZV7w3Vvz3NbMTcJSNbUf0ZxPwpFS-xfgye1h-4Q,3583
-nui_shared_utils/utils.py,sha256=oQQBmPA-0dM-XFRLBEBk_hh9FtRZyoY9_egmviyGemg,8146
+nui_shared_utils/utils.py,sha256=gOpw80tZGC24QsyesR8EySRODY-TFXG8cXUvggPBsRI,8184
 nui_shared_utils/slack_setup/__init__.py,sha256=OElyS3xk4F_YKH5uUUTDpN0ah1dOO3e52muIPjAMPW8,320
 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-1.3.2.dist-info/METADATA,sha256=-N4PxQPpnnqdwBjiZ-uCWfVdAgeYARr7tRfcXsoUuto,19387
-nui_python_shared_utils-1.3.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-nui_python_shared_utils-1.3.2.dist-info/entry_points.txt,sha256=TrJ3Z4kz3oXfy6InXn20jHu7rnTwo-4EA0KRFX3fkL0,66
-nui_python_shared_utils-1.3.2.dist-info/top_level.txt,sha256=sNceq5okmEB54L-gm4a0OgGhnPlU62zYmlUoXKn-Fa8,41
-nui_python_shared_utils-1.3.2.dist-info/RECORD,,
+nui_python_shared_utils-1.3.3.dist-info/METADATA,sha256=y_FgR8-pq8PWqEayZQfYAtOqzijcsdG2UOQDVxd4-7E,19387
+nui_python_shared_utils-1.3.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+nui_python_shared_utils-1.3.3.dist-info/entry_points.txt,sha256=TrJ3Z4kz3oXfy6InXn20jHu7rnTwo-4EA0KRFX3fkL0,66
+nui_python_shared_utils-1.3.3.dist-info/top_level.txt,sha256=sNceq5okmEB54L-gm4a0OgGhnPlU62zYmlUoXKn-Fa8,41
+nui_python_shared_utils-1.3.3.dist-info/RECORD,,

nui_shared_utils/__init__.py

@@ -1,252 +1,263 @@
 """
 Enterprise-grade utilities for AWS Lambda functions with Slack, Elasticsearch, and monitoring integrations.
+
+Public API is resolved lazily via PEP 562 ``__getattr__`` to keep package import
+cheap. Submodules and their dependencies (boto3, slack-sdk, elasticsearch, etc.)
+are only imported when an attribute is first accessed.
 """
 
-# Configuration system
-from .config import (
-    Config,
-    get_config,
-    set_config,
-    configure,
-    get_es_host,
-    get_es_credentials_secret,
-    get_db_credentials_secret,
-    get_slack_credentials_secret,
-)
+import importlib
+from typing import TYPE_CHECKING, Any, List
 
-# Core utilities
-from .secrets_helper import (
-    get_secret,
-    get_database_credentials,
-    get_elasticsearch_credentials,
-    get_slack_credentials,
-    get_api_key,
-    clear_cache,
-)
+# Map public name -> (submodule, attr_name).
+# Optional integrations: keep their entries here; on ImportError during lazy
+# resolution we return None to preserve historical behaviour where consumers
+# could check ``if nui.SlackClient is not None``.
+_LAZY_EXPORTS = {
+    # Configuration system
+    "Config": ("config", "Config"),
+    "get_config": ("config", "get_config"),
+    "set_config": ("config", "set_config"),
+    "configure": ("config", "configure"),
+    "get_es_host": ("config", "get_es_host"),
+    "get_es_credentials_secret": ("config", "get_es_credentials_secret"),
+    "get_db_credentials_secret": ("config", "get_db_credentials_secret"),
+    "get_slack_credentials_secret": ("config", "get_slack_credentials_secret"),
+    # Secrets
+    "get_secret": ("secrets_helper", "get_secret"),
+    "get_database_credentials": ("secrets_helper", "get_database_credentials"),
+    "get_elasticsearch_credentials": ("secrets_helper", "get_elasticsearch_credentials"),
+    "get_slack_credentials": ("secrets_helper", "get_slack_credentials"),
+    "get_api_key": ("secrets_helper", "get_api_key"),
+    "clear_cache": ("secrets_helper", "clear_cache"),
+    # Common utilities
+    "resolve_config_value": ("utils", "resolve_config_value"),
+    "resolve_aws_region": ("utils", "resolve_aws_region"),
+    "create_aws_client": ("utils", "create_aws_client"),
+    "handle_client_errors": ("utils", "handle_client_errors"),
+    "merge_dimensions": ("utils", "merge_dimensions"),
+    "validate_required_param": ("utils", "validate_required_param"),
+    "safe_close_connection": ("utils", "safe_close_connection"),
+    "format_log_context": ("utils", "format_log_context"),
+    "DEFAULT_AWS_REGION": ("utils", "DEFAULT_AWS_REGION"),
+    # Base client architecture
+    "BaseClient": ("base_client", "BaseClient"),
+    "ServiceHealthMixin": ("base_client", "ServiceHealthMixin"),
+    "RetryableOperationMixin": ("base_client", "RetryableOperationMixin"),
+    # Timezone helpers
+    "nz_time": ("timezone", "nz_time"),
+    "format_nz_time": ("timezone", "format_nz_time"),
+    # Slack formatting (no external deps)
+    "SlackBlockBuilder": ("slack_formatter", "SlackBlockBuilder"),
+    "format_currency": ("slack_formatter", "format_currency"),
+    "format_percentage": ("slack_formatter", "format_percentage"),
+    "format_number": ("slack_formatter", "format_number"),
+    "format_nz_time_slack": ("slack_formatter", "format_nz_time"),
+    "format_date_range": ("slack_formatter", "format_date_range"),
+    "format_daily_header": ("slack_formatter", "format_daily_header"),
+    "format_weekly_header": ("slack_formatter", "format_weekly_header"),
+    "format_error_alert": ("slack_formatter", "format_error_alert"),
+    "SEVERITY_EMOJI": ("slack_formatter", "SEVERITY_EMOJI"),
+    "STATUS_EMOJI": ("slack_formatter", "STATUS_EMOJI"),
+    # Error handling
+    "RetryableError": ("error_handler", "RetryableError"),
+    "NonRetryableError": ("error_handler", "NonRetryableError"),
+    "ErrorPatternMatcher": ("error_handler", "ErrorPatternMatcher"),
+    "ErrorAggregator": ("error_handler", "ErrorAggregator"),
+    "with_retry": ("error_handler", "with_retry"),
+    "retry_on_network_error": ("error_handler", "retry_on_network_error"),
+    "retry_on_db_error": ("error_handler", "retry_on_db_error"),
+    "retry_on_es_error": ("error_handler", "retry_on_es_error"),
+    "handle_lambda_error": ("error_handler", "handle_lambda_error"),
+    "categorize_retryable_error": ("error_handler", "categorize_retryable_error"),
+    # CloudWatch metrics
+    "MetricsPublisher": ("cloudwatch_metrics", "MetricsPublisher"),
+    "MetricAggregator": ("cloudwatch_metrics", "MetricAggregator"),
+    "StandardMetrics": ("cloudwatch_metrics", "StandardMetrics"),
+    "TimedMetric": ("cloudwatch_metrics", "TimedMetric"),
+    "track_lambda_performance": ("cloudwatch_metrics", "track_lambda_performance"),
+    "create_service_dimensions": ("cloudwatch_metrics", "create_service_dimensions"),
+    "publish_health_metric": ("cloudwatch_metrics", "publish_health_metric"),
+    # Log processing (no external deps)
+    "extract_cloudwatch_logs_from_kinesis": ("log_processors", "extract_cloudwatch_logs_from_kinesis"),
+    "derive_index_name": ("log_processors", "derive_index_name"),
+    "CloudWatchLogEvent": ("log_processors", "CloudWatchLogEvent"),
+    "CloudWatchLogsData": ("log_processors", "CloudWatchLogsData"),
+    # Lambda context helpers
+    "get_lambda_environment_info": ("lambda_helpers", "get_lambda_environment_info"),
+    # Optional: Slack client (slack-sdk)
+    "SlackClient": ("slack_client", "SlackClient"),
+    # Optional: Elasticsearch client + query builder
+    "ElasticsearchClient": ("es_client", "ElasticsearchClient"),
+    "ESQueryBuilder": ("es_query_builder", "ESQueryBuilder"),
+    "build_error_rate_query": ("es_query_builder", "build_error_rate_query"),
+    "build_top_errors_query": ("es_query_builder", "build_top_errors_query"),
+    "build_response_time_query": ("es_query_builder", "build_response_time_query"),
+    "build_service_volume_query": ("es_query_builder", "build_service_volume_query"),
+    "build_user_activity_query": ("es_query_builder", "build_user_activity_query"),
+    "build_pattern_detection_query": ("es_query_builder", "build_pattern_detection_query"),
+    "build_tender_participant_query": ("es_query_builder", "build_tender_participant_query"),
+    # Optional: Database client (pymysql / psycopg2)
+    "DatabaseClient": ("db_client", "DatabaseClient"),
+    "PostgreSQLClient": ("db_client", "PostgreSQLClient"),
+    "get_pool_stats": ("db_client", "get_pool_stats"),
+    # Optional: AWS Powertools
+    "get_powertools_logger": ("powertools_helpers", "get_powertools_logger"),
+    "powertools_handler": ("powertools_helpers", "powertools_handler"),
+    # Optional: JWT validation (rsa)
+    "validate_jwt": ("jwt_auth", "validate_jwt"),
+    "require_auth": ("jwt_auth", "require_auth"),
+    "check_auth": ("jwt_auth", "check_auth"),
+    "get_jwt_public_key": ("jwt_auth", "get_jwt_public_key"),
+    "JWTValidationError": ("jwt_auth", "JWTValidationError"),
+    "AuthenticationError": ("jwt_auth", "AuthenticationError"),
+}
 
-# Common utilities
-from .utils import (
-    resolve_config_value,
-    create_aws_client,
-    handle_client_errors,
-    merge_dimensions,
-    validate_required_param,
-)
+# Submodules that are optional integrations; ImportError during lazy load
+# resolves to None instead of propagating, matching pre-1.4 behaviour.
+# Includes ``slack_setup`` which is also handled by a special-case branch in
+# ``__getattr__`` (it is exposed as a submodule object, not an attribute).
+_OPTIONAL_SUBMODULES = {
+    "slack_client",
+    "es_client",
+    "es_query_builder",
+    "db_client",
+    "powertools_helpers",
+    "jwt_auth",
+    "slack_setup",
+}
 
-# Base client architecture
-from .base_client import BaseClient, ServiceHealthMixin, RetryableOperationMixin
 
-# Client implementations - only fail if actually used
-try:
-    from .slack_client import SlackClient
-except ImportError:
-    SlackClient = None  # type: ignore
+def __getattr__(name: str) -> Any:
+    # ``slack_setup`` is exposed as a submodule attribute (``nui.slack_setup``).
+    if name == "slack_setup":
+        try:
+            mod = importlib.import_module(".slack_setup", __name__)
+        except ImportError:
+            if name in _OPTIONAL_SUBMODULES:
+                mod = None
+            else:
+                raise
+        globals()["slack_setup"] = mod
+        return mod
 
-try:
-    from .es_client import ElasticsearchClient
-except ImportError:
-    ElasticsearchClient = None  # type: ignore
+    if name in _LAZY_EXPORTS:
+        submod_name, attr = _LAZY_EXPORTS[name]
+        try:
+            submod = importlib.import_module(f".{submod_name}", __name__)
+            value = getattr(submod, attr)
+        except ImportError:
+            if submod_name in _OPTIONAL_SUBMODULES:
+                value = None
+            else:
+                raise
+        globals()[name] = value
+        return value
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
-try:
-    from .db_client import DatabaseClient, PostgreSQLClient, get_pool_stats
-except ImportError:
-    DatabaseClient = None  # type: ignore
-    PostgreSQLClient = None  # type: ignore
-    get_pool_stats = None  # type: ignore
 
-from .timezone import nz_time, format_nz_time
+def __dir__() -> List[str]:
+    return sorted(set(globals()) | set(_LAZY_EXPORTS) | {"slack_setup"})
 
-# Slack formatting utilities (no external dependencies)
-from .slack_formatter import (
-    SlackBlockBuilder,
-    format_currency,
-    format_percentage,
-    format_number,
-    format_nz_time as format_nz_time_slack,
-    format_date_range,
-    format_daily_header,
-    format_weekly_header,
-    format_error_alert,
-    SEVERITY_EMOJI,
-    STATUS_EMOJI,
-)
 
-# ES query builder - optional import
-try:
+if TYPE_CHECKING:
+    # Imported for type checkers / IDE completion only; not executed at runtime.
+    from .config import (
+        Config,
+        configure,
+        get_config,
+        get_db_credentials_secret,
+        get_es_credentials_secret,
+        get_es_host,
+        get_slack_credentials_secret,
+        set_config,
+    )
+    from .secrets_helper import (
+        clear_cache,
+        get_api_key,
+        get_database_credentials,
+        get_elasticsearch_credentials,
+        get_secret,
+        get_slack_credentials,
+    )
+    from .utils import (
+        DEFAULT_AWS_REGION,
+        create_aws_client,
+        format_log_context,
+        handle_client_errors,
+        merge_dimensions,
+        resolve_aws_region,
+        resolve_config_value,
+        safe_close_connection,
+        validate_required_param,
+    )
+    from .base_client import BaseClient, RetryableOperationMixin, ServiceHealthMixin
+    from .timezone import format_nz_time, nz_time
+    from .slack_formatter import (
+        SEVERITY_EMOJI,
+        STATUS_EMOJI,
+        SlackBlockBuilder,
+        format_currency,
+        format_daily_header,
+        format_date_range,
+        format_error_alert,
+        format_number,
+        format_nz_time as format_nz_time_slack,
+        format_percentage,
+        format_weekly_header,
+    )
+    from .error_handler import (
+        ErrorAggregator,
+        ErrorPatternMatcher,
+        NonRetryableError,
+        RetryableError,
+        categorize_retryable_error,
+        handle_lambda_error,
+        retry_on_db_error,
+        retry_on_es_error,
+        retry_on_network_error,
+        with_retry,
+    )
+    from .cloudwatch_metrics import (
+        MetricAggregator,
+        MetricsPublisher,
+        StandardMetrics,
+        TimedMetric,
+        create_service_dimensions,
+        publish_health_metric,
+        track_lambda_performance,
+    )
+    from .log_processors import (
+        CloudWatchLogEvent,
+        CloudWatchLogsData,
+        derive_index_name,
+        extract_cloudwatch_logs_from_kinesis,
+    )
+    from .lambda_helpers import get_lambda_environment_info
+    from .slack_client import SlackClient
+    from .es_client import ElasticsearchClient
     from .es_query_builder import (
         ESQueryBuilder,
         build_error_rate_query,
-        build_top_errors_query,
+        build_pattern_detection_query,
         build_response_time_query,
         build_service_volume_query,
-        build_user_activity_query,
-        build_pattern_detection_query,
         build_tender_participant_query,
+        build_top_errors_query,
+        build_user_activity_query,
     )
-except ImportError:
-    ESQueryBuilder = None  # type: ignore
-    build_error_rate_query = None  # type: ignore
-    build_top_errors_query = None  # type: ignore
-    build_response_time_query = None  # type: ignore
-    build_service_volume_query = None  # type: ignore
-    build_user_activity_query = None  # type: ignore
-    build_pattern_detection_query = None  # type: ignore
-    build_tender_participant_query = None  # type: ignore
-from .error_handler import (
-    RetryableError,
-    NonRetryableError,
-    ErrorPatternMatcher,
-    ErrorAggregator,
-    with_retry,
-    retry_on_network_error,
-    retry_on_db_error,
-    retry_on_es_error,
-    handle_lambda_error,
-    categorize_retryable_error,
-)
-from .cloudwatch_metrics import (
-    MetricsPublisher,
-    MetricAggregator,
-    StandardMetrics,
-    TimedMetric,
-    track_lambda_performance,
-    create_service_dimensions,
-    publish_health_metric,
-)
-
-# AWS Powertools integration - optional import
-try:
+    from .db_client import DatabaseClient, PostgreSQLClient, get_pool_stats
     from .powertools_helpers import get_powertools_logger, powertools_handler
-except ImportError:
-    get_powertools_logger = None  # type: ignore
-    powertools_handler = None  # type: ignore
-
-# Log processing utilities (no external dependencies)
-from .log_processors import (
-    CloudWatchLogEvent,
-    CloudWatchLogsData,
-    derive_index_name,
-    extract_cloudwatch_logs_from_kinesis,
-)
-
-# Lambda context helpers (no external dependencies)
-from .lambda_helpers import get_lambda_environment_info
-
-# JWT authentication - optional import
-try:
     from .jwt_auth import (
-        validate_jwt,
-        require_auth,
+        AuthenticationError,
+        JWTValidationError,
         check_auth,
         get_jwt_public_key,
-        JWTValidationError,
-        AuthenticationError,
+        require_auth,
+        validate_jwt,
     )
-except ImportError:
-    validate_jwt = None  # type: ignore
-    require_auth = None  # type: ignore
-    check_auth = None  # type: ignore
-    get_jwt_public_key = None  # type: ignore
-    JWTValidationError = None  # type: ignore
-    AuthenticationError = None  # type: ignore
-
-# Slack setup utilities (for CLI usage) - optional import
-try:
     from . import slack_setup
-except ImportError:
-    slack_setup = None  # type: ignore
 
-__all__ = [
-    # Configuration system
-    "Config",
-    "get_config",
-    "set_config",
-    "configure",
-    "get_es_host",
-    "get_es_credentials_secret",
-    "get_db_credentials_secret",
-    "get_slack_credentials_secret",
-    # Core utilities
-    "get_secret",
-    "get_database_credentials",
-    "get_elasticsearch_credentials",
-    "get_slack_credentials",
-    "get_api_key",
-    "clear_cache",
-    # Common utilities
-    "resolve_config_value",
-    "create_aws_client",
-    "handle_client_errors",
-    "merge_dimensions",
-    "validate_required_param",
-    # Base client architecture
-    "BaseClient",
-    "ServiceHealthMixin",
-    "RetryableOperationMixin",
-    # Client implementations
-    "SlackClient",
-    "ElasticsearchClient",
-    "DatabaseClient",
-    "PostgreSQLClient",
-    "get_pool_stats",  # Legacy compatibility (None)
-    "nz_time",
-    "format_nz_time",
-    "slack_setup",
-    # Slack formatting
-    "SlackBlockBuilder",
-    "format_currency",
-    "format_percentage",
-    "format_number",
-    "format_nz_time_slack",
-    "format_date_range",
-    "format_daily_header",
-    "format_weekly_header",
-    "format_error_alert",
-    "SEVERITY_EMOJI",
-    "STATUS_EMOJI",
-    # ES query building
-    "ESQueryBuilder",
-    "build_error_rate_query",
-    "build_top_errors_query",
-    "build_response_time_query",
-    "build_service_volume_query",
-    "build_user_activity_query",
-    "build_pattern_detection_query",
-    "build_tender_participant_query",
-    # Error handling
-    "RetryableError",
-    "NonRetryableError",
-    "ErrorPatternMatcher",
-    "ErrorAggregator",
-    "with_retry",
-    "retry_on_network_error",
-    "retry_on_db_error",
-    "retry_on_es_error",
-    "handle_lambda_error",
-    "categorize_retryable_error",
-    # CloudWatch metrics
-    "MetricsPublisher",
-    "MetricAggregator",
-    "StandardMetrics",
-    "TimedMetric",
-    "track_lambda_performance",
-    "create_service_dimensions",
-    "publish_health_metric",
-    # AWS Powertools integration
-    "get_powertools_logger",
-    "powertools_handler",
-    # Log processing
-    "extract_cloudwatch_logs_from_kinesis",
-    "derive_index_name",
-    "CloudWatchLogEvent",
-    "CloudWatchLogsData",
-    # Lambda context helpers
-    "get_lambda_environment_info",
-    # JWT authentication
-    "validate_jwt",
-    "require_auth",
-    "check_auth",
-    "get_jwt_public_key",
-    "JWTValidationError",
-    "AuthenticationError",
-]
+
+__all__ = list(sorted(set(_LAZY_EXPORTS) | {"slack_setup"}))

nui_shared_utils/cloudwatch_metrics.py

@@ -9,8 +9,6 @@ import logging
 from typing import Dict, List, Optional, Union
 from datetime import datetime
 from collections import defaultdict
-import boto3
-from botocore.exceptions import ClientError
 
 log = logging.getLogger(__name__)
 
@@ -45,9 +43,19 @@ class MetricsPublisher:
         self.namespace = namespace
         self.default_dimensions = dimensions or {}
         self.auto_flush_size = auto_flush_size
-        self.client = boto3.client("cloudwatch", region_name=region)
+        self._region = region
+        self._client = None
         self.metric_buffer: List[Dict] = []
 
+    @property
+    def client(self):
+        """Lazily construct the boto3 CloudWatch client on first use."""
+        if self._client is None:
+            import boto3
+
+            self._client = boto3.client("cloudwatch", region_name=self._region)
+        return self._client
+
     def put_metric(
         self,
         metric_name: str,
@@ -148,6 +156,8 @@ class MetricsPublisher:
         if not self.metric_buffer:
             return True
 
+        from botocore.exceptions import ClientError
+
         try:
             # CloudWatch allows max 20 metrics per request
             for i in range(0, len(self.metric_buffer), 20):

nui_shared_utils/powertools_helpers.py

@@ -26,15 +26,34 @@ try:
 except ImportError:
     COLOREDLOGS_AVAILABLE = False
 
-try:
-    from .slack_client import SlackClient
+from .lambda_helpers import get_lambda_environment_info
 
-    SLACK_CLIENT_AVAILABLE = True
-except ImportError:
-    SLACK_CLIENT_AVAILABLE = False
-    SlackClient = None  # type: ignore
+# SlackClient is loaded lazily on first use to keep this module's import
+# cost low for callers that don't enable Slack alerting (it transitively
+# pulls in slack_sdk, which is the dominant cost).
+SLACK_CLIENT_AVAILABLE = False
+SlackClient = None  # type: ignore[assignment]
 
-from .lambda_helpers import get_lambda_environment_info
+
+def _ensure_slack_client_loaded() -> None:
+    """Lazy-import :class:`SlackClient` and update module-level flags.
+
+    Idempotent: returns immediately if ``SlackClient`` has already been
+    populated (real import or test mock).
+    """
+    global SLACK_CLIENT_AVAILABLE, SlackClient
+    if SlackClient is not None:
+        # Already populated (real import or test mock) — keep the availability
+        # flag in sync so callers don't see a stale False.
+        SLACK_CLIENT_AVAILABLE = True
+        return
+    try:
+        from .slack_client import SlackClient as _SC
+
+        SlackClient = _SC
+        SLACK_CLIENT_AVAILABLE = True
+    except ImportError:
+        SLACK_CLIENT_AVAILABLE = False
 
 
 __all__ = ["get_powertools_logger", "powertools_handler"]
@@ -99,6 +118,7 @@ def get_powertools_logger(
             if func is not None:
                 return func
             return lambda f: f
+
         logger.inject_lambda_context = _mock_inject_lambda_context  # type: ignore
 
         return logger
@@ -194,14 +214,16 @@ def powertools_handler(
 
         # Create Slack client if channel provided
         slack_client = None
-        if slack_alert_channel and SLACK_CLIENT_AVAILABLE:
-            try:
-                slack_client = SlackClient(
-                    account_names=slack_account_names,
-                    account_names_config=slack_account_names_config,
-                )
-            except Exception as e:
-                logger.warning("Failed to initialize Slack client: %s", e)
+        if slack_alert_channel:
+            _ensure_slack_client_loaded()
+            if SLACK_CLIENT_AVAILABLE and SlackClient is not None:
+                try:
+                    slack_client = SlackClient(
+                        account_names=slack_account_names,
+                        account_names_config=slack_account_names_config,
+                    )
+                except Exception as e:
+                    logger.warning("Failed to initialize Slack client: %s", e)
 
         @functools.wraps(func)
         def wrapper(event: dict, context: Any) -> dict:

nui_shared_utils/secrets_helper.py

@@ -7,8 +7,6 @@ import os
 import json
 import logging
 from typing import Dict, Optional
-import boto3
-from botocore.exceptions import ClientError
 
 from .config import get_config
 
@@ -35,6 +33,9 @@ def get_secret(secret_name: str) -> Dict:
     if secret_name in _secrets_cache:
         return _secrets_cache[secret_name]
 
+    import boto3
+    from botocore.exceptions import ClientError
+
     # Create a Secrets Manager client
     session = boto3.session.Session()
     client = session.client(service_name="secretsmanager", region_name=session.region_name or "ap-southeast-2")

nui_shared_utils/utils.py

@@ -7,53 +7,49 @@ import time
 import logging
 import functools
 from typing import Union, List, Optional, Any, Dict
-import boto3
-from botocore.exceptions import ClientError, NoCredentialsError
 
 from .config import get_config
 
 log = logging.getLogger(__name__)
 
-# AWS region resolution constants
+# AWS region fallback. Used only when no explicit region, env var, config,
+# or boto3 session region is available. Override at deploy time via the
+# ``AWS_REGION_FALLBACK`` environment variable.
 DEFAULT_AWS_REGION = "ap-southeast-2"
 
 
-def resolve_config_value(
-    param_value: Optional[Any], 
-    env_var_names: Union[str, List[str]], 
-    config_default: Any
-) -> Any:
+def resolve_config_value(param_value: Optional[Any], env_var_names: Union[str, List[str]], config_default: Any) -> Any:
     """
     Resolve configuration value with priority: param > env vars > config default.
-    
+
     Args:
         param_value: Explicitly provided parameter value
         env_var_names: Environment variable name(s) to check (string or list)
         config_default: Default value from configuration
-        
+
     Returns:
         Resolved configuration value
-        
+
     Example:
         host = resolve_config_value(
-            host_param, 
-            ["ES_HOST", "ELASTICSEARCH_HOST"], 
+            host_param,
+            ["ES_HOST", "ELASTICSEARCH_HOST"],
             "localhost:9200"
         )
     """
     # Parameter takes highest precedence
     if param_value is not None:
         return param_value
-    
+
     # Check environment variables
     if isinstance(env_var_names, str):
         env_var_names = [env_var_names]
-    
+
     for env_var in env_var_names:
         value = os.environ.get(env_var)
         if value is not None:
             return value
-    
+
     # Fall back to config default
     return config_default
 
@@ -61,70 +57,72 @@ def resolve_config_value(
 def resolve_aws_region(explicit_region: Optional[str] = None) -> str:
     """
     Resolve AWS region with priority: param > env > config > session > default.
-    
+
     Args:
         explicit_region: Explicitly provided region
-        
+
     Returns:
         AWS region string
     """
     # Explicit parameter wins
     if explicit_region:
         return explicit_region
-    
+
     # Check environment variables
-    env_region = resolve_config_value(
-        None,
-        ["AWS_REGION", "AWS_DEFAULT_REGION"],
-        None
-    )
+    env_region = resolve_config_value(None, ["AWS_REGION", "AWS_DEFAULT_REGION"], None)
     if env_region:
         return env_region
-    
+
     # Check config
     config = get_config()
-    if hasattr(config, 'aws_region') and config.aws_region:
+    if hasattr(config, "aws_region") and config.aws_region:
         return config.aws_region
-    
+
     # Check boto3 session default
     try:
+        import boto3
+        from botocore.exceptions import NoCredentialsError
+
         session = boto3.session.Session()
         if session.region_name:
             return session.region_name
-    except Exception as e:
-        log.debug(f"Failed to get session region: {e}")
-    
-    # Final fallback
-    return DEFAULT_AWS_REGION
+    except ImportError as e:
+        log.warning(f"boto3 not available for session-based region resolution: {e}")
+    except NoCredentialsError as e:
+        log.warning(f"No AWS credentials configured for session-based region resolution: {e}")
+
+    # Final fallback. Operators can override the package default via
+    # AWS_REGION_FALLBACK without forking or monkey-patching the constant.
+    return os.environ.get("AWS_REGION_FALLBACK") or DEFAULT_AWS_REGION
 
 
 def create_aws_client(service_name: str, region: Optional[str] = None):
     """
     Create AWS client with consistent region resolution and error handling.
-    
+
     Args:
         service_name: AWS service name (e.g., 'secretsmanager', 'cloudwatch')
         region: Optional explicit region
-        
+
     Returns:
         AWS service client
-        
+
     Raises:
         NoCredentialsError: When AWS credentials are not configured
         ClientError: When client creation fails
     """
     resolved_region = resolve_aws_region(region)
-    
+
+    import boto3
+    from botocore.exceptions import ClientError, NoCredentialsError
+
     try:
         session = boto3.session.Session()
-        client = session.client(
-            service_name=service_name,
-            region_name=resolved_region
-        )
-        
+        client = session.client(service_name=service_name, region_name=resolved_region)
+
         log.debug(f"Created {service_name} client for region {resolved_region}")
         return client
-        
+
     except NoCredentialsError:
         log.error(f"AWS credentials not configured for {service_name} client")
         raise
@@ -137,65 +135,59 @@ def create_aws_client(service_name: str, region: Optional[str] = None):
 
 
 def handle_client_errors(
-    default_return: Any = None,
-    log_context: Optional[Dict[str, Any]] = None,
-    reraise: bool = False
+    default_return: Any = None, log_context: Optional[Dict[str, Any]] = None, reraise: bool = False
 ):
     """
     Decorator for standardized client error handling.
-    
+
     Args:
         default_return: Value to return on error (if not reraising)
         log_context: Additional context for error logging
         reraise: Whether to re-raise exceptions after logging
-        
+
     Example:
         @handle_client_errors(default_return=[])
         def search_documents(self, query):
             # Implementation that might fail
             return results
     """
+
     def decorator(func):
         @functools.wraps(func)
-        def wrapper(*args, **kwargs):
+        def wrapper(*args, **kwargs) -> Any:
             try:
                 return func(*args, **kwargs)
             except Exception as e:
                 # Build log context
-                context = {
-                    "function": func.__name__,
-                    "error_type": type(e).__name__,
-                    "error_message": str(e)
-                }
+                context = {"function": func.__name__, "error_type": type(e).__name__, "error_message": str(e)}
                 if log_context:
                     context.update(log_context)
-                
-                log.error(
-                    f"{func.__name__} failed: {e}",
-                    exc_info=True,
-                    extra=context
-                )
-                
+
+                log.error(f"{func.__name__} failed: {e}", exc_info=True, extra=context)
+
                 if reraise:
                     raise
-                
+
                 return default_return
-        
+
         return wrapper
+
     return decorator
 
 
-def merge_dimensions(base_dimensions: Dict[str, str], additional_dimensions: Optional[Dict[str, str]] = None) -> List[Dict[str, str]]:
+def merge_dimensions(
+    base_dimensions: Dict[str, str], additional_dimensions: Optional[Dict[str, str]] = None
+) -> List[Dict[str, str]]:
     """
     Merge CloudWatch metric dimensions and format for API.
-    
+
     Args:
         base_dimensions: Base dimensions dictionary
         additional_dimensions: Additional dimensions to merge
-        
+
     Returns:
         List of dimension dictionaries formatted for CloudWatch API
-        
+
     Example:
         dimensions = merge_dimensions(
             {"Service": "auth", "Environment": "prod"},
@@ -206,40 +198,37 @@ def merge_dimensions(base_dimensions: Dict[str, str], additional_dimensions: Opt
     all_dimensions = {**base_dimensions}
     if additional_dimensions:
         all_dimensions.update(additional_dimensions)
-    
-    return [
-        {"Name": str(key), "Value": str(value)} 
-        for key, value in all_dimensions.items()
-    ]
+
+    return [{"Name": str(key), "Value": str(value)} for key, value in all_dimensions.items()]
 
 
 def validate_required_param(param_value: Any, param_name: str) -> Any:
     """
     Validate that a required parameter is provided.
-    
+
     Args:
         param_value: Parameter value to validate
         param_name: Parameter name for error messages
-        
+
     Returns:
         The parameter value if valid
-        
+
     Raises:
         ValueError: If parameter is None or empty string
     """
     if param_value is None:
         raise ValueError(f"{param_name} is required")
-    
+
     if isinstance(param_value, str) and not param_value.strip():
         raise ValueError(f"{param_name} cannot be empty")
-    
+
     return param_value
 
 
 def safe_close_connection(connection) -> None:
     """
     Safely close a database connection with proper error handling.
-    
+
     Args:
         connection: Database connection to close
     """
@@ -251,29 +240,26 @@ def safe_close_connection(connection) -> None:
                 return
             if hasattr(connection, "open") and not connection.open:
                 return
-                
+
             # Generic close
             connection.close()
             log.debug("Database connection closed successfully")
-            
+
         except Exception as e:
             log.debug(f"Error closing connection (non-fatal): {e}")
 
 
-def format_log_context(
-    operation: str,
-    **context_data
-) -> Dict[str, Any]:
+def format_log_context(operation: str, **context_data) -> Dict[str, Any]:
     """
     Format consistent logging context for operations.
-    
+
     Args:
         operation: Operation name
         **context_data: Additional context key-value pairs
-        
+
     Returns:
         Formatted context dictionary
-        
+
     Example:
         context = format_log_context(
             "database_query",
@@ -287,5 +273,5 @@ def format_log_context(
         "timestamp": time.time(),
     }
     context.update(context_data)
-    
-    return context
+
+    return context