nui-python-shared-utils 1.3.1__tar.gz → 1.3.3__tar.gz

{nui_python_shared_utils-1.3.1 → nui_python_shared_utils-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-python-shared-utils
-Version: 1.3.1
+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.3/nui_lambda_shared_utils/__init__.py

@@ -0,0 +1,44 @@
+"""
+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 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. "
+    "This shim will be removed in version 2.0.0.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+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.1 → nui_python_shared_utils-1.3.3}/nui_python_shared_utils.egg-info/SOURCES.txt

@@ -73,6 +73,7 @@ nui_shared_utils/slack_setup/setup_helpers.py
 redirect/README.md
 redirect/pyproject.toml
 redirect/setup.py
+scripts/bench_imports.py
 tests/__init__.py
 tests/test_aws_utils.py
 tests/test_base_client.py
@@ -84,6 +85,7 @@ tests/test_es_client.py
 tests/test_es_query_builder.py
 tests/test_jwt_auth.py
 tests/test_lambda_helpers.py
+tests/test_lazy_imports.py
 tests/test_log_processors.py
 tests/test_powertools_helpers.py
 tests/test_secrets_helper.py

nui_python_shared_utils-1.3.3/nui_shared_utils/__init__.py

@@ -0,0 +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.
+"""
+
+import importlib
+from typing import TYPE_CHECKING, Any, List
+
+# 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"),
+}
+
+# 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",
+}
+
+
+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
+
+    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}")
+
+
+def __dir__() -> List[str]:
+    return sorted(set(globals()) | set(_LAZY_EXPORTS) | {"slack_setup"})
+
+
+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_pattern_detection_query,
+        build_response_time_query,
+        build_service_volume_query,
+        build_tender_participant_query,
+        build_top_errors_query,
+        build_user_activity_query,
+    )
+    from .db_client import DatabaseClient, PostgreSQLClient, get_pool_stats
+    from .powertools_helpers import get_powertools_logger, powertools_handler
+    from .jwt_auth import (
+        AuthenticationError,
+        JWTValidationError,
+        check_auth,
+        get_jwt_public_key,
+        require_auth,
+        validate_jwt,
+    )
+    from . import slack_setup
+
+
+__all__ = list(sorted(set(_LAZY_EXPORTS) | {"slack_setup"}))

{nui_python_shared_utils-1.3.1 → nui_python_shared_utils-1.3.3}/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_python_shared_utils-1.3.1 → nui_python_shared_utils-1.3.3}/nui_shared_utils/es_client.py

@@ -52,14 +52,14 @@ class ElasticsearchClient(BaseClient, ServiceHealthMixin):
     def _resolve_credentials_from_env(self) -> Optional[Dict[str, Any]]:
         """Resolve Elasticsearch credentials from environment variables.
 
-        Checks for ES_PASSWORD (required to trigger).
-        ES_USERNAME defaults to "elastic" if not set.
+        Accepts both conventions: ES_PASSWORD/ES_USERNAME and ES_PASS/ES_USER.
+        Password is required to trigger. Username defaults to "elastic".
         """
-        password = os.environ.get("ES_PASSWORD")
+        password = os.environ.get("ES_PASSWORD") or os.environ.get("ES_PASS")
         if not password:
             return None
         return {
-            "username": os.environ.get("ES_USERNAME", "elastic"),
+            "username": os.environ.get("ES_USERNAME") or os.environ.get("ES_USER") or "elastic",
             "password": password,
         }
 

{nui_python_shared_utils-1.3.1 → nui_python_shared_utils-1.3.3}/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_python_shared_utils-1.3.1 → nui_python_shared_utils-1.3.3}/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")
@@ -112,13 +113,29 @@ def get_elasticsearch_credentials(secret_name: Optional[str] = None) -> Dict:
     """
     Get Elasticsearch credentials.
 
+    Precedence (matching BaseServiceClient pattern):
+    1. Environment variables (ES_PASSWORD/ES_PASS + ES_USERNAME/ES_USER)
+    2. AWS Secrets Manager
+
     Args:
-        secret_name: Override default from configuration or environment
+        secret_name: Override default secret name for Secrets Manager lookup.
+            Ignored when credentials are resolved from environment variables.
 
     Returns:
         Dict with host, username, password
     """
     config = get_config()
+
+    # Environment variables first (local dev, CLI usage)
+    es_password = os.environ.get("ES_PASSWORD") or os.environ.get("ES_PASS")
+    if es_password:
+        es_user = os.environ.get("ES_USERNAME") or os.environ.get("ES_USER") or "elastic"
+        host = os.environ.get("ES_HOST") or config.es_host
+        if ":" not in host and not host.startswith("http"):
+            host = f"{host}:9200"
+        return {"host": host, "username": es_user, "password": es_password}
+
+    # Secrets Manager (Lambda runtime)
     secret = secret_name or os.environ.get("ES_CREDENTIALS_SECRET") or config.es_credentials_secret
     if not secret:
         raise ValueError("No Elasticsearch secret name provided")