Yandex Cloud Python SDK

yandexcloud is the official Python SDK for Yandex Cloud, the Russian/CIS public cloud platform. It wraps auto-generated gRPC/protobuf service stubs for roughly fifty Yandex Cloud services — compute, managed databases (ClickHouse, PostgreSQL, MySQL, MongoDB, Redis, Kafka, Greenplum, OpenSearch, SQL Server), object storage, serverless functions and containers, data processing (Dataproc, Spark), Kubernetes, load balancing, and more — behind a single SDK entry point.

The SDK handles the parts every service client needs but nobody wants to rewrite: authentication (VM/Function metadata service, service-account JSON keys turned into signed IAM JWTs, or raw IAM tokens), per-service endpoint routing and channel caching, gRPC-level retry policies with throttling-aware backoff, and a long-running-operation waiter that polls Yandex Cloud’s async Operation objects and unpacks their typed response/metadata. Application code mostly still talks to the raw generated protobuf stubs directly, with the SDK providing the connection, auth, and operation-polling glue around them.

What You Get

• A single SDK class that authenticates via metadata service, service-account key, or IAM token and exposes .client(stub_ctor) to construct any of ~50 supported service clients
• Automatic endpoint resolution and channel caching per service, with per-client or per-SDK endpoint overrides for custom or regional (e.g. api.yandexcloud.kz) deployments
• Configurable gRPC retry policy with exponential backoff and token-bucket retry throttling to avoid retry-storm amplification against the API
• wait_operation_and_get_result / create_operation_and_get_result helpers that poll Yandex Cloud’s async long-running operations and unpack the typed response and metadata for you
• Higher-level Wrappers helpers layered over selected services (e.g. Dataproc cluster creation) for common multi-call workflows

Common Use Cases

• Provisioning and tearing down Compute Cloud VMs from CI pipelines or infrastructure scripts
• Automating managed database cluster lifecycle (ClickHouse, PostgreSQL, MongoDB, Redis, Kafka, etc.) from application or ops tooling
• Invoking Yandex Cloud Serverless Functions/Containers and reading their async operation results programmatically
• Reporting SaaS usage to Yandex Cloud Marketplace’s metering API
• Running and monitoring Dataproc/Spark data-processing jobs from Python orchestration code

Under The Hood

Architecture The SDK class in yandexcloud/_sdk.py is the sole entry point: it owns a _channels.Channels object that lazily builds and caches one gRPC channel per service, resolved through a _service_for_ctor lookup that maps a generated stub’s module name (yandex.cloud.*) to its endpoint alias via a large _supported_modules table. Long-running operations are handled by _operation_waiter.OperationWaiter, an iterator that polls OperationService.Get until the operation completes, with get_operation_result unpacking the typed response/metadata and raising a structured OperationError on failure. Authentication is decoupled into _auth_fabric/_auth_plugin (metadata service, service-account key, or raw IAM token) and plugged in as gRPC call credentials, while retry behavior is configured separately through _retry_policy.RetryPolicy (attached as gRPC service config with token-bucket throttling) and a distinct _retry_interceptor.RetryInterceptor used specifically by the operation waiter. A Wrappers layer adds a handful of higher-level, multi-call helpers on top of the raw generated stubs. The hand-written yandexcloud/ package is a thin, cleanly separated construction/auth/retry layer sitting in front of the much larger auto-generated yandex/ protobuf/gRPC stub tree (mirrored from the cloudapi/ proto definitions checked into the repo) — changing the core SDK class would ripple through every service wrapper and example, but the auth, retry, and channel pieces can each be swapped independently.

Tech Stack Built for Python 3.9–3.14 on grpcio and protobuf/googleapis-common-protos for RPC and message handling, cryptography and pyjwt for signing IAM JWTs from service-account keys, requests for metadata-service HTTP calls, and grpcio-tools for proto compilation; six remains as a legacy compatibility shim. Packaging uses setuptools via pyproject.toml with dependencies managed by uv. Tooling is comprehensive: black/isort for formatting, mypy for type checking, flake8/pylint for style, pytest plus tox for cross-version testing, and five separate GitHub Actions workflows (tests, checks, pre-commit, proto generation, and an automated python-semantic-release publish to PyPI on every push to master).

Code Quality Twelve test modules cover the hand-written core specifically — retry policy, retry interceptor, backoff functions, operation waiter, channel caching/endpoint overrides, and both service-account and metadata-based auth — using lightweight mock gRPC and metadata servers (grpc_server_mock.py, metadata_server_mock.py) rather than hitting real infrastructure. Type hints are used consistently through the core modules and checked with mypy; errors are explicit and typed (OperationError carries a structured message and operation result rather than a bare exception), and naming conventions clearly distinguish internal modules (_-prefixed) from the public surface. The much larger yandex/ generated-stub tree is, by nature, untested directly — test coverage is concentrated on the SDK’s own logic rather than the generated code it wraps.

API Design The public surface is deliberately minimal: one SDK class configured with an auth method, and a generic .client(stub_ctor) that hands back a raw generated gRPC stub for any of the ~50 supported services. This keeps auth and channel setup boilerplate low, but there’s no resource-oriented convenience layer — callers still import the generated *_service_pb2_grpc stub and build a *_pb2 request message themselves for every call (e.g. no sdk.compute.list_instances()). wait_operation_and_get_result/create_operation_and_get_result are the main DX conveniences on top of that raw layer, turning Yandex Cloud’s async operations into a single synchronous call with unpacked typed results. Naming is consistent (endpoint aliases mirror proto package names 1:1), and with no separate documentation site, the 11 example scripts under examples/ (compute, Dataproc, Spark, managed databases, Marketplace metering) are the primary onboarding path for new users.