python-manilaclient — Summary

Reverse-specification of 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

• Scope: the whole repository, focused on the OSC commands and the Python API they call. The change history (step 7) was not requested.
• Dependencies read at fixed versions: osc-lib 4.7.0, cliff 4.16.0, keystoneauth1 5.17.0 and openstacksdk 4.20.0, cited with the prefixes osc-lib:, cliff:, keystoneauth:. python-openstackclient at 8bb083b83 (openstackclient:), and Manila at 4fbc4b4f3 (manila:), read only.
• References are file:line from the repository root. [inferred] marks a statement not followed to the end. [observed] marks a behaviour seen by running the real openstack shell against a local stub on 127.0.0.1.
• The stub is not a service. Observed behaviour says what the client sends and how it reacts to a given answer. It says nothing about what a real Manila does. No lab, cluster or cloud was contacted.

Files of this specification

File 06 (change history) is absent because it was not requested.

Overview

python-manilaclient is the plugin that gives the openstack CLI its share commands, and a Python library for Manila, the Shared File System service. Each command:

1. resolves its arguments, often by listing a collection to turn a name into an ID;
2. checks the microversion locally;
3. calls a manager of manilaclient.v2, which picks a variant of the method for the microversion and sends REST calls through keystoneauth;
4. prints the result through cliff.

It has no database, message bus, server or background process. The legacy manila command was removed in January 2026 (commit e448fc8), so openstack is the only way in.

Architecture

flowchart LR
  user[User or script] -->|argv, env| osc[openstack process]
  cfg[clouds.yaml, OS_* variables] --> osc
  osc -->|entry points| plugin[manilaclient.osc.plugin]
  plugin --> cmds[manilaclient/osc/v2: 154 commands]
  cmds --> mgr[manilaclient/v2: 32 managers]
  mgr --> sc[SessionClient]
  sc --> ksa[keystoneauth1]
  cmds -->|project and user lookups| ksc[python-keystoneclient]
  ksc --> ksa
  cmds -->|Neutron names, two commands| sdk[openstacksdk]
  sdk --> ksa
  ksa -->|HTTPS, X-Auth-Token| ks[Keystone]
  ksa -->|HTTPS, X-OpenStack-Manila-API-Version| m[Manila]
  ksa -->|HTTPS| n[Neutron]
  py[Python programs] -.->|library| mgr

Processes

There is no separate legacy shell: no console_scripts in pyproject.toml, and manilaclient/shell.py no longer exists.

External dependencies

Key figures

Points of attention

1. **share set always sends reset_task_state with null [observed]** (manilaclient/osc/v2/share.py:958). share server set --status does the same (manilaclient/osc/v2/share_servers.py:530). On a real Manila this action is admin-only, so a member's rename should succeed and exit 1, and an admin's should clear the task state [inferred from manila:manila/policies/shares.py:564].
2. **share server migration start --check-only can start a real migration [observed]**, when the check answers an empty body (manilaclient/osc/v2/share_servers.py:740-757).
3. Crashes below the version they assume [observed]: share snapshot create below 2.73, share network set below 2.63, share network subnet create below 2.78, share server adopt at 2.49 and 2.50. These matter when a server is older than the client, since the client lowers its version silently.
4. Options that cannot work [observed]: share adopt --public and share quota set --class --encryption-keys raise TypeError.
5. **share access list --properties drops the other filters [observed]** (manilaclient/osc/v2/share_access_rules.py:351).
6. **share restore <name> sends the name in the URL [observed]**, despite its help text (manilaclient/osc/v2/share.py:1818).
7. Exit 0 on failures [observed]: share create --wait on an error status, share backup unset on a failed update. **--wait has no time limit on status waits.**
8. **OS_SHARE_API_VERSION=2 breaks every share command [observed]** (manilaclient/api_versions.py:54), and --os-share-api-version stops at 2.98 while Manila announces 2.99.
9. A name lookup lists the whole collection, four times for shares from 2.69 [observed] (manilaclient/base.py:253-279). A service that ignores is_soft_deleted breaks it.
10. Dict filters travel as a Python repr in the query string [observed] (manilaclient/base.py:229).
11. Hard requirements on answers: collection and resource keys, size, is_public, required_extra_specs, backend_details, and a non-empty JSON error body. Without them, a bare Python message is printed [observed]. See 02 § 5.
12. Unit tests cannot catch these: they use mocks (manilaclient/tests/unit/osc/v2/fakes.py:27). share restore has no test.
13. Secrets: --password of security services is visible in the process list, and share transfer create prints the auth_key (manilaclient/osc/v2/security_services.py:118, manilaclient/osc/v2/share_transfers.py:73).
14. **openstackclient.share.v2 does not interfere**: it is ignored by OSC, it holds 40 of the 154 names, and it differs in negotiation and in a few options. See 01 § 4.

Blind spots / [inferred]

• No service was contacted. Real Manila behaviour is read in its code at most, and marked [inferred]. Status transitions in the diagram of 01 are [inferred]. Whether a real Manila returns what the client needs in every microversion was not tested.
• Functional tests (manilaclient/tests/functional/osc, 24 files) need a cloud and were not run.
• The shaped stub answers one body for everything, with every key. It hides field-level mismatches between the client and a real service, and exit 0 there only means the client accepted that body.
• Synthetic arguments follow one path per command. Options are covered only by the all-options run at 2.98, and by the targeted cases. The version sweep uses minimal arguments, so a gate behind an option is not exercised by it.
• **--wait loops** were run in only a few cases, as polling takes time.
• OpenKeel's Manila was neither read nor run.
• **manilaclient/v1**, HTTPClient and the Client(input_auth_token=…) path are outside the commands, and were read only briefly. Library use by other programs (for example manila-ui) was not surveyed.
• Keystone and Neutron paths go through keystoneclient and the SDK, and only their first requests were seen.
• Output formatting was not specified command by command, beyond what 01 says; the catalogue and stdout samples in wire-probe-shaped give the columns.
• Python 3.13 on macOS only.

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