Librarian is a tool for managing Google Cloud client libraries across multiple languages. It handles code generation from API definitions, version management, and publishing to package registries.
$ go install github.com/julieqiu/librarian/cmd/librarian@latestLet's build Python client libraries for Google Cloud APIs.
$ mkdir my-python-libs && cd my-python-libs
$ librarian init python
Created librarian.yamlThis creates a minimal configuration:
version: v1
language: python
sources:
googleapis:
url: https://github.com/googleapis/googleapis/archive/main.tar.gz
sha256: ...
defaults:
output: packages/
one_library_per: api
transport: grpc+rest
generate: all
release:
tag_format: '{name}/v{version}'
libraries: []The generate: all setting auto-discovers and generates all APIs:
$ librarian generate --all
Discovering APIs from googleapis...
Found 237 APIs, generating 182 libraries...
✓ packages/google-cloud-secretmanager/
✓ packages/google-cloud-vision/
✓ packages/google-cloud-translate/
... 179 more ...
Done.$ cd packages/google-cloud-vision/
$ vim google/cloud/vision_v1/helpers.py
# Add custom helper functions$ vim librarian.yamllibraries:
- name: google-cloud-vision
keep:
- google/cloud/vision_v1/helpers.py
- tests/unit/test_helpers.py$ librarian generate --all
Regenerating packages/google-cloud-vision...
Preserving: helpers.py, test_helpers.py
✓ GeneratedYour handwritten code is preserved!
Generated - Created from googleapis APIs:
# With generate: all, these are auto-discovered
# Only list them if you need to add settingsHybrid - Generated + handwritten code:
- name: google-cloud-vision
keep:
- google/cloud/vision_v1/helpers.pyHandwritten - Fully custom (no generation):
- name: pubsub
path: pubsub/
- name: auth
path: auth/Generate all mode - Auto-discover and generate everything:
defaults:
generate: all
libraries:
# Only list libraries that need settings
- name: google-cloud-vision
keep: [...]Explicit mode - Generate only listed:
defaults:
generate: explicit
libraries:
- name: google-cloud-secretmanager
api: google/cloud/secretmanager/v1
- name: google-cloud-vision
api: google/cloud/vision/v1
- name: google-cloud-translate
api: google/cloud/translate/v3API-level (one_library_per: api) - Python/Go default:
- All versions → one library
google/cloud/vision/v1+google/cloud/vision/v1beta→packages/google-cloud-vision/
Channel-level (one_library_per: channel) - Rust/Dart default:
- Each channel → separate library
google/cloud/vision/v1→src/generated/google-cloud-vision-v1/google/cloud/vision/v1beta→src/generated/google-cloud-vision-v1beta/
version: v1
language: go
defaults:
output: ./
one_library_per: api
generate: all
libraries:
# Exception: handwritten IAM client
- name: batch
keep:
- ^batch/apiv1/iam_policy_client\.go$
# Handwritten libraries
- name: pubsub
path: pubsub/
- name: storage
path: storage/See doc/config.md for complete configuration reference.
output - Where generated code goes:
defaults:
output: packages/ # Python: packages/google-cloud-*/
output: ./ # Go: */
output: src/generated/ # Rust: src/generated/google-cloud-*-v*/one_library_per - Bundling strategy:
one_library_per: api # Bundle all versions (Python/Go)
one_library_per: channel # Separate per version (Rust/Dart)generate - Generation mode:
defaults:
generate: all # Auto-discover all APIs
generate: explicit # Only generate listed librarieslibraries - What to configure:
# With generate: all, only list libraries that need settings
libraries:
- name: google-cloud-vision
keep:
- google/cloud/vision_v1/helpers.py
- tests/unit/test_*.py
# With generate: explicit, list all libraries
libraries:
- name: google-cloud-secretmanager
api: google/cloud/secretmanager/v1# Initialize repository
$ librarian init <language>
# Generate libraries
$ librarian generate --all
$ librarian generate packages/google-cloud-vision
# Release
$ librarian release packages/google-cloud-visionversion: v1
language: python
sources:
googleapis:
url: https://github.com/googleapis/googleapis/archive/abc123.tar.gz
sha256: 81e6057...
defaults:
output: packages/
one_library_per: api
transport: grpc+rest
rest_numeric_enums: true
generate: all
release:
tag_format: '{name}/v{version}'
name_overrides:
- api: google/cloud/bigquery/storage/v1
name: google-cloud-bigquery-storage
libraries:
# Hybrid libraries (generated + handwritten)
- name: google-cloud-vision
keep:
- google/cloud/vision_v1/helpers.py
- tests/unit/test_helpers.py
- name: google-cloud-bigquery-storage
keep:
- google/cloud/bigquery_storage_v1/client.py
- google/cloud/bigquery_storage_v1/reader.py
# Handwritten libraries
- name: pubsub
path: pubsub/
- name: auth
path: auth/
- name: datastore
path: datastore/Result: 200+ libraries generated with only 6 explicit configurations.
Librarian follows these principles:
- Minimal configuration - Only configure what's different
- Clear naming - Field names describe what they contain
- Explicit fields - Use
name:andapi:fields, not YAML keys - Two modes - Auto-discover everything or list explicitly
- Name overrides - Separate concerns (naming vs. configuration)
- doc/config.md - Complete configuration reference
- doc/alternatives.md - Design decisions and alternatives
Librarian is actively developed. Feedback and contributions welcome!