[briankfung]

What changes

• An operation's own header is a keyword of its own. The generator reads each operation's optional header parameters, where it skipped them before. Each becomes a keyword of that method's own, named from the header in snake_case and typed from the spec. process_message takes payer_authorization, sent as Payer-Authorization, and every existing call works as it did:

  checked = client.process_message(message, payer_authorization=f"Bearer {access_token}")

• Held where nothing prints it. A header can carry a credential, so the method holds the keyword at once in HeldHeaders, which prints as <headers hidden> and is never pickled, and deletes the name, as it already does for a request body. A traceback that records each frame's local variables shows nothing of it.

• Checked before sending. The value is checked against the parameter's schema (its maxLength and pattern, plus no line break, since Python's $ would match before a final one) in a frame of its own. A value the API would refuse raises Haau3Error before anything is sent, and the message names the keyword, never the value.

• Precedence. The keyword wins over the same header in extra_headers, as correlation_id does for X-Request-Id.

• The generator stops on a required header, a cookie, a header whose name clashes with a query parameter or a call option, a schema that is not a string, a pattern Python cannot read, and a header on an operation a batch can carry.

• Docs: api.md, the method's docstring and the README's Options say how it works.

Why

The spec declares Payer-Authorization on process_message, but the generator built methods from path and query parameters only, so the header could be sent only through extra_headers, unchecked, as an ordinary local a traceback would print. The value is the whole header (Bearer and the token), as the spec's schema types it.

Tests

tests/test_header_options.py, each run sync, on asyncio and on trio:

• the header is sent beside the key's own Authorization, and not sent when unset (the control);
• any case of the scheme is taken;
• a bare token, another scheme, an empty value, a final line break and 4,097 characters are each refused before anything is sent, with the value nowhere in the error or in the SDK's own frames printed with their local variables, and 4,096 characters are taken;
• the keyword wins over extra_headers, is sent again on a retry, and is carried by no error the API answers;
• the holder never prints or pickles what it holds, and only process_message takes the keyword.

A positive control checks that the SDK's frames are printed with their locals. tests/test_generate.py covers the generator's new keyword and each case it stops on.

Negative controls, each failing its tests: the keyword's name kept in the method's frame (5 fail), the pattern unchecked (9), extra_headers winning (3), the refusal raised in the frame that holds the value (9).

pytest (672 passed), ruff check, ruff format --check, mypy, pyright, pyright --verifytypes (100%) and ty check pass. The generated files are current.

🤖 Generated with Claude Code