zipher-sdk 0.4.6__tar.gz → 0.4.7__tar.gz

{zipher_sdk-0.4.6/zipher_sdk.egg-info → zipher_sdk-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zipher-sdk
-Version: 0.4.6
+Version: 0.4.7
 Summary: Python SDK for programmatic access to the Zipher API
 Author: Zipher Inc.
 Author-email: yoav@zipher.cloud
@@ -29,6 +29,7 @@ The Zipher SDK is a Python library for interacting with Zipher's APIs.
 - [Package Installation](#package-installation)
 - [Granting access to Zipher](#providing-zipher-with-access-to-databricks-workspace)
 - [Usage](#sdk-usage)
+- [Telemetry](#telemetry)
 
 ## Package Installation
 
@@ -223,3 +224,46 @@ optimized_tasks = client.get_optimized_tasks(job_id="my-job-id", tasks=tasks_to_
 
 # Continue with sending the optimized tasks to Databricks via the Databricks python SDK, Airflow operator, etc.
 ```
+
+## Telemetry
+
+Every request the SDK sends to Zipher's APIs carries your API key and two headers:
+
+- `User-Agent: zipher-sdk/<version>` identifies the SDK. It is always sent and is not part of the opt-out
+  telemetry below.
+- `X-Zipher-Client-Info` is the opt-out telemetry: a compact JSON object describing the environment the SDK runs in,
+  for example
+  `{"airflow":"2.10.1","arch":"x86_64","databricks_sdk":"0.102.0","os":"linux","pydantic":"2.9.0","python":"3.11.4","python_impl":"CPython","requests":"2.32.3","sdk":"0.4.7"}`.
+  We collect it to know which Python, Airflow and databricks-sdk versions our customers run, so we know what to
+  support.
+
+You can stop the SDK from sending `X-Zipher-Client-Info` (and from collecting it) by passing
+`send_client_info=False` in the client config:
+
+```python
+from zipher import Client, Config
+
+client = Client(customer_id="...", config=Config(send_client_info=False))
+```
+
+or by setting `DO_NOT_TRACK=1` (`true` and `yes` also work) in the environment.
+
+Fields of `X-Zipher-Client-Info` (a field is left out when it does not apply, e.g. Airflow is not installed, and set to `"error"` when it applies
+but could not be read):
+
+| Field | Contents |
+| --- | --- |
+| `sdk` | Version of `zipher-sdk` (`unknown` when running from a source checkout) |
+| `python` | Python version, e.g. `3.11.4` |
+| `python_impl` | Python implementation, e.g. `CPython` |
+| `os` | Operating system name, e.g. `linux`, `darwin`, `windows` |
+| `arch` | CPU architecture, e.g. `x86_64`, `arm64` |
+| `databricks_sdk` | Installed `databricks-sdk` version |
+| `requests` | Installed `requests` version |
+| `pydantic` | Installed `pydantic` version |
+| `airflow` | Installed `apache-airflow` version, when Airflow is installed |
+| `dbr` | Databricks Runtime version (the `DATABRICKS_RUNTIME_VERSION` environment variable), when running on Databricks |
+
+Package versions are read from the installed package metadata; the packages themselves are not imported.
+No hostnames, usernames, workspace IDs, job contents or credentials are sent. Values are limited to 64 ASCII
+characters.

{zipher_sdk-0.4.6 → zipher_sdk-0.4.7}/README.md

@@ -6,6 +6,7 @@ The Zipher SDK is a Python library for interacting with Zipher's APIs.
 - [Package Installation](#package-installation)
 - [Granting access to Zipher](#providing-zipher-with-access-to-databricks-workspace)
 - [Usage](#sdk-usage)
+- [Telemetry](#telemetry)
 
 ## Package Installation
 
@@ -199,4 +200,47 @@ tasks_to_optimize = [
 optimized_tasks = client.get_optimized_tasks(job_id="my-job-id", tasks=tasks_to_optimize)
 
 # Continue with sending the optimized tasks to Databricks via the Databricks python SDK, Airflow operator, etc.
-```
+```
+
+## Telemetry
+
+Every request the SDK sends to Zipher's APIs carries your API key and two headers:
+
+- `User-Agent: zipher-sdk/<version>` identifies the SDK. It is always sent and is not part of the opt-out
+  telemetry below.
+- `X-Zipher-Client-Info` is the opt-out telemetry: a compact JSON object describing the environment the SDK runs in,
+  for example
+  `{"airflow":"2.10.1","arch":"x86_64","databricks_sdk":"0.102.0","os":"linux","pydantic":"2.9.0","python":"3.11.4","python_impl":"CPython","requests":"2.32.3","sdk":"0.4.7"}`.
+  We collect it to know which Python, Airflow and databricks-sdk versions our customers run, so we know what to
+  support.
+
+You can stop the SDK from sending `X-Zipher-Client-Info` (and from collecting it) by passing
+`send_client_info=False` in the client config:
+
+```python
+from zipher import Client, Config
+
+client = Client(customer_id="...", config=Config(send_client_info=False))
+```
+
+or by setting `DO_NOT_TRACK=1` (`true` and `yes` also work) in the environment.
+
+Fields of `X-Zipher-Client-Info` (a field is left out when it does not apply, e.g. Airflow is not installed, and set to `"error"` when it applies
+but could not be read):
+
+| Field | Contents |
+| --- | --- |
+| `sdk` | Version of `zipher-sdk` (`unknown` when running from a source checkout) |
+| `python` | Python version, e.g. `3.11.4` |
+| `python_impl` | Python implementation, e.g. `CPython` |
+| `os` | Operating system name, e.g. `linux`, `darwin`, `windows` |
+| `arch` | CPU architecture, e.g. `x86_64`, `arm64` |
+| `databricks_sdk` | Installed `databricks-sdk` version |
+| `requests` | Installed `requests` version |
+| `pydantic` | Installed `pydantic` version |
+| `airflow` | Installed `apache-airflow` version, when Airflow is installed |
+| `dbr` | Databricks Runtime version (the `DATABRICKS_RUNTIME_VERSION` environment variable), when running on Databricks |
+
+Package versions are read from the installed package metadata; the packages themselves are not imported.
+No hostnames, usernames, workspace IDs, job contents or credentials are sent. Values are limited to 64 ASCII
+characters.

{zipher_sdk-0.4.6 → zipher_sdk-0.4.7}/setup.py

@@ -8,7 +8,7 @@ with open('README.md', encoding='utf-8') as f:
 
 setup(
     name='zipher-sdk',
-    version='0.4.6',
+    version='0.4.7',
     description='Python SDK for programmatic access to the Zipher API',
     long_description=long_description,
     long_description_content_type='text/markdown',

zipher_sdk-0.4.7/tests/unit/conftest.py

@@ -0,0 +1,12 @@
+import os
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def hermetic_environment(monkeypatch):
+    """Neither the developer's shell nor the CI environment may influence a unit test."""
+    for name in list(os.environ):
+        if name.startswith(("DATABRICKS_", "ZIPHER_")):
+            monkeypatch.delenv(name)
+    monkeypatch.delenv("DO_NOT_TRACK", raising=False)

zipher_sdk-0.4.7/tests/unit/test_client.py

@@ -0,0 +1,47 @@
+import pytest
+import responses
+
+from zipher import _version
+from zipher.client import Client
+from zipher.models import Config
+
+CONFIG_URL = "https://api.zipher.cloud/default/get_clusterspec"
+TASKS_URL = "https://api.zipher.cloud/default/get_optimized_tasks"
+
+
+@pytest.fixture
+def client():
+    return Client(customer_id="customer-1", zipher_api_key="key-123")
+
+
+class TestUserAgent:
+    @pytest.mark.parametrize("send_client_info", [True, False])
+    @pytest.mark.parametrize("endpoint", ["config", "tasks"])
+    @responses.activate
+    def test_is_always_sent_and_identifies_the_sdk(self, endpoint, send_client_info):
+        client = Client(
+            customer_id="customer-1",
+            zipher_api_key="key-123",
+            config=Config(send_client_info=send_client_info),
+        )
+        if endpoint == "config":
+            responses.get(CONFIG_URL, json={})
+            client.get_optimized_config(job_id="1")
+        else:
+            responses.get(TASKS_URL, json=[])
+            client.get_optimized_tasks(job_id="1", tasks=[])
+
+        headers = responses.calls[0].request.headers
+
+        assert headers["User-Agent"] == f"zipher-sdk/{_version.SDK_VERSION}"
+
+    @responses.activate
+    def test_is_sent_when_do_not_track_is_set(self, client, monkeypatch):
+        monkeypatch.setenv("DO_NOT_TRACK", "1")
+        responses.get(CONFIG_URL, json={})
+
+        client.get_optimized_config(job_id="1")
+
+        headers = responses.calls[0].request.headers
+        assert headers["User-Agent"] == f"zipher-sdk/{_version.SDK_VERSION}"
+        assert "X-Zipher-Client-Info" not in headers

zipher_sdk-0.4.7/tests/unit/test_telemetry.py

@@ -0,0 +1,298 @@
+import importlib.metadata
+import json
+import platform
+
+import pytest
+import responses
+
+import zipher
+from zipher import _telemetry, _version
+from zipher.client import Client
+from zipher.models import Config
+
+CONFIG_URL = "https://api.zipher.cloud/default/get_clusterspec"
+TASKS_URL = "https://api.zipher.cloud/default/get_optimized_tasks"
+INFO_HEADER = "X-Zipher-Client-Info"
+
+DISTRIBUTION_FIELDS = {
+    "databricks_sdk": "databricks-sdk",
+    "requests": "requests",
+    "pydantic": "pydantic",
+    "airflow": "apache-airflow",
+}
+
+
+@pytest.fixture(autouse=True)
+def fresh_client_info():
+    """The client info is cached per process: no test may see another test's result."""
+    _telemetry._collect_client_info.cache_clear()
+    yield
+    _telemetry._collect_client_info.cache_clear()
+
+
+@pytest.fixture
+def installed(monkeypatch):
+    """Make importlib.metadata.version answer from a dict.
+
+    Unknown distributions are missing, or, with ``passthrough``, answered by the real lookup.
+    """
+    real_version = importlib.metadata.version
+
+    def install(versions, error=importlib.metadata.PackageNotFoundError, passthrough=False):
+        def fake_version(name):
+            if name in versions:
+                return versions[name]
+            if passthrough:
+                return real_version(name)
+            raise error(name)
+
+        monkeypatch.setattr(importlib.metadata, "version", fake_version)
+
+    return install
+
+
+@pytest.fixture
+def metadata_lookups(monkeypatch):
+    """Record every distribution looked up, i.e. every client-info collection.
+
+    The cache is kept cold by fresh_client_info, so a collection always shows up here.
+    """
+    calls = []
+    real_version = importlib.metadata.version
+
+    def counting_version(name):
+        calls.append(name)
+        return real_version(name)
+
+    monkeypatch.setattr(importlib.metadata, "version", counting_version)
+    return calls
+
+
+def real_distribution_version(distribution):
+    try:
+        return importlib.metadata.version(distribution)
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def info_sent(headers=None):
+    return json.loads((headers or _telemetry.client_info_headers())[INFO_HEADER])
+
+
+class TestSdkVersion:
+    def test_is_the_installed_distribution_version(self):
+        assert importlib.metadata.version("zipher-sdk") == _version.SDK_VERSION
+        assert zipher.__version__ == _version.SDK_VERSION
+
+    def test_falls_back_to_unknown_when_the_distribution_is_not_installed(self, installed):
+        installed({})
+
+        assert _version._sdk_version() == "unknown"
+
+
+class TestClientInfoFields:
+    def test_all_fields_come_from_their_sources(self, monkeypatch, installed):
+        expected = {
+            "sdk": _version.SDK_VERSION,
+            "python": platform.python_version(),
+            "python_impl": platform.python_implementation(),
+            "os": platform.system().lower(),
+            "arch": platform.machine(),
+            "airflow": "2.10.1",  # deterministic: whether Airflow is installed varies by env
+            "dbr": "15.4",
+        }
+        for field, distribution in DISTRIBUTION_FIELDS.items():
+            version = real_distribution_version(distribution)
+            if version and field != "airflow":
+                expected[field] = version
+        installed({"apache-airflow": "2.10.1"}, passthrough=True)
+        monkeypatch.setenv("DATABRICKS_RUNTIME_VERSION", "15.4")
+
+        assert _telemetry.get_client_info() == expected
+
+    def test_distribution_field_is_omitted_when_not_installed_not_marked_as_error(self, installed):
+        # Airflow is the only optional distribution; the others are hard dependencies.
+        installed({"apache-airflow": "1.2.3"})
+        assert _telemetry.get_client_info()["airflow"] == "1.2.3"
+
+        _telemetry._collect_client_info.cache_clear()
+        installed({})
+        info = _telemetry.get_client_info()
+        assert "airflow" not in info
+        assert "error" not in info.values()
+        assert "python" in info  # the other fields are unaffected
+
+    def test_versions_are_never_found_by_importing_the_package(self, installed, monkeypatch):
+        installed({"apache-airflow": "2.10.1"})
+        monkeypatch.setitem(__import__("sys").modules, "airflow", None)  # import would raise
+
+        assert _telemetry.get_client_info()["airflow"] == "2.10.1"
+
+    def test_dbr_is_present_only_when_the_runtime_env_var_is_set(self, monkeypatch):
+        monkeypatch.setenv("DATABRICKS_RUNTIME_VERSION", "14.3")
+        assert _telemetry.get_client_info()["dbr"] == "14.3"
+
+        _telemetry._collect_client_info.cache_clear()
+        monkeypatch.delenv("DATABRICKS_RUNTIME_VERSION")
+        assert "dbr" not in _telemetry.get_client_info()
+
+    @pytest.mark.parametrize("value", ["", "  \n"])
+    def test_dbr_is_omitted_when_the_env_var_is_empty_or_blank(self, monkeypatch, value):
+        monkeypatch.setenv("DATABRICKS_RUNTIME_VERSION", value)
+
+        assert "dbr" not in _telemetry.get_client_info()
+
+
+class TestRobustness:
+    @pytest.mark.parametrize("error", [OSError, ValueError])
+    def test_unreadable_metadata_marks_only_that_field_as_error(self, monkeypatch, error):
+        real_version = importlib.metadata.version
+
+        def flaky(name):
+            if name == "pydantic":
+                raise error("broken metadata")
+            return real_version(name)
+
+        monkeypatch.setattr(importlib.metadata, "version", flaky)
+
+        info = _telemetry.get_client_info()
+
+        assert info["pydantic"] == "error"
+        assert info["requests"] == real_version("requests")
+        assert info["python"] == platform.python_version()
+
+    def test_hostile_values_still_make_a_valid_header(self, monkeypatch):
+        monkeypatch.setenv("DATABRICKS_RUNTIME_VERSION", "15.4\r\nX-Injected: yesé中" + "z" * 500)
+
+        header = _telemetry.client_info_headers()[INFO_HEADER]
+
+        assert header.isascii() and "\r" not in header and "\n" not in header
+        dbr = json.loads(header)["dbr"]
+        assert "\r" not in dbr and "\n" not in dbr  # JSON escaping alone would hide these
+        assert dbr.isascii()  # ensure_ascii alone would hide non-ASCII
+        assert len(dbr) <= _telemetry.MAX_VALUE_LENGTH
+        assert dbr.startswith("15.4")
+
+
+class TestHeaders:
+    def test_client_info_is_computed_once_per_process(self, metadata_lookups):
+        _telemetry.client_info_headers()
+        first_collection = list(metadata_lookups)
+        _telemetry.client_info_headers()
+        _telemetry.get_client_info()
+
+        assert sorted(first_collection) == sorted(DISTRIBUTION_FIELDS.values())
+        assert metadata_lookups == first_collection
+
+
+@pytest.fixture
+def client():
+    return Client(customer_id="customer-1", zipher_api_key="key-123")
+
+
+def call_api(client, endpoint):
+    if endpoint == "config":
+        responses.get(CONFIG_URL, json={})
+        client.get_optimized_config(job_id="1")
+    else:
+        responses.get(TASKS_URL, json=[])
+        client.get_optimized_tasks(job_id="1", tasks=[])
+    return responses.calls[0].request.headers
+
+
+class TestClientSendsHeaders:
+    @pytest.mark.parametrize("endpoint", ["config", "tasks"])
+    @responses.activate
+    def test_both_endpoints_send_client_info_and_api_key(
+        self, client, monkeypatch, installed, endpoint
+    ):
+        installed({"databricks-sdk": "0.102.0", "requests": "2.32.3"})
+        monkeypatch.setenv("DATABRICKS_RUNTIME_VERSION", "15.4")
+
+        headers = call_api(client, endpoint)
+
+        assert headers["x-api-key"] == "key-123"
+        info = info_sent(headers)
+        assert info["sdk"] == _version.SDK_VERSION
+        assert info["python"] == platform.python_version()
+        assert info["os"] == platform.system().lower()
+        assert info["databricks_sdk"] == "0.102.0"
+        assert info["dbr"] == "15.4"
+        assert "airflow" not in info and "pydantic" not in info
+
+
+OPTED_OUT = ["1", "true", "TRUE", "yes", " 1 "]
+NOT_OPTED_OUT = [None, "", "0", "false", "no", "garbage"]
+
+
+def set_do_not_track(monkeypatch, value):
+    if value is None:
+        monkeypatch.delenv("DO_NOT_TRACK", raising=False)
+    else:
+        monkeypatch.setenv("DO_NOT_TRACK", value)
+
+
+class TestOptOutViaConfig:
+    @pytest.mark.parametrize("endpoint", ["config", "tasks"])
+    @responses.activate
+    def test_both_endpoints_send_api_key_but_no_client_info(self, monkeypatch, endpoint):
+        client = Client(
+            customer_id="customer-1",
+            zipher_api_key="key-123",
+            config=Config(send_client_info=False),
+        )
+
+        headers = call_api(client, endpoint)
+
+        assert headers["x-api-key"] == "key-123"
+        assert INFO_HEADER not in headers
+
+    def test_headers_omit_client_info_and_do_not_collect_it(self, metadata_lookups):
+        assert _telemetry.client_info_headers(enabled=False) == {}
+        assert metadata_lookups == []
+
+
+class TestDoNotTrack:
+    @pytest.mark.parametrize("value", OPTED_OUT + NOT_OPTED_OUT)
+    @responses.activate
+    def test_real_client_request(self, client, monkeypatch, value):
+        set_do_not_track(monkeypatch, value)
+
+        headers = call_api(client, "config")
+
+        assert headers["x-api-key"] == "key-123"
+        assert (INFO_HEADER in headers) == (value not in OPTED_OUT)
+
+    @responses.activate
+    def test_is_read_on_every_call_even_with_a_warm_cache(self, client, monkeypatch):
+        responses.get(CONFIG_URL, json={})
+
+        client.get_optimized_config(job_id="1")
+        monkeypatch.setenv("DO_NOT_TRACK", "1")
+        client.get_optimized_config(job_id="1")
+        monkeypatch.delenv("DO_NOT_TRACK")
+        client.get_optimized_config(job_id="1")
+
+        first, second, third = (call.request.headers for call in responses.calls)
+        assert INFO_HEADER in first
+        assert INFO_HEADER not in second
+        assert INFO_HEADER in third
+
+    def test_does_not_collect_client_info_when_set(self, monkeypatch, metadata_lookups):
+        monkeypatch.setenv("DO_NOT_TRACK", "1")
+
+        _telemetry.client_info_headers()
+
+        assert metadata_lookups == []
+
+
+class TestClientInfoIsolation:
+    def test_mutating_the_returned_info_does_not_change_later_requests(self):
+        info = _telemetry.get_client_info()
+        info["sdk"] = "tampered"
+        info["extra"] = "x"
+
+        sent = info_sent()
+
+        assert sent["sdk"] == _version.SDK_VERSION
+        assert "extra" not in sent

zipher_sdk-0.4.7/zipher/__init__.py

@@ -0,0 +1,5 @@
+from ._version import SDK_VERSION
+from .client import Client
+from .models import Config
+
+__version__ = SDK_VERSION

zipher_sdk-0.4.7/zipher/_telemetry.py

@@ -0,0 +1,109 @@
+"""The X-Zipher-Client-Info header: what the SDK tells Zipher about the environment it runs in.
+
+Everything here is best effort and must never fail or slow down a request. Each field is
+collected inside its own guard: a field that does not apply (Airflow not installed, not running
+on Databricks) is omitted, and a field that applies but could not be read is set to "error".
+Versions are read from installed package metadata, never by importing the package (importing
+Airflow, for instance, is slow and has side effects).
+
+The header is opt-out: pass ``enabled=False`` (``Config(send_client_info=False)``) or set the
+``DO_NOT_TRACK`` environment variable to ``1``, ``true`` or ``yes``. When opted out nothing is
+collected. The User-Agent is not part of this: it is always sent, see ``zipher.client``.
+"""
+
+import contextlib
+import functools
+import importlib.metadata
+import json
+import os
+import platform
+from typing import Callable, Optional
+
+from zipher._version import SDK_VERSION
+
+MAX_VALUE_LENGTH = 64
+CLIENT_INFO_HEADER = "X-Zipher-Client-Info"
+COLLECTION_ERROR = "error"
+_DO_NOT_TRACK_VALUES = frozenset({"1", "true", "yes"})
+
+
+def _distribution_version(distribution: str) -> Callable[[], Optional[str]]:
+    def collect() -> Optional[str]:
+        try:
+            return importlib.metadata.version(distribution)
+        except importlib.metadata.PackageNotFoundError:
+            return None
+
+    return collect
+
+
+def _dbr() -> Optional[str]:
+    return os.environ.get("DATABRICKS_RUNTIME_VERSION")
+
+
+def _fields() -> dict[str, Callable[[], Optional[str]]]:
+    return {
+        "sdk": lambda: SDK_VERSION,
+        "python": platform.python_version,
+        "python_impl": platform.python_implementation,
+        "os": lambda: platform.system().lower(),
+        "arch": platform.machine,
+        "databricks_sdk": _distribution_version("databricks-sdk"),
+        "requests": _distribution_version("requests"),
+        "pydantic": _distribution_version("pydantic"),
+        "airflow": _distribution_version("apache-airflow"),
+        "dbr": _dbr,
+    }
+
+
+def _clean(value) -> str:
+    """Make a value safe for a header: ASCII, single line, bounded length."""
+    text = str(value).replace("\r", " ").replace("\n", " ").strip()
+    return text.encode("ascii", "replace").decode("ascii")[:MAX_VALUE_LENGTH]
+
+
+@functools.cache
+def _collect_client_info() -> dict[str, str]:
+    info: dict[str, str] = {}
+    try:
+        for name, collect in _fields().items():
+            try:
+                raw = collect()
+                value = None if raw is None else _clean(raw)
+            except Exception:  # noqa: BLE001 - only this field is marked as failed
+                value = COLLECTION_ERROR
+            if value:
+                info[name] = value
+    except Exception:  # noqa: BLE001, S110 - keep whatever was collected
+        pass
+    return info
+
+
+def get_client_info() -> dict[str, str]:
+    """The client-info fields, computed once per process: omitted if n/a, "error" if unreadable.
+
+    Returns a copy, so a caller can't alter what later requests send.
+    """
+    return dict(_collect_client_info())
+
+
+def _do_not_track() -> bool:
+    """Whether DO_NOT_TRACK is set to 1/true/yes; read on every call, never cached."""
+    return os.environ.get("DO_NOT_TRACK", "").strip().lower() in _DO_NOT_TRACK_VALUES
+
+
+def client_info_headers(*, enabled: bool = True) -> dict[str, str]:
+    """The X-Zipher-Client-Info header, or ``{}``; never raises.
+
+    Nothing is collected, and ``{}`` is returned, when ``enabled`` is False or the DO_NOT_TRACK
+    env var is set.
+    """
+    with contextlib.suppress(Exception):  # on failure send no client info
+        # If the DO_NOT_TRACK check itself fails we raise here too, i.e. fail closed.
+        if enabled and not _do_not_track():
+            return {
+                CLIENT_INFO_HEADER: json.dumps(
+                    get_client_info(), separators=(",", ":"), sort_keys=True, ensure_ascii=True
+                )
+            }
+    return {}

zipher_sdk-0.4.7/zipher/_version.py

@@ -0,0 +1,13 @@
+"""The SDK's own version."""
+
+import importlib.metadata
+
+
+def _sdk_version() -> str:
+    try:
+        return importlib.metadata.version("zipher-sdk")
+    except Exception:  # noqa: BLE001 - the version must never fail an import
+        return "unknown"
+
+
+SDK_VERSION = _sdk_version()

{zipher_sdk-0.4.6 → zipher_sdk-0.4.7}/zipher/client.py

@@ -4,9 +4,14 @@ from typing import Dict, Optional
 
 import requests
 from databricks.sdk.service.compute import ClusterSpec
+from zipher._telemetry import client_info_headers
+from zipher._version import SDK_VERSION
 from zipher.models import ConfFetcherRequest, GetOptimizedTasksRequest, Config
 from zipher.exceptions import MissingAPIKeyError
 
+USER_AGENT = f'zipher-sdk/{SDK_VERSION}'
+
+
 class Client:
     def __init__(self, customer_id: str, zipher_api_key: str = '', config: Optional[Config] = None):
         self.config = config or Config()
@@ -19,7 +24,9 @@ class Client:
 
     def _call_conf_fetcher_api(self, params: ConfFetcherRequest):
         headers = {
-            'x-api-key': self.zipher_api_key
+            'x-api-key': self.zipher_api_key,
+            'User-Agent': USER_AGENT,
+            **client_info_headers(enabled=self.config.send_client_info),
         }
         response = requests.get(
             url=self.config.zipher_config_fetcher_api_endpoint,
@@ -33,7 +40,9 @@ class Client:
 
     def _call_get_optimized_tasks_api(self, params: GetOptimizedTasksRequest):
         headers = {
-            'x-api-key': self.zipher_api_key
+            'x-api-key': self.zipher_api_key,
+            'User-Agent': USER_AGENT,
+            **client_info_headers(enabled=self.config.send_client_info),
         }
         response = requests.get(
             url=self.config.zipher_get_optimized_tasks_api_endpoint,

{zipher_sdk-0.4.6 → zipher_sdk-0.4.7}/zipher/models.py

@@ -28,6 +28,9 @@ class Config(BaseModel, extra='forbid', use_enum_values=True):
     zipher_config_fetcher_api_endpoint: str = 'https://api.zipher.cloud/default/get_clusterspec'
     zipher_get_optimized_tasks_api_endpoint: str = 'https://api.zipher.cloud/default/get_optimized_tasks'
 
+    # Set False to stop sending the X-Zipher-Client-Info header; User-Agent is always sent.
+    send_client_info: bool = True
+
 class GetOptimizedTasksRequest(BaseModel):
     customer_id: str
     job_id: str

{zipher_sdk-0.4.6 → zipher_sdk-0.4.7/zipher_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zipher-sdk
-Version: 0.4.6
+Version: 0.4.7
 Summary: Python SDK for programmatic access to the Zipher API
 Author: Zipher Inc.
 Author-email: yoav@zipher.cloud
@@ -29,6 +29,7 @@ The Zipher SDK is a Python library for interacting with Zipher's APIs.
 - [Package Installation](#package-installation)
 - [Granting access to Zipher](#providing-zipher-with-access-to-databricks-workspace)
 - [Usage](#sdk-usage)
+- [Telemetry](#telemetry)
 
 ## Package Installation
 
@@ -223,3 +224,46 @@ optimized_tasks = client.get_optimized_tasks(job_id="my-job-id", tasks=tasks_to_
 
 # Continue with sending the optimized tasks to Databricks via the Databricks python SDK, Airflow operator, etc.
 ```
+
+## Telemetry
+
+Every request the SDK sends to Zipher's APIs carries your API key and two headers:
+
+- `User-Agent: zipher-sdk/<version>` identifies the SDK. It is always sent and is not part of the opt-out
+  telemetry below.
+- `X-Zipher-Client-Info` is the opt-out telemetry: a compact JSON object describing the environment the SDK runs in,
+  for example
+  `{"airflow":"2.10.1","arch":"x86_64","databricks_sdk":"0.102.0","os":"linux","pydantic":"2.9.0","python":"3.11.4","python_impl":"CPython","requests":"2.32.3","sdk":"0.4.7"}`.
+  We collect it to know which Python, Airflow and databricks-sdk versions our customers run, so we know what to
+  support.
+
+You can stop the SDK from sending `X-Zipher-Client-Info` (and from collecting it) by passing
+`send_client_info=False` in the client config:
+
+```python
+from zipher import Client, Config
+
+client = Client(customer_id="...", config=Config(send_client_info=False))
+```
+
+or by setting `DO_NOT_TRACK=1` (`true` and `yes` also work) in the environment.
+
+Fields of `X-Zipher-Client-Info` (a field is left out when it does not apply, e.g. Airflow is not installed, and set to `"error"` when it applies
+but could not be read):
+
+| Field | Contents |
+| --- | --- |
+| `sdk` | Version of `zipher-sdk` (`unknown` when running from a source checkout) |
+| `python` | Python version, e.g. `3.11.4` |
+| `python_impl` | Python implementation, e.g. `CPython` |
+| `os` | Operating system name, e.g. `linux`, `darwin`, `windows` |
+| `arch` | CPU architecture, e.g. `x86_64`, `arm64` |
+| `databricks_sdk` | Installed `databricks-sdk` version |
+| `requests` | Installed `requests` version |
+| `pydantic` | Installed `pydantic` version |
+| `airflow` | Installed `apache-airflow` version, when Airflow is installed |
+| `dbr` | Databricks Runtime version (the `DATABRICKS_RUNTIME_VERSION` environment variable), when running on Databricks |
+
+Package versions are read from the installed package metadata; the packages themselves are not imported.
+No hostnames, usernames, workspace IDs, job contents or credentials are sent. Values are limited to 64 ASCII
+characters.

{zipher_sdk-0.4.6 → zipher_sdk-0.4.7}/zipher_sdk.egg-info/SOURCES.txt

@@ -6,7 +6,13 @@ tests/test_client.py
 tests/test_acl/__init__.py
 tests/test_acl/sample_job.py
 tests/test_acl/test_acl.py
+tests/unit/__init__.py
+tests/unit/conftest.py
+tests/unit/test_client.py
+tests/unit/test_telemetry.py
 zipher/__init__.py
+zipher/_telemetry.py
+zipher/_version.py
 zipher/cli.py
 zipher/client.py
 zipher/exceptions.py

zipher_sdk-0.4.6/zipher/__init__.py

@@ -1,2 +0,0 @@
-from .client import Client
-from .models import Config