databricks-sdk 0.29.0__py3-none-any.whl → 0.30.0__py3-none-any.whl

databricks/sdk/useragent.py

@@ -0,0 +1,144 @@
+import copy
+import logging
+import os
+import platform
+import re
+from typing import List, Optional, Tuple
+
+from .version import __version__
+
+# Constants
+RUNTIME_KEY = 'runtime'
+CICD_KEY = 'cicd'
+AUTH_KEY = 'auth'
+
+_product_name = "unknown"
+_product_version = "0.0.0"
+
+logger = logging.getLogger("databricks.sdk.useragent")
+
+_extra = []
+
+# Precompiled regex patterns
+alphanum_pattern = re.compile(r'^[a-zA-Z0-9_.+-]+$')
+semver_pattern = re.compile(r'^v?(\d+\.)?(\d+\.)?(\*|\d+)$')
+
+
+def _match_alphanum(value):
+    if not alphanum_pattern.match(value):
+        raise ValueError(f"Invalid alphanumeric value: {value}")
+
+
+def _match_semver(value):
+    if not semver_pattern.match(value):
+        raise ValueError(f"Invalid semantic version: {value}")
+
+
+def _match_alphanum_or_semver(value):
+    if not alphanum_pattern.match(value) and not semver_pattern.match(value):
+        raise ValueError(f"Invalid value: {value}")
+
+
+def product() -> Tuple[str, str]:
+    """Return the global product name and version that will be submitted to Databricks on every request."""
+    return _product_name, _product_version
+
+
+def with_product(name: str, version: str):
+    """Change the product name and version that will be submitted to Databricks on every request."""
+    global _product_name, _product_version
+    _match_alphanum(name)
+    _match_semver(version)
+    logger.debug(f'Changing product from {_product_name}/{_product_version} to {name}/{version}')
+    _product_name = name
+    _product_version = version
+
+
+def _reset_product():
+    """[Internal API] Reset product name and version to the default values.
+
+    Used for testing purposes only."""
+    global _product_name, _product_version
+    _product_name = "unknown"
+    _product_version = "0.0.0"
+
+
+def with_extra(key: str, value: str):
+    """Add extra metadata to all requests submitted to Databricks.
+
+    User-specified extra metadata can be inserted into request headers to provide additional context to Databricks
+    about usage of different tools in the Databricks ecosystem. This can be useful for collecting telemetry about SDK
+    usage from tools that are built on top of the SDK.
+    """
+    global _extra
+    _match_alphanum(key)
+    _match_alphanum_or_semver(value)
+    logger.debug(f'Adding {key}/{value} to User-Agent')
+    _extra.append((key, value))
+
+
+def extra() -> List[Tuple[str, str]]:
+    """Returns the current extra metadata that will be submitted to Databricks on every request."""
+    return copy.deepcopy(_extra)
+
+
+def _reset_extra(extra: List[Tuple[str, str]]):
+    """[INTERNAL API] Reset the extra metadata to a new list.
+
+    Prefer using with_user_agent_extra instead of this method to avoid overwriting other information included in the
+    user agent."""
+    global _extra
+    _extra = extra
+
+
+def with_partner(partner: str):
+    """Adds the given partner to the metadata submitted to Databricks on every request."""
+    with_extra("partner", partner)
+
+
+def _get_upstream_user_agent_info() -> List[Tuple[str, str]]:
+    """[INTERNAL API] Return the upstream product and version if specified in the system environment."""
+    product = os.getenv("DATABRICKS_SDK_UPSTREAM")
+    version = os.getenv("DATABRICKS_SDK_UPSTREAM_VERSION")
+    if not product or not version:
+        return []
+    return [("upstream", product), ("upstream-version", version)]
+
+
+def _get_runtime_info() -> List[Tuple[str, str]]:
+    """[INTERNAL API] Return the runtime version if running on Databricks."""
+    if 'DATABRICKS_RUNTIME_VERSION' in os.environ:
+        runtime_version = os.environ['DATABRICKS_RUNTIME_VERSION']
+        if runtime_version != '':
+            runtime_version = _sanitize_header_value(runtime_version)
+            return [('runtime', runtime_version)]
+    return []
+
+
+def _sanitize_header_value(value: str) -> str:
+    value = value.replace(' ', '-')
+    value = value.replace('/', '-')
+    return value
+
+
+def to_string(alternate_product_info: Optional[Tuple[str, str]] = None,
+              other_info: Optional[List[Tuple[str, str]]] = None) -> str:
+    """Compute the full User-Agent header.
+
+    The User-Agent header contains the product name, version, and other metadata that is submitted to Databricks on
+    every request. There are some static components that are included by default in every request, like the SDK version,
+    OS name, and Python version. Other components can be optionally overridden or augmented in DatabricksConfig, like
+    the product name, product version, and extra user-defined information."""
+    base = []
+    if alternate_product_info:
+        base.append(alternate_product_info)
+    else:
+        base.append((_product_name, _product_version))
+    base.extend([("databricks-sdk-py", __version__), ("python", platform.python_version()),
+                 ("os", platform.uname().system.lower()), ])
+    if other_info:
+        base.extend(other_info)
+    base.extend(_extra)
+    base.extend(_get_upstream_user_agent_info())
+    base.extend(_get_runtime_info())
+    return " ".join(f"{k}/{v}" for k, v in base)

databricks/sdk/version.py

@@ -1 +1 @@
-__version__ = '0.29.0'
+__version__ = '0.30.0'

{databricks_sdk-0.29.0.dist-info → databricks_sdk-0.30.0.dist-info}/METADATA

@@ -1,13 +1,11 @@
 Metadata-Version: 2.1
 Name: databricks-sdk
-Version: 0.29.0
+Version: 0.30.0
 Summary: Databricks SDK for Python (Beta)
 Home-page: https://databricks-sdk-py.readthedocs.io
 Author: Serge Smertin
 Author-email: serge.smertin@databricks.com
-License: UNKNOWN
 Keywords: databricks sdk
-Platform: UNKNOWN
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -24,24 +22,24 @@ Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: google-auth (~=2.0)
 Requires-Dist: requests (<3,>=2.28.1)
+Requires-Dist: google-auth (~=2.0)
 Provides-Extra: dev
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: pytest-cov ; extra == 'dev'
+Requires-Dist: pytest-xdist ; extra == 'dev'
+Requires-Dist: pytest-mock ; extra == 'dev'
+Requires-Dist: yapf ; extra == 'dev'
+Requires-Dist: pycodestyle ; extra == 'dev'
 Requires-Dist: autoflake ; extra == 'dev'
-Requires-Dist: databricks-connect ; extra == 'dev'
+Requires-Dist: isort ; extra == 'dev'
+Requires-Dist: wheel ; extra == 'dev'
 Requires-Dist: ipython ; extra == 'dev'
 Requires-Dist: ipywidgets ; extra == 'dev'
-Requires-Dist: isort ; extra == 'dev'
-Requires-Dist: pycodestyle ; extra == 'dev'
+Requires-Dist: requests-mock ; extra == 'dev'
 Requires-Dist: pyfakefs ; extra == 'dev'
-Requires-Dist: pytest ; extra == 'dev'
-Requires-Dist: pytest-cov ; extra == 'dev'
-Requires-Dist: pytest-mock ; extra == 'dev'
+Requires-Dist: databricks-connect ; extra == 'dev'
 Requires-Dist: pytest-rerunfailures ; extra == 'dev'
-Requires-Dist: pytest-xdist ; extra == 'dev'
-Requires-Dist: requests-mock ; extra == 'dev'
-Requires-Dist: wheel ; extra == 'dev'
-Requires-Dist: yapf ; extra == 'dev'
 Provides-Extra: notebook
 Requires-Dist: ipython (<9,>=8) ; extra == 'notebook'
 Requires-Dist: ipywidgets (<9,>=8) ; extra == 'notebook'
@@ -78,6 +76,7 @@ The SDK's internal HTTP client is robust and handles failures on different level
 - [Long-running operations](#long-running-operations)
 - [Paginated responses](#paginated-responses)
 - [Single-sign-on with OAuth](#single-sign-on-sso-with-oauth)
+- [User Agent Request Attribution](#user-agent-request-attribution)
 - [Error handling](#error-handling)
 - [Logging](#logging)
 - [Integration with `dbutils`](#interaction-with-dbutils)
@@ -556,6 +555,29 @@ logging.info(f'Created new custom app: '
              f'--client_secret {custom_app.client_secret}')
 ```
 
+## User Agent Request Attribution<a id="user-agent-request-attribution"></a>
+
+The Databricks SDK for Python uses the `User-Agent` header to include request metadata along with each request. By default, this includes the version of the Python SDK, the version of the Python language used by your application, and the underlying operating system. To statically add additional metadata, you can use the `with_partner()` and `with_product()` functions in the `databricks.sdk.useragent` module. `with_partner()` can be used by partners to indicate that code using the Databricks SDK for Go should be attributed to a specific partner. Multiple partners can be registered at once. Partner names can contain any number, digit, `.`, `-`, `_` or `+`.
+
+```python
+from databricks.sdk import useragent
+useragent.with_product("partner-abc")
+useragent.with_partner("partner-xyz")
+```
+
+`with_product()` can be used to define the name and version of the product that is built with the Databricks SDK for Python. The product name has the same restrictions as the partner name above, and the product version must be a valid [SemVer](https://semver.org/). Subsequent calls to `with_product()` replace the original product with the new user-specified one.
+
+```go
+from databricks.sdk import useragent
+useragent.with_product("databricks-example-product", "1.2.0")
+```
+
+If both the `DATABRICKS_SDK_UPSTREAM` and `DATABRICKS_SDK_UPSTREAM_VERSION` environment variables are defined, these will also be included in the `User-Agent` header.
+
+If additional metadata needs to be specified that isn't already supported by the above interfaces, you can use the `with_user_agent_extra()` function to register arbitrary key-value pairs to include in the user agent. Multiple values associated with the same key are allowed. Keys have the same restrictions as the partner name above. Values must be either as described above or SemVer strings.
+
+Additional `User-Agent` information can be associated with different instances of `DatabricksConfig`. To add metadata to a specific instance of `DatabricksConfig`, use the `with_user_agent_extra()` method.
+
 ## Error handling<a id="error-handling"></a>
 
 The Databricks SDK for Python provides a robust error-handling mechanism that allows developers to catch and handle API errors. When an error occurs, the SDK will raise an exception that contains information about the error, such as the HTTP status code, error message, and error details. Developers can catch these exceptions and handle them appropriately in their code.
@@ -655,5 +677,3 @@ API clients for all services are generated from specification files that are syn
 You are highly encouraged to pin the exact dependency version and read the [changelog](https://github.com/databricks/databricks-sdk-py/blob/main/CHANGELOG.md) 
 where Databricks documents the changes. Databricks may have minor [documented](https://github.com/databricks/databricks-sdk-py/blob/main/CHANGELOG.md) 
 backward-incompatible changes, such as renaming some type names to bring more consistency.
-
-

{databricks_sdk-0.29.0.dist-info → databricks_sdk-0.30.0.dist-info}/RECORD

@@ -1,18 +1,20 @@
 databricks/__init__.py,sha256=CF2MJcZFwbpn9TwQER8qnCDhkPooBGQNVkX4v7g6p3g,537
-databricks/sdk/__init__.py,sha256=BvgOwu_sZ7kMVO0ukpgMLnAxKHkGnY5_4QeBr-AdFt8,44140
+databricks/sdk/__init__.py,sha256=I1YtsgPGK82d8EknfaKJLmp950-rg2kdDpl-forqUfA,46636
 databricks/sdk/_property.py,sha256=sGjsipeFrjMBSVPjtIb0HNCRcMIhFpVx6wq4BkC3LWs,1636
 databricks/sdk/azure.py,sha256=8P7nEdun0hbQCap9Ojo7yZse_JHxnhYsE6ApojnPz7Q,1009
 databricks/sdk/casing.py,sha256=NKYPrfPbQjM7lU4hhNQK3z1jb_VEA29BfH4FEdby2tg,1137
 databricks/sdk/clock.py,sha256=Ivlow0r_TkXcTJ8UXkxSA0czKrY0GvwHAeOvjPkJnAQ,1360
-databricks/sdk/config.py,sha256=sBIWdZHaL3WfJz9gVrlxSRiQpe_tPBMpWA0aaO4bHD4,21745
-databricks/sdk/core.py,sha256=R9PeiAhPMapuC9S5Mw6UmpI2MDp4E32-NzhWm4oFAck,20018
-databricks/sdk/credentials_provider.py,sha256=RVyP0IQbiUbXeUTv2IPmweRzvrgyEhmc6VB0zuetR2I,29204
+databricks/sdk/config.py,sha256=FWEiIY34C_4Mmv8B9w284BR2FHug2T2ySpmtyg51ttA,21139
+databricks/sdk/core.py,sha256=PWU2kTHXOF6x7i9_yRUFGj-iusr_Mo7awROiBpA9nJQ,20398
+databricks/sdk/credentials_provider.py,sha256=V8QxVUvZmOfVjEpogNEzu5nUBXzRLevWfi-NiPaDOks,29232
+databricks/sdk/data_plane.py,sha256=Er2z2fT-KVupJKzGozGGZ-jCQ3AmDWq-DZppahIK6tU,2591
 databricks/sdk/dbutils.py,sha256=HFCuB-el6SFKhF8qRfJxYANtyLTm-VG9GtQuQgZXFkM,15741
 databricks/sdk/environments.py,sha256=5KoVuVfF-ZX17rua1sH3EJCCtniVrREXBXsMNDEV-UU,4293
 databricks/sdk/oauth.py,sha256=KzcJPYLL3JL6RDvf_Q8SDAaF9xSaoYNCRD4rYInZDuo,18319
 databricks/sdk/py.typed,sha256=pSvaHpbY1UPNEXyVFUjlgBhjPFZMmVC_UNrPC7eMOHI,74
 databricks/sdk/retries.py,sha256=WgLh12bwdBc6fCQlaig3kKu18cVhPzFDGsspvq629Ew,2454
-databricks/sdk/version.py,sha256=mXICichpk9VjfOW_vwM-zwKsrhkYyfYKUsV4l3tgiYM,23
+databricks/sdk/useragent.py,sha256=8yXu6l2mGZR6874u9Jtn2qNSDuNDEp4jzh0CbJ9yssw,5028
+databricks/sdk/version.py,sha256=dSJBJnSMHNhD9IFG9yG2hFHceWiae5G4B2UFREtze5M,23
 databricks/sdk/_widgets/__init__.py,sha256=Qm3JB8LmdPgEn_-VgxKkodTO4gn6OdaDPwsYcDmeIRI,2667
 databricks/sdk/_widgets/default_widgets_utils.py,sha256=Rk59AFzVYVpOektB_yC_7j-vSt5OdtZA85IlG0kw0xA,1202
 databricks/sdk/_widgets/ipywidgets_utils.py,sha256=P-AyGeahPiX3S59mxpAMgffi4gyJ0irEOY7Ekkn9nQ0,2850
@@ -25,33 +27,34 @@ databricks/sdk/errors/private_link.py,sha256=6wVRJQqousGQC7qfT0pV8LqujqfR3XLbSix
 databricks/sdk/errors/sdk.py,sha256=_euMruhvquB0v_SKtgqxJUiyXHWuTb4Jl7ji6_h0E_A,109
 databricks/sdk/mixins/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 databricks/sdk/mixins/compute.py,sha256=khb00BzBckc4RLUF4-GnNMCSO5lXKt_XYMM3IhiUxlA,11237
-databricks/sdk/mixins/files.py,sha256=8Nh4TAB0BASZfTylW1P93_Sj_-zBlzEZ6CN38x2UoTQ,20205
+databricks/sdk/mixins/files.py,sha256=bLGFu1kVIQECTmuc_9jUf-n_Cth4COBMbmKqAYxkEkM,20542
 databricks/sdk/mixins/workspace.py,sha256=dWMNvuEi8jJ5wMhrDt1LiqxNdWSsmEuDTzrcZR-eJzY,4896
 databricks/sdk/runtime/__init__.py,sha256=9NnZkBzeZXZRQxcE1qKzAszQEzcpIgpL7lQzW3_kxEU,7266
 databricks/sdk/runtime/dbutils_stub.py,sha256=UFbRZF-bBcwxjbv_pxma00bjNtktLLaYpo8oHRc4-9g,11421
 databricks/sdk/service/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 databricks/sdk/service/_internal.py,sha256=nWbJfW5eJCQgAZ3TmA26xoWb6SNZ5N76ZA8bO1N4AsU,1961
-databricks/sdk/service/billing.py,sha256=Hbe5bMsBrpebuAl8yj-GwVRGktrzKwiZJj3gq1wUMaI,50625
-databricks/sdk/service/catalog.py,sha256=m69PNTCN8AmvYeU5NFKQHIf6JsPLkNm4Q9Vj_bm2mlE,416701
-databricks/sdk/service/compute.py,sha256=Wn0M4irami1Qy6wUoyU8Ub_CbSwsSVUF_bdHqUpEh0M,398609
-databricks/sdk/service/dashboards.py,sha256=Ac7K8ekefbfXyZ2ITq7h7uN1MRjCHC6mQoVPcCFgPX8,48962
+databricks/sdk/service/apps.py,sha256=536HvScC96edq9EXMUcyVh1h2jE5zCeCMa_l7HZiu20,38170
+databricks/sdk/service/billing.py,sha256=Ru6GumI-M4_X71HTMj2VSVBQ7tRMTrwKzhdwNyiC3fA,69733
+databricks/sdk/service/catalog.py,sha256=DT-T8vSdHN3GL_dBUDp2fFS6ypNIgqVxtlKijw-fpUc,421856
+databricks/sdk/service/compute.py,sha256=2CkQPllHlpVZGWXCWIe9bcVcQyDsldfE4kmiXFoF7Jc,420685
+databricks/sdk/service/dashboards.py,sha256=SqaySudMTniP3AIMW5Lx2v6k0yxwVtIEZQzEJNPW3-Q,75352
 databricks/sdk/service/files.py,sha256=VCt83YSI9rhQexmxaQdrUXHq2UCYfZcDMLvJx5X6n1M,38162
-databricks/sdk/service/iam.py,sha256=11L45bjOYwzxMVlAXpKrFMOxrZzgZy75JSIOkeAXuFg,147645
-databricks/sdk/service/jobs.py,sha256=v9BoJ0k0BRr0dAjmwX_BQ0Ao8n-gU5t7rhrF1qc0KE4,303103
-databricks/sdk/service/marketplace.py,sha256=0xNm1Ob7G6Le5ieG7meJpBbmkt18gko1bhmORG9DwoM,141176
+databricks/sdk/service/iam.py,sha256=fj1RQtCdg8E8oUt1SEnm6PzMR6UB-jaCn8M354KiB-o,148500
+databricks/sdk/service/jobs.py,sha256=Jc2PF58kvpDuHOTVfwQQAJsdR_RJ9Q7qDDtr4Hpqggo,304259
+databricks/sdk/service/marketplace.py,sha256=Fgk_8V9zbQ8QcNPUw-yZehHv8LgnDtFJUe-YixjxkYo,136405
 databricks/sdk/service/ml.py,sha256=vohBdESClI3EOpO-ZZ44W-CMz1alq5Tw4oJnWa99Z2M,236128
-databricks/sdk/service/oauth2.py,sha256=yBY6S_rI2ottFjttYDDijjyoAWFndwfqFC50sdimcSY,37100
-databricks/sdk/service/pipelines.py,sha256=Zp-ogtJl2VN5ssi65ii2wI2nbOYPE8Qdhgp36aUitfo,118753
+databricks/sdk/service/oauth2.py,sha256=67pr6gUnYwO6BaGNQfjW1qvcEB3ejdNbI9Pmvqs5bSE,39928
+databricks/sdk/service/pipelines.py,sha256=tGCo1F3tW1GxB9Q63qsh2AyisJmXqYSsGkJK0OdS06Q,119378
 databricks/sdk/service/provisioning.py,sha256=DP4Df4X-p0JEUk4zAJQhjX_wxpMi673OKLXFhxl6YSE,142678
-databricks/sdk/service/serving.py,sha256=Hg5v87ap49j4H5B6_RKe8auGKDamWskp1PQTBDCCwQ0,150238
-databricks/sdk/service/settings.py,sha256=7c_gSsOZtTpmSGE-OVKMnkpbc5wqoN447zX-vyDhrJk,177409
-databricks/sdk/service/sharing.py,sha256=dtMJdIhGLh8a70Aq55dqGsUG12ykiz_7zgEvg2Iw42A,100135
-databricks/sdk/service/sql.py,sha256=v8oP0sA_mix3ftSujtaVG4tfXGnSHeBJbA7c6iWW-1c,262958
+databricks/sdk/service/serving.py,sha256=BfShf0ceupXgLccU5zp1CZyBW1260Ga73USM2T5KxXs,140008
+databricks/sdk/service/settings.py,sha256=7PXxsrXUe7exM35O7_iUp9r78zn5oGnPbhX_sh3v1_0,193732
+databricks/sdk/service/sharing.py,sha256=kalJYd0v1SwuGhlCaq4l2ZhzNlev9OwNbCXFIOKIMXU,113253
+databricks/sdk/service/sql.py,sha256=b8FoGZnwHqxDb2FQr_XOeegFVqDEfBXZH318NpRVtdU,337519
 databricks/sdk/service/vectorsearch.py,sha256=ZfiTEpTNg8nnzPuw24MeiDn8eq6PHmEWqTHS0zdDdEo,62484
 databricks/sdk/service/workspace.py,sha256=FKLf5esRmfFstIXo7HQg6HQCzQ2svrb6ulr8yzZ7-8U,101182
-databricks_sdk-0.29.0.dist-info/LICENSE,sha256=afBgTZo-JsYqj4VOjnejBetMuHKcFR30YobDdpVFkqY,11411
-databricks_sdk-0.29.0.dist-info/METADATA,sha256=4w5fp5admIsLz4trTedAhLYAvDfpqmm_e75ZIs3qsMc,35819
-databricks_sdk-0.29.0.dist-info/NOTICE,sha256=Qnc0m8JjZNTDV80y0h1aJGvsr4GqM63m1nr2VTypg6E,963
-databricks_sdk-0.29.0.dist-info/WHEEL,sha256=G16H4A3IeoQmnOrYV4ueZGKSjhipXx8zc8nu9FGlvMA,92
-databricks_sdk-0.29.0.dist-info/top_level.txt,sha256=7kRdatoSgU0EUurRQJ_3F1Nv4EOSHWAr6ng25tJOJKU,11
-databricks_sdk-0.29.0.dist-info/RECORD,,
+databricks_sdk-0.30.0.dist-info/LICENSE,sha256=afBgTZo-JsYqj4VOjnejBetMuHKcFR30YobDdpVFkqY,11411
+databricks_sdk-0.30.0.dist-info/METADATA,sha256=00btvZMl5DDI3ovz5PebGVKtknsKQDnL_Fi1rKIZG-I,37967
+databricks_sdk-0.30.0.dist-info/NOTICE,sha256=Qnc0m8JjZNTDV80y0h1aJGvsr4GqM63m1nr2VTypg6E,963
+databricks_sdk-0.30.0.dist-info/WHEEL,sha256=R0nc6qTxuoLk7ShA2_Y-UWkN8ZdfDBG2B6Eqpz2WXbs,91
+databricks_sdk-0.30.0.dist-info/top_level.txt,sha256=7kRdatoSgU0EUurRQJ_3F1Nv4EOSHWAr6ng25tJOJKU,11
+databricks_sdk-0.30.0.dist-info/RECORD,,

{databricks_sdk-0.29.0.dist-info → databricks_sdk-0.30.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.37.1)
+Generator: setuptools (72.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any