python-designateclient — Rewrite pack

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

Branch stable/2026.2 @ 9231eef90192 — repository https://opendev.org/openstack/python-designateclient — analysed on 2026-11-01

This pack serves two purposes:

• Keep the commands and the Python API working against a re-implemented DNS service, by stating what they require.
• Re-implement the commands, from the machine-readable catalogue.

No replay against a real service was possible. Everything on the wire comes from a local stub, and the requirements below are what the client does with a response, not what Designate does. See § 5.

1. Contents of _rewrite/

The generic rewrite_pack.py and conformance_capture.py were not used: they expect a service or functional tests running in-process, while the functional tests here need a live cloud (designateclient/functionaltests/config.py:21).

Versions: python-designateclient 7.0.1.dev2, osc-lib 4.7.0, cliff 4.16.0, python-openstackclient 10.3.1, keystoneauth1 5.17.0, requests-mock 1.12.1, Python 3.13.

To regenerate:

python -I -B _rewrite/extract_plugin_stable-2026.2.py <repo> python-designateclient designateclient _rewrite
for m in 404 200 fixture; do python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-$m> --mode $m; done
python -I -B _rewrite/repro_defects_stable-2026.2.py _rewrite/probe_plugin_stable-2026.2.py <repro.json>
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-1>/c.json <repo>/designateclient/tests <repo>
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-2>/c.json <repo>/designateclient/tests <repo>
python -I -B _rewrite/build_contract_stable-2026.2.py . <dir-404>/wire-probe_stable-2026.2.json <dir-200>/wire-probe_stable-2026.2.json <dir-fixture>/wire-probe_stable-2026.2.json <run-1>/c.json <run-2>/c.json <repro.json> <designate-routes.json> <gen-dir>

Set HOME to an empty directory and unset OS_*, so that no real clouds.yaml is read. The stub binds to 127.0.0.1.

2. What the client requires from a DNS service

Apply this to any service that must work with the unmodified client. "Client" evidence is on the stub; the service column of Designate is what was read.

Fields the commands display but do not need are listed per command in the class columns. A missing one gives an empty cell, not an error.

What the Python API users add

3. Coverage against Designate

Static comparison with reverse-spec-designate/_rewrite/routes_stable-2026.2.json: 61 of 61 client operations exist there. Of its 78 routes, 16 are never called by the client: the /admin API, pool administration, GET /recordsets/{id}, the /service_status alias, and GET /zones/{id}/tasks/abandon. GET /pools is reachable only through the Python API. This compares method and path only, with no bodies, and nothing was run.

4. For a rewrite of the commands

Recommendation: keep the Python client and fix it upstream rather than rewriting it. It is small (60 commands, thin controllers), and Neutron and Heat call its Python API. A Go rewrite would not serve them.

5. Conformance: what was proved

Replay against a real service, the usual bar, is not met. The mocks also hide real defects: none of the 18 defects is caught by a unit test.

To close the gap: run the probe's fixture commands, with real resources, against a devstack on stable/2026.2, and compare statuses and keys; or run designateclient/functionaltests against it. Neither was attempted, as the rules for this work allow only the local stub.

Command classes without a command vector

55 of 60. Vectors exist only for CreateRecordSetCommand, ListRecordSetsCommand, ListTLDsCommand, CreateZoneCommand, ListZonesCommand. The controllers behind the others mostly have API vectors, which do not test argument parsing. Zone shares, exports and transfers do have API vectors [see unit-vectors].

6. Gaps found while building the pack

• The generic stub's version document pointed at /dns/, without /v2, so every command would have gone to /dns/zones [inferred; the unfixed stub was not run]. It was replaced by the shape of Designate before the first probe. Scenario discovery-root-404 then gave requirement 2.
• The tool's logging.disable hid every error message, so it was removed.
• OSC caches the client on the class (osc-lib:osc_lib/clientmanager.py:51). Without a reset, one in-process run leaked --sudo-project-id into later scenarios, which is how defect 8 was found.
• capture_plugin records check_parser only, and would have missed the 87 API tests. It was extended.
• Name lookups are not in the wire probes, since those pass UUIDs. They are in defects-repro.

7. Non-functional requirements

• Latency: each openstack invocation asks for a token and reads the version document, so these two are on the hot path. A script of N commands sends N token requests.
• Name arguments cost one to two extra requests per command.
• Listing cost: lists read all pages; the page size is the service's.
• Payload: zone import create reads the whole file into memory, then sends it (designateclient/v2/cli/zones.py:737).

8. Checklist for a DNS service

• [ ] dns in the catalog, with a public endpoint.
• [ ] Version document at the catalog root, or /v2 in the catalog URL.
• [ ] Every route of api-surface_stable-2026.2.md implemented, or its absence documented.
• [ ] Collection keys always present; links.next only when there is more.
• [ ] masters, attributes, records, capabilities, stats, id always present where read.
• [ ] Delete and set answers carry a body.
• [ ] Failures use the translated statuses, or the gap is accepted knowingly.
• [ ] Fault bodies are objects with message.
• [ ] text/dns import and export, JSON import with attributes.
• [ ] Feature headers honoured, values True and true accepted.
• [ ] The probe in fixture mode's commands, pointed at the service, exit 0 with real resources.

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