[fostimus]

Summary

Layer 2 of 4, on #97. One requests-based transport replaces gql for GraphQL and the ratelimit decorators for REST, bringing the client to node-anvil's behavior.

• Anvil(api_key, base_url=...) sends every request to one host, REST and GraphQL alike; the hardcoded graphql.useanvil.com host and endpoint_url are gone. OAuth access tokens are accepted (access_token), sent as-is when they are JWTs and base64 encoded otherwise.
• Rate limits come from the first response with X-RateLimit-* headers, counted over a sliding window like the API's; requests made before the first response wait for it. A request counts from when it is sent until an interval after its response arrives, because the API counts from when the request reached it, which is in between: the first staging run of the rate limiting check got a 429 when the client counted from send time, since a new connection's handshake put a request on the wrong side of the window. Every client in the process with the same base_url and credentials shares one limiter, as the account's limit is shared, so an app that makes a client per request is limited as a whole, as it was with the ratelimit decorator. A 429 is retried after its Retry-After plus 50ms, or after a second without one. The limiter is thread-safe.
• Every request is retried on 500, 502, 503, 504 and connection errors, up to max_retries (5) times with exponential backoff, the policy gql's transport applied to GraphQL requests in 5.x, now for REST too. Mutations are retried as before; max_retries=0 turns it off.
• API errors raise AnvilRequestError with the normalized errors (GraphQL errors, REST errors, validation errors with their fields), status code, headers and any partial data. Methods return the data itself: PDF bytes, or the GraphQL data dict. include_headers, debug and retry are gone.
• Multipart uploads follow the GraphQL multipart request spec directly. Anvil.prepare_graphql_file takes a path, bytes or a file object; a retried upload reopens a path and rewinds a file object, and fails clearly for one that can't be read again.
• The queries and mutations live in python_anvil.graphql, copied from node-anvil's src/graphql, and are validated against the schema from @anvilco/types in the tests. That check found that casts and welds are paginated now, which the old get_casts and get_welds queries no longer matched.
• New: get_etch_packet, remove_weld_data, request_graphql, request_rest, response_query and mutation overrides, data_type="stream", and a 5 minute request timeout.
• test-client.py from [Refactor] Modernization: Python 3.10-3.15, ruff, PEP 621 packaging and tag-triggered publishing #97 is updated to the 6.0 API. Its diff in this PR is the list of behavior changes a caller sees: the constructor, request_rest's signature, include_headers gone, generate_etch_signing_url returning the URL, and the GraphQL methods that replace raw queries. It keeps the 5.x upload path (an open file base64 encoded into the variables) alongside the new multipart one, and the convenience queries, and adds a rate limiting check: after the first request has taught the client the account's limit, it sends two more requests than the limit allows at once and checks that they took at least an interval and that none got a 429.

An audit against 5.1.2 (one pass by hand, one by an independent reviewer with the diff and the changelog) found nothing in the methods themselves, and a handful of edge cases, fixed in the last commit: limits are taken from the first response that has the headers rather than the first response; a 429 with no Retry-After waits a second instead of 50ms; a 2xx JSON body with a name key is data, not an error; a full URL on another host is refused; environment still works positionally; a builder's mutation_res_query still works; and forge_submit with a webhook_url works, which it did not in 5.x. The changelog now names every removed public name. Two things the audit flagged as node-anvil parity were instead kept as 5.x had them, since they are the better behavior for Python callers: 5xx and connection errors are retried, and the rate limiter is shared per credentials rather than per client instance.

A second audit of the retry and shared-limiter commits found one bug, fixed in the last commit: a raw data= file object passed to request_rest was re-sent empty on a retry. It also hardened the rest: a limiter slot can't leak on an interrupt, the shared-limiter registry is weak and keyed on a hash of the credentials, Retry-After is capped at a minute and must be a finite number, and read timeouts are deliberately not retried.

The HTTP tests run the real client against a local server (tests/server.py), so the auth encoding, multipart bodies, rate limit timing and error handling are checked on the wire rather than through mocks.

How to verify

• ANVIL_API_KEY=<staging key> make test-client reports PASS for every method against staging, including the rate limiting check, which prints the limit learned from the API and the time a burst over it took, including the base64 upload path and get_casts/get_welds, which FAIL on [Refactor] Modernization: Python 3.10-3.15, ruff, PEP 621 packaging and tag-triggered publishing #97 (not run here: no staging key in this environment)
• Basic auth is base64(api_key + ":"); a JWT access token is sent as Bearer <token> as-is, any other access token base64 encoded
• Every URL derives from base_url: /api/v1/fill/{id}.pdf, /api/v1/generate-pdf, /api/document-group/{eid}.zip and /graphql
• The first response's X-RateLimit-Limit and X-RateLimit-Interval-Ms set the limits; concurrent requests wait for that first response; no more than the limit is sent in any interval
• A 429 is retried after Retry-After plus 50ms, and retried again if the retry is also a 429
• A GraphQL error in a 200 response raises AnvilRequestError with status_code == 200, the errors list and the partial data
• A REST validation error raises with its fields; a non-JSON 502 raises with the status text; an empty JSON body raises a JSONDecodeError error
• A file from prepare_graphql_file is sent as operations, map and a file part with the right filename and mimetype; a base64 dict is sent as plain JSON
• A rate-limited upload from a path is sent in full again; a non-seekable file object fails with an error rather than sending an empty file
• fill_pdf(..., data_type="stream") returns a requests.Response that streams the PDF
• generate_etch_signing_url returns the URL string; get_etch_packet the packet; remove_weld_data a bool
• A first response without rate limit headers (e.g. a proxy 502) does not fix the client at 1 request/s: the next response with headers sets the limits
• A 2xx JSON response with a top-level name key is returned as data, and request_rest("GET", "https://other.host/...") raises a ValueError
• request_rest("POST", ..., data=<file object>) that gets a 503 is retried with the full body, and a body that can't be rewound raises instead of being sent empty
• A Retry-After of 1e9 on a 503 waits 60 seconds, not 31 years; nan falls back to backoff
• A 503 is retried with backoff and the eventual 200 returned; a 4xx is not retried; max_retries=0 sends once; a retried upload is sent in full again
• Two clients with the same key and base_url share one rate limiter and the limits the first response taught; clients for different keys do not
• create_etch_packet({"name": ..., "webhookURL": ..., "mergePDFs": True}) and forge_submit({"forgeEid": ..., "payload": {}}) accept the camelCase keys the docstrings promised
• Anvil(key, "prod") works with a DeprecationWarning, and forge_submit({"forge_eid": ..., "payload": {}, "webhook_url": "https://..."}) sends the URL

Breaking Changes

A major release (6.0.0). The constructor, return values, error type, request_rest signature and removed classes are listed under Unreleased in CHANGELOG.md.

---

Open workspace in Conductor