databricks-sdk 0.44.1__py3-none-any.whl → 0.45.0__py3-none-any.whl

databricks/sdk/errors/details.py

@@ -0,0 +1,417 @@
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ErrorInfo:
+    """Describes the cause of the error with structured details."""
+
+    reason: str
+    domain: str
+    metadata: Dict[str, str]
+
+
+@dataclass
+class RequestInfo:
+    """
+    Contains metadata about the request that clients can attach when
+    filing a bug or providing other forms of feedback.
+    """
+
+    request_id: str
+    serving_data: str
+
+
+@dataclass
+class RetryInfo:
+    """
+    Describes when the clients can retry a failed request. Clients could
+    ignore the recommendation here or retry when this information is missing
+    from error responses.
+
+    It's always recommended that clients should use exponential backoff
+    when retrying.
+
+    Clients should wait until `retry_delay` amount of time has passed since
+    receiving the error response before retrying.  If retrying requests also
+    fail, clients should use an exponential backoff scheme to gradually
+    increase the delay between retries based on `retry_delay`, until either
+    a maximum number of retries have been reached or a maximum retry delay
+    cap has been reached.
+    """
+
+    retry_delay_seconds: float
+
+
+@dataclass
+class DebugInfo:
+    """Describes additional debugging info."""
+
+    stack_entries: List[str]
+    detail: str
+
+
+@dataclass
+class QuotaFailureViolation:
+    """Describes a single quota violation."""
+
+    subject: str
+    description: str
+
+
+@dataclass
+class QuotaFailure:
+    """
+    Describes how a quota check failed.
+
+    For example if a daily limit was exceeded for the calling project, a
+    service could respond with a QuotaFailure detail containing the project
+    id and the description of the quota limit that was exceeded.  If the
+    calling project hasn't enabled the service in the developer console,
+    then a service could respond with the project id and set
+    `service_disabled` to true.
+
+    Also see RetryInfo and Help types for other details about handling a
+    quota failure.
+    """
+
+    violations: List[QuotaFailureViolation]
+
+
+@dataclass
+class PreconditionFailureViolation:
+    """Describes a single precondition violation."""
+
+    type: str
+    subject: str
+    description: str
+
+
+@dataclass
+class PreconditionFailure:
+    """Describes what preconditions have failed."""
+
+    violations: List[PreconditionFailureViolation]
+
+
+@dataclass
+class BadRequestFieldViolation:
+    """Describes a single field violation in a bad request."""
+
+    field: str
+    description: str
+
+
+@dataclass
+class BadRequest:
+    """
+    Describes violations in a client request. This error type
+    focuses on the syntactic aspects of the request.
+    """
+
+    field_violations: List[BadRequestFieldViolation]
+
+
+@dataclass
+class ResourceInfo:
+    """Describes the resource that is being accessed."""
+
+    resource_type: str
+    resource_name: str
+    owner: str
+    description: str
+
+
+@dataclass
+class HelpLink:
+    """Describes a single help link."""
+
+    description: str
+    url: str
+
+
+@dataclass
+class Help:
+    """
+    Provides links to documentation or for performing an out of
+    band action.
+
+    For example, if a quota check failed with an error indicating
+    the calling project hasn't enabled the accessed service, this
+    can contain a URL pointing directly to the right place in the
+    developer console to flip the bit.
+    """
+
+    links: List[HelpLink]
+
+
+@dataclass
+class ErrorDetails:
+    """
+    ErrorDetails contains the error details of an API error. It
+    is the union of known error details types and unknown details.
+    """
+
+    error_info: Optional[ErrorInfo] = None
+    request_info: Optional[RequestInfo] = None
+    retry_info: Optional[RetryInfo] = None
+    debug_info: Optional[DebugInfo] = None
+    quota_failure: Optional[QuotaFailure] = None
+    precondition_failure: Optional[PreconditionFailure] = None
+    bad_request: Optional[BadRequest] = None
+    resource_info: Optional[ResourceInfo] = None
+    help: Optional[Help] = None
+    unknown_details: List[Any] = field(default_factory=list)
+
+
+# Supported error details proto types.
+_ERROR_INFO_TYPE = "type.googleapis.com/google.rpc.ErrorInfo"
+_REQUEST_INFO_TYPE = "type.googleapis.com/google.rpc.RequestInfo"
+_RETRY_INFO_TYPE = "type.googleapis.com/google.rpc.RetryInfo"
+_DEBUG_INFO_TYPE = "type.googleapis.com/google.rpc.DebugInfo"
+_QUOTA_FAILURE_TYPE = "type.googleapis.com/google.rpc.QuotaFailure"
+_PRECONDITION_FAILURE_TYPE = "type.googleapis.com/google.rpc.PreconditionFailure"
+_BAD_REQUEST_TYPE = "type.googleapis.com/google.rpc.BadRequest"
+_RESOURCE_INFO_TYPE = "type.googleapis.com/google.rpc.ResourceInfo"
+_HELP_TYPE = "type.googleapis.com/google.rpc.Help"
+
+
+def parse_error_details(details: List[Any]) -> ErrorDetails:
+    ed = ErrorDetails()
+
+    if not details:
+        return ed
+
+    for d in details:
+        pd = _parse_json_error_details(d)
+
+        if isinstance(pd, ErrorInfo):
+            ed.error_info = pd
+        elif isinstance(pd, RequestInfo):
+            ed.request_info = pd
+        elif isinstance(pd, RetryInfo):
+            ed.retry_info = pd
+        elif isinstance(pd, DebugInfo):
+            ed.debug_info = pd
+        elif isinstance(pd, QuotaFailure):
+            ed.quota_failure = pd
+        elif isinstance(pd, PreconditionFailure):
+            ed.precondition_failure = pd
+        elif isinstance(pd, BadRequest):
+            ed.bad_request = pd
+        elif isinstance(pd, ResourceInfo):
+            ed.resource_info = pd
+        elif isinstance(pd, Help):
+            ed.help = pd
+        else:
+            ed.unknown_details.append(pd)
+
+    return ed
+
+
+def _parse_json_error_details(value: Any) -> Any:
+    """
+    Attempts to parse an error details type from the given JSON value. If the
+    value is not a known error details type, it returns the input as is.
+
+    :param value: The JSON value to parse.
+    :return: The parsed error details type or the input value if it is not
+        a known error details type.
+    """
+
+    if not isinstance(value, dict):
+        return value  # not a JSON object
+
+    t = value.get("@type")
+    if not isinstance(t, str):
+        return value  # JSON object with no @type field
+
+    try:
+        if t == _ERROR_INFO_TYPE:
+            return _parse_error_info(value)
+        elif t == _REQUEST_INFO_TYPE:
+            return _parse_req_info(value)
+        elif t == _RETRY_INFO_TYPE:
+            return _parse_retry_info(value)
+        elif t == _DEBUG_INFO_TYPE:
+            return _parse_debug_info(value)
+        elif t == _QUOTA_FAILURE_TYPE:
+            return _parse_quota_failure(value)
+        elif t == _PRECONDITION_FAILURE_TYPE:
+            return _parse_precondition_failure(value)
+        elif t == _BAD_REQUEST_TYPE:
+            return _parse_bad_request(value)
+        elif t == _RESOURCE_INFO_TYPE:
+            return _parse_resource_info(value)
+        elif t == _HELP_TYPE:
+            return _parse_help(value)
+        else:  # unknown type
+            return value
+    except (TypeError, ValueError):
+        return value  # not a valid known type
+    except Exception:
+        return value
+
+
+def _parse_error_info(d: Dict[str, Any]) -> ErrorInfo:
+    return ErrorInfo(
+        domain=_parse_string(d.get("domain", "")),
+        reason=_parse_string(d.get("reason", "")),
+        metadata=_parse_dict(d.get("metadata", {})),
+    )
+
+
+def _parse_req_info(d: Dict[str, Any]) -> RequestInfo:
+    return RequestInfo(
+        request_id=_parse_string(d.get("request_id", "")),
+        serving_data=_parse_string(d.get("serving_data", "")),
+    )
+
+
+def _parse_retry_info(d: Dict[str, Any]) -> RetryInfo:
+    delay = 0.0
+    if "retry_delay" in d:
+        delay = _parse_seconds(d["retry_delay"])
+
+    return RetryInfo(
+        retry_delay_seconds=delay,
+    )
+
+
+def _parse_debug_info(d: Dict[str, Any]) -> DebugInfo:
+    di = DebugInfo(
+        stack_entries=[],
+        detail=_parse_string(d.get("detail", "")),
+    )
+
+    if "stack_entries" not in d:
+        return di
+
+    if not isinstance(d["stack_entries"], list):
+        raise ValueError(f"Expected list, got {d['stack_entries']!r}")
+    for entry in d["stack_entries"]:
+        di.stack_entries.append(_parse_string(entry))
+
+    return di
+
+
+def _parse_quota_failure_violation(d: Dict[str, Any]) -> QuotaFailureViolation:
+    return QuotaFailureViolation(
+        subject=_parse_string(d.get("subject", "")),
+        description=_parse_string(d.get("description", "")),
+    )
+
+
+def _parse_quota_failure(d: Dict[str, Any]) -> QuotaFailure:
+    violations = []
+    if "violations" in d:
+        if not isinstance(d["violations"], list):
+            raise ValueError(f"Expected list, got {d['violations']!r}")
+        for violation in d["violations"]:
+            if not isinstance(violation, dict):
+                raise ValueError(f"Expected dict, got {violation!r}")
+            violations.append(_parse_quota_failure_violation(violation))
+    return QuotaFailure(violations=violations)
+
+
+def _parse_precondition_failure_violation(d: Dict[str, Any]) -> PreconditionFailureViolation:
+    return PreconditionFailureViolation(
+        type=_parse_string(d.get("type", "")),
+        subject=_parse_string(d.get("subject", "")),
+        description=_parse_string(d.get("description", "")),
+    )
+
+
+def _parse_precondition_failure(d: Dict[str, Any]) -> PreconditionFailure:
+    violations = []
+    if "violations" in d:
+        if not isinstance(d["violations"], list):
+            raise ValueError(f"Expected list, got {d['violations']!r}")
+        for v in d["violations"]:
+            if not isinstance(v, dict):
+                raise ValueError(f"Expected dict, got {v!r}")
+            violations.append(_parse_precondition_failure_violation(v))
+    return PreconditionFailure(violations=violations)
+
+
+def _parse_bad_request_field_violation(d: Dict[str, Any]) -> BadRequestFieldViolation:
+    return BadRequestFieldViolation(
+        field=_parse_string(d.get("field", "")),
+        description=_parse_string(d.get("description", "")),
+    )
+
+
+def _parse_bad_request(d: Dict[str, Any]) -> BadRequest:
+    field_violations = []
+    if "field_violations" in d:
+        if not isinstance(d["field_violations"], list):
+            raise ValueError(f"Expected list, got {d['field_violations']!r}")
+        for violation in d["field_violations"]:
+            if not isinstance(violation, dict):
+                raise ValueError(f"Expected dict, got {violation!r}")
+            field_violations.append(_parse_bad_request_field_violation(violation))
+    return BadRequest(field_violations=field_violations)
+
+
+def _parse_resource_info(d: Dict[str, Any]) -> ResourceInfo:
+    return ResourceInfo(
+        resource_type=_parse_string(d.get("resource_type", "")),
+        resource_name=_parse_string(d.get("resource_name", "")),
+        owner=_parse_string(d.get("owner", "")),
+        description=_parse_string(d.get("description", "")),
+    )
+
+
+def _parse_help_link(d: Dict[str, Any]) -> HelpLink:
+    return HelpLink(
+        description=_parse_string(d.get("description", "")),
+        url=_parse_string(d.get("url", "")),
+    )
+
+
+def _parse_help(d: Dict[str, Any]) -> Help:
+    links = []
+    if "links" in d:
+        if not isinstance(d["links"], list):
+            raise ValueError(f"Expected list, got {d['links']!r}")
+        for link in d["links"]:
+            if not isinstance(link, dict):
+                raise ValueError(f"Expected dict, got {link!r}")
+            links.append(_parse_help_link(link))
+    return Help(links=links)
+
+
+def _parse_string(a: Any) -> str:
+    if isinstance(a, str):
+        return a
+    raise ValueError(f"Expected string, got {a!r}")
+
+
+def _parse_dict(a: Any) -> Dict[str, str]:
+    if not isinstance(a, dict):
+        raise ValueError(f"Expected Dict[str, str], got {a!r}")
+    for key, value in a.items():
+        if not isinstance(key, str) or not isinstance(value, str):
+            raise ValueError(f"Expected Dict[str, str], got {a!r}")
+    return a
+
+
+def _parse_seconds(a: Any) -> float:
+    """
+    Parse a duration string into a float representing the number of seconds.
+
+    The duration type is encoded as a string rather than an where the string
+    ends in the suffix "s" (indicating seconds) and is preceded by a decimal
+    number of seconds. For example, "3.000000001s", represents a duration of
+    3 seconds and 1 nanosecond.
+    """
+
+    if not isinstance(a, str):
+        raise ValueError(f"Expected string, got {a!r}")
+
+    match = re.match(r"^(\d+(\.\d+)?)s$", a)
+    if match:
+        return float(match.group(1))
+
+    raise ValueError(f"Expected duration string, got {a!r}")

databricks/sdk/errors/mapper.py

@@ -11,7 +11,7 @@ def _error_mapper(response: requests.Response, raw: dict) -> DatabricksError:
         if override.matches(response, raw):
             return override.custom_error(**raw)
     status_code = response.status_code
-    error_code = raw.get('error_code', None)
+    error_code = raw.get("error_code", None)
     if error_code in platform.ERROR_CODE_MAPPING:
         # more specific error codes override more generic HTTP status codes
         return platform.ERROR_CODE_MAPPING[error_code](**raw)

databricks/sdk/errors/overrides.py

@@ -6,28 +6,31 @@ from .base import _ErrorOverride
 from .platform import ResourceDoesNotExist
 
 _ALL_OVERRIDES = [
-    _ErrorOverride(debug_name="Clusters InvalidParameterValue=>ResourceDoesNotExist",
-                   path_regex=re.compile(r'^/api/2\.\d/clusters/get'),
-                   verb="GET",
-                   status_code_matcher=re.compile(r'^400$'),
-                   error_code_matcher=re.compile(r'INVALID_PARAMETER_VALUE'),
-                   message_matcher=re.compile(r'Cluster .* does not exist'),
-                   custom_error=ResourceDoesNotExist,
-                   ),
-    _ErrorOverride(debug_name="Jobs InvalidParameterValue=>ResourceDoesNotExist",
-                   path_regex=re.compile(r'^/api/2\.\d/jobs/get'),
-                   verb="GET",
-                   status_code_matcher=re.compile(r'^400$'),
-                   error_code_matcher=re.compile(r'INVALID_PARAMETER_VALUE'),
-                   message_matcher=re.compile(r'Job .* does not exist'),
-                   custom_error=ResourceDoesNotExist,
-                   ),
-    _ErrorOverride(debug_name="Job Runs InvalidParameterValue=>ResourceDoesNotExist",
-                   path_regex=re.compile(r'^/api/2\.\d/jobs/runs/get'),
-                   verb="GET",
-                   status_code_matcher=re.compile(r'^400$'),
-                   error_code_matcher=re.compile(r'INVALID_PARAMETER_VALUE'),
-                   message_matcher=re.compile(r'(Run .* does not exist|Run: .* in job: .* doesn\'t exist)'),
-                   custom_error=ResourceDoesNotExist,
-                   ),
+    _ErrorOverride(
+        debug_name="Clusters InvalidParameterValue=>ResourceDoesNotExist",
+        path_regex=re.compile(r"^/api/2\.\d/clusters/get"),
+        verb="GET",
+        status_code_matcher=re.compile(r"^400$"),
+        error_code_matcher=re.compile(r"INVALID_PARAMETER_VALUE"),
+        message_matcher=re.compile(r"Cluster .* does not exist"),
+        custom_error=ResourceDoesNotExist,
+    ),
+    _ErrorOverride(
+        debug_name="Jobs InvalidParameterValue=>ResourceDoesNotExist",
+        path_regex=re.compile(r"^/api/2\.\d/jobs/get"),
+        verb="GET",
+        status_code_matcher=re.compile(r"^400$"),
+        error_code_matcher=re.compile(r"INVALID_PARAMETER_VALUE"),
+        message_matcher=re.compile(r"Job .* does not exist"),
+        custom_error=ResourceDoesNotExist,
+    ),
+    _ErrorOverride(
+        debug_name="Job Runs InvalidParameterValue=>ResourceDoesNotExist",
+        path_regex=re.compile(r"^/api/2\.\d/jobs/runs/get"),
+        verb="GET",
+        status_code_matcher=re.compile(r"^400$"),
+        error_code_matcher=re.compile(r"INVALID_PARAMETER_VALUE"),
+        message_matcher=re.compile(r"(Run .* does not exist|Run: .* in job: .* doesn\'t exist)"),
+        custom_error=ResourceDoesNotExist,
+    ),
 ]

databricks/sdk/errors/parser.py

@@ -26,7 +26,9 @@ _error_deserializers = [
 # A list of _ErrorCustomizers that are applied to the error arguments after they are parsed. Customizers can modify the
 # error arguments in any way, including adding or removing fields. Customizers are applied in order, so later
 # customizers can override the changes made by earlier customizers.
-_error_customizers = [_RetryAfterCustomizer(), ]
+_error_customizers = [
+    _RetryAfterCustomizer(),
+]
 
 
 def _unknown_error(response: requests.Response) -> str:
@@ -36,9 +38,10 @@ def _unknown_error(response: requests.Response) -> str:
     """
     request_log = RoundTrip(response, debug_headers=True, debug_truncate_bytes=10 * 1024).generate()
     return (
-        'This is likely a bug in the Databricks SDK for Python or the underlying '
-        'API. Please report this issue with the following debugging information to the SDK issue tracker at '
-        f'https://github.com/databricks/databricks-sdk-go/issues. Request log:```{request_log}```')
+        "This is likely a bug in the Databricks SDK for Python or the underlying "
+        "API. Please report this issue with the following debugging information to the SDK issue tracker at "
+        f"https://github.com/databricks/databricks-sdk-go/issues. Request log:```{request_log}```"
+    )
 
 
 class _Parser:
@@ -49,13 +52,15 @@ class _Parser:
     issue tracker.
     """
 
-    def __init__(self,
-                 extra_error_parsers: List[_ErrorDeserializer] = [],
-                 extra_error_customizers: List[_ErrorCustomizer] = []):
-        self._error_parsers = _error_deserializers + (extra_error_parsers
-                                                      if extra_error_parsers is not None else [])
-        self._error_customizers = _error_customizers + (extra_error_customizers
-                                                        if extra_error_customizers is not None else [])
+    def __init__(
+        self,
+        extra_error_parsers: List[_ErrorDeserializer] = [],
+        extra_error_customizers: List[_ErrorCustomizer] = [],
+    ):
+        self._error_parsers = _error_deserializers + (extra_error_parsers if extra_error_parsers is not None else [])
+        self._error_customizers = _error_customizers + (
+            extra_error_customizers if extra_error_customizers is not None else []
+        )
 
     def get_api_error(self, response: requests.Response) -> Optional[DatabricksError]:
         """
@@ -73,11 +78,18 @@ class _Parser:
                             customizer.customize_error(response, error_args)
                         return _error_mapper(response, error_args)
                 except Exception as e:
-                    logging.debug(f'Error parsing response with {parser}, continuing', exc_info=e)
-            return _error_mapper(response,
-                                 {'message': 'unable to parse response. ' + _unknown_error(response)})
+                    logging.debug(
+                        f"Error parsing response with {parser}, continuing",
+                        exc_info=e,
+                    )
+            return _error_mapper(
+                response,
+                {"message": "unable to parse response. " + _unknown_error(response)},
+            )
 
         # Private link failures happen via a redirect to the login page. From a requests-perspective, the request
         # is successful, but the response is not what we expect. We need to handle this case separately.
         if _is_private_link_redirect(response):
             return _get_private_link_validation_error(response.url)
+
+        return None

databricks/sdk/errors/platform.py

@@ -103,14 +103,14 @@ STATUS_CODE_MAPPING = {
 }
 
 ERROR_CODE_MAPPING = {
-    'INVALID_STATE': InvalidState,
-    'INVALID_PARAMETER_VALUE': InvalidParameterValue,
-    'RESOURCE_DOES_NOT_EXIST': ResourceDoesNotExist,
-    'ABORTED': Aborted,
-    'ALREADY_EXISTS': AlreadyExists,
-    'RESOURCE_ALREADY_EXISTS': ResourceAlreadyExists,
-    'RESOURCE_EXHAUSTED': ResourceExhausted,
-    'REQUEST_LIMIT_EXCEEDED': RequestLimitExceeded,
-    'UNKNOWN': Unknown,
-    'DATA_LOSS': DataLoss,
+    "INVALID_STATE": InvalidState,
+    "INVALID_PARAMETER_VALUE": InvalidParameterValue,
+    "RESOURCE_DOES_NOT_EXIST": ResourceDoesNotExist,
+    "ABORTED": Aborted,
+    "ALREADY_EXISTS": AlreadyExists,
+    "RESOURCE_ALREADY_EXISTS": ResourceAlreadyExists,
+    "RESOURCE_EXHAUSTED": ResourceExhausted,
+    "REQUEST_LIMIT_EXCEEDED": RequestLimitExceeded,
+    "UNKNOWN": Unknown,
+    "DATA_LOSS": DataLoss,
 }

databricks/sdk/errors/private_link.py

@@ -15,29 +15,28 @@ class _PrivateLinkInfo:
 
     def error_message(self):
         return (
-            f'The requested workspace has {self.serviceName} enabled and is not accessible from the current network. '
-            f'Ensure that {self.serviceName} is properly configured and that your device has access to the '
-            f'{self.endpointName}. For more information, see {self.referencePage}.')
+            f"The requested workspace has {self.serviceName} enabled and is not accessible from the current network. "
+            f"Ensure that {self.serviceName} is properly configured and that your device has access to the "
+            f"{self.endpointName}. For more information, see {self.referencePage}."
+        )
 
 
 _private_link_info_map = {
-    Cloud.AWS:
-    _PrivateLinkInfo(serviceName='AWS PrivateLink',
-                     endpointName='AWS VPC endpoint',
-                     referencePage='https://docs.databricks.com/en/security/network/classic/privatelink.html',
-                     ),
-    Cloud.AZURE:
-    _PrivateLinkInfo(
-        serviceName='Azure Private Link',
-        endpointName='Azure Private Link endpoint',
-        referencePage='https://learn.microsoft.com/en-us/azure/databricks/security/network/classic/private-link-standard#authentication-troubleshooting',
+    Cloud.AWS: _PrivateLinkInfo(
+        serviceName="AWS PrivateLink",
+        endpointName="AWS VPC endpoint",
+        referencePage="https://docs.databricks.com/en/security/network/classic/privatelink.html",
+    ),
+    Cloud.AZURE: _PrivateLinkInfo(
+        serviceName="Azure Private Link",
+        endpointName="Azure Private Link endpoint",
+        referencePage="https://learn.microsoft.com/en-us/azure/databricks/security/network/classic/private-link-standard#authentication-troubleshooting",
+    ),
+    Cloud.GCP: _PrivateLinkInfo(
+        serviceName="Private Service Connect",
+        endpointName="GCP VPC endpoint",
+        referencePage="https://docs.gcp.databricks.com/en/security/network/classic/private-service-connect.html",
     ),
-    Cloud.GCP:
-    _PrivateLinkInfo(
-        serviceName='Private Service Connect',
-        endpointName='GCP VPC endpoint',
-        referencePage='https://docs.gcp.databricks.com/en/security/network/classic/private-service-connect.html',
-    )
 }
 
 
@@ -48,13 +47,14 @@ class PrivateLinkValidationError(PermissionDenied):
 
 def _is_private_link_redirect(resp: requests.Response) -> bool:
     parsed = parse.urlparse(resp.url)
-    return parsed.path == '/login.html' and 'error=private-link-validation-error' in parsed.query
+    return parsed.path == "/login.html" and "error=private-link-validation-error" in parsed.query
 
 
 def _get_private_link_validation_error(url: str) -> PrivateLinkValidationError:
     parsed = parse.urlparse(url)
     env = get_environment_for_hostname(parsed.hostname)
-    return PrivateLinkValidationError(message=_private_link_info_map[env.cloud].error_message(),
-                                      error_code='PRIVATE_LINK_VALIDATION_ERROR',
-                                      status_code=403,
-                                      )
+    return PrivateLinkValidationError(
+        message=_private_link_info_map[env.cloud].error_message(),
+        error_code="PRIVATE_LINK_VALIDATION_ERROR",
+        status_code=403,
+    )