feat: support visibility labels in discovery.build() and requests

[Capstan]

PR: feat: support visibility labels in discovery.build() and requests

Note

Status: Unit tests passing. Live integration testing completed and verified against a private local mock gateway.

Description

This PR adds support for passing a list of visibility labels (e.g., PREVIEW, GOOGLE_INTERNAL) when building client API resources using discovery.build(), aligning the Python client with visibility configurations defined in google/api/visibility.proto (AIP-185).

How It Works

1. Discovery Phase: Added a new labels parameter (a list of strings) to discovery.build() and build_from_document(). If provided, these labels are dynamically expanded as query parameters in the discovery document URL (using RFC 6570 list expansion, e.g. ?labels=PREVIEW&labels=GOOGLE_INTERNAL).
2. Automatic Cache Fallback: When labels are provided, static_discovery defaults to False (unless explicitly requested otherwise) to ensure the client fetches the live discovery document containing the restricted private/preview definitions instead of relying on stale static files.
3. API Request Phase: The labels list is stored on the client Resource instance (self._labels). On subsequent API requests dynamically generated by the resource, the X-Goog-Visibilities header is automatically injected containing the comma-separated list of labels (e.g., X-Goog-Visibilities: PREVIEW,GOOGLE_INTERNAL).

Important

Backend Limitation: While the Python client supports passing and serializing multiple labels (expanding to multiple query parameters in discovery and a comma-separated list in headers), Google's API servers may not currently support evaluating multiple visibility labels simultaneously on a single request.

Code Changes

• googleapiclient/discovery.py:
  • Modified DISCOVERY_URI and V2_DISCOVERY_URI templates to support query parameter list expansions: {?labels*} and {&labels*}.
  • Added labels parameter to build() and build_from_document().
  • Stored labels on the Resource instance.
  • Injected the X-Goog-Visibilities header in createMethod().
• tests/test_discovery.py:
  • Added test_discovery_with_labels unit test to verify both the dynamic discovery URL query string parameters and the automatic injection of X-Goog-Visibilities headers on subsequent API requests.
  • Added test_discovery_with_labels_and_cache_miss and test_discovery_with_labels_and_cache_hit unit tests to validate that discovery caching behaves correctly and uses the expanded discovery URL (including the labels query parameters) as the cache key.
  • Added test_discovery_with_labels_v2_fallback unit test to validate V2 dynamic discovery URL expansion and fallback.
  • Updated test_pickle object keys to account for the new _labels instance variable.

Verification

Ran the unit tests locally under pytest:

pytest tests/test_discovery.py::Discovery -k "test_discovery_with_labels"

Result: 7 passed, 173 deselected in 0.36s (Passed successfully).

Related Issues

• Fixes Support visibility labels in discovery requests #935

[gemini-code-assist]

Code Review

This pull request introduces support for visibility labels in the Google API Discovery service, allowing users to filter discovery documents and restrict request visibility. It updates discovery URI templates, adds a labels parameter to build() and build_from_document(), and injects the X-Goog-Visibilities header into API requests. The review feedback highlights a potential runtime TypeError if an iterable of non-string elements is passed to labels, suggesting stricter validation to ensure all elements are strings, along with an additional test case to verify this behavior.

[Capstan]

In this PR, static discovery is configured to default to False when labels are provided, because the static document loader does not yet support filtering by labels.

However, I have implemented a follow-up feature that extends static discovery to support loading pre-packaged labeled discovery documents (using a dash - separator for multiple labels to avoid underscore collisions, e.g., zoo.v1.GOOGLE_INTERNAL-PREVIEW.json).

I can either:

1. Include this feature in this PR (it is ready and tested in the static-discovery-labels branch).
2. Handle it as a fast follow-up PR (I can open a Feature Request issue for it).

Please let me know your preference!

[Capstan]

If you are google-internal, I have a standalone zoo repro case that models all the visibility behaviors for discovery and API use you can run locally; LMK if you'd like a pointer. I did some additional integration testing (beyond the unit testing) against this server.