nui-python-shared-utils 2.0__tar.gz → 2.2__tar.gz

{nui_python_shared_utils-2.0 → nui_python_shared_utils-2.2}/.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [ main, master, develop ]
 
+permissions:
+  contents: read
+
 jobs:
   test:
     name: Test Python ${{ matrix.python-version }}
@@ -74,6 +77,42 @@ jobs:
         name: codecov-umbrella
         fail_ci_if_error: false
 
+  es-compat:
+    name: Elasticsearch client ${{ matrix.elasticsearch-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Every major the [elasticsearch] extra allows. The ES tests drive the
+        # real client with a stubbed transport, so a call shape that a major
+        # stops accepting fails here. 8.x is pinned at three points because the
+        # client handles `body=` differently across the major: 8.0-8.11 route it
+        # through the parameter-rewriting fallback, 8.12+ take it as a declared
+        # parameter, and a bare `8.*` only ever resolves to the latter.
+        elasticsearch-version: ['7.17.*', '8.0.*', '8.11.*', '8.*', '9.*']
+
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        persist-credentials: false
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest pytest-mock
+        pip install -e .
+        pip install "elasticsearch==${{ matrix.elasticsearch-version }}"
+        python -c "import elasticsearch; print('elasticsearch', elasticsearch.__version__)"
+
+    - name: Test Elasticsearch client
+      run: |
+        pytest tests/test_es_client.py tests/test_es_client_compat.py tests/test_es_query_builder.py -v
+
   build:
     name: Build Package
     runs-on: ubuntu-latest

{nui_python_shared_utils-2.0 → nui_python_shared_utils-2.2}/AGENTS.md

@@ -40,7 +40,7 @@ This is `nui-python-shared-utils`, a Python package providing production-ready u
 - **JWT Authentication** (`jwt_auth.py`) - RS256 token validation for API Gateway Lambdas (uses `rsa` package)
 - **LLM Helper** (`llm.py`) - Generic Anthropic (Claude) client plumbing: API-key/Bedrock auth, forced tool-use call, text call (uses `anthropic`)
 - **Error Handling** (`error_handler.py`) - Retry patterns with exponential backoff
-- **Timezone Utils** (`timezone.py`) - Timezone conversion and formatting utilities
+- **Timezone Utils** (`timezone.py`) - Timezone conversion and formatting utilities (stdlib `zoneinfo`)
 
 ### Optional Dependencies
 
@@ -52,6 +52,7 @@ The package uses optional extras to minimize Lambda bundle size:
 - `jwt` - RS256 JWT validation (`rsa` package)
 - `snowflake` - Pure-Python Snowflake SQL API client (`snowflake-sql-api`)
 - `llm` - Anthropic (Claude) client helper (`anthropic[bedrock]`, both API-key and Bedrock IAM auth)
+- `timezone` - `tzdata`, for minimal images with no system IANA database (Alpine, distroless)
 - `all` - All integrations
 - `dev` - Development and testing tools
 

{nui_python_shared_utils-2.0 → nui_python_shared_utils-2.2}/PKG-INFO

@@ -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.2/docs/decisions/ADR-007-elasticsearch-client-version-range.md

@@ -0,0 +1,85 @@
+# ADR-007: Support elasticsearch-py 7.17, 8.x and 9.x from one call shape
+
+**Status**: Proposed
+**Date**: 2026-07-27
+
+## Context
+
+The `[elasticsearch]` extra selects the client library a consumer installs alongside this
+package. Because an extra is a hard requirement range, a narrow range is not a
+conservative default: it is a wall. A consumer already on `elasticsearch>=8` cannot install
+`nui-python-shared-utils[elasticsearch]` at all if the extra caps at `<8` -- the resolver
+fails outright rather than degrading. Consumers span clusters of different vintages, so any
+single-major range excludes part of the audience.
+
+The client majors differ in how a request body is passed:
+
+- **7.17** takes the whole request as `body=`, with URL parameters (`size`, `ignore_unavailable`)
+  as separate keywords. It emits a deprecation warning for `body=` pointing at 8.x.
+- **8.x / 9.x** expose body fields as first-class keywords (`query=`, `aggs=`, `size=`) and keep
+  `body=` as a raw escape hatch. Mixing the two forms is the trap: passing `body=` *and* a body
+  field as a keyword folds that keyword into the caller's dict (mutating it in place) and raises
+  `ValueError: Received multiple values for 'size'` if the key is already present. So
+  `search(index=..., body=body, size=n)` works once, then fails the second time the same body
+  dict is reused with a different size.
+
+That mixed form is what `es_client` sent, which means the `<8` cap was not merely stale: the
+code as written was correct only for 7.x.
+
+## Decision
+
+The `[elasticsearch]` extra allows `>=7.17.0,<10.0.0`, and `es_client` sends the one call
+shape all three majors accept: `size` folded into a **copy** of the caller's body
+(`_body_with_size`), passed as `body=` with only genuine URL parameters
+(`ignore_unavailable`) as keywords. No version sniffing, no branching.
+
+- `search` / `aggregate` carry `size` inside the body copy; an explicit `size` argument wins
+  over a `size` already in the body, and the caller's dict is never mutated.
+- `count`, `cat.indices`, `info` and `cluster.health` already used a form valid on every major.
+- `get_indices_info` normalises the 8.x/9.x response wrapper to a plain `list`.
+
+`tests/test_es_client_compat.py` drives the real client with a stubbed transport (no server),
+so an incompatible call shape fails as a test rather than in a consumer's Lambda. The CI
+`es-compat` matrix runs it against 7.17, 8.x and 9.x, pinning 8.x at three points (8.0, 8.11
+and latest) because the client routes `body=` through the parameter-rewriting fallback up to
+8.11 and takes it as a declared parameter from 8.12 on.
+
+The `<10` ceiling is the untested next major, not a known incompatibility.
+
+## Alternatives considered
+
+- **Cap at `<8` and tell consumers to pin down.** The status quo. Rejected: it forecloses the
+  extra for anyone on a current client, and the resolver failure (`ResolutionImpossible`) gives
+  no path forward short of forking.
+- **Move to `>=8` only and use the native keyword API** (`query=`, `aggs=`, `size=`). Cleaner
+  code, and drops a deprecated form. Rejected because it moves the wall rather than removing
+  it: consumers on 7.17 clusters would be the ones locked out, and this package exists to be
+  installable next to what a consumer already runs.
+- **Detect the installed major at runtime and branch** (`body=` on 7.x, keywords on 8/9).
+  Rejected: two call paths, one of which is exercised only on whichever major CI happens to
+  install, for no behavioural gain over a shape that is already valid everywhere.
+- **Mock-only tests.** The existing ES tests replace `Elasticsearch` with a `Mock`, which pins
+  our call shape but cannot tell whether the installed client accepts it -- precisely the bug
+  class here. Hence the stubbed-transport tests against the real client.
+
+## Consequences
+
+- The extra installs alongside 7.17, 8.x or 9.x, so the ES helpers are reusable by consumers on
+  current clients instead of only legacy ones.
+- Body dicts are safe to reuse across calls on every major; the 8.x/9.x in-place mutation is gone.
+- `size` is a body field in the request we send. A consumer reading the wire format sees it in
+  the body rather than the query string, on every major.
+- The compat tests bind us to the real client's request-building layer, so a breaking change in a
+  future client shows up as a CI failure in the `es-compat` job.
+
+## Load-bearing premises (supersede triggers)
+
+- **`body=` remains a supported escape hatch on 8.x/9.x.** It is documented as such today. If a
+  future major removes it, the single-shape decision breaks and the choice becomes: drop 7.x and
+  move to the keyword API, or branch by version.
+- **Consumers still run 7.17 clients.** The whole cost here is keeping a deprecated call form
+  alive. Once no supported consumer needs 7.x, raising the floor to `>=8` and moving to the
+  native keyword API is strictly simpler.
+- **The extra's range is a hard constraint on the consumer's environment.** If the ES helpers
+  ever moved behind a runtime-optional import with no declared range, the reasoning for a wide
+  range would change.

nui_python_shared_utils-2.2/docs/decisions/ADR-008-stdlib-zoneinfo-over-pytz.md

@@ -0,0 +1,89 @@
+# ADR-008: Zone data from stdlib `zoneinfo`, not a bundled `pytz`
+
+**Status**: Proposed
+**Date**: 2026-07-27
+
+## Context
+
+Every install of this package pays for its base dependencies, whatever the consumer imports.
+`pytz` sat in that base set for two modules (`timezone.py`, `slack_formatter.py`), so a Lambda
+that wanted only the logging contract or the metrics helper still shipped it.
+
+The cost is not the code. `pytz` bundles its own copy of the Olson/IANA database (0.86 MB of a
+1.0 MB installed package, measured on `pytz==2025.2`), and that copy is redundant on
+every interpreter this package supports: `requires-python = ">=3.9"`, and `zoneinfo` has been in
+the standard library since 3.9, reading the system database that Linux, macOS, and the AWS Lambda
+runtimes all ship.
+
+`pytz` also carries an API predating PEP 495. Its zones must be attached through
+`tz.localize(dt)` rather than `datetime(..., tzinfo=tz)`, because a bare `pytz` zone object
+defaults to whatever offset was in effect at the start of that zone's records: attaching
+`pytz.timezone("Pacific/Auckland")` to a 2024 datetime yields the 1868 LMT offset of `+11:39`.
+`ZoneInfo` resolves the offset from the datetime itself, giving `+13:00`, so the direct
+constructor form is correct.
+
+## Decision
+
+Zone data comes from stdlib `zoneinfo`. `pytz` is dropped from the base dependencies and from
+the package entirely, with no compatibility shim.
+
+- `NZ_TZ`, `AUS_TZ`, `US_EAST_TZ`, `US_WEST_TZ`, `EUR_TZ` are `ZoneInfo` instances.
+- `pytz.UTC.localize(dt)` becomes `dt.replace(tzinfo=timezone.utc)`.
+- `slack_formatter` imports `NZ_TZ` from `timezone` rather than constructing its own zone, so
+  one module owns the zone constants.
+- The package's own conversions take UTC input, so no code path here has to resolve an ambiguous
+  wall time. Callers attaching a zone to a naive local time do, and the default differs from
+  `pytz`: `datetime(..., tzinfo=NZ_TZ)` uses `fold=0`, the first (still-daylight) occurrence of a
+  repeated hour, where `pytz.localize()` defaulted to `is_dst=False`, the second. `fold=1`
+  reproduces the old default. `TestAmbiguousWallTimes` pins both sides.
+
+Zone data availability is handled where it actually differs by platform, rather than by shipping
+a database to everyone:
+
+- `tzdata>=2023.3; platform_system == "Windows"` in the base dependencies. Windows ships no
+  system database; POSIX consumers resolve the marker to nothing and install neither package.
+- A `[timezone]` extra (`tzdata`) for minimal images (Alpine, distroless) that carry no
+  `/usr/share/zoneinfo`. No environment marker can detect those, so it is opt-in.
+
+## Alternatives considered
+
+- **Move `pytz` into an extra, keep the code as-is.** Fixes the unconditional cost and nothing
+  else: consumers of `timezone.py` still install a redundant database, and the `localize()` API
+  stays. Rejected as half the change for most of the churn.
+- **Keep `pytz` and accept the base-dependency cost.** The status quo. Rejected: the package
+  exists to be bundled into Lambdas, where the base set is the floor nobody can opt out of.
+- **Depend on `tzdata` unconditionally instead of the system database.** Trades one bundled
+  database for another (a 0.35 MB wheel) on platforms that already have one. Rejected; the
+  marker plus the extra cover the platforms that genuinely need it.
+- **Ship a `localize()`-compatible wrapper for the exported zone constants.** Rejected: it
+  preserves a pre-PEP-495 idiom indefinitely to spare a one-line call-site change.
+
+## Consequences
+
+- A base install drops ~1 MB and one runtime dependency. Nothing in the package imports a
+  third-party timezone library.
+- **Breaking for code importing the zone constants from `nui_shared_utils.timezone`.**
+  `NZ_TZ.localize(dt)` is gone; use `datetime(..., tzinfo=NZ_TZ)` or `dt.replace(tzinfo=NZ_TZ)`,
+  with `fold=1` where the old `is_dst=False` default mattered. `NZ_TZ.zone` is now `NZ_TZ.key`.
+  The top-level package exports only `nz_time` / `format_nz_time`, whose behaviour is unchanged,
+  so consumers going through `nui_shared_utils` see nothing.
+- Attaching a zone at construction is now correct rather than a bug, so the sharp edge that made
+  `localize()` mandatory is gone.
+- `slack_formatter.format_nz_time()` called with no argument is fixed as a side effect. It built
+  a naive `datetime.utcnow()` and handed it to `astimezone()`, which reads a naive datetime as
+  *local* time: right on a UTC host, an hour or thirteen out anywhere else. It now starts from an
+  aware UTC now, so the result no longer depends on the host clock's zone.
+- On an image with no system database, `import nui_shared_utils.timezone` raises
+  `ZoneInfoNotFoundError` instead of silently working. That is a louder failure than `pytz` gave,
+  and the `[timezone]` extra is the fix.
+- Zone data tracks the host, not a pinned package version. DST rule changes arrive with system
+  updates instead of a dependency bump, which is the desired direction for long-lived Lambda
+  images but does mean a stale base image carries stale rules.
+
+## Load-bearing premises (supersede triggers)
+
+- **The interpreter floor stays at 3.9+.** `zoneinfo` is stdlib from 3.9. A drop below that
+  would need `backports.zoneinfo`, at which point the calculus changes.
+- **Target runtimes ship a system IANA database.** True of Linux, macOS, and the AWS Lambda
+  runtimes today. If the primary deployment target became one that does not, `tzdata` belongs in
+  the base dependencies unconditionally and this ADR's marker split is obsolete.

{nui_python_shared_utils-2.0 → nui_python_shared_utils-2.2}/docs/decisions/README.md

@@ -29,3 +29,5 @@ Keep each ADR under two pages. Longer than that means it is a plan, not an ADR.
 | [004](ADR-004-credential-resolution-precedence.md) | Credential resolution precedence: explicit dict, then env vars, then Secrets Manager | Proposed | 2026-07-13 |
 | [005](ADR-005-explicit-secrets-manager-region.md) | Resolve the Secrets Manager region explicitly (session, then env); no hidden default, fail loud | Proposed | 2026-07-13 |
 | [006](ADR-006-snowflake-sql-api-client.md) | Snowflake access via the pure-Python SQL API client, not the native connector | Proposed | 2026-07-13 |
+| [007](ADR-007-elasticsearch-client-version-range.md) | Support elasticsearch-py 7.17, 8.x and 9.x from one call shape | Proposed | 2026-07-27 |
+| [008](ADR-008-stdlib-zoneinfo-over-pytz.md) | Zone data from stdlib `zoneinfo`, not a bundled `pytz` | Proposed | 2026-07-27 |

{nui_python_shared_utils-2.0 → nui_python_shared_utils-2.2}/docs/getting-started/installation.md

@@ -34,6 +34,9 @@ pip install nui-python-shared-utils[database]
 # JWT authentication only
 pip install nui-python-shared-utils[jwt]
 
+# Zone data, for minimal images with no system IANA database (Alpine, distroless)
+pip install nui-python-shared-utils[timezone]
+
 # All integrations
 pip install nui-python-shared-utils[all]
 
@@ -59,15 +62,23 @@ pip install -e .[dev]
 ### Core Dependencies (Always Installed)
 
 - `boto3` - AWS SDK for Python
-- `pytz` - Timezone handling
 - `click` - CLI framework
 - `pyyaml` - YAML configuration parsing
+- `tzdata` - Zone data, **Windows only** (installed via an environment marker)
+
+Timezone conversion uses the standard library's `zoneinfo`, which reads the
+system IANA database. Linux, macOS, and the AWS Lambda runtimes all ship one,
+so nothing extra is installed there.
 
 ### Optional Dependencies by Extra
 
 #### elasticsearch
 
-- `elasticsearch>=7.17.0,<8.0.0` - Elasticsearch client
+- `elasticsearch>=7.17.0,<10.0.0` - Elasticsearch client
+
+  Client majors 7.17, 8.x and 9.x are all supported and tested; pick whichever
+  your cluster needs. The `<10` ceiling is the untested next major, not a known
+  incompatibility. See [ADR-007](../decisions/ADR-007-elasticsearch-client-version-range.md).
 
 #### database
 
@@ -82,6 +93,18 @@ pip install -e .[dev]
 
 - `rsa>=4.9` - Pure Python RSA implementation (~100KB, no C extensions)
 
+#### timezone
+
+- `tzdata>=2023.3` - Zone data for images that carry no system IANA database
+
+  Only needed on a minimal image (Alpine, distroless) where `/usr/share/zoneinfo`
+  is absent, which no environment marker can detect. Without it, importing
+  `nui_shared_utils.timezone` raises `ZoneInfoNotFoundError`. Windows already
+  gets `tzdata` from the core dependencies.
+
+  `[all]` covers the integrations and does **not** include this; on a minimal
+  image ask for it by name (`[all,timezone]`).
+
 #### dev
 
 - `pytest>=7.0.0` - Testing framework

{nui_python_shared_utils-2.0 → nui_python_shared_utils-2.2}/docs/guides/elasticsearch-integration.md

@@ -35,6 +35,23 @@ Install with the elasticsearch extra:
 pip install nui-python-shared-utils[elasticsearch]
 ```
 
+### Supported client versions
+
+The extra allows `elasticsearch>=7.17.0,<10.0.0`. Client majors 7.17, 8.x and 9.x are all
+supported and covered by CI, so the extra installs alongside whichever client your cluster
+needs. `ElasticsearchClient` sends one request form that every one of those majors accepts;
+`size` travels inside the request body rather than as a separate argument, and your body dict
+is copied, never mutated, so it is safe to reuse across calls.
+
+Pin the client yourself if you need a specific major:
+
+```bash
+pip install nui-python-shared-utils[elasticsearch] "elasticsearch<9"
+```
+
+See [ADR-007](../decisions/ADR-007-elasticsearch-client-version-range.md) for the reasoning
+and the `<10` ceiling.
+
 ## Configuration
 
 ### AWS Secrets Manager Setup