yandexcloud 0.337.0__py3-none-any.whl → 0.339.0__py3-none-any.whl

yandex/cloud/spark/v1/maintenance_pb2.pyi

@@ -0,0 +1,123 @@
+"""
+@generated by mypy-protobuf.  Do not edit manually!
+isort:skip_file
+"""
+
+import builtins
+import google.protobuf.descriptor
+import google.protobuf.internal.enum_type_wrapper
+import google.protobuf.message
+import google.protobuf.timestamp_pb2
+import sys
+import typing
+
+if sys.version_info >= (3, 10):
+    import typing as typing_extensions
+else:
+    import typing_extensions
+
+DESCRIPTOR: google.protobuf.descriptor.FileDescriptor
+
+@typing.final
+class MaintenanceWindow(google.protobuf.message.Message):
+    DESCRIPTOR: google.protobuf.descriptor.Descriptor
+
+    ANYTIME_FIELD_NUMBER: builtins.int
+    WEEKLY_MAINTENANCE_WINDOW_FIELD_NUMBER: builtins.int
+    @property
+    def anytime(self) -> global___AnytimeMaintenanceWindow: ...
+    @property
+    def weekly_maintenance_window(self) -> global___WeeklyMaintenanceWindow: ...
+    def __init__(
+        self,
+        *,
+        anytime: global___AnytimeMaintenanceWindow | None = ...,
+        weekly_maintenance_window: global___WeeklyMaintenanceWindow | None = ...,
+    ) -> None: ...
+    def HasField(self, field_name: typing.Literal["anytime", b"anytime", "policy", b"policy", "weekly_maintenance_window", b"weekly_maintenance_window"]) -> builtins.bool: ...
+    def ClearField(self, field_name: typing.Literal["anytime", b"anytime", "policy", b"policy", "weekly_maintenance_window", b"weekly_maintenance_window"]) -> None: ...
+    def WhichOneof(self, oneof_group: typing.Literal["policy", b"policy"]) -> typing.Literal["anytime", "weekly_maintenance_window"] | None: ...
+
+global___MaintenanceWindow = MaintenanceWindow
+
+@typing.final
+class AnytimeMaintenanceWindow(google.protobuf.message.Message):
+    DESCRIPTOR: google.protobuf.descriptor.Descriptor
+
+    def __init__(
+        self,
+    ) -> None: ...
+
+global___AnytimeMaintenanceWindow = AnytimeMaintenanceWindow
+
+@typing.final
+class WeeklyMaintenanceWindow(google.protobuf.message.Message):
+    DESCRIPTOR: google.protobuf.descriptor.Descriptor
+
+    class _WeekDay:
+        ValueType = typing.NewType("ValueType", builtins.int)
+        V: typing_extensions.TypeAlias = ValueType
+
+    class _WeekDayEnumTypeWrapper(google.protobuf.internal.enum_type_wrapper._EnumTypeWrapper[WeeklyMaintenanceWindow._WeekDay.ValueType], builtins.type):
+        DESCRIPTOR: google.protobuf.descriptor.EnumDescriptor
+        WEEK_DAY_UNSPECIFIED: WeeklyMaintenanceWindow._WeekDay.ValueType  # 0
+        MON: WeeklyMaintenanceWindow._WeekDay.ValueType  # 1
+        TUE: WeeklyMaintenanceWindow._WeekDay.ValueType  # 2
+        WED: WeeklyMaintenanceWindow._WeekDay.ValueType  # 3
+        THU: WeeklyMaintenanceWindow._WeekDay.ValueType  # 4
+        FRI: WeeklyMaintenanceWindow._WeekDay.ValueType  # 5
+        SAT: WeeklyMaintenanceWindow._WeekDay.ValueType  # 6
+        SUN: WeeklyMaintenanceWindow._WeekDay.ValueType  # 7
+
+    class WeekDay(_WeekDay, metaclass=_WeekDayEnumTypeWrapper): ...
+    WEEK_DAY_UNSPECIFIED: WeeklyMaintenanceWindow.WeekDay.ValueType  # 0
+    MON: WeeklyMaintenanceWindow.WeekDay.ValueType  # 1
+    TUE: WeeklyMaintenanceWindow.WeekDay.ValueType  # 2
+    WED: WeeklyMaintenanceWindow.WeekDay.ValueType  # 3
+    THU: WeeklyMaintenanceWindow.WeekDay.ValueType  # 4
+    FRI: WeeklyMaintenanceWindow.WeekDay.ValueType  # 5
+    SAT: WeeklyMaintenanceWindow.WeekDay.ValueType  # 6
+    SUN: WeeklyMaintenanceWindow.WeekDay.ValueType  # 7
+
+    DAY_FIELD_NUMBER: builtins.int
+    HOUR_FIELD_NUMBER: builtins.int
+    day: global___WeeklyMaintenanceWindow.WeekDay.ValueType
+    hour: builtins.int
+    """Hour of the day in UTC."""
+    def __init__(
+        self,
+        *,
+        day: global___WeeklyMaintenanceWindow.WeekDay.ValueType = ...,
+        hour: builtins.int = ...,
+    ) -> None: ...
+    def ClearField(self, field_name: typing.Literal["day", b"day", "hour", b"hour"]) -> None: ...
+
+global___WeeklyMaintenanceWindow = WeeklyMaintenanceWindow
+
+@typing.final
+class MaintenanceOperation(google.protobuf.message.Message):
+    DESCRIPTOR: google.protobuf.descriptor.Descriptor
+
+    INFO_FIELD_NUMBER: builtins.int
+    DELAYED_UNTIL_FIELD_NUMBER: builtins.int
+    LATEST_MAINTENANCE_TIME_FIELD_NUMBER: builtins.int
+    NEXT_MAINTENANCE_WINDOW_TIME_FIELD_NUMBER: builtins.int
+    info: builtins.str
+    @property
+    def delayed_until(self) -> google.protobuf.timestamp_pb2.Timestamp: ...
+    @property
+    def latest_maintenance_time(self) -> google.protobuf.timestamp_pb2.Timestamp: ...
+    @property
+    def next_maintenance_window_time(self) -> google.protobuf.timestamp_pb2.Timestamp: ...
+    def __init__(
+        self,
+        *,
+        info: builtins.str = ...,
+        delayed_until: google.protobuf.timestamp_pb2.Timestamp | None = ...,
+        latest_maintenance_time: google.protobuf.timestamp_pb2.Timestamp | None = ...,
+        next_maintenance_window_time: google.protobuf.timestamp_pb2.Timestamp | None = ...,
+    ) -> None: ...
+    def HasField(self, field_name: typing.Literal["delayed_until", b"delayed_until", "latest_maintenance_time", b"latest_maintenance_time", "next_maintenance_window_time", b"next_maintenance_window_time"]) -> builtins.bool: ...
+    def ClearField(self, field_name: typing.Literal["delayed_until", b"delayed_until", "info", b"info", "latest_maintenance_time", b"latest_maintenance_time", "next_maintenance_window_time", b"next_maintenance_window_time"]) -> None: ...
+
+global___MaintenanceOperation = MaintenanceOperation

yandex/cloud/spark/v1/maintenance_pb2_grpc.py

@@ -0,0 +1,24 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+
+GRPC_GENERATED_VERSION = '1.70.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + f' but the generated code in yandex/cloud/spark/v1/maintenance_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )

yandex/cloud/spark/v1/maintenance_pb2_grpc.pyi

@@ -0,0 +1,17 @@
+"""
+@generated by mypy-protobuf.  Do not edit manually!
+isort:skip_file
+"""
+
+import abc
+import collections.abc
+import grpc
+import grpc.aio
+import typing
+
+_T = typing.TypeVar("_T")
+
+class _MaybeAsyncIterator(collections.abc.AsyncIterator[_T], collections.abc.Iterator[_T], metaclass=abc.ABCMeta): ...
+
+class _ServicerContext(grpc.ServicerContext, grpc.aio.ServicerContext):  # type: ignore[misc, type-arg]
+    ...

yandexcloud/__init__.py

@@ -8,7 +8,7 @@ from yandexcloud._backoff import (
     default_backoff,
 )
 from yandexcloud._retry_interceptor import RetryInterceptor
-from yandexcloud._retry_policy import RetryPolicy
+from yandexcloud._retry_policy import RetryPolicy, ThrottlingMode
 from yandexcloud._sdk import SDK
 
-__version__ = "0.337.0"
+__version__ = "0.339.0"

yandexcloud/_operation_waiter.py

@@ -63,44 +63,42 @@ def get_operation_result(
     operation_result: OperationResult[ResponseType, MetaType] = OperationResult(operation)
     created_at = datetime.fromtimestamp(operation.created_at.seconds)
     message = (
-        "Running Yandex.Cloud operation. ID: {id}. "
-        "Description: {description}. Created at: {created_at}. "
-        "Created by: {created_by}."
-    )
-    message = message.format(
-        id=operation.id,
-        description=operation.description,
-        created_at=created_at,
-        created_by=operation.created_by,
+        f"Running Yandex.Cloud operation. ID: {operation.id}. "
+        f"Description: {operation.description}. Created at: {created_at}. "
+        f"Created by: {operation.created_by}."
     )
+
     if meta_type and meta_type is not Empty:
         unpacked_meta = meta_type()
         operation.metadata.Unpack(unpacked_meta)
         operation_result.meta = unpacked_meta
         message += f" Meta: {unpacked_meta}."
+
     logger.info(message)
+
     result = wait_for_operation(sdk, operation.id, timeout=timeout)
     if result is None:
-        return OperationError(message="Unexpected operation result", operation_result=OperationResult(operation))
+        raise OperationError(message="Unexpected operation result", operation_result=operation_result)
+
     if result.error and result.error.code:
         error_message = (
-            "Error Yandex.Cloud operation. ID: {id}. Error code: {code}. Details: {details}. Message: {message}."
-        )
-        error_message = error_message.format(
-            id=result.id,
-            code=result.error.code,
-            details=result.error.details,
-            message=result.error.message,
+            f"Error Yandex.Cloud operation. ID: {result.id}. "
+            f"Error code: {result.error.code}. "
+            f"Details: {result.error.details}. "
+            f"Message: {result.error.message}. "
+            f"Meta: {operation_result.meta}."
         )
         logger.error(error_message)
-        raise OperationError(message=error_message, operation_result=OperationResult(operation))
+        raise OperationError(message=error_message, operation_result=operation_result)
 
     log_message = f"Done Yandex.Cloud operation. ID: {operation.id}."
     if response_type and response_type is not Empty:
         unpacked_response = response_type()
         result.response.Unpack(unpacked_response)
         operation_result.response = unpacked_response
-        log_message += f" Response: {unpacked_response}."
+        log_message += f" Response: {operation_result.response}."
+        log_message += f" Meta: {operation_result.meta}."
+
     logger.info(log_message)
     return operation_result
 

yandexcloud/_retry_policy.py

@@ -1,14 +1,28 @@
 import json
-from typing import Tuple
+from enum import Enum
+from typing import Any, Dict, Tuple
 
 import grpc
 
 
+class ThrottlingMode(str, Enum):
+    PERSISTENT = "persistent"
+    TEMPORARY = "temporary"
+
+
+def get_throttling_policy(throttling_mode: ThrottlingMode) -> Dict[str, Any]:
+    if throttling_mode == ThrottlingMode.PERSISTENT:
+        return {"maxTokens": 100, "tokenRatio": 0.1}
+
+    return {"maxTokens": 6, "tokenRatio": 0.1}
+
+
 class RetryPolicy:
     def __init__(
         self,
         max_attempts: int = 4,
         status_codes: Tuple["grpc.StatusCode"] = (grpc.StatusCode.UNAVAILABLE,),
+        throttling_mode: ThrottlingMode = ThrottlingMode.TEMPORARY,
     ):
         self.__policy = {
             "methodConfig": [
@@ -21,10 +35,10 @@ class RetryPolicy:
                         "backoffMultiplier": 2,
                         "retryableStatusCodes": [status.name for status in status_codes],
                     },
+                    "waitForReady": True,
                 }
             ],
-            "retryThrottling": {"maxTokens": 100, "tokenRatio": 0.1},
-            "waitForReady": True,
+            "retryThrottling": get_throttling_policy(throttling_mode),
         }
 
     def to_json(self) -> str:

yandexcloud/_wrappers/dataproc/__init__.py

@@ -474,6 +474,45 @@ class Dataproc:
             meta_type=cluster_service_pb.DeleteClusterMetadata,
         )
 
+    def stop_cluster(self, cluster_id=None, decommission_timeout=0):
+        """
+        Stop Yandex.Cloud Data Proc cluster.
+        :param cluster_id: ID of the cluster to stop.
+        :type cluster_id: str
+        :param decommission_timeout: Timeout to gracefully decommission nodes during downscaling. In seconds.
+        :type decommission_timeout: int
+        """
+        cluster_id = cluster_id or self.cluster_id
+        if not cluster_id:
+            raise RuntimeError("Cluster id must be specified.")
+
+        request = cluster_service_pb.StopClusterRequest(
+            cluster_id=cluster_id, decommission_timeout=decommission_timeout
+        )
+        return self.sdk.create_operation_and_get_result(
+            request,
+            service=cluster_service_grpc_pb.ClusterServiceStub,
+            method_name="Stop",
+            meta_type=cluster_service_pb.StopClusterMetadata,
+        )
+
+    def start_cluster(self, cluster_id=None):
+        """
+        Start Yandex.Cloud Data Proc cluster.
+        :param cluster_id: ID of the cluster to start.
+        :type cluster_id: str
+        """
+        cluster_id = cluster_id or self.cluster_id
+        if not cluster_id:
+            raise RuntimeError("Cluster id must be specified.")
+        request = cluster_service_pb.StartClusterRequest(cluster_id=cluster_id)
+        return self.sdk.create_operation_and_get_result(
+            request,
+            service=cluster_service_grpc_pb.ClusterServiceStub,
+            method_name="Start",
+            meta_type=cluster_service_pb.StartClusterMetadata,
+        )
+
     def create_hive_job(
         self,
         query=None,

{yandexcloud-0.337.0.dist-info → yandexcloud-0.339.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: yandexcloud
-Version: 0.337.0
+Version: 0.339.0
 Summary: The Yandex Cloud official SDK
 Author-email: Yandex LLC <cloud@support.yandex.ru>
 License: MIT
@@ -185,22 +185,22 @@ set_up_yc_api_endpoint(kz_region_endpoint)
 ```
 
 ### Retries
-If you want to retry SDK requests, build SDK with `retry_policy` field using `RetryPolicy` class:
+SDK provide built-in retry policy, that supports [exponential backoff and jitter](https://aws.amazon.com/ru/blogs/architecture/exponential-backoff-and-jitter/), and also [retry budget](https://github.com/grpc/proposal/blob/master/A6-client-retries.md#throttling-retry-attempts-and-hedged-rpcs). It's necessary to avoid retry amplification.
 
 ```python
 import grpc
 from yandexcloud import SDK, RetryPolicy
 
-sdk = SDK(retry_policy=RetryPolicy(max_attempts=2, status_codes=(grpc.StatusCode.UNAVAILABLE,)))
+sdk = SDK(retry_policy=RetryPolicy())
 ```
 
-It's **strongly recommended** to use default settings of RetryPolicy to avoid retry amplification:
-```python
-import grpc
-from yandexcloud import SDK, RetryPolicy
+SDK provide different modes for retry throttling policy:
+
+* `persistent` is suitable when you use SDK in any long-lived application, when SDK instance will live long enough for manage budget;
+* `temporary` is suitable when you use SDK in any short-lived application, e.g. scripts or CI/CD.
+
+By default, SDK will use temporary mode, but you can change it through `throttling_mode` argument.
 
-sdk = SDK(retry_policy=RetryPolicy())
-```
 
 ## Contributing
 ### Dependencies