python-manilaclient — Rewrite pack

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

Branch stable/2026.2 @ d18a7e966 (6.3.0 + 2 maintenance commits) — repository https://opendev.org/openstack/python-manilaclient — analysed on 2026-11-01

This pack has two uses:

• **Keep openstack share working against the OpenKeel Manila service in Go**, by stating what the client requires.
• Re-implement the plugin, thanks to the machine-readable catalogue.

No Manila ran. Everything observed was against a local stub on 127.0.0.1, which answers version discovery, a Keystone token, and fixed bodies. It shows what the client sends and how it reacts. It says nothing about what a real service does, and no OpenKeel or Python Manila was contacted. 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. The functional tests here need a live cloud (manilaclient/tests/functional/osc/base.py:24).

Versions: python-manilaclient 6.3.1.dev2 at this commit (the installed copy was compared with the clone: identical), python-openstackclient 10.3.1, osc-lib 4.7.0, cliff 4.16.0, keystoneauth1 5.17.0, openstacksdk 4.20.0, Python 3.13.

To regenerate (HOME set to an empty directory, OS_* unset):

python -I -B _rewrite/extract_plugin_stable-2026.2.py <repo> python-manilaclient manilaclient _rewrite
python -I -B _rewrite/manager_routes_stable-2026.2.py <repo> <mr.json>
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir> --mode 404      # then 200, shaped
PROBE_ALL_OPTIONS=1 python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir> --mode shaped
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir> --mode shaped --api-version 2.N   # for N in 0..98
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-N>/c.json <repo>/manilaclient/tests/unit/osc/v2 <repo>   # twice
python -I -B _rewrite/defects_stable-2026.2.py _rewrite/probe_plugin_stable-2026.2.py <defects.json>
python -I -B _rewrite/build_contract_stable-2026.2.py . <gen-dir> <404> <200> <shaped> <all-options> <run-1> <run-2> <mr.json> <sweep-dir> <defects.json>

2. What the plugin requires from a service

3. Microversion coverage

• Range: client 2.0 to 2.98. Manila on this branch goes to 2.99 (manila:manila/api/openstack/api_version_request.py:229). The field snapshot_inherit_share_access_support of 2.99 is not requested by this client, and the CLI refuses --os-share-api-version 2.99.
• Gates: 86 sites in the commands, on 43 microversions. Their list is in client-contract_stable-2026.2.json.
• Variants: 288 across 187 manager methods.
• Minimum for a useful client: shares, types, and snapshots mostly work from 2.0 to 2.9. Backups need 2.80, locks 2.81, transfers 2.77, QoS 2.94, groups 2.31, snapshot export locations 2.32. The version sweep gives this per command.

OpenKeel: openkeel-chart, openkeel-lab and the OpenKeel Manila service were not read or contacted for this pack. Whether a Go Manila exists at the announced version must be checked separately, starting from [api-surface_stable-2026.2.md](_rewrite/api-surface_stable-2026.2.md).

4. For a rewrite of the plugin itself

Recommendation: keep the Python plugin, make the service compatible, and propose defects 1 to 12 upstream. The surface is 154 commands with 288 manager variants, and the OSC shell cannot host a non-Python plugin.

5. Conformance: what was proved

The usual "replay is mandatory" bar is not met for service behaviour. No vector was replayed against a rewrite, and nothing was compared with a running Python Manila. The mocks also hide real defects: defects 1 to 12 of 02 § 4 all pass the unit tests, except defect 11, which has none.

To close the gap: run the probe's argv from wire-probe-shaped_stable-2026.2.json against a devstack on stable/2026.2 with real resources, or run manilaclient/tests/functional/osc against both implementations.

Class without a unit vector (1): manilaclient.osc.v2.share:RestoreShare.

6. Gaps found while building the pack

• 55 of the 232 operations are static only. Most are variants below 2.98, such as /os-services, or manager methods no command reaches.
• 8 static client methods do not resolve, because they are Resource methods or to_dict: set_keys, unset_keys, to_dict, share_access_rules.list. The wire probe shows the first ones, for example POST /types/{id}/extra_specs.
• manager_routes calls each method with its required arguments only, so optional body fields are not all in manager-routes. wire-probe-all-options covers them at 2.98 only.
• The extractor's static call list follows variables assigned from find_resource and get, not attributes passed through helpers. The unit vectors cover that.
• The route check uses Manila's generated OpenAPI. Its 5 misses are /services/enable and /services/disable, which it stores as /services/{id}; /os-services/* likewise; and /types/{id}/os-share-type-access below 2.7.

7. Non-functional requirements

• Latency: each invocation authenticates and reads discovery. Keystone and GET / of Manila are on the hot path.
• Listing cost: a name lookup lists the collection four times for shares from 2.69, twice elsewhere. A service must keep GET /shares/detail fast with all_tenants=1.
• Polling: 1 GET every 5 s per waiting command, without a limit for status waits.

8. Checklist for an OpenKeel Manila service

• [ ] Catalog entry shared-file-system or sharev2, with public, and /v2 in the URL path.
• [ ] Version document at the base URL, with a CURRENT entry, version, min_version.
• [ ] X-OpenStack-Manila-API-Version honoured; every announced microversion implemented.
• [ ] Experimental header accepted on every route.
• [ ] GET /<resource>/{name} gives 404; all_tenants, is_public, is_soft_deleted honoured on lists.
• [ ] Empty lists keep their key; required fields present; errors in {"<key>": {"code": n, "message": "…"}}, never {}.
• [ ] Dict filters parsed from a Python repr.
• [ ] migration_check never answers empty.
• [ ] reset_task_state with null handled as Manila does, since every share set sends it.
• [ ] Each operation of api-surface_stable-2026.2.md implemented, or its absence documented.
• [ ] The argv of wire-probe-shaped_stable-2026.2.json, pointed at the service with real resources, gives the same routes and exit 0.

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