python-neutronclient — Rewrite pack

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

Branch stable/2026.2 @ 596a9d99b188 (14.0.0 + 2 maintenance commits) — repository https://opendev.org/openstack/python-neutronclient — analysed on 2026-11-01

This pack states what a Neutron replacement must do so that these keep working unmodified:

• the 34 commands of the plugin;
• the projects that import neutronclient.v2_0.client.Client.

No replay against a real Neutron was possible. The client ran against a local stub. See § 6 for what was proved and what was not.

1. Contents of _rewrite/

Versions: python-neutronclient 14.0.1.dev2 (the venv's copy is identical to the clone), python-openstackclient 10.3.1, osc-lib 4.7.0, cliff 4.16.0, openstacksdk 4.20.0, keystoneauth1 5.17.0, python-keystoneclient 6.0.0, Python 3.13.

To regenerate, with HOME set to an empty directory and no OS_* variable:

python -I -B _rewrite/extract_plugin_stable-2026.2.py <repo> python-neutronclient neutronclient _rewrite
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-404> --mode 404
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-200> --mode 200
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-rich> --mode rich
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-all> --mode rich --all-options
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-1>/c.json <repo>/neutronclient/tests/unit <repo>
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-2>/c.json <repo>/neutronclient/tests/unit <repo>
python -I -B _rewrite/sweep_client_stable-2026.2.py <repo> <dir-of-clones> _rewrite/python-api_stable-2026.2.json
python -I -B _rewrite/repro_defects_stable-2026.2.py _rewrite <repro.json>
python -I -B _rewrite/build_contract_stable-2026.2.py . <gen-dir> <dir-404>/wire-probe_stable-2026.2.json <dir-200>/wire-probe_stable-2026.2.json <dir-rich>/wire-probe_stable-2026.2.json <dir-all>/wire-probe_stable-2026.2.json <run-1>/c.json <run-2>/c.json <repro.json>

2. What a Neutron service must do

Which requests a command sends

Read observed_requests in the contract first, then static_requests. The {} mode is excluded from observed_requests: there the SDK uses the name as ID, which gives routes such as DELETE /sfc/port_chains/x that a real service would not see.

3. Coverage of OpenKeel

Read in openkeel-neutron:internal/api/api.go:72-77, not run:

• log/logs and log/loggable_resources are stubs: list empty, other calls 501. So network log list would print an empty table, and network log create would fail.
• No SFC route was found by search, and neither was onboard_network_subnets, so the 27 sfc commands and network onboard subnets would get what an unknown route answers [inferred].
• The OSC spec's lab run gave 404 for extension commands (OSC 07 § 3). This plugin was not run on the lab.

Which matters for OpenKeel: the Python class matters more than these 34 commands, because Nova and Heat depend on it unless replaced too. Requirements 4, 5, 8 and 10 to 12 carry the weight.

4. Consumers of the library

Name search in non-test Python code, at these commits. A method is counted when a call with its name exists, so false positives are possible [inferred], and no consumer was run.

Not consumers at these commits: python-openstackclient (in doc/requirements.txt only, openstackclient:doc/requirements.txt:22, plus IGNORED_MODULES), and Horizon and Octavia, which only mention it in comments (horizon:openstack_dashboard/api/neutron.py:1032, octavia:octavia/common/keystone.py:63). openstacksdk keeps a comment about the hard-coded /v2.0 (openstacksdk:openstack/config/cloud_region.py:1210). In Neutron it is a test dependency only (neutron:test-requirements.txt:11). requirements:upper-constraints.txt:370 pins 14.0.0.

Exceptions caught by Nova, by count: NeutronClientException 18, PortNotFoundClient 4, NetworkNotFoundClient 4, Unauthorized 3, Conflict 3 and others. These names and their inheritance are a Python API that a drop-in replacement of this package must keep.

The Python surface, by path family

Counts come from the surface. "Matched" is a text search in neutron-lib definitions and neutron extensions, so it is a hint: a path can match and not be served.

5. For a rewrite of the commands

Recommendation: keep the plugin as it is, and fix the service side first. The surface is small, but it runs inside OSC, and the class's users are Python services that OpenKeel may replace on its own schedule.

6. Conformance: what was proved

Replay against a real service was not done, and the unit vectors were not replayed against a rewrite, since none exists. The usual "replay is mandatory" bar is not met for service behaviour. The mocks hide real defects: items 1 to 7 of 02 § 4 all pass the unit tests.

Unit tests exercise no 3-node cycle and no empty event: neutronclient/tests/unit/osc/v2/sfc/test_service_graph.py:1 has no test named for a cycle, and the fake log event is always set (neutronclient/tests/unit/osc/v2/logging/fakes.py:77).

To close the gap: run probe_plugin_stable-2026.2.py against a devstack with networking-sfc and logging enabled, and compare it with wire-probe-rich_stable-2026.2.json.

7. Gaps found while building the pack

• The extractor gives no REST route for neutronclient.* calls, because it resolves only SDK methods; the sweep fills that in the contract's static_requests. find_resource depends on its argument, so only the observed routes show it.
• 64 of the 154 tests record no check_parser call, and so give no vector.
• --project-domain and --l7-parameters were left out of the all-options run; --l7-parameters has its own run, and --project-domain was not run.
• The stub never served a real tap_enabled default, chain_id or group_id.

8. Non-functional requirements

• Cost per command: authentication once per process; an SFC update costs up to 7 GET before the PUT [observed pc-set-append].
• Client startup: every Client scans the neutronclient.extension entry points (neutronclient/v2_0/client.py:2544, neutronclient/common/extension.py:22).
• No timeout is set by the plugin, so a stuck service can block a command [inferred].

9. Checklist for an OpenKeel Neutron

• [ ] The catalog URL of type network has no version suffix.
• [ ] Errors hold NeutronError.type, message and detail; type keeps the original names.
• [ ] Lists always hold the collection key; single objects are wrapped.
• [ ] ?id= and ?name= filter exactly; GET /x/{name} gives 404.
• [ ] Each operation of api-surface_stable-2026.2.md part 1 is implemented, or its absence is documented.
• [ ] Each method that Nova, Heat, Manila and Zun call is served, checked against part 2.
• [ ] /quotas/tenant and /quotas/{id}/details.json respond, if the library stays in use.
• [ ] The cycle check of service graphs is done on the server, if SFC is implemented.
• [ ] The probe, pointed at the lab, gives the same routes, and exit 0 with real resources.

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