googleapis / googleapis/librarian

librarian(python): support 'librarian add' for existing libraries with custom GAPIC options (opt_args_by_api)

Closed
#7,600 0 comments 0 reactions 0 assignees View on GitHub
priority: p2 type: bug
Dominant language
Go
Stars
45
Forks
61
Avg merge
19h 11m
Merged PRs (30d)
181

Description

When adding a new API version (e.g., `google/cloud/networkservices/v1beta1`) to an existing Python client library that defines custom GAPIC options in `librarian.yaml` (e.g., `google-cloud-network-services`), `librarian add` fails immediately with an error and does not update `librarian.yaml`.
**Command & Error Output**
```text
$ librarian add google/cloud/networkservices/v1beta1
librarian: new APIs cannot be automatically added to a library with custom GAPIC options
exit status 1
```

When onboarding google/cloud/networkservices/v1beta1:

- `FindExistingLibraryForNewAPI` correctly matches google-cloud-network-services because they share the same versionless path (google/cloud/networkservices/).
- `ValidateNewAPIs` rejects the addition because `len(lib.Python.OptArgsByAPI) != 0`.
- As a result, automated onboarding workflows and scripts fail to add the API path, blocking subsequent librarian generate and librarian tidy runs unless librarian.yaml is manually modified beforehand.

I think I lack the context on this:
What is the reason we choose to return this error? Does it make sense to copy the existing setting for the new API path? Do we have any concern on blindly copying these settings?

### Proposed Solutions / Suggestions

Option 1 (Automatic Inheritance - Recommended):

When adding a new API version to an existing library that already has opt_args_by_api configured for sister API versions in the same service (e.g., google/cloud/networkservices/v1), automatically propagate matching sister options (like python-gapic-name) to the newly added API path in opt_args_by_api.
Option 2 (Permissive Addition with Warning):

Allow librarian add to append the new API path to apis:, emit a warning indicating that custom GAPIC options exist for sister APIs, and let subsequent generation/tidy handle or flag any discrepancies.

Contributor guide

Open the contributing guide

Research direction

Start with FindExistingLibraryForNewAPI and ValidateNewAPIs, then inspect how librarian.yaml represents Python opt_args_by_api. Reproduce librarian add google/cloud/networkservices/v1beta1 against a library with existing custom GAPIC options. Done means the new API is handled consistently without the current failure, with validation or tests covering the chosen inheritance or warning behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.