python-heatclient — Rewrite pack

Client contract (rewrite pack) — python-heatclient — branch stable/2026.2

Branch stable/2026.2 @ 88120f11830d (5.3.0-2-g88120f1) — repository https://opendev.org/openstack/python-heatclient — analysed on 2026-11-01 Heat reference: [../reverse-spec-heat/](../reverse-spec-heat/00-summary_stable-2026.2.md), branch stable/2026.2 @ 5872396e5, read only. Versions: osc-lib 4.7.0, cliff 4.16.0, keystoneauth1 5.17.0, python-openstackclient 10.3.1.

The goal is to state **what the openstack orchestration commands require from Heat, so that a Go Heat keeps them working unchanged, and to provide data for testing it. The evidence comes from a local stub and from mocks. **No Python Heat and no rewrite were involved, so nothing here proves conformance of any service. See § 5.

1. Contents of _rewrite/

Adaptations: the probe's stub answers Heat's lookup 302 and Heat's fault body, and has fixture files, because otherwise half of the commands stop at the first answer. The capture runs from the repository root, where the tests expect their templates. All runs: empty HOME, no OS_*, stdin from /dev/null, 127.0.0.1 only.

2. What the commands require from Heat

Transport and routing

Correction to the Heat reverse-spec: its 07 cites heatclient:heatclient/common/http.py:191-243 for "the client re-sends the same method on 302". That code belongs to the older HTTPClient. With OSC, the path is SessionClient, and keystoneauth re-sends the method (keystoneauth1:keystoneauth1/session.py:1246) [observed]. The requirement stands; the source differs.

Response keys the client reads

Missing keys cause the raw errors of 02 § 4, defect 12. Keys marked * have no fallback.

Texts and values the client parses

A rewrite must keep these strings exactly.

stack_status for cancellation is lowered and compared with create_in_progress and update_in_progress (heatclient/osc/v1/stack.py:1307-1318).

What the commands never call

GET /stacks/detail, GET / (versions), CFN routes, PUT /software_deployments/{id} from OSC (heatclient/v1/software_deployments.py:70 serves the legacy shell), and the actions:* other than the 5 listed. A Heat rewrite must validate them by other means: see the Heat pack.

3. Interaction sequences worth testing

Scenarios G01 to G31 give good sequences. Those a service most easily breaks:

1. Name lookup with each method (G05, G06, G08, G27).
2. Event paging: limit=1&sort_dir=desc to get a marker, then marker=<id>&sort_dir=asc until the stack event (G02, G05).
3. 404 on events once a stack is gone (G08).
4. Nested events: nested_depth with a root_stack link (G13); without it, the fallback multiplies requests (G14).
5. Hook cycle: event texts in order (G17), unset_hook signal on name/id (G18).
6. Client pagination: limit returning fewer than asked, then marker=<last id> (G10).

4. For a rewrite of the CLI itself

Recommendation: keep the Python client and make the service compatible. The commands are thin, the behaviour worth keeping sits in template handling and event logic, and the plugin only loads in Python. If the plugin is carried forward, fix defects 1, 2, 3 and 5 first. Those are small changes, but none was made here, because the repository is read-only for this work.

5. Conformance: what was proved

The usual "replay is mandatory" bar is not met. No vector was replayed against a Python Heat or a rewrite, because the rules of this work exclude any real service. To close the gap, on a devstack stable/2026.2:

1. run heatclient/tests/functional/osc;
2. run the probe's argv and the scenario argv with a real template, and compare routes and statuses with the JSON files here;
3. then do the same against the Go Heat.

Also compare the Heat pack's exchanges_stable-2026.2.json, which recorded this client's requests on the real Python Heat through heat-tempest-plugin: a useful cross-check, not done here.

Classes without a unit vector (1)

heatclient.osc.v1.stack:ListFileStack (stack file list, heatclient/osc/v1/stack.py:628): no test. It was seen on the stub only.

Vectors without calls: 13 tests stop on the client before any call, on purpose (bad arguments, a declined prompt).

6. Gaps found while building the pack

• 3 operations were never sent by the probes, only by scenarios: POST /software_deployments, DELETE /software_deployments/{id}, GET …/events/{id}.
• 4 commands send nothing with minimal arguments: software deployment create (defect 1), software deployment output show, stack output show (both need an optional positional or --all), stack update (needs -t or --existing). Their variants do.
• The 200 probe stops at the first {} that the client cannot use, so only the scenarios reach later steps.
• --wait paths ran with time.sleep replaced, so real timing was not tested.
• Swift calls were seen only with the legacy shell, on a stub answering 201 to everything.
• The extractor's REST resolution targets openstacksdk, so it found almost nothing here (with_rest=2). The static route table in build_contract_stable-2026.2.py was written by hand from heatclient/v1/*.py. A route added to a manager would not appear by itself.

7. Checklist for a Go Heat

• [ ] 302 lookup with every method, sub-paths, the query kept (§ 2 #2–5).
• [ ] Fault body with error.message, JSON content type (§ 2 #7–9).
• [ ] 404 semantics, including events of a deleted stack (§ 2 #10).
• [ ] Response keys of § 2, collection keys always present, even when empty.
• [ ] Event texts and links of § 2, unchanged.
• [ ] events honouring marker, limit, sort_dir, sort_keys, nested_depth, with a root_stack link.
• [ ] At least 2 template versions with aliases.
• [ ] Decide global_tenant policy knowing that stack list --long sends it (defect 2).
• [ ] Run the probes' argv with software deployment create --signal-transport NO_SIGNAL, since the default fails on the client.

Source: reverse-spec-python-heatclient/07-rewrite-pack_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.