021-python-clients 0.1.0__py3-none-any.whl

021_python_clients-0.1.0.dist-info/METADATA

@@ -0,0 +1,327 @@
+Metadata-Version: 2.5
+Name: 021-python-clients
+Version: 0.1.0
+Summary: Observed clients for Redis, SQS, QStash, S3, HTTP, email and KMS, 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
+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'
+Description-Content-Type: text/markdown
+
+# 021-python-clients
+
+Clients for the external services our Python services call, with the observability of
+[021-python-observability](https://pypi.org/project/021-python-observability/) built in.
+A service uses these instead of calling `redis`, `boto3`, `httpx` or an email SDK directly, so every
+dependency call gets the same span, the same metrics under a stable dependency name, and
+the same failure type.
+
+```bash
+uv add "021-python-clients[redis,aws,httpx2]"   # pick the extras you use
+```
+
+| 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.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 |
+| `clients_021.s3` | `aws` | `S3Client`: put, get, head, delete, presigned URLs |
+| `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.kms` | `aws` | `KmsClient`: encrypt, decrypt and data keys bound to an encryption context; AES-256-GCM envelopes |
+
+Every client takes the service's `Observability` (from `setup_observability`) and a
+`dependency` name, which becomes the `dependency` label of its metrics.
+
+## Organization
+
+Providers with the same purpose live under one capability package: `email/` contains
+Resend and SES; `queue/` contains SQS and QStash. Import queue clients explicitly:
+
+```python
+from clients_021.queue.sqs import SqsClient
+from clients_021.queue.qstash import QStashClient
+```
+
+SQS supports polling, receipts and visibility changes; QStash delivers to an HTTP endpoint.
+Their provider APIs remain separate inside `queue/`. Email providers share `EmailSender`
+because both implement the same send operation. A shared package does not imply that every
+provider implements an interchangeable consumption protocol. Importing `queue` or QStash
+does not load the optional AWS SDK.
+
+## 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`).
+- A counter and a duration histogram: `db.client.operation.*` (Redis, shared with SQL),
+  `messaging.client.operation.*` (SQS, QStash, email), `storage.client.operation.*` (S3),
+  `crypto.client.operation.*` (KMS), `http.client.request.*` (HTTP, and the HTTP request
+  under QStash and Resend). Labels are bounded; see [CONTRACT.md](CONTRACT.md).
+- Redis, SQS, QStash, S3, email and KMS emit a `dependency.call_failed` warning on failure,
+  with dependency, operation and error type only. HTTP transports emit spans and metrics.
+- `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,
+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).
+
+## Examples
+
+```python
+from clients_021 import DependencyUnavailable, HttpClient
+from clients_021.redis import RedisClient
+from clients_021.s3 import S3Client
+from clients_021.queue.sqs import SqsClient
+
+redis = RedisClient.from_url(obs, settings.redis_url)
+await redis.set_json("session:abc", {"user": "ana"}, ttl_seconds=1800)
+used = await redis.incr_window("ratelimit:ip:1.2.3.4:28735", by=1, ttl_seconds=61)
+
+queue = SqsClient.create(obs, settings.queue_url, region="us-east-1")
+await queue.send(body, attributes={"type": "notes.created.v1"})
+for message in await queue.receive(wait_seconds=20):
+    with obs.tracer.start_as_current_span("handle", context=message.trace_context()):
+        ...
+    await queue.delete(message.receipt)
+
+files = S3Client.create(obs, "service-uploads", region="us-east-1")
+await files.put("reports/2026-10.pdf", data, content_type="application/pdf")
+url = files.presign_get("reports/2026-10.pdf", expires_seconds=300)
+
+http = HttpClient(obs, timeout_seconds=10)
+response = await http.request("GET", jwks_url, dependency="identity-provider")
+```
+
+### QStash
+
+```python
+from clients_021.queue.qstash import QStashClient
+
+qstash = QStashClient(
+    obs,
+    token=settings.qstash_token,
+    base_url=settings.qstash_url,  # the API URL for your selected region
+    timeout_seconds=10,           # this service's publication request
+)
+try:
+    published = await qstash.publish_json(
+        settings.events_url,
+        {"type": "notes.created.v1", "data": {"note_id": note_id}},
+        deduplication_id=event_id,  # stable across retries of this logical event
+        delivery_retries=3,
+        delivery_timeout_seconds=60,
+        delay_seconds=0,
+        label="notes.created.v1",
+        forward_headers={"X-Request-ID": request_id},
+    )
+    # published.message_id and published.deduplicated describe QStash acceptance.
+finally:
+    await qstash.aclose()
+```
+
+Create the client once per service lifecycle; the example closes it explicitly for
+completeness. `publish_json` targets one HTTP(S) URL and supports any JSON value, including
+`null`. Acknowledgement means queued, not delivered. Deduplication keys are required and
+preserved verbatim; QStash rejects keys containing `:`, so this client raises `ValueError`
+for those keys before making a request. Use a UUID or a stable hash of a composite business
+key instead of replacing punctuation, which can collapse different keys. Reuse the key after an uncertain publication outcome; scope it to the
+logical event and destination. QStash's deduplication window is finite, so consumers must
+still be idempotent. See [Upstash's deduplication contract](https://upstash.com/docs/qstash/features/deduplication).
+
+The publisher forwards the current trace to the destination by default. Use
+`propagate=False` for destinations that should not receive it. Caller-supplied forwarded
+trace headers are replaced or removed together. `forward_headers` uses ordinary header
+names; the client adds the provider prefix. These headers are sent to QStash for delivery,
+so only pass credentials intended for that destination.
+
+The first slice covers publishing, not schedules, batches, URL groups or a web framework's
+receiving endpoint. Authenticate incoming deliveries using
+[QStash signature verification](https://upstash.com/docs/qstash/howto/signature).
+
+### Email
+
+Behind one protocol, so a service can switch between Resend and SES by configuration:
+
+```python
+from clients_021.email import EmailMessage, EmailRejected, EmailSender, ResendSender
+from clients_021.email.ses import SesSender
+
+email: EmailSender = (
+    ResendSender(obs, settings.resend_api_key)
+    if settings.email_provider == "resend"
+    else SesSender.create(obs, region="us-east-1", configuration_set="transactional")
+)
+message = EmailMessage(
+    sender="021 <hola@from021.io>",
+    to=user.email,
+    subject="Your sign-in code",
+    text=f"Your code is {code}",
+    tags={"category": "sign_in"},
+)
+try:
+    await email.send(message, idempotency_key=f"sign-in:{attempt.id}")
+except EmailRejected as rejected:  # the address, the domain or the credentials; not an outage
+    log.warning("email.rejected", status=rejected.status, code=rejected.code)
+```
+
+`EmailRejected` carries the provider's status and error name (`validation_error`,
+`MessageRejected`, ...), never its message. Resend sends each request once; with an
+`idempotency_key` a retry after `DependencyUnavailable` within 24 hours cannot send twice.
+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.
+
+### KMS
+
+The encryption context is required on every call, so a ciphertext only decrypts for the
+purpose it was made for:
+
+```python
+from clients_021.kms import KmsClient
+
+keys = KmsClient.create(obs, settings.session_key_arn, region="us-east-1")
+context = {"purpose": "refresh-token", "tenant": tenant_id}
+stored = await keys.encrypt(refresh_token, context=context)   # up to 4096 bytes
+refresh_token = await keys.decrypt(stored, context=context)
+envelope = await keys.seal(document, context=context)          # any size
+document = await keys.unseal(envelope, context=context)
+```
+
+The context is logged by KMS in CloudTrail in plaintext: it names a purpose, never a
+secret. `seal` makes one `GenerateDataKey` call and encrypts locally with AES-256-GCM;
+`unseal` makes one `Decrypt` call. A wrong context, a tampered ciphertext or another key's
+ciphertext keep their botocore type (they are bugs or attacks, not outages); a tampered
+envelope raises `cryptography`'s `InvalidTag`. The envelope layout is in
+[CONTRACT.md](CONTRACT.md).
+
+### SDKs on httpx2
+
+For an SDK on httpx2:
+
+```python
+from anthropic import AsyncAnthropic, DefaultAsyncHttpxClient
+from clients_021.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`.
+The transport preserves SDK exceptions so the SDK retains control of retries and error
+handling; it does not convert them to `DependencyUnavailable`.
+
+## Service integration
+
+Create clients once during service startup and reuse their connection pools. Keep business
+rules in service adapters: queue envelopes, deduplication-key generation, storage integrity and key naming
+do not belong in this library. Inject the configured SDK client into the constructor when
+you need provider-specific options (for example S3 addressing style or credentials).
+
+Close clients during shutdown, after stopping consumers and waiting for in-flight calls.
+`aclose()` closes the underlying client, including an injected one; do not share that SDK
+client with another owner. An `AsyncExitStack` makes cleanup explicit:
+
+```python
+from contextlib import AsyncExitStack
+
+async with AsyncExitStack() as resources:
+    http = HttpClient(obs, timeout_seconds=10)
+    resources.push_async_callback(http.aclose)
+    redis = RedisClient.from_url(obs, settings.redis_url)
+    resources.push_async_callback(redis.aclose)
+    files = S3Client.create(obs, "service-uploads", region="us-east-1")
+    resources.push_async_callback(files.aclose)
+    queue = SqsClient.create(obs, settings.queue_url, region="us-east-1")
+    resources.push_async_callback(queue.aclose)
+    email = ResendSender(obs, settings.resend_api_key)
+    resources.push_async_callback(email.aclose)
+    keys = KmsClient.create(obs, settings.session_key_arn, region="us-east-1")
+    resources.push_async_callback(keys.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,
+  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
+  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.
+  SQS allows ten message attributes including trace context; reserve two for `traceparent`
+  and `tracestate`, which belong to the library.
+- Redis keeps the injected SDK's retry policy. For non-idempotent operations such as
+  `take_json` and `incr_window`, do not configure automatic replay after an ambiguous
+  timeout. Authentication and authorization errors keep their Redis exception type.
+- QStash sends each publication POST once. `delivery_retries` configures subsequent
+  delivery by QStash, not retrying this request. HTTP 429 and 5xx become
+  `DependencyUnavailable`; other rejected statuses and invalid acknowledgements raise
+  `QStashResponseError` with a status code and no provider body. Delivery timeouts and
+  delays use integer seconds and remain subject to the provider plan's limits.
+- httpx2 SDKs own their retries; `ObservedTransport` adds no extra retry loop.
+
+`DependencyUnavailable` signals a transient dependency failure, **not permission to replay
+any operation**. Map it at the service boundary and apply the operation's idempotency rules.
+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
+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.
+
+## Development
+
+```bash
+uv sync --all-extras
+make check   # ruff, pyright strict, pytest (Redis at REDIS_URL, default redis://127.0.0.1:63799/15)
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the module layout and the checklist for adding
+clients. QStash protocol tests need no external service. To exercise actual delivery and
+deduplication, start the [official local server](https://upstash.com/docs/qstash/howto/local-development),
+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
+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.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+clients_021/__init__.py,sha256=-nha2Z2GGtWvRsjSdMt4SLRCa9gDoA5VRyhfFg3v8AY,730
+clients_021/_aws.py,sha256=sj2kCfod-vz9J93UyeVzNVLGK3M25yipKdW15KyIkw4,1722
+clients_021/_observe.py,sha256=7HbFKH3x6sQonz_lpH7DLFuLBnSLgiSGUtlt4lN17NU,3779
+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/kms.py,sha256=iEzIqzizOhs387VF_w5pV5cRTUCx7uepvYCxFl5gWK8,7254
+clients_021/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clients_021/redis.py,sha256=sOPUMXE7z7X639T3SLPDWRAQSFysp2bj1kCWzdtXiEM,4926
+clients_021/s3.py,sha256=2iK6N_UVVjZRIFfe24p3PWtRFHqCDsZvjcs5GIzhZSY,5938
+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/ses.py,sha256=0ukHvuVE0nTU5mYWRy2EaHY5v9dUwi4GSKES93pjqBg,4668
+clients_021/queue/__init__.py,sha256=CesweOrXmX5cyU-mRvqu-4wLkNJI15zi_Lows6SPupY,338
+clients_021/queue/qstash.py,sha256=j3vz_S9-ed0YQZCaWwQg5wPwf8Bv5P1voNsx8WD8Zhc,8315
+clients_021/queue/sqs.py,sha256=jnccgbxyglzs2mR_DsH04IisEwygDlw6s3RxR0UtMTc,6693
+021_python_clients-0.1.0.dist-info/METADATA,sha256=lqElbrid3Ug6ZM5Mg0jUNhjKpiNPnvormJf32oXNn84,16655
+021_python_clients-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+021_python_clients-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+021_python_clients-0.1.0.dist-info/RECORD,,

021_python_clients-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

021_python_clients-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

clients_021/__init__.py

@@ -0,0 +1,22 @@
+"""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.redis` needs the `redis` extra; `clients_021.queue.sqs`, `clients_021.s3`,
+`clients_021.email.ses` and `clients_021.kms` the `aws` extra; `clients_021.httpx2` the
+`httpx2` extra.
+"""
+
+from importlib.metadata import version
+
+from clients_021.errors import DependencyUnavailable
+from clients_021.http import IDEMPOTENT_METHODS, HttpClient, HttpMethod, HttpResponse
+
+__version__ = version("021-python-clients")
+__all__ = [
+    "IDEMPOTENT_METHODS",
+    "DependencyUnavailable",
+    "HttpClient",
+    "HttpMethod",
+    "HttpResponse",
+    "__version__",
+]

clients_021/_aws.py

@@ -0,0 +1,55 @@
+"""What the AWS clients share: botocore configuration and the error classification."""
+
+from __future__ import annotations
+
+from botocore.config import Config
+from botocore.exceptions import (
+    ClientError,
+    ConnectionClosedError,
+    ConnectTimeoutError,
+    EndpointConnectionError,
+    ReadTimeoutError,
+)
+
+# Codes AWS uses for "slow down" across services.
+_THROTTLED = frozenset(
+    {
+        "Throttling",
+        "ThrottlingException",
+        "ThrottledException",
+        "RequestThrottled",
+        "RequestThrottledException",
+        "TooManyRequestsException",
+        "SlowDown",
+        "RequestLimitExceeded",
+        "ProvisionedThroughputExceededException",
+    }
+)
+
+
+def config(*, connect_seconds: float, read_seconds: float) -> Config:
+    """Bounded timeouts and the SDK's standard retry mode (backoff with jitter, 3 attempts)."""
+    return Config(
+        connect_timeout=connect_seconds,
+        read_timeout=read_seconds,
+        retries={"mode": "standard", "total_max_attempts": 3},
+    )
+
+
+def classify(error: BaseException) -> str | None:
+    if isinstance(error, ConnectTimeoutError | ReadTimeoutError):
+        return "timeout"
+    if isinstance(error, EndpointConnectionError | ConnectionClosedError):
+        return "connection_error"
+    if isinstance(error, ClientError):
+        code = str(error.response.get("Error", {}).get("Code", ""))
+        status = int(error.response.get("ResponseMetadata", {}).get("HTTPStatusCode", 0))
+        if code in _THROTTLED:
+            return "throttled"
+        if status >= 500:
+            return f"status_{status}"
+    return None
+
+
+def error_code(error: ClientError) -> str:
+    return str(error.response.get("Error", {}).get("Code", ""))