nui-python-shared-utils 1.4.1__tar.gz → 1.6.0__tar.gz

{nui_python_shared_utils-1.4.1 → nui_python_shared_utils-1.6.0}/.github/workflows/ci.yml

@@ -15,15 +15,17 @@ jobs:
         python-version: ['3.9', '3.10', '3.11', '3.12']
     
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
+      with:
+        persist-credentials: false
     
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
     
     - name: Cache pip dependencies
-      uses: actions/cache@v3
+      uses: actions/cache@v6
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml', '**/setup.py') }}
@@ -65,9 +67,9 @@ jobs:
         pytest --cov=nui_shared_utils --cov-report=xml --cov-report=term-missing -v
     
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v5
       with:
-        file: ./coverage.xml
+        files: ./coverage.xml
         flags: unittests
         name: codecov-umbrella
         fail_ci_if_error: false
@@ -78,10 +80,12 @@ jobs:
     needs: test
     
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
+      with:
+        persist-credentials: false
     
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v6
       with:
         python-version: '3.11'
     

{nui_python_shared_utils-1.4.1 → nui_python_shared_utils-1.6.0}/.github/workflows/publish.yml

@@ -3,9 +3,7 @@ name: Build and Publish to PyPI
 on:
   push:
     tags:
-      - '[0-9]*'  # Trigger on version tags like 1.3.0
-  release:
-    types: [published]
+      - '[0-9]*'  # Trigger on version tags like 1.3.0 (a published GitHub Release also creates the tag)
   workflow_dispatch:  # Allow manual triggering
 
 jobs:
@@ -17,10 +15,12 @@ jobs:
         python-version: ['3.9', '3.10', '3.11', '3.12']
     
     steps:
-    - uses: actions/checkout@v4
-    
+    - uses: actions/checkout@v5
+      with:
+        persist-credentials: false
+
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
     
@@ -41,9 +41,9 @@ jobs:
         pytest --cov=nui_shared_utils --cov-report=xml --cov-report=term-missing
     
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v5
       with:
-        file: ./coverage.xml
+        files: ./coverage.xml
         fail_ci_if_error: false
 
   build:
@@ -52,12 +52,13 @@ jobs:
     needs: test
     
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
       with:
+        persist-credentials: false
         fetch-depth: 0  # Full history for version calculation
     
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v6
       with:
         python-version: '3.11'
     
@@ -75,7 +76,7 @@ jobs:
         python -m tarfile -l dist/*.tar.gz
     
     - name: Upload artifacts
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v6
       with:
         name: dist
         path: dist/
@@ -85,7 +86,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: [test, build]
     # Only publish on tagged releases
-    if: github.event_name == 'release' || startsWith(github.ref, 'refs/tags/')
+    if: startsWith(github.ref, 'refs/tags/')
     environment:
       name: pypi
       url: https://pypi.org/project/nui-python-shared-utils/
@@ -96,7 +97,7 @@ jobs:
     
     steps:
     - name: Download artifacts
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v7
       with:
         name: dist
         path: dist/
@@ -106,13 +107,14 @@ jobs:
       with:
         verbose: true
         print-hash: true
+        skip-existing: true  # No-op instead of failing if the version is already on PyPI (safe re-runs)
 
   publish-test:
     name: Publish to TestPyPI
     runs-on: ubuntu-latest
     needs: [test, build]
-    # Publish to TestPyPI on manual trigger or development branches
-    if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/'))
+    # Publish to TestPyPI on manual (non-tag) dispatch only; tag pushes go to PyPI above
+    if: github.event_name == 'workflow_dispatch' && !startsWith(github.ref, 'refs/tags/')
     environment:
       name: testpypi
       url: https://test.pypi.org/project/nui-python-shared-utils/
@@ -123,7 +125,7 @@ jobs:
     
     steps:
     - name: Download artifacts
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v7
       with:
         name: dist
         path: dist/

{nui_python_shared_utils-1.4.1 → nui_python_shared_utils-1.6.0}/.github/workflows/test.yml

@@ -14,10 +14,12 @@ jobs:
         python-version: ['3.9', '3.10', '3.11']
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v5
+      with:
+        persist-credentials: false
     
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
     

{nui_python_shared_utils-1.4.1 → nui_python_shared_utils-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-python-shared-utils
-Version: 1.4.1
+Version: 1.6.0
 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.4.1 → nui_python_shared_utils-1.6.0}/docs/README.md

@@ -17,6 +17,7 @@ Welcome to the comprehensive documentation for `nui-python-shared-utils` (former
 Component-specific guides for major features:
 
 - **[AWS Powertools Integration](guides/powertools-integration.md)** - Standardized logging, metrics, and error handling
+- **[Structured Logging Contract](guides/structured-logging-contract.md)** - Canonical dotted field registry, request-scoped binders, and payload redaction
 - **[Lambda Context Helpers](guides/lambda-utilities.md)** - Environment info extraction for logging and metrics
 - **[Slack Integration](guides/slack-integration.md)** - Messaging, formatting, and file uploads
 - **[Elasticsearch Integration](guides/elasticsearch-integration.md)** - Search, bulk indexing, health checks

nui_python_shared_utils-1.6.0/docs/decisions/ADR-001-structured-logging-field-vocabulary.md

@@ -0,0 +1,108 @@
+# ADR-001: Structured logging field vocabulary
+
+**Status**: Proposed
+**Date**: 2026-07-11
+
+## Context
+
+This package is the shared logging entry point for a fleet of Python Lambda functions and
+long-running services whose structured logs are shipped to a central log store and queried by
+operators and automated agents. Reliable querying, dashboards, and alerting need a predictable
+field shape: consistent key names and stable leaf types across every producer.
+
+Today the logger helper (`get_powertools_logger`) sets service, level, timezone, and timestamp
+format, but takes no position on field names or shape. Each call site hand-assembles its own
+`extra={}` keys. Across the fleet this has grown several incompatible conventions in the same log
+stream: flat single-word keys (`order_id`), dotted namespaced keys (`request.order_id`), nested
+dicts (`extra={"request": {...}}`), and unstructured message strings.
+
+This is a **producer-side** problem, and its cost is independent of which store the logs land in:
+
+- A **schema-enforcing** store (Elasticsearch) turns field drift into loud failures: mapping
+  conflicts and silent nulls when `status` is a number in one document and a string in the next.
+- A **schema-less** store (VictoriaLogs, Loki) accepts the drift silently. `{"status": 200}` and
+  `{"status": "timeout"}` are both ingested with no error, and the skew surfaces later as a
+  dashboard panel or an alert rule (`5xx rate`, `exception spike`) that quietly stops matching.
+
+So the log store is deliberately out of scope for this decision (it is itself under evaluation),
+and the contract is **store-neutral**. The one property of the stack that does constrain the wire
+shape is producer-side:
+
+**The Powertools `Logger.append_keys` merge is shallow.** Binding context incrementally with
+nested dicts clobbers earlier keys: `append_keys(request={"a": 1})` then `append_keys(request={"b": 2})`
+emits `request={"b": 2}` and loses `a`. Dotted keys (`append_keys(**{"request.a": 1})`, then
+`request.b`) are independent top-level keys and both survive. (Confirmed on `aws-lambda-powertools`
+3.6.0.) Incremental binding (bind request at entry, add more later) therefore requires dotted keys.
+
+(Incidental, not load-bearing: while Elasticsearch is a store, it expands dotted field names into
+`object`-datatype paths at index time, so `request.order_id` and `{"request": {"order_id": ...}}`
+map and query identically. Wire shape does not change queryability there. A store swap does not
+disturb this decision because the decision does not rest on it.)
+
+## Decision
+
+This package owns a canonical **dotted** field vocabulary as the fleet's logging contract, defined
+independently of any log store:
+
+- **A field registry (schema object)**: one importable module where each canonical dotted field
+  carries its type, whether it is indexed (i.e. meant to be queried vs retrieval-only), a
+  sensitivity flag, and any deprecated aliases. Covers `request.*`, `user.*`, `route.*`,
+  `response.*`, `error.*`, `trace.*`, `request.body_json` / `response.output_json`, plus a `target`
+  routing field. Single source of truth from which the default redaction set and the field-migration
+  map are derived. (A plain `dataclass`, not a heavyweight model dependency: the registry is static
+  metadata.)
+- **Binding helpers** (`bind_request`, `bind_user`, `log_exception`, and a body helper that
+  serialises to a single `request.body_json` string with redaction) so callers never hand-type keys.
+- **A consistency test** that asserts the registry's names, importable so consumers guard against
+  drift in CI.
+- The vocabulary is **backend-agnostic**: consumed identically from the Powertools path and from a
+  standard-library JSON-formatter path, so short-lived functions and long-running services share one
+  contract.
+
+Wire shape is **dotted**, names are **snake_case** dotted paths. Nested-dict emission is not used.
+
+## Alternatives considered
+
+- **Nested dicts as the emitted shape.** Ergonomic to build in one call and natural in Python.
+  Rejected because it clobbers under incremental `append_keys` binding, and because the fleet's
+  existing namespaced emitters already use dotted. Nested-*feeling* ergonomics are kept: the binding
+  helpers take keyword args and emit dotted keys.
+- **Flat single-word keys** (`order_id`, `user_id`). Simplest, but no namespacing, so unrelated
+  fields collide and there is no structural grouping for operators or mappings.
+- **A per-repo constants module.** Two codebases independently grew partial dotted taxonomies, which
+  proves the convention is wanted, but a per-repo copy re-introduces drift. One shared registry is
+  the point.
+- **Bake the vocabulary into a single logger factory.** Cannot span the two logging backends in use,
+  so the contract lives in a backend-agnostic registry plus helpers rather than a factory.
+- **Defer the contract until the log store is chosen.** Rejected: the drift is producer-side and
+  costs the same under either candidate store. A store-neutral contract is the piece that survives
+  (and is required by) a store migration, not one that blocks on it. Under a schema-less store it is
+  the *only* drift guard, since nothing downstream rejects a malformed field.
+
+## Consequences
+
+- One field shape across the fleet; the cost of field-name/type drift (loud mapping conflicts on a
+  schema-enforcing store, silent query/alert skew on a schema-less one) goes away as consumers adopt
+  it.
+- `request.body_json` as one opaque, retrieval-only string keeps unbounded, caller-controlled payloads
+  from bloating the field set (a concern under any store, acute on a mapping-based one), and
+  centralises redaction in one helper. A response-payload twin (`response.output_json`) applies the
+  same treatment where a service logs unbounded response bodies.
+- Callers stop hand-assembling keys; a name change happens in one registry, not N call sites; CI
+  catches drift.
+- Consumers must migrate off flat/nested/message-only shapes. Adoption is opt-in per repo and staged,
+  so no consumer breaks on adoption.
+- The registry's `type` / `indexed` metadata lets a schema-enforcing store derive its index mapping
+  from the registry (define once, derive the mapping). That export is store-specific and belongs with
+  the store's own tooling, not in this store-neutral core.
+
+## Load-bearing premises (supersede triggers)
+
+- Powertools `append_keys` stays a shallow merge. If it gained deep-merge semantics, the nested
+  ergonomics argument would reopen.
+- Request-scoped context (bind at entry, clear at exit) is expressible on both backends without a
+  per-request logger factory. If a `contextvars`-based filter cannot isolate concurrent requests
+  cleanly on the long-running (non-Lambda) services, the backend-agnostic claim reopens.
+- The value of a producer-side vocabulary does not depend on the store enforcing a schema. (It is
+  higher, not lower, when the store enforces nothing.) A change of log store does not supersede this
+  ADR.

nui_python_shared_utils-1.6.0/docs/decisions/README.md

@@ -0,0 +1,26 @@
+# Architecture Decision Records
+
+Decisions that outlive any single change: the "why" behind a choice future readers will want to
+verify, challenge, or build on. These are scoped to this package.
+
+## Format
+
+```markdown
+# ADR-NNN: <Short title>
+
+**Status**: Proposed | Accepted | Superseded by ADR-XXX
+**Date**: YYYY-MM-DD
+
+## Context      # the situation forcing the decision (present tense, the standing rationale)
+## Decision     # what we decide to do
+## Alternatives considered
+## Consequences  # what this makes easier, harder, or rules out
+```
+
+Keep each ADR under two pages. Longer than that means it is a plan, not an ADR.
+
+## Index
+
+| # | Decision | Status | Date |
+|---|----------|--------|------|
+| [001](ADR-001-structured-logging-field-vocabulary.md) | Structured logging field vocabulary (dotted registry + helpers + consistency test) | Proposed | 2026-07-11 |

{nui_python_shared_utils-1.4.1 → nui_python_shared_utils-1.6.0}/docs/guides/powertools-integration.md

@@ -106,20 +106,29 @@ logger = get_powertools_logger("my-service", local_dev_colors=False)
 
 ### Structured Logging
 
-The logger supports structured logging with the `extra` parameter:
+The logger supports structured logging with the `extra` parameter. Use the shared
+**[structured logging contract](structured-logging-contract.md)** so field names are
+consistent and queryable across the fleet: dotted, snake_case keys via the `F`
+constants (and consumer-defined domain fields like `order.*`), not ad-hoc flat keys.
 
 ```python
+from nui_shared_utils import F
+
 logger.info(
     "Order processed successfully",
     extra={
-        "order_id": "ORD-12345",
-        "user_id": 789,
-        "total_amount": 250.00,
-        "processing_time_ms": 123
-    }
+        "order.id": "ORD-12345",        # consumer domain field (order.* namespace)
+        F.USER_ID: 789,
+        F.RESPONSE_DURATION_MS: 123,
+    },
 )
 ```
 
+Better still, bind request/user context once per request with the contract's binding
+helpers so every log line carries it automatically. See the
+[contract guide](structured-logging-contract.md) for `bind_request` / `bind_user` /
+`log_exception` and the full field registry.
+
 ### Elasticsearch-Compatible Timestamps
 
 The logger automatically formats timestamps for Elasticsearch compatibility:
@@ -209,7 +218,7 @@ def handler(event, context):
 ### Complete Example (All Features)
 
 ```python
-from nui_shared_utils import get_powertools_logger, powertools_handler
+from nui_shared_utils import get_powertools_logger, powertools_handler, F
 
 logger = get_powertools_logger("order-processor")
 
@@ -230,7 +239,7 @@ def handler(event, context):
     - Proper error response formatting
     """
 
-    logger.info("Processing order", extra={"event_id": event.get("id")})
+    logger.info("Processing order", extra={F.REQUEST_ID: event.get("id")})
 
     try:
         order = validate_order(event)
@@ -239,8 +248,8 @@ def handler(event, context):
         logger.info(
             "Order processed successfully",
             extra={
-                "order_id": order["id"],
-                "processing_time_ms": result["duration"]
+                "order.id": order["id"],                 # consumer domain field
+                F.RESPONSE_DURATION_MS: result["duration"],
             }
         )
 
@@ -250,7 +259,7 @@ def handler(event, context):
         }
 
     except ValidationError as e:
-        logger.error("Order validation failed", extra={"error": str(e)})
+        logger.error("Order validation failed", extra={F.ERROR_TYPE: type(e).__name__, F.ERROR_MESSAGE: str(e)})
         return {
             "statusCode": 400,
             "body": json.dumps({"error": "Invalid order"})
@@ -510,12 +519,17 @@ logger: Union[PowertoolsLogger, PythonLogger] = get_powertools_logger("my-servic
 
 ### 1. Use Structured Logging
 
+Use the [structured logging contract](structured-logging-contract.md)'s dotted field
+names (via `F` and consumer domain fields), not ad-hoc flat keys:
+
 ```python
-# ✓ Good - Searchable, filterable
+from nui_shared_utils import F
+
+# ✓ Good - Searchable, filterable, consistent field names
 logger.info("Order created", extra={
-    "order_id": order.id,
-    "user_id": user.id,
-    "amount": order.total
+    "order.id": order.id,       # consumer domain field
+    F.USER_ID: user.id,
+    F.RESPONSE_STATUS: 200,
 })
 
 # ✗ Bad - Unstructured string
@@ -563,6 +577,8 @@ def handler(event, context):
 ### 4. Graceful Error Handling
 
 ```python
+from nui_shared_utils import F
+
 @powertools_handler(service_name="my-service", slack_alert_channel="#errors")
 @logger.inject_lambda_context
 def handler(event, context):
@@ -573,7 +589,7 @@ def handler(event, context):
 
     except ValidationError as e:
         # Expected errors - log and return 400
-        logger.warning("Validation failed", extra={"error": str(e)})
+        logger.warning("Validation failed", extra={F.ERROR_TYPE: type(e).__name__, F.ERROR_MESSAGE: str(e)})
         return {"statusCode": 400, "body": json.dumps({"error": str(e)})}
 
     # Unexpected errors caught by decorator -> 500 + Slack alert