From e1d35fca89a4090ad44d6cf53ececdfe82278b4d Mon Sep 17 00:00:00 2001 From: David Davis Date: Thu, 16 Apr 2026 18:35:42 +0000 Subject: [PATCH] Add client bindings generation docs to CLAUDE.md Document how to generate and install Python client bindings using oci-env generate-client, including common gotchas for stale bindings. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CLAUDE.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index ff0bb39087..1618fa13d7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,11 +30,32 @@ oci-env test --help # run the functional/unit tests oci-env pulpcore-manager # run any pulpcore or Django commands ``` +## Generating client bindings + +Functional tests require Python client bindings (generated from the OpenAPI spec). The bindings must be regenerated whenever the API spec changes (e.g. new fields, endpoints, or serializer changes). The `pulp-openapi-generator` repo must be cloned as a sibling directory (`../pulp-openapi-generator`). + +```bash +# Generate and install client bindings for ALL plugins in DEV_SOURCE_PATH +oci-env generate-client -i + +# Generate and install bindings for a specific plugin only +oci-env generate-client -i pulpcore +oci-env generate-client -i pulp_file + +# Generate without installing (e.g. to inspect the generated code) +oci-env generate-client pulp_file + +# Generate Ruby bindings instead of Python +oci-env generate-client -l ruby pulp_file +``` + +**Common gotcha:** If functional tests fail with `AttributeError` or missing client classes, it usually means the bindings are stale. Regenerate and reinstall them with `oci-env generate-client -i`. + ## Running/Writing tests Prefer writing functional tests for new changes/bugfixes and only fallback on unit tests when the change is not easily testable through the API. -pulpcore & pulp-file functional tests require both client bindings to be installed. The bindings must be regenerated for any changes to the API spec. +pulpcore & pulp-file functional tests require both client bindings to be installed. The bindings must be regenerated for any changes to the API spec (see [Generating client bindings](#generating-client-bindings) above). **Always** use the `oci-env` to run the functional and unit tests.