021-python-clients 0.4.0__tar.gz → 0.5.0__tar.gz

{021_python_clients-0.4.0 → 021_python_clients-0.5.0}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes are recorded here by release-please from Conventional Commits.
 
+## [0.5.0](https://github.com/from021-io/python-clients/compare/v0.4.0...v0.5.0) (2026-10-29)
+
+
+### Features
+
+* **compute:** create and delete Job-owned Secrets ([7f62939](https://github.com/from021-io/python-clients/commit/7f62939c08b5bc1672543e8819cb0781028320b7))
+* **compute:** create and delete Job-owned Secrets ([9507539](https://github.com/from021-io/python-clients/commit/9507539a84882b29a6f6baa63e1a9df17c08add8))
+* **featureflags:** add AppConfig feature flags client ([039c2b2](https://github.com/from021-io/python-clients/commit/039c2b2cc27f3cc3715a892032e369047bb108a3))
+* **featureflags:** add AppConfig feature flags client ([2c40ddb](https://github.com/from021-io/python-clients/commit/2c40ddbb493dca39d483406b28ffa7cfa883faba))
+
+
+### Bug fixes
+
+* **ci:** actualiza herramientas de instalación y publicación ([5c35e84](https://github.com/from021-io/python-clients/commit/5c35e844f679ce905335629ed7d3b4608b77c988))
+* **ci:** actualiza herramientas de instalación y publicación ([234a84a](https://github.com/from021-io/python-clients/commit/234a84af950a9e0d2f9460e807d124411b367953))
+* **deps:** support observability 0.4 ([#23](https://github.com/from021-io/python-clients/issues/23)) ([7363894](https://github.com/from021-io/python-clients/commit/7363894a8010abd345a60a54f29a55247e3307a3))
+
 ## [0.4.0](https://github.com/from021-io/python-clients/compare/v0.3.0...v0.4.0) (2026-10-22)
 
 

{021_python_clients-0.4.0 → 021_python_clients-0.5.0}/CONTRACT.md

@@ -49,6 +49,8 @@ version, environment). Durations use 021-python-observability's buckets.
 | `llm.client.token.usage` | Counter / `{token}` | dependency, operation, token.type | Bedrock (Converse and ConverseStream) |
 | `compute.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | Kubernetes Jobs |
 | `compute.client.operation.duration` | Histogram / `s` | same | Kubernetes Jobs |
+| `config.client.operation.count` | Counter / `{operation}` | dependency, operation, status, error.type | Feature flags (AppConfig) |
+| `config.client.operation.duration` | Histogram / `s` | same | Feature flags (AppConfig) |
 | `http.client.request.count` | Counter / `{request}` | dependency, http.request.method, http.response.status_code, error.type, http.response.body.complete | HTTP, httpx2, QStash transport, Resend (its HTTP request) |
 | `http.client.request.duration` | Histogram / `s` | same | HTTP, httpx2, QStash transport, Resend (its HTTP request) |
 
@@ -59,15 +61,18 @@ version, environment). Durations use 021-python-observability's buckets.
   Email (Resend, SES): `send`. KMS:
   `encrypt`, `decrypt`, `generate_data_key`; `seal` and `unseal` record the KMS call they make
   (`generate_data_key`, `decrypt`), not the local AES work. Secrets Manager: `get`.
+  Feature flags: `start_session`, `get_configuration`; reading a flag from the snapshot
+  records nothing.
   Bedrock: `converse`, `converse_stream`, `invoke_model`, `invoke_model_with_response_stream`,
   `count_tokens`. A streaming operation ends when its event stream is exhausted, fails or is
-  closed, not when the call returns. Kubernetes Jobs: `create`, `get`, `delete`; each also
-  records its HTTP request (`http.client.request.*`) under the same `dependency`. A missing
-  Job (`get`, `delete`) and an existing one (`create`) are `status=ok`.
+  closed, not when the call returns. Kubernetes Jobs: `create`, `get`, `delete`, `create_secret`,
+  `delete_secret`; each also records its HTTP request (`http.client.request.*`) under the same
+  `dependency`. A missing Job or Secret (`get`, `delete`, `delete_secret`) and an existing one
+  (`create`, `create_secret`) are `status=ok`.
 - `token.type`: `input`, `output`, `cache_read`, `cache_write`, as reported by Bedrock in
   the Converse response or the ConverseStream `metadata` event. InvokeModel bodies are
   model-specific and are not read.
-- Redis/SQS/S3/Vercel Blob/QStash/email/KMS/Secrets Manager/Bedrock/Kubernetes Jobs `error.type`: `timeout`, `connection_error`, `throttled`,
+- Redis/SQS/S3/Vercel Blob/QStash/email/KMS/Secrets Manager/Bedrock/Kubernetes Jobs/feature flags `error.type`: `timeout`, `connection_error`, `throttled`,
   `status_<5xx>`, `cancelled`, or the exception class name for errors that are not outages
   (`EmailRejected` for every email rejection; botocore's class, such as `ClientError` or
   `NotFoundException`, for KMS).
@@ -87,10 +92,11 @@ version, environment). Durations use 021-python-observability's buckets.
 CLIENT spans named `<dependency> <operation>` (`HTTP <dependency>` for HTTP), with the
 metric labels plus `db.system.name=redis`, `messaging.system=aws_sqs`,
 `messaging.system=upstash_qstash`, `messaging.system=resend`, `messaging.system=aws_ses`, or
-`rpc.system=aws-api` + `rpc.service=S3` / `rpc.service=KMS` / `rpc.service=SecretsManager` /
+`rpc.system=aws-api` + `rpc.service=S3` / `rpc.service=KMS` / `rpc.service=AppConfigData` / `rpc.service=SecretsManager` /
 `rpc.service=BedrockRuntime` (plus `gen_ai.system=aws.bedrock`), `rpc.system=vercel-blob`, or
-`rpc.system=kubernetes` + `rpc.service=Job`. Kubernetes Jobs' `HTTP <dependency>` span is a
-child of its `<dependency> <operation>` span.
+`rpc.system=kubernetes` + `rpc.service=Job` (`rpc.service=Secret` for `create_secret` and
+`delete_secret`). Kubernetes Jobs' `HTTP <dependency>` span is a child of its
+`<dependency> <operation>` span.
 Resend's `HTTP <dependency>` span is a child of its `<dependency> send` span. Status ERROR on failure (and on HTTP
 status ≥ 400).
 Cancellation propagates unchanged and records ERROR with `error.type=cancelled`.
@@ -117,7 +123,7 @@ Local input validation occurs before either operation is recorded.
 
 ## Logging and coverage limits
 
-Redis, SQS, QStash, S3, Vercel Blob, Resend, SES, KMS, Secrets Manager, Bedrock and Kubernetes Jobs emit a structured
+Redis, SQS, QStash, S3, Vercel Blob, Resend, SES, KMS, Secrets Manager, Bedrock, Kubernetes Jobs and feature flags emit a structured
 `dependency.call_failed` warning when an observed remote operation raises an exception.
 Fields are `dependency`, `operation` and `error_type`; provider messages and exception
 chains are not logged. Successful calls and cancellation do not emit this warning;
@@ -157,7 +163,7 @@ telemetry reaches an external backend.
   When enabled, both caller-supplied trace headers are replaced with the current context.
 - Resend: nothing is sent. The `traceparent`, `tracestate` and `x-request-id` headers that
   the HTTP transport adds are removed before the request leaves.
-- SES, KMS, Secrets Manager, Bedrock and Vercel Blob: nothing is sent by the default transports.
+- SES, KMS, Secrets Manager, Bedrock, feature flags and Vercel Blob: nothing is sent by the default transports.
 - SQS: `traceparent` and `tracestate` are message attributes; `ReceivedMessage.trace_context()`
   returns the producer's context. Caller-supplied values for both trace attributes are
   replaced with the current context.
@@ -200,6 +206,14 @@ it. Resend's request is sent once; `idempotency_key` becomes its `Idempotency-Ke
 (1–256 characters, kept by Resend for 24 hours). SES has no idempotency key: the argument is
 validated and ignored.
 
+Feature flags: throttling, 5xx, timeouts and connection failures are `DependencyUnavailable`,
+raised only while no snapshot exists; once one does, a failed refresh serves it stale and
+retries after `retry_seconds`. Access denied and missing application, environment or profile
+keep their botocore type. A configuration that is not feature flag JSON (an object of
+`{"enabled": bool, ...}` entries) raises `ValueError` on the first load and is ignored, with a
+`featureflags.invalid_configuration` warning, afterwards. An expired session token
+(`BadRequestException`) opens one new session.
+
 KMS: throttling, 5xx (`KMSInternalException`, `DependencyTimeoutException`,
 `KeyUnavailableException`), timeouts and connection failures are `DependencyUnavailable`.
 Access denied, disabled or missing keys, invalid key state, a wrong encryption context or a
@@ -225,13 +239,21 @@ at INFO. A model call is not idempotent in cost: botocore's retries bill each at
 
 Kubernetes Jobs: 429 is `throttled`, 5xx `status_<5xx>`, transport timeouts and connection
 failures `timeout` / `connection_error`, all `DependencyUnavailable`. A 409 whose reason is
-`AlreadyExists` on `create` and a 404 on `get` or `delete` are results, not errors. Any other
+`AlreadyExists` on `create` or `create_secret` and a 404 on `get`, `delete` or `delete_secret`
+are results, not errors. Any other
 non-success status raises `KubernetesApiError(status_code, reason)`, where `reason` is the
 Status object's machine-readable reason (`Forbidden`, `Invalid`, `Conflict`, ...) or
 `Unknown`; a 201 whose name does not match raises it with `InvalidResponse`. POST is sent
 once; GET and DELETE retry 502/503/504 and network failures once. Local validation (DNS-label
 names and namespace, `metadata.name` required, `generateName` refused, `kind` must be Job)
-happens before any request.
+happens before any request. `JobCreated.uid` (on 201) and `JobStatus.uid` carry the Job's
+`metadata.uid`, or `None` when absent or when `create` found an existing Job.
+`create_secret(name, data, *, job, job_uid)` posts an `Opaque`, `immutable` Secret with base64
+`data` and one owner reference (`batch/v1` Job, name and uid, no `blockOwnerDeletion`); an
+existing Secret is kept unchanged (`SecretCreated(created=False)`). Its local validation
+(DNS-label Secret and Job names, non-empty `data`, keys of 1-253 letters, digits, `-`, `_`
+or `.`, `str` or `bytes` values, a uid of letters, digits and `-`) raises `ValueError`
+before any request, with a message that names neither keys nor values.
 
 Vercel Blob (`clients_021.storage.vercel_blob`): HTTP 429 maps to `throttled`; 5xx to
 `status_<code>`; HTTP timeouts and total deadlines to `timeout`; network/remote protocol
@@ -254,8 +276,8 @@ A new data key is generated for every envelope.
 
 ## Lifecycle and retry limits
 
-HTTP, Redis, SQS, QStash, S3, Vercel Blob, Resend, SES, KMS, Secrets Manager, Bedrock and Kubernetes
-Jobs expose `aclose()` (Bedrock also `close()`). Close them after
+HTTP, Redis, SQS, QStash, S3, Vercel Blob, Resend, SES, KMS, Secrets Manager, Bedrock, Kubernetes
+Jobs and feature flags expose `aclose()` (Bedrock also `close()`). Close them after
 in-flight calls complete; the wrapper owns the underlying client, including one supplied
 through the constructor.
 AWS factories configure three total attempts; injected clients retain their own policy.
@@ -307,13 +329,15 @@ these clients, or each request would be counted twice.
 
 ## Never recorded
 
-Keys, URLs, query strings, bodies, message ids, receipts, object names, bucket or queue
+Feature flags: application, environment and profile identifiers, flag names, attributes, values
+and session tokens. Keys, URLs, query strings, bodies, message ids, receipts, object names, bucket or queue
 names, provider error messages. Email: sender, recipient and reply-to addresses, subjects,
 text and HTML bodies, tags, idempotency keys, API keys, configuration set names. KMS: key
 ids, ARNs and aliases, encryption contexts, plaintext, ciphertext and data keys. Secrets
 Manager: secret ids, names and ARNs, version ids, version stages and secret values. Bedrock:
 model ids, inference profile ARNs, prompts, system prompts, outputs, tool arguments and
 results, request ids and guardrail details. Kubernetes Jobs: namespaces, Job names, labels,
-manifests, API server addresses, service account tokens and Status messages.
+manifests, API server addresses, service account tokens and Status messages; Secret names,
+data keys and values (plain or base64), owner Job names and uids.
 
 Vercel Blob: read-write tokens, store IDs, pathnames, delivery URLs, content and ETags.

021_python_clients-0.4.0/README.md → 021_python_clients-0.5.0/PKG-INFO

@@ -1,3 +1,39 @@
+Metadata-Version: 2.5
+Name: 021-python-clients
+Version: 0.5.0
+Summary: Observed clients for Redis, SQS, QStash, S3, Vercel Blob, HTTP, email, KMS, Secrets Manager, Bedrock and Kubernetes Jobs and AppConfig feature flags, built on 021-python-observability
+Project-URL: Repository, https://github.com/from021-io/python-clients
+Project-URL: Changelog, https://github.com/from021-io/python-clients/blob/main/CHANGELOG.md
+Project-URL: Contract, https://github.com/from021-io/python-clients/blob/main/CONTRACT.md
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: appconfig,bedrock,email,feature-flags,httpx,kms,kubernetes,observability,opentelemetry,qstash,redis,resend,s3,secrets-manager,ses,sqs
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: 021-python-observability<0.5,>=0.3
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: opentelemetry-api<2,>=1.44
+Provides-Extra: aws
+Requires-Dist: boto3<2,>=1.40; extra == 'aws'
+Requires-Dist: cryptography>=44; extra == 'aws'
+Provides-Extra: httpx2
+Requires-Dist: httpx2<3,>=2; extra == 'httpx2'
+Provides-Extra: redis
+Requires-Dist: redis<9,>=6; extra == 'redis'
+Provides-Extra: vercel-blob
+Requires-Dist: httpx2<3,>=2; extra == 'vercel-blob'
+Requires-Dist: vercel-blob<0.6,>=0.5; extra == 'vercel-blob'
+Description-Content-Type: text/markdown
+
 # 021-python-clients
 
 Clients for the external services our Python services call, with the observability of
@@ -23,7 +59,9 @@ uv add "021-python-clients[redis,aws,httpx2,vercel-blob]"   # pick the extras yo
 | `clients_021.email.ses` | `aws` | `SesSender`: the same protocol over Amazon SES v2 |
 | `clients_021.crypto.kms` | `aws` | `KmsClient`: encrypt, decrypt and data keys bound to an encryption context; AES-256-GCM envelopes |
 | `clients_021.secrets.secrets_manager` | `aws` | `SecretsManagerClient`: read a secret by id, version id or stage; the value is never printed |
-| `clients_021.compute.kubernetes` | none | `KubernetesJobsClient`: create (idempotent by name), read and delete Jobs in a namespace, in-cluster service account |
+| `clients_021.compute.kubernetes` | none | `KubernetesJobsClient`: create (idempotent by name), read and delete Jobs in a namespace, and the Secrets they own; in-cluster service account |
+| `clients_021.featureflags` | none | `Flag` and the `FeatureFlags` protocol services type against |
+| `clients_021.featureflags.appconfig` | `aws` | `AppConfigFlags`: AWS AppConfig feature flags, cached and refreshed on an interval |
 | `clients_021.llm.bedrock` | `aws` | `BedrockRuntime`: an observed `bedrock-runtime` client to pass to SDKs such as LangChain's `ChatBedrockConverse`; streams measured to the end, token usage counted |
 
 Every client takes the service's `Observability` (from `setup_observability`) and a
@@ -33,7 +71,7 @@ Every client takes the service's `Observability` (from `setup_observability`) an
 
 Providers with the same purpose live under one capability package: `email/` contains
 Resend and SES; `queue/` contains SQS and QStash; `storage/` contains S3 and Vercel Blob; `cache/`
-contains Redis; `crypto/` contains KMS; `secrets/` contains Secrets Manager; `llm/` contains Bedrock; `compute/` contains Kubernetes Jobs. `http/` contains the httpx client and httpx2
+contains Redis; `crypto/` contains KMS; `secrets/` contains Secrets Manager; `llm/` contains Bedrock; `compute/` contains Kubernetes Jobs; `featureflags/` contains AppConfig. `http/` contains the httpx client and httpx2
 transport. Import providers explicitly:
 
 ```python
@@ -65,13 +103,13 @@ published exports; `clients_021.httpx2.ObservedTransport` remains an alias for
 
 - A CLIENT span named `<dependency> <operation>` (`HTTP <dependency>` for HTTP), with the
   system attribute (`db.system.name=redis`, `messaging.system=aws_sqs|resend|aws_ses`,
-  `rpc.service=S3|KMS|SecretsManager|BedrockRuntime`, `rpc.system=vercel-blob`, `rpc.system=kubernetes`;
+  `rpc.service=S3|KMS|SecretsManager|BedrockRuntime|AppConfigData`, `rpc.system=vercel-blob`, `rpc.system=kubernetes`;
   Bedrock also `gen_ai.system=aws.bedrock`).
 - A counter and a duration histogram: `db.client.operation.*` (Redis, shared with SQL),
   `messaging.client.operation.*` (SQS, QStash, email), `storage.client.operation.*` (S3, Vercel Blob),
   `crypto.client.operation.*` (KMS), `secrets.client.operation.*` (Secrets Manager),
   `llm.client.operation.*` and `llm.client.token.usage` (Bedrock), `compute.client.operation.*`
-  (Kubernetes Jobs),
+  (Kubernetes Jobs), `config.client.operation.*` (feature flags),
   `http.client.request.*` (HTTP, and the HTTP request
   under QStash and Resend). Labels are bounded; see [CONTRACT.md](CONTRACT.md).
 - Redis, SQS, QStash, S3, Vercel Blob, email, KMS, Secrets Manager, Bedrock and Kubernetes Jobs emit a `dependency.call_failed` warning on failure,
@@ -85,7 +123,7 @@ published exports; `clients_021.httpx2.ObservedTransport` remains an alias for
 Never in this library's spans, metrics or logs: keys, URLs, bodies, message ids or object
 names; email addresses, subjects, bodies or tags; secret ids, version ids, stages and
 values; model ids, prompts and outputs; namespaces, Job names, manifests and service
-account tokens; KMS key ids, encryption contexts,
+account tokens; feature flag names, values and AppConfig identifiers; KMS key ids, encryption contexts,
 plaintext, ciphertext or data keys. Use static dependency names such as `identity-provider` or `uploads`; never derive
 them from a tenant, user or request. All clients apply observability's identifier rule
 (1–96 letters, digits, `_`, `.` or `-`, starting with a letter or digit).
@@ -268,6 +306,33 @@ DELETE retry 502, 503, 504 and network failures once. 429, 5xx, timeouts and con
 failures raise `DependencyUnavailable`; other rejections raise `KubernetesApiError` with the
 status code and the API's reason, never its message.
 
+A value the pod needs but that must not be readable in the Job's spec (a run token, say) goes
+in a Secret the Job owns:
+
+```python
+created = await jobs.create(manifest)      # the container reads env from secretKeyRef
+uid = created.uid or (await jobs.get(name)).uid   # None in created when the Job existed
+await jobs.create_secret(f"{name}-token", {"token": run_token}, job=name, job_uid=uid)
+```
+
+```yaml
+env:
+  - name: RUN_TOKEN
+    valueFrom: { secretKeyRef: { name: cmd-4821-token, key: token } }
+```
+
+The Secret is `Opaque` and `immutable`, with an owner reference to the Job's name and uid, so
+the garbage collector deletes it with the Job (including through `ttlSecondsAfterFinished`).
+The Job is created first because the reference needs its uid; the kubelet keeps retrying a
+pod whose Secret does not exist yet. `create_secret` is idempotent by name like `create`: a
+409 `AlreadyExists` returns `created=False` and keeps the existing Secret without comparing or
+updating it, so a retry must reuse the same value (or `delete_secret` and create again).
+`delete_secret` returns `False` when there was none. `blockOwnerDeletion` is not set, so the
+caller needs only `create` and `delete` on `secrets` (no `get`, and nothing on
+`jobs/finalizers`). Secret names, data keys and values never reach telemetry, logs or error
+messages; the request body is still in the chained httpx exception's `request`, so do not log
+`__cause__` details.
+
 ### Bedrock
 
 ```python
@@ -306,6 +371,33 @@ copy when the same secret is read often. A missing secret, access denied, a valu
 decrypt or a secret scheduled for deletion keep their botocore type; throttling, 5xx and
 timeouts raise `DependencyUnavailable`. `repr(secret)` never shows the value.
 
+### Feature flags (AWS AppConfig)
+
+Reads [AppConfig feature flags](https://aws.amazon.com/blogs/mt/using-aws-appconfig-feature-flags/)
+through the AppConfig Data API and keeps a snapshot in memory; evaluating a flag is a lookup:
+
+```python
+from clients_021.featureflags import FeatureFlags          # the protocol, no extra needed
+from clients_021.featureflags.appconfig import AppConfigFlags
+
+flags: FeatureFlags = AppConfigFlags.create(
+    obs, settings.appconfig_app, settings.appconfig_env, settings.appconfig_profile,
+    region="us-east-1",
+)
+if await flags.is_enabled("new-checkout"):          # unknown flag -> default=False
+    ...
+limit = await flags.flag("rate-limit")              # Flag(enabled=True, attributes={"rps": 50})
+```
+
+The snapshot is refreshed by the first request after `refresh_seconds` (default 45, minimum
+15), one poll at a time. If a refresh fails while a snapshot exists, the stale one keeps
+serving and the next attempt is 15 seconds later; with no snapshot yet the outage raises
+`DependencyUnavailable`. A configuration that is not valid flag JSON raises `ValueError` on
+the first load and is ignored with a warning afterwards. Supports plain flags and their
+attributes; multi-variant flags and rules need the AppConfig Agent, which evaluates them.
+The IAM role needs `appconfig:StartConfigurationSession` and
+`appconfig:GetLatestConfiguration` on the configuration profile.
+
 ### KMS
 
 The encryption context is required on every call, so a ciphertext only decrypts for the
@@ -422,7 +514,7 @@ Retry policies are explicit:
   POST and PATCH run once. Invalid URLs/protocols and invalid request construction keep
   their original exception. HTTP status responses are returned for the caller to handle.
 - Resend sends each request once (POST); send an `idempotency_key` and retry in the caller.
-- AWS factories (SQS, S3, SES, KMS, Secrets Manager, Bedrock) use botocore standard retries with at most **three total
+- AWS factories (SQS, S3, SES, KMS, Secrets Manager, Bedrock, feature flags) use botocore standard retries with at most **three total
   attempts**.
   Injected SDK clients keep their configured policy. SQS consumers must tolerate duplicate
   messages; a timeout does not prove that a send or write was not applied.
@@ -445,7 +537,7 @@ any operation**. Map it at the service boundary and apply the operation's idempo
 Its message and structured fields are safe to log when dependency names are static. Its
 chained SDK exception may contain sensitive provider data; do not log exception chains.
 
-S3, SQS, SES, KMS and Secrets Manager run the synchronous AWS SDK in worker threads. Cancelling the await does not
+S3, SQS, SES, KMS, Secrets Manager and feature flags run the synchronous AWS SDK in worker threads. Cancelling the await does not
 stop an SDK request already running in its thread. Timeouts are per SDK/network attempt,
 not an overall deadline. Limit consumer concurrency and let in-flight work finish before
 closing the clients. Redis window counters require Redis server 7 or newer (`EXPIRE NX`).

021_python_clients-0.4.0/PKG-INFO → 021_python_clients-0.5.0/README.md

@@ -1,39 +1,3 @@
-Metadata-Version: 2.5
-Name: 021-python-clients
-Version: 0.4.0
-Summary: Observed clients for Redis, SQS, QStash, S3, Vercel Blob, HTTP, email, KMS, Secrets Manager, Bedrock and Kubernetes Jobs, built on 021-python-observability
-Project-URL: Repository, https://github.com/from021-io/python-clients
-Project-URL: Changelog, https://github.com/from021-io/python-clients/blob/main/CHANGELOG.md
-Project-URL: Contract, https://github.com/from021-io/python-clients/blob/main/CONTRACT.md
-License-Expression: Apache-2.0
-License-File: LICENSE
-Keywords: bedrock,email,httpx,kms,kubernetes,observability,opentelemetry,qstash,redis,resend,s3,secrets-manager,ses,sqs
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: System :: Monitoring
-Classifier: Typing :: Typed
-Requires-Python: >=3.12
-Requires-Dist: 021-python-observability<0.4,>=0.3
-Requires-Dist: httpx<1,>=0.28
-Requires-Dist: opentelemetry-api<2,>=1.44
-Provides-Extra: aws
-Requires-Dist: boto3<2,>=1.40; extra == 'aws'
-Requires-Dist: cryptography>=44; extra == 'aws'
-Provides-Extra: httpx2
-Requires-Dist: httpx2<3,>=2; extra == 'httpx2'
-Provides-Extra: redis
-Requires-Dist: redis<9,>=6; extra == 'redis'
-Provides-Extra: vercel-blob
-Requires-Dist: httpx2<3,>=2; extra == 'vercel-blob'
-Requires-Dist: vercel-blob<0.6,>=0.5; extra == 'vercel-blob'
-Description-Content-Type: text/markdown
-
 # 021-python-clients
 
 Clients for the external services our Python services call, with the observability of
@@ -59,7 +23,9 @@ uv add "021-python-clients[redis,aws,httpx2,vercel-blob]"   # pick the extras yo
 | `clients_021.email.ses` | `aws` | `SesSender`: the same protocol over Amazon SES v2 |
 | `clients_021.crypto.kms` | `aws` | `KmsClient`: encrypt, decrypt and data keys bound to an encryption context; AES-256-GCM envelopes |
 | `clients_021.secrets.secrets_manager` | `aws` | `SecretsManagerClient`: read a secret by id, version id or stage; the value is never printed |
-| `clients_021.compute.kubernetes` | none | `KubernetesJobsClient`: create (idempotent by name), read and delete Jobs in a namespace, in-cluster service account |
+| `clients_021.compute.kubernetes` | none | `KubernetesJobsClient`: create (idempotent by name), read and delete Jobs in a namespace, and the Secrets they own; in-cluster service account |
+| `clients_021.featureflags` | none | `Flag` and the `FeatureFlags` protocol services type against |
+| `clients_021.featureflags.appconfig` | `aws` | `AppConfigFlags`: AWS AppConfig feature flags, cached and refreshed on an interval |
 | `clients_021.llm.bedrock` | `aws` | `BedrockRuntime`: an observed `bedrock-runtime` client to pass to SDKs such as LangChain's `ChatBedrockConverse`; streams measured to the end, token usage counted |
 
 Every client takes the service's `Observability` (from `setup_observability`) and a
@@ -69,7 +35,7 @@ Every client takes the service's `Observability` (from `setup_observability`) an
 
 Providers with the same purpose live under one capability package: `email/` contains
 Resend and SES; `queue/` contains SQS and QStash; `storage/` contains S3 and Vercel Blob; `cache/`
-contains Redis; `crypto/` contains KMS; `secrets/` contains Secrets Manager; `llm/` contains Bedrock; `compute/` contains Kubernetes Jobs. `http/` contains the httpx client and httpx2
+contains Redis; `crypto/` contains KMS; `secrets/` contains Secrets Manager; `llm/` contains Bedrock; `compute/` contains Kubernetes Jobs; `featureflags/` contains AppConfig. `http/` contains the httpx client and httpx2
 transport. Import providers explicitly:
 
 ```python
@@ -101,13 +67,13 @@ published exports; `clients_021.httpx2.ObservedTransport` remains an alias for
 
 - A CLIENT span named `<dependency> <operation>` (`HTTP <dependency>` for HTTP), with the
   system attribute (`db.system.name=redis`, `messaging.system=aws_sqs|resend|aws_ses`,
-  `rpc.service=S3|KMS|SecretsManager|BedrockRuntime`, `rpc.system=vercel-blob`, `rpc.system=kubernetes`;
+  `rpc.service=S3|KMS|SecretsManager|BedrockRuntime|AppConfigData`, `rpc.system=vercel-blob`, `rpc.system=kubernetes`;
   Bedrock also `gen_ai.system=aws.bedrock`).
 - A counter and a duration histogram: `db.client.operation.*` (Redis, shared with SQL),
   `messaging.client.operation.*` (SQS, QStash, email), `storage.client.operation.*` (S3, Vercel Blob),
   `crypto.client.operation.*` (KMS), `secrets.client.operation.*` (Secrets Manager),
   `llm.client.operation.*` and `llm.client.token.usage` (Bedrock), `compute.client.operation.*`
-  (Kubernetes Jobs),
+  (Kubernetes Jobs), `config.client.operation.*` (feature flags),
   `http.client.request.*` (HTTP, and the HTTP request
   under QStash and Resend). Labels are bounded; see [CONTRACT.md](CONTRACT.md).
 - Redis, SQS, QStash, S3, Vercel Blob, email, KMS, Secrets Manager, Bedrock and Kubernetes Jobs emit a `dependency.call_failed` warning on failure,
@@ -121,7 +87,7 @@ published exports; `clients_021.httpx2.ObservedTransport` remains an alias for
 Never in this library's spans, metrics or logs: keys, URLs, bodies, message ids or object
 names; email addresses, subjects, bodies or tags; secret ids, version ids, stages and
 values; model ids, prompts and outputs; namespaces, Job names, manifests and service
-account tokens; KMS key ids, encryption contexts,
+account tokens; feature flag names, values and AppConfig identifiers; KMS key ids, encryption contexts,
 plaintext, ciphertext or data keys. Use static dependency names such as `identity-provider` or `uploads`; never derive
 them from a tenant, user or request. All clients apply observability's identifier rule
 (1–96 letters, digits, `_`, `.` or `-`, starting with a letter or digit).
@@ -304,6 +270,33 @@ DELETE retry 502, 503, 504 and network failures once. 429, 5xx, timeouts and con
 failures raise `DependencyUnavailable`; other rejections raise `KubernetesApiError` with the
 status code and the API's reason, never its message.
 
+A value the pod needs but that must not be readable in the Job's spec (a run token, say) goes
+in a Secret the Job owns:
+
+```python
+created = await jobs.create(manifest)      # the container reads env from secretKeyRef
+uid = created.uid or (await jobs.get(name)).uid   # None in created when the Job existed
+await jobs.create_secret(f"{name}-token", {"token": run_token}, job=name, job_uid=uid)
+```
+
+```yaml
+env:
+  - name: RUN_TOKEN
+    valueFrom: { secretKeyRef: { name: cmd-4821-token, key: token } }
+```
+
+The Secret is `Opaque` and `immutable`, with an owner reference to the Job's name and uid, so
+the garbage collector deletes it with the Job (including through `ttlSecondsAfterFinished`).
+The Job is created first because the reference needs its uid; the kubelet keeps retrying a
+pod whose Secret does not exist yet. `create_secret` is idempotent by name like `create`: a
+409 `AlreadyExists` returns `created=False` and keeps the existing Secret without comparing or
+updating it, so a retry must reuse the same value (or `delete_secret` and create again).
+`delete_secret` returns `False` when there was none. `blockOwnerDeletion` is not set, so the
+caller needs only `create` and `delete` on `secrets` (no `get`, and nothing on
+`jobs/finalizers`). Secret names, data keys and values never reach telemetry, logs or error
+messages; the request body is still in the chained httpx exception's `request`, so do not log
+`__cause__` details.
+
 ### Bedrock
 
 ```python
@@ -342,6 +335,33 @@ copy when the same secret is read often. A missing secret, access denied, a valu
 decrypt or a secret scheduled for deletion keep their botocore type; throttling, 5xx and
 timeouts raise `DependencyUnavailable`. `repr(secret)` never shows the value.
 
+### Feature flags (AWS AppConfig)
+
+Reads [AppConfig feature flags](https://aws.amazon.com/blogs/mt/using-aws-appconfig-feature-flags/)
+through the AppConfig Data API and keeps a snapshot in memory; evaluating a flag is a lookup:
+
+```python
+from clients_021.featureflags import FeatureFlags          # the protocol, no extra needed
+from clients_021.featureflags.appconfig import AppConfigFlags
+
+flags: FeatureFlags = AppConfigFlags.create(
+    obs, settings.appconfig_app, settings.appconfig_env, settings.appconfig_profile,
+    region="us-east-1",
+)
+if await flags.is_enabled("new-checkout"):          # unknown flag -> default=False
+    ...
+limit = await flags.flag("rate-limit")              # Flag(enabled=True, attributes={"rps": 50})
+```
+
+The snapshot is refreshed by the first request after `refresh_seconds` (default 45, minimum
+15), one poll at a time. If a refresh fails while a snapshot exists, the stale one keeps
+serving and the next attempt is 15 seconds later; with no snapshot yet the outage raises
+`DependencyUnavailable`. A configuration that is not valid flag JSON raises `ValueError` on
+the first load and is ignored with a warning afterwards. Supports plain flags and their
+attributes; multi-variant flags and rules need the AppConfig Agent, which evaluates them.
+The IAM role needs `appconfig:StartConfigurationSession` and
+`appconfig:GetLatestConfiguration` on the configuration profile.
+
 ### KMS
 
 The encryption context is required on every call, so a ciphertext only decrypts for the
@@ -458,7 +478,7 @@ Retry policies are explicit:
   POST and PATCH run once. Invalid URLs/protocols and invalid request construction keep
   their original exception. HTTP status responses are returned for the caller to handle.
 - Resend sends each request once (POST); send an `idempotency_key` and retry in the caller.
-- AWS factories (SQS, S3, SES, KMS, Secrets Manager, Bedrock) use botocore standard retries with at most **three total
+- AWS factories (SQS, S3, SES, KMS, Secrets Manager, Bedrock, feature flags) use botocore standard retries with at most **three total
   attempts**.
   Injected SDK clients keep their configured policy. SQS consumers must tolerate duplicate
   messages; a timeout does not prove that a send or write was not applied.
@@ -481,7 +501,7 @@ any operation**. Map it at the service boundary and apply the operation's idempo
 Its message and structured fields are safe to log when dependency names are static. Its
 chained SDK exception may contain sensitive provider data; do not log exception chains.
 
-S3, SQS, SES, KMS and Secrets Manager run the synchronous AWS SDK in worker threads. Cancelling the await does not
+S3, SQS, SES, KMS, Secrets Manager and feature flags run the synchronous AWS SDK in worker threads. Cancelling the await does not
 stop an SDK request already running in its thread. Timeouts are per SDK/network attempt,
 not an overall deadline. Limit consumer concurrency and let in-flight work finish before
 closing the clients. Redis window counters require Redis server 7 or newer (`EXPIRE NX`).

{021_python_clients-0.4.0 → 021_python_clients-0.5.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "021-python-clients"
-version = "0.4.0"
-description = "Observed clients for Redis, SQS, QStash, S3, Vercel Blob, HTTP, email, KMS, Secrets Manager, Bedrock and Kubernetes Jobs, built on 021-python-observability"
+version = "0.5.0"
+description = "Observed clients for Redis, SQS, QStash, S3, Vercel Blob, HTTP, email, KMS, Secrets Manager, Bedrock and Kubernetes Jobs and AppConfig feature flags, built on 021-python-observability"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 requires-python = ">=3.12"
-keywords = ["redis", "sqs", "qstash", "s3", "httpx", "email", "ses", "resend", "kms", "secrets-manager", "bedrock", "kubernetes", "opentelemetry", "observability"]
+keywords = ["redis", "sqs", "qstash", "s3", "httpx", "email", "ses", "resend", "kms", "secrets-manager", "bedrock", "kubernetes", "appconfig", "feature-flags", "opentelemetry", "observability"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
@@ -24,7 +24,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "021-python-observability>=0.3,<0.4",
+  "021-python-observability>=0.3,<0.5",
   "httpx>=0.28,<1",
   "opentelemetry-api>=1.44,<2",
 ]
@@ -51,7 +51,7 @@ dev = [
   "ruff>=0.16,<0.17",
   "pyright>=1.1.405",
   "moto[sqs,s3,ses,kms,secretsmanager]>=5.2,<6",
-  "boto3-stubs[sqs,s3,sesv2,kms,secretsmanager,bedrock-runtime]>=1.40,<2",
+  "boto3-stubs[sqs,s3,sesv2,kms,secretsmanager,bedrock-runtime,appconfigdata]>=1.40,<2",
 ]
 
 [tool.hatch.build.targets.wheel]

{021_python_clients-0.4.0 → 021_python_clients-0.5.0}/src/clients_021/__init__.py

@@ -4,7 +4,8 @@
 `clients_021.compute.kubernetes` need no extras;
 `clients_021.cache.redis` needs the `redis` extra; `clients_021.queue.sqs`,
 `clients_021.storage.s3`, `clients_021.email.ses`, `clients_021.crypto.kms`,
-`clients_021.secrets.secrets_manager` and `clients_021.llm.bedrock` the `aws` extra;
+`clients_021.secrets.secrets_manager`, `clients_021.llm.bedrock` and
+`clients_021.featureflags.appconfig` the `aws` extra (`clients_021.featureflags` needs none);
 `clients_021.http.httpx2` the `httpx2` extra.
 `clients_021.storage.vercel_blob` needs the `vercel-blob` extra.
 """

{021_python_clients-0.4.0 → 021_python_clients-0.5.0}/src/clients_021/_observe.py

@@ -2,11 +2,11 @@
 
 The `db` family reuses the instruments 021-python-observability already creates for SQL
 (`db.client.operation.*`), so Redis and Postgres share dashboards. `messaging` (SQS, email),
-`storage` (S3, Vercel Blob), `crypto` (KMS), `secrets` (Secrets Manager), `llm` (Bedrock) and
-`compute` (Kubernetes Jobs) get their own pair on the same meter. `Call` is the same
-measurement for synchronous SDK calls and for operations that end later than they start, such
-as a model response stream. Attributes are bounded: dependency, operation, status and
-error.type; never keys, URLs, bodies or ids.
+`storage` (S3, Vercel Blob), `crypto` (KMS), `secrets` (Secrets Manager), `llm` (Bedrock),
+`compute` (Kubernetes Jobs) and `config` (feature flags) get their own pair on the same
+meter. `Call` is the same measurement for synchronous SDK calls and for operations that end
+later than they start, such as a model response stream. Attributes are bounded: dependency,
+operation, status and error.type; never keys, URLs, bodies or ids.
 """
 
 from __future__ import annotations
@@ -24,7 +24,7 @@ from opentelemetry.trace import SpanKind, StatusCode
 
 from clients_021.errors import DependencyUnavailable
 
-Family = Literal["db", "messaging", "storage", "crypto", "secrets", "llm", "compute"]
+Family = Literal["db", "messaging", "storage", "crypto", "secrets", "llm", "compute", "config"]
 # Returns the reason when an exception means "the dependency failed", None for a bug.
 Classifier = Callable[[BaseException], str | None]
 
@@ -37,6 +37,7 @@ _UNITS = {
     "secrets": "{operation}",
     "llm": "{operation}",
     "compute": "{operation}",
+    "config": "{operation}",
 }
 _cache: WeakKeyDictionary[Observability, dict[Family, tuple[Counter, Histogram]]] = (
     WeakKeyDictionary()