021-python-clients 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

{021_python_clients-0.2.0.dist-info → 021_python_clients-0.4.0.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: 021-python-clients
-Version: 0.2.0
-Summary: Observed clients for Redis, SQS, QStash, S3, Vercel Blob, HTTP, email and KMS, built on 021-python-observability
+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: email,httpx,kms,observability,opentelemetry,qstash,redis,resend,s3,ses,sqs
+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
@@ -48,8 +48,8 @@ uv add "021-python-clients[redis,aws,httpx2,vercel-blob]"   # pick the extras yo
 
 | Module | Extra | What it gives |
 | --- | --- | --- |
-| `clients_021.http` | none | `HttpClient`: one httpx client per dependency, timeouts, retries on idempotent methods |
-| `clients_021.httpx2` | `httpx2` | `ObservedTransport` for SDKs built on httpx2 (Anthropic, OpenAI) |
+| `clients_021.http.httpx` | none | `HttpClient`: buffered requests, streaming and full-body telemetry; native `ObservedTransport` |
+| `clients_021.http.httpx2` | `httpx2` | `ObservedTransport` for SDKs built on httpx2 (Anthropic, OpenAI) |
 | `clients_021.cache.redis` | `redis` | `RedisClient`: JSON with TTL, one-time reads, windowed counters, ping |
 | `clients_021.queue.qstash` | none | `QStashClient`: JSON publishing, deduplication, delivery options and forwarded trace context |
 | `clients_021.queue.sqs` | `aws` | `SqsClient`: send, receive, delete, visibility, trace carried in the message |
@@ -58,6 +58,9 @@ uv add "021-python-clients[redis,aws,httpx2,vercel-blob]"   # pick the extras yo
 | `clients_021.email` | none | `EmailMessage`, the `EmailSender` protocol, `ResendSender` (Resend's HTTP API) |
 | `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.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
 `dependency` name, which becomes the `dependency` label of its metrics.
@@ -66,15 +69,20 @@ 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. HTTP transports remain at the root. Import providers
-explicitly:
+contains Redis; `crypto/` contains KMS; `secrets/` contains Secrets Manager; `llm/` contains Bedrock; `compute/` contains Kubernetes Jobs. `http/` contains the httpx client and httpx2
+transport. Import providers explicitly:
 
 ```python
+from clients_021.http import HttpClient
+from clients_021.http.httpx2 import ObservedTransport  # requires the httpx2 extra
 from clients_021.queue.sqs import SqsClient
 from clients_021.queue.qstash import QStashClient
 from clients_021.storage.s3 import S3Client
 from clients_021.cache.redis import RedisClient
 from clients_021.crypto.kms import KmsClient
+from clients_021.secrets.secrets_manager import SecretsManagerClient
+from clients_021.llm.bedrock import BedrockRuntime
+from clients_021.compute.kubernetes import KubernetesJobsClient
 ```
 
 SQS supports polling, receipts and visibility changes; QStash delivers to an HTTP endpoint.
@@ -85,26 +93,35 @@ does not load the optional AWS SDK.
 
 The 0.1.0 imports `clients_021.redis`, `clients_021.s3` and `clients_021.kms` remain
 compatible aliases for the same classes and result types. Importing a capability package
-does not load its optional SDKs.
+does not load its optional SDKs. `clients_021.HttpClient` and `clients_021.http` keep their
+published exports; `clients_021.httpx2.ObservedTransport` remains an alias for
+`clients_021.http.httpx2.ObservedTransport`.
 
 ## What every call gets
 
 - 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`, `rpc.system=vercel-blob`).
+  `rpc.service=S3|KMS|SecretsManager|BedrockRuntime`, `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), `http.client.request.*` (HTTP, and the HTTP request
+  `crypto.client.operation.*` (KMS), `secrets.client.operation.*` (Secrets Manager),
+  `llm.client.operation.*` and `llm.client.token.usage` (Bedrock), `compute.client.operation.*`
+  (Kubernetes Jobs),
+  `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 and KMS emit a `dependency.call_failed` warning on failure,
-  with dependency, operation and error type only. HTTP transports emit spans and metrics.
+- Redis, SQS, QStash, S3, Vercel Blob, email, KMS, Secrets Manager, Bedrock and Kubernetes Jobs emit a `dependency.call_failed` warning on failure,
+  with dependency, operation and error type only. HTTP/httpx2 also log failed attempts,
+  including body failures and cancellation; QStash/Resend suppress the nested HTTP log.
 - `DependencyUnavailable(dependency, operation, reason)` when the service timed out,
   refused the connection, throttled or failed with a 5xx. Map it to a 503. Errors that mean
   the request is wrong (access denied, a missing bucket, a wrong Redis type) keep their
   original type: they are bugs, not outages.
 
 Never in this library's spans, metrics or logs: keys, URLs, bodies, message ids or object
-names; email addresses, subjects, bodies or tags; KMS key ids, encryption contexts,
+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,
 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).
@@ -267,6 +284,64 @@ except EmailRejected as rejected:  # the address, the domain or the credentials;
 SES has no idempotency key (the argument is ignored): deduplicate in the caller when a retry
 must not send twice. Tags are for provider analytics; never put personal data in them.
 
+### Kubernetes Jobs
+
+```python
+from clients_021.compute.kubernetes import KubernetesJobsClient
+
+jobs = KubernetesJobsClient.in_cluster(obs, namespace="agent-runs")
+created = await jobs.create({"metadata": {"name": "cmd-4821"}, "spec": job_spec})
+status = await jobs.get("cmd-4821")        # JobStatus(phase="running", ...) or None
+await jobs.delete("cmd-4821", propagation="Background")
+```
+
+No SDK: it calls the `batch/v1` REST API through `HttpClient`. `in_cluster` uses the pod's
+service account (CA bundle, namespace, and a token it re-reads at most once a minute because
+projected tokens rotate). `create` is idempotent by name: `generateName` is refused, and an
+existing Job returns `created=False`, so a caller can repeat it after a timeout. `get`
+returns `None` and `delete` returns `False` for a missing Job. POST is sent once; GET and
+DELETE retry 502, 503, 504 and network failures once. 429, 5xx, timeouts and connection
+failures raise `DependencyUnavailable`; other rejections raise `KubernetesApiError` with the
+status code and the API's reason, never its message.
+
+### Bedrock
+
+```python
+from clients_021.llm.bedrock import BedrockRuntime
+from langchain_aws import ChatBedrockConverse
+
+runtime = BedrockRuntime.create(obs, region="us-east-1")
+model = ChatBedrockConverse(model=settings.inference_profile, client=runtime)
+```
+
+`BedrockRuntime` keeps boto3's call signatures for `converse`, `converse_stream`,
+`invoke_model`, `invoke_model_with_response_stream` and `count_tokens`, and passes every
+other attribute (`meta`, `exceptions`) through to the boto3 client, so an SDK can take it
+where it expects one. Calls stay synchronous like boto3's. A streaming call is measured
+until its event stream ends; leaving the loop early or calling `close()` ends it as `ok`.
+Converse and ConverseStream add the reported input, output and cache tokens to
+`llm.client.token.usage`. Throttling (also mid-stream), 5xx, a model still loading and the
+stream errors Bedrock documents as retryable raise `DependencyUnavailable`; access denied,
+validation errors, a missing model and quota limits keep their botocore type. A retried
+model call is billed again.
+
+### Secrets Manager
+
+```python
+from clients_021.secrets.secrets_manager import SecretsManagerClient
+
+secrets = SecretsManagerClient.create(obs, region="us-east-1")
+secret = await secrets.get("connections/brain")
+token = secret.text()            # SecretString; secret.binary() for SecretBinary
+previous = await secrets.get("connections/brain", version_stage="AWSPREVIOUS")
+```
+
+`get` reads the current version unless a `version_id` or a `version_stage` is given (not
+both). The client does not cache: every call is a billed request, so keep a short-lived
+copy when the same secret is read often. A missing secret, access denied, a value KMS cannot
+decrypt or a secret scheduled for deletion keep their botocore type; throttling, 5xx and
+timeouts raise `DependencyUnavailable`. `repr(secret)` never shows the value.
+
 ### KMS
 
 The encryption context is required on every call, so a ciphertext only decrypts for the
@@ -290,21 +365,58 @@ ciphertext keep their botocore type (they are bugs or attacks, not outages); a t
 envelope raises `cryptography`'s `InvalidTag`. The envelope layout is in
 [CONTRACT.md](CONTRACT.md).
 
+### HTTP bodies and streaming
+
+```python
+from clients_021.http import HttpClient
+
+http = HttpClient(obs, timeout_seconds=10)
+try:
+    async with http.stream("GET", download_url, dependency="documents") as response:
+        response.raise_for_status()
+        async for chunk in response.aiter_bytes():
+            await write_chunk(chunk)
+finally:
+    await http.aclose()
+```
+
+These async clients run on asyncio. `request()` returns a buffered `HttpResponse`; `stream()` yields a native httpx response
+without buffering and accepts an async iterable as upload `content`. Streaming sends once,
+even for GET. The buffered client's configured idempotent retries are unchanged. Close the
+response context before closing the client. For SDKs using native httpx, inject
+`clients_021.http.httpx.ObservedTransport`; httpx2 SDKs use the transport below.
+
+Each HTTP attempt emits one span, counter and duration after body EOF and connection close,
+or early close. This includes upload, download, pauses between chunks and cleanup. Body
+errors after 200 headers are recorded as errors. `http.response.body.complete` distinguishes
+EOF from partial/unread close; it does not mean the status or cleanup succeeded. Intentional
+partial close is INFO `dependency.stream_closed`; exceptions, cancellation and HTTP >= 400
+produce WARNING `dependency.call_failed`. No success log, URL, header, body or provider
+error message is emitted. `log_failures=False` disables attempt logs when an enclosing
+operation owns the warning, as QStash and Resend do.
+
+These duration semantics and the completion label change the 0.2.x telemetry contract;
+see [migration notes](CONTRACT.md#migration-from-02x) before updating dashboards or alerts.
+
 ### SDKs on httpx2
 
 For an SDK on httpx2:
 
 ```python
 from anthropic import AsyncAnthropic, DefaultAsyncHttpxClient
-from clients_021.httpx2 import ObservedTransport
+from clients_021.http.httpx2 import ObservedTransport
 
 transport = ObservedTransport(obs, dependency="anthropic")
 claude = AsyncAnthropic(http_client=DefaultAsyncHttpxClient(transport=transport))
 ```
 
-It does not send `traceparent` to third-party APIs unless `propagate=True`.
+It does not inject trace context into third-party API requests unless `propagate=True`.
 The transport preserves SDK exceptions so the SDK retains control of retries and error
-handling; it does not convert them to `DependencyUnavailable`.
+handling; it does not convert them to `DependencyUnavailable`. Its span stays open through
+incremental response reads and close. Use the SDK's stream context manager, or close manual
+responses explicitly; abandoning a stream leaves both its connection and span open. Caller
+processing keeps its own trace context, including when streams are interleaved or consumed
+in another task.
 
 ## Service integration
 
@@ -333,18 +445,20 @@ async with AsyncExitStack() as resources:
     resources.push_async_callback(email.aclose)
     keys = KmsClient.create(obs, settings.session_key_arn, region="us-east-1")
     resources.push_async_callback(keys.aclose)
+    secrets = SecretsManagerClient.create(obs, region="us-east-1")
+    resources.push_async_callback(secrets.aclose)
     # Run the service here. Stop its background workers before leaving this scope.
 ```
 
 Retry policies are explicit:
 
-- HTTP retries GET, HEAD, OPTIONS, PUT and DELETE on network failures, timeouts,
+- Buffered HTTP (`request`) retries GET, HEAD, OPTIONS, PUT and DELETE on network failures, timeouts,
   remote protocol/proxy connection failures and 502/503/504. `retries=2` means at most
   three attempts.
   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) use botocore standard retries with at most **three total
+- AWS factories (SQS, S3, SES, KMS, Secrets Manager, Bedrock) 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.
@@ -367,15 +481,16 @@ 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 and KMS run the synchronous AWS SDK in worker threads. Cancelling the await does not
+S3, SQS, SES, KMS and Secrets Manager 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`).
 
-HTTP transport spans end when response headers arrive. Body downloads and SDK streaming
-are outside that span; instrument the enclosing service/SDK operation when you need total
-latency or failures while consuming the body. S3 `get` buffers the entire object in memory;
-use a dedicated streaming adapter for large files.
+HTTP spans now include network body consumption and cleanup. The SDK/application still
+owns content decoding, JSON/SSE interpretation and processing errors outside raw-stream I/O.
+Timeouts remain per I/O, not a total stream deadline. Cancellation waits for shielded body
+cleanup before propagating. Close all responses and consumers before shutdown/flush.
+S3 `get` buffers the entire object in memory; use a dedicated streaming adapter for large files.
 
 ## Development
 
@@ -390,6 +505,8 @@ deduplication, start the [official local server](https://upstash.com/docs/qstash
 set its `QSTASH_URL` and `QSTASH_TOKEN`, and run `uv run python tests/qstash_local.py`.
 That smoke test accepts only a loopback QStash server and binds its destination dynamically.
 
-SQS, S3, SES and KMS tests run against [moto](https://github.com/getmoto/moto) (plus
+Kubernetes Jobs tests use httpx's `MockTransport`. Bedrock tests use botocore's Stubber and
+fake event streams. SQS, S3, SES, KMS and Secrets
+Manager tests run against [moto](https://github.com/getmoto/moto) (plus
 botocore's Stubber where moto ignores a field or differs from AWS); Resend tests use httpx's
 `MockTransport`; Redis tests need a real Redis. Licensed under Apache-2.0.

{021_python_clients-0.2.0.dist-info → 021_python_clients-0.4.0.dist-info}/RECORD

@@ -1,28 +1,37 @@
-clients_021/__init__.py,sha256=sF_9ZsxPumQbZ-9iCXoLP8JcU_tITDT6Xk1mXF9PVuQ,816
+clients_021/__init__.py,sha256=D7i865mBaxw32ycKWsMazMRljtYFdabdSG8dHjfWg3M,921
 clients_021/_aws.py,sha256=sj2kCfod-vz9J93UyeVzNVLGK3M25yipKdW15KyIkw4,1722
-clients_021/_observe.py,sha256=Xjg5Qck-e8Gt5NQHOND6nzr7DvTn46PmBdccubiD3Dk,3792
+clients_021/_observe.py,sha256=Kh-2gitT2bI4vNa-Y7PYsCns60XJzJ_N7ZbTuyX82lo,6977
 clients_021/errors.py,sha256=GS_fN8mjr7MCOkhqPhH6LweIvQ20Vd29U-aZY8zBeJQ,972
-clients_021/http.py,sha256=-AsGLfngd-eEJnTuZEPdVBI9myYiuggmnrvjQjaMpT8,5045
-clients_021/httpx2.py,sha256=w248IcEtDZtsEDkkvj4Bpfl7MU7IJ08EHqHWhryC_3k,3880
+clients_021/httpx2.py,sha256=rNbNGJuPJPZUwVbNN5L88IF0g3Tq6EHqj_uFmJ3RmLQ,161
 clients_021/kms.py,sha256=YcZXURpqIZTkjcP0fpWMD6X_adMAYwN7zAJNhUImR4s,183
 clients_021/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clients_021/redis.py,sha256=xC3tji_ldJAwaBntkZTuPhNHLIzl3F3nDzkikMrbJCc,169
 clients_021/s3.py,sha256=6Q5_1emngSB00IwvBdrmV3iAg-Q_Ndco1HGzYObL5FI,231
 clients_021/cache/__init__.py,sha256=3OyQQ-uZeghpgJvvJ2k56_t50q3CCwbAp3dBrCMMcSU,76
 clients_021/cache/redis.py,sha256=DRXCMc8MqY8KsZ50j4X4mUsd0lvvmP-UDuUD2wJXyW8,4932
+clients_021/compute/__init__.py,sha256=PP23LVKxoJGkwzzFbuKMRd35LugdYqJWElp9lWymllM,78
+clients_021/compute/kubernetes.py,sha256=a0-9ldOg1mQjJBVzWAhZH4QGEN6qAzcgl_n8Ty0rSts,12456
 clients_021/crypto/__init__.py,sha256=qESFBPQBKcHhdFXqeJzSyEP41yveG7rFrxnpITmqlNU,77
 clients_021/crypto/kms.py,sha256=My5Xyg0bOiT9YHYWojQSszpREEh3bSYMMB26wy6fNEI,7261
 clients_021/email/__init__.py,sha256=ivmdu9hhNDwPqBn3G7uNG0Zpc3DEMnlnWBVVoVQ-fQA,790
 clients_021/email/_message.py,sha256=ulTX2cXPxSVaq_5FVF0e6glePVJ7wiO5P3M4WUWN3N0,3258
-clients_021/email/resend.py,sha256=ugENkEzw9eUlYih3BZcCVQswTF1MDikPgZyuqdapCjc,5347
+clients_021/email/resend.py,sha256=1EjvEbNbbVDQs5TZfYuZrqh14io8cb5ADneNA63DQbg,5416
 clients_021/email/ses.py,sha256=0ukHvuVE0nTU5mYWRy2EaHY5v9dUwi4GSKES93pjqBg,4668
+clients_021/http/__init__.py,sha256=P4OmYruhkQfJwJzHA90FXKWg_A2rh5iOl-ES_NTMMVQ,311
+clients_021/http/_observe.py,sha256=hpTzcej9MhlvM-RgUZWicR57ulE90GmZMs5U_qFoquQ,6922
+clients_021/http/httpx.py,sha256=gvqSpO1rb6nBA5i01W1yos5mPBwLqa3-HDYwMtQXc6s,10627
+clients_021/http/httpx2.py,sha256=fmqH4bikDKZ6YY0sNBHZbocff2zU40Gpks1aoRuOGeQ,2810
+clients_021/llm/__init__.py,sha256=pEI4drpN0MKg_gp8BP1U7kpVd3NDV_Sa9eFD3J87LPw,86
+clients_021/llm/bedrock.py,sha256=GJafCh6PhBrsDgs_GapoKiVflv32V7BUqyAj52pMQiA,9367
 clients_021/queue/__init__.py,sha256=CesweOrXmX5cyU-mRvqu-4wLkNJI15zi_Lows6SPupY,338
-clients_021/queue/qstash.py,sha256=j3vz_S9-ed0YQZCaWwQg5wPwf8Bv5P1voNsx8WD8Zhc,8315
+clients_021/queue/qstash.py,sha256=NndlqmNkcBgs0ExGsT-3-bMAdU0skO8Djptqj8NoJAM,8335
 clients_021/queue/sqs.py,sha256=jnccgbxyglzs2mR_DsH04IisEwygDlw6s3RxR0UtMTc,6693
+clients_021/secrets/__init__.py,sha256=LdxphQvruITeP5jXZR69ly2jxMxuHCI1BDavw2mU0EY,76
+clients_021/secrets/secrets_manager.py,sha256=ttP3_vCXRtOYvbUaNIkFlSTzYYr4yU3Uwim3juXUfPM,4746
 clients_021/storage/__init__.py,sha256=KrJViRHBK7PkIYnagg7vyXp95SzMFp9cUCKEnMeFr84,78
 clients_021/storage/s3.py,sha256=NDtG9QzHSXvrcazTYTq1EH5VjuRd2xMMsMvaumqci4Q,5946
 clients_021/storage/vercel_blob.py,sha256=FlnoKiahqtk3PpLsGpyu_Gy87otg15i4BlJZsIB3LfM,6511
-021_python_clients-0.2.0.dist-info/METADATA,sha256=gx7Jt2wjPNVFhyUHCze-tQ5YVu-Kqrt2GwAyia6HdXs,20595
-021_python_clients-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-021_python_clients-0.2.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-021_python_clients-0.2.0.dist-info/RECORD,,
+021_python_clients-0.4.0.dist-info/METADATA,sha256=Q4ITtnJ9tRJxxH3gdoE-1nl3A4ClHkAV5yihBGN1JTg,27808
+021_python_clients-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+021_python_clients-0.4.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+021_python_clients-0.4.0.dist-info/RECORD,,

clients_021/__init__.py

@@ -1,9 +1,11 @@
 """Observed clients for the external services Python services call.
 
-`clients_021.http`, `clients_021.queue.qstash` and `clients_021.email` (Resend) need no extras;
+`clients_021.http`, `clients_021.queue.qstash`, `clients_021.email` (Resend) and
+`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` and `clients_021.crypto.kms` the `aws` extra;
-`clients_021.httpx2` the `httpx2` extra.
+`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.http.httpx2` the `httpx2` extra.
 `clients_021.storage.vercel_blob` needs the `vercel-blob` extra.
 """
 

clients_021/_observe.py

@@ -2,8 +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) and `crypto` (KMS) get their own pair on the same meter. 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) 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.
 """
 
 from __future__ import annotations
@@ -12,7 +15,7 @@ import asyncio
 import time
 from collections.abc import AsyncGenerator, Callable
 from contextlib import asynccontextmanager
-from typing import Literal
+from typing import Literal, NoReturn
 from weakref import WeakKeyDictionary
 
 from observability_021 import Observability, get_logger
@@ -21,7 +24,7 @@ from opentelemetry.trace import SpanKind, StatusCode
 
 from clients_021.errors import DependencyUnavailable
 
-Family = Literal["db", "messaging", "storage", "crypto"]
+Family = Literal["db", "messaging", "storage", "crypto", "secrets", "llm", "compute"]
 # Returns the reason when an exception means "the dependency failed", None for a bug.
 Classifier = Callable[[BaseException], str | None]
 
@@ -31,6 +34,9 @@ _UNITS = {
     "messaging": "{operation}",
     "storage": "{operation}",
     "crypto": "{operation}",
+    "secrets": "{operation}",
+    "llm": "{operation}",
+    "compute": "{operation}",
 }
 _cache: WeakKeyDictionary[Observability, dict[Family, tuple[Counter, Histogram]]] = (
     WeakKeyDictionary()
@@ -104,3 +110,83 @@ async def observed(
         finally:
             count.add(1, attributes)
             duration.record(time.perf_counter() - started, attributes)
+
+
+class Call:
+    """One observed operation started now and finished by `ok`, `fail` or `cancelled`.
+
+    The synchronous counterpart of `observed`, with the same span, instruments, labels and
+    warning. It also covers operations that outlive the call that started them: a stream is
+    finished when it is exhausted, fails or is closed. Finishing twice is ignored.
+    """
+
+    def __init__(
+        self,
+        obs: Observability,
+        *,
+        family: Family,
+        system: dict[str, str],
+        dependency: str,
+        operation: str,
+        classify: Classifier,
+    ) -> None:
+        self._attributes: dict[str, str] = {"dependency": dependency, "operation": operation}
+        self._count, self._duration = instruments(obs, family)
+        self._classify = classify
+        self._started = time.perf_counter()
+        self._span = obs.tracer.start_span(
+            f"{dependency} {operation}",
+            kind=SpanKind.CLIENT,
+            attributes={**system, **self._attributes},
+            record_exception=False,
+            set_status_on_exception=False,
+        )
+        self._done = False
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    def _finish(self) -> None:
+        self._done = True
+        self._span.set_attributes(self._attributes)
+        self._span.end()
+        self._count.add(1, self._attributes)
+        self._duration.record(time.perf_counter() - self._started, self._attributes)
+
+    def ok(self) -> None:
+        if self._done:
+            return
+        self._attributes["status"] = "ok"
+        self._finish()
+
+    def cancelled(self) -> None:
+        if self._done:
+            return
+        self._attributes["status"] = "error"
+        self._attributes["error.type"] = "cancelled"
+        self._span.set_status(StatusCode.ERROR)
+        self._finish()
+
+    def fail(self, error: BaseException) -> NoReturn:
+        """Records the failure, then raises DependencyUnavailable or the error itself."""
+        if isinstance(error, asyncio.CancelledError | KeyboardInterrupt | GeneratorExit):
+            self.cancelled()
+            raise error
+        reason = self._classify(error)
+        if not self._done:
+            self._attributes["status"] = "error"
+            self._attributes["error.type"] = reason or type(error).__name__
+            self._span.set_status(StatusCode.ERROR)
+            logger.warning(
+                "dependency.call_failed",
+                dependency=self._attributes["dependency"],
+                operation=self._attributes["operation"],
+                error_type=self._attributes["error.type"],
+            )
+            self._finish()
+        if reason is None:
+            raise error
+        raise DependencyUnavailable(
+            self._attributes["dependency"], self._attributes["operation"], reason
+        ) from error

clients_021/compute/__init__.py

@@ -0,0 +1 @@
+"""Compute clients. Import providers explicitly; SDKs are optional extras."""