datamasque-python 1.0.2__tar.gz → 1.0.4__tar.gz

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/HISTORY.rst

@@ -2,6 +2,20 @@
 History
 =======
 
+1.0.4 (2026-06-09)
+------------------
+
+* Added ``informix`` to ``DatabaseType`` enum.
+* Pool HTTP connections via a per-client ``requests.Session`` so TCP/TLS connections are reused across calls. Note: a client is not thread-safe; construct one per worker.
+* Send a descriptive ``User-Agent`` identifying the SDK name, version, Python interpreter, and OS.
+* Only re-authenticate and replay on a ``401`` for requests that actually sent a token (gate the retry on ``requires_authorization``).
+
+1.0.3 (2026-05-27)
+------------------
+
+* Added ``databricks`` to ``DatabaseType`` enum.
+* Removed ``DatabricksDeltaS3ConnectionConfig``.
+
 1.0.2 (2026-05-14)
 ------------------
 

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datamasque-python
-Version: 1.0.2
+Version: 1.0.4
 Summary: Official Python client for the DataMasque data-masking API.
 Project-URL: Homepage, https://datamasque.com/
 Project-URL: Documentation, https://datamasque-python.readthedocs.io/

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/datamasque/client/__init__.py

@@ -30,7 +30,7 @@ from datamasque.client.models.connection import (
     ConnectionId,
     DatabaseConnectionConfig,
     DatabaseType,
-    DatabricksDeltaS3ConnectionConfig,
+    DatabricksConnectionConfig,
     DynamoConnectionConfig,
     FileConnectionConfig,
     MongoConnectionConfig,
@@ -129,7 +129,7 @@ __all__ = [
     "DataMasqueUserError",
     "DatabaseConnectionConfig",
     "DatabaseType",
-    "DatabricksDeltaS3ConnectionConfig",
+    "DatabricksConnectionConfig",
     "DiscoveryMatch",
     "DynamoConnectionConfig",
     "FailedToStartError",

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/datamasque/client/base.py

@@ -1,7 +1,10 @@
 import logging
+import platform
+import sys
 import warnings
 from contextlib import contextmanager
 from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
 from io import BufferedIOBase, BytesIO, TextIOBase
 from pathlib import Path
 from typing import Any, Callable, Iterator, Optional, Type, TypeVar, Union
@@ -24,6 +27,44 @@ logger = logging.getLogger(__name__)
 FileOrContent = Union[str, bytes, TextIOBase, BufferedIOBase, Path]
 _T = TypeVar("_T", bound=BaseModel)
 
+
+def _build_user_agent() -> str:
+    """
+    Identify ourselves to the DataMasque server in access logs and audit trails.
+
+    Default `python-requests/x.y.z` is anonymous; this surfaces the SDK name +
+    version, Python interpreter, and OS so operators can correlate API traffic
+    with a specific SDK release (e.g. when triaging a bug report).
+    """
+
+    try:
+        sdk_version = version("datamasque-python")
+    except PackageNotFoundError:
+        # Source checkouts without installed metadata.
+        sdk_version = "dev"
+    py = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    return f"datamasque-python/{sdk_version} (Python/{py}; {platform.system()}/{platform.release()})"
+
+
+USER_AGENT = _build_user_agent()
+
+
+def _build_session(verify_ssl: bool) -> requests.Session:
+    """
+    Build a configured `requests.Session` for one client's lifetime.
+
+    Centralises the `User-Agent` and `verify` defaults so every call site
+    inherits them automatically — keeping the per-call code free of
+    boilerplate and removing the risk of forgetting either flag on a new
+    endpoint.
+    """
+
+    session = requests.Session()
+    session.headers["User-Agent"] = USER_AGENT
+    session.verify = verify_ssl
+    return session
+
+
 # Substrings (case-insensitive) that mark a key whose value should be redacted
 # before logging on an error path, so that passwords, API tokens, and similar secrets don't
 # end up in user-visible logs when a request fails.
@@ -71,6 +112,15 @@ class BaseClient:
 
     Holds the connection config, cached auth token, and the core `make_request` dispatcher
     used by all per-feature mixins that compose `DataMasqueClient`.
+
+    Uses a single `requests.Session` for the lifetime of the client so that
+    per-host TCP / TLS connections are pooled across calls (paginated list
+    endpoints and tight polling loops benefit most). Session-wide defaults
+    (`User-Agent`, `verify`) are set once on construction; per-call headers
+    like `Authorization` are merged at request time.
+
+    `requests.Session` is not thread-safe; do not share a client between
+    threads. Construct one per worker.
     """
 
     token: str = ""
@@ -86,6 +136,7 @@ class BaseClient:
         self.password = connection_config.password
         self.verify_ssl = connection_config.verify_ssl
         self.token_source = connection_config.token_source
+        self._session = _build_session(self.verify_ssl)
 
     @contextmanager
     def _maybe_suppress_insecure_warning(self) -> Iterator[None]:
@@ -186,28 +237,32 @@ class BaseClient:
         url = urljoin(self.base_url, path)
 
         def send() -> Response:
-            headers: Optional[dict] = {"Authorization": self.token} if requires_authorization else None
+            headers = {"Authorization": self.token} if requires_authorization else None
             try:
                 with self._maybe_suppress_insecure_warning():
                     if files:
                         files_payload = {f.field_name: (f.filename, f.content, f.content_type or "") for f in files}
-                        return requests.request(
+                        return self._session.request(
                             method,
                             url,
                             data=data,
                             params=params,
                             headers=headers,
                             files=files_payload,
-                            verify=self.verify_ssl,
                         )
-                    return requests.request(
-                        method, url, json=data, params=params, headers=headers, verify=self.verify_ssl
-                    )
+                    return self._session.request(method, url, json=data, params=params, headers=headers)
             except requests.RequestException as e:
                 raise DataMasqueTransportError(f"Failed to reach DataMasque server at {url}: {e}") from e
 
         response = send()
-        if response.status_code == 401:
+        if response.status_code == 401 and requires_authorization:
+            # Token-expiry recovery: re-auth and replay. Only meaningful when the
+            # caller actually sent a token; on `requires_authorization=False`
+            # calls a 401 means the server itself is rejecting anonymous access
+            # (e.g. admin-install on an already-configured instance), and
+            # re-authing with whatever creds the client happens to hold would
+            # both misdiagnose the failure and emit a misleading
+            # "credentials are incorrect" error to the user.
             logger.debug("Re-authenticating")
             self.authenticate()
             # Reset file pointers so the retry doesn't send empty files

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/datamasque/client/ifm.py

@@ -17,7 +17,7 @@ import requests
 from pydantic import BaseModel
 from requests import Response
 
-from datamasque.client.base import suppress_insecure_warning_if_needed
+from datamasque.client.base import _build_session, suppress_insecure_warning_if_needed
 from datamasque.client.exceptions import (
     DataMasqueApiError,
     DataMasqueNotReadyError,
@@ -82,6 +82,9 @@ class DataMasqueIfmClient:
         self.password = connection_config.password
         self.verify_ssl = connection_config.verify_ssl
         self.token_source = connection_config.token_source
+        # One session for both admin-server (JWT login/refresh) and IFM (data plane)
+        # traffic -- different hosts, but a single session handles per-host pooling.
+        self._session = _build_session(self.verify_ssl)
 
     def authenticate(self) -> None:
         """Obtain an access (and refresh) token from the admin server, or via `token_source`."""
@@ -95,10 +98,9 @@ class DataMasqueIfmClient:
         login_url = urljoin(self.admin_server_base_url, "/api/auth/jwt/login/")
         try:
             with self._maybe_suppress_insecure_warning():
-                response = requests.post(
+                response = self._session.post(
                     login_url,
                     json={"username": self.username, "password": self.password},
-                    verify=self.verify_ssl,
                 )
         except requests.RequestException as e:
             raise DataMasqueTransportError(f"Failed to reach admin server at {login_url}: {e}") from e
@@ -122,10 +124,9 @@ class DataMasqueIfmClient:
         refresh_url = urljoin(self.admin_server_base_url, "/api/auth/jwt/refresh/")
         try:
             with self._maybe_suppress_insecure_warning():
-                response = requests.post(
+                response = self._session.post(
                     refresh_url,
                     json={"refresh": self.refresh_token},
-                    verify=self.verify_ssl,
                 )
         except requests.RequestException as e:
             raise DataMasqueTransportError(f"Failed to reach admin server at {refresh_url}: {e}") from e
@@ -187,13 +188,12 @@ class DataMasqueIfmClient:
         def send() -> Response:
             try:
                 with self._maybe_suppress_insecure_warning():
-                    return requests.request(
+                    return self._session.request(
                         method,
                         url,
                         json=json_body,
                         params=params,
                         headers={"Authorization": f"Bearer {self.access_token}"},
-                        verify=self.verify_ssl,
                     )
             except requests.RequestException as e:
                 raise DataMasqueTransportError(f"Failed to reach IFM server at {url}: {e}") from e

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/datamasque/client/models/connection.py

@@ -45,6 +45,8 @@ class DatabaseType(Enum):
     snowflake = "snowflake"
     mongodb = "mongodb"
     databricks_lakebase = "databricks_lakebase"
+    databricks = "databricks"
+    informix = "informix"
 
 
 class SnowflakeStageLocation(str, Enum):
@@ -280,6 +282,8 @@ class DatabaseConnectionConfig(ConnectionConfig):
             raise ValueError("For Snowflake, use the SnowflakeConnectionConfig class instead")
         if self.database_type is DatabaseType.mongodb:
             raise ValueError("For MongoDB, use the MongoConnectionConfig class instead")
+        if self.database_type is DatabaseType.databricks:
+            raise ValueError("For Databricks SQL Warehouse, use the DatabricksConnectionConfig class instead")
         return self
 
     mask_type: Literal["database"] = "database"
@@ -391,19 +395,36 @@ class MountedShareConnectionConfig(FileConnectionConfig):
     type: Literal["mounted_share_connection"] = "mounted_share_connection"
 
 
-class DatabricksDeltaS3ConnectionConfig(FileConnectionConfig):
-    """Connection configuration for Databricks Delta tables stored in S3."""
+class DatabricksConnectionConfig(ConnectionConfig):
+    """Connection configuration for a Databricks SQL Warehouse."""
 
-    type: Literal["databricks_delta_s3_connection"] = "databricks_delta_s3_connection"
-    bucket: str = ""
-    iam_role_arn: Optional[str] = None
+    server_hostname: str
+    http_path: str
+    access_token: Optional[str] = None
+    catalog: str
+    db_schema: Optional[str] = Field(default=None, alias="schema")
+    is_read_only: bool = False
+    version: str = "1.0"
+
+    mask_type: Literal["database"] = "database"
+    db_type: Literal["databricks"] = "databricks"
+
+    @property
+    def database_type(self) -> DatabaseType:
+        return DatabaseType.databricks
+
+    @model_validator(mode="before")
+    @classmethod
+    def _strip_encrypted_token(cls, data: dict) -> dict:
+        if isinstance(data, dict):
+            data.pop("access_token_encrypted", None)
+        return data
 
 
 FILE_TYPE_MAP: dict[str, type[FileConnectionConfig]] = {
     "s3_connection": S3ConnectionConfig,
     "azure_blob_connection": AzureConnectionConfig,
     "mounted_share_connection": MountedShareConnectionConfig,
-    "databricks_delta_s3_connection": DatabricksDeltaS3ConnectionConfig,
 }
 
 DB_TYPE_MAP: dict[str, type[ConnectionConfig]] = {
@@ -411,6 +432,7 @@ DB_TYPE_MAP: dict[str, type[ConnectionConfig]] = {
     DatabaseType.mongodb.value: MongoConnectionConfig,
     DatabaseType.snowflake.value: SnowflakeConnectionConfig,
     DatabaseType.mssql_linked.value: MssqlLinkedServerConnectionConfig,
+    DatabaseType.databricks.value: DatabricksConnectionConfig,
     # others use the default `DatabaseConnectionConfig`
 }
 

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "datamasque-python"
-version = "1.0.2"
+version = "1.0.4"
 description = "Official Python client for the DataMasque data-masking API."
 authors = [
     { name = "DataMasque Ltd" },

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.0.2
+current_version = 1.0.4
 commit = True
 tag = True
 

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/tests/test_base.py

@@ -10,6 +10,7 @@ import requests_mock
 from urllib3.exceptions import InsecureRequestWarning
 
 from datamasque.client import DataMasqueClient, RunId
+from datamasque.client.base import USER_AGENT
 from datamasque.client.exceptions import (
     DataMasqueApiError,
     DataMasqueNotReadyError,
@@ -74,8 +75,12 @@ def test_healthcheck_transport_failure(client):
 
 
 @pytest.mark.parametrize("verify_ssl", [True, False])
-def test_make_request_verify_ssl_true_by_default(config, verify_ssl):
-    """Verifies SSL setting is passed through to the `requests` call."""
+def test_session_verify_reflects_config(config, verify_ssl):
+    """
+    `verify_ssl` is applied to the client's `requests.Session` once at construction.
+
+    Every outgoing call then inherits it without per-call boilerplate.
+    """
     config_with_ssl = DataMasqueInstanceConfig(
         base_url=config.base_url,
         username=config.username,
@@ -84,24 +89,14 @@ def test_make_request_verify_ssl_true_by_default(config, verify_ssl):
     )
     client = DataMasqueClient(config_with_ssl)
 
-    with patch(
-        "datamasque.client.base.requests.request",
-        return_value=make_ok_response(),
-    ) as mock_request:
-        client.make_request("GET", "/api/test/")
-
-    _, kwargs = mock_request.call_args
-    assert kwargs["verify"] is verify_ssl
+    assert client._session.verify is verify_ssl
 
 
 def test_make_request_verify_ssl_true_does_not_touch_global_warning_filter(client):
     """With `verify_ssl=True`, the client should not modify `warnings.filters`."""
     filters_before = list(warnings.filters)
 
-    with patch(
-        "datamasque.client.base.requests.request",
-        return_value=make_ok_response(),
-    ):
+    with patch.object(client._session, "request", return_value=make_ok_response()):
         client.make_request("GET", "/api/test/")
 
     assert warnings.filters == filters_before
@@ -125,10 +120,7 @@ def test_make_request_verify_ssl_false_suppresses_warning_locally(config):
 
     with warnings.catch_warnings(record=True) as captured:
         warnings.simplefilter("always")  # ensure we'd otherwise see the warning
-        with patch(
-            "datamasque.client.base.requests.request",
-            side_effect=raise_insecure_warning_then_respond,
-        ):
+        with patch.object(client._session, "request", side_effect=raise_insecure_warning_then_respond):
             client.make_request("GET", "/api/test/")
 
         # The warning raised inside the request call was suppressed by the client.
@@ -289,6 +281,68 @@ def test_token_source_called_again_on_401_retry():
     assert client.token == "Token t2"
 
 
+def test_user_agent_identifies_the_sdk(client):
+    """
+    Every outgoing request must carry an SDK-identifying User-Agent header.
+
+    This lets operators attribute API traffic to a specific SDK release rather
+    than the generic `python-requests/x.y.z` default.
+    """
+    assert USER_AGENT.startswith("datamasque-python/")
+
+    with requests_mock.Mocker() as m:
+        m.get("http://test-server/api/healthcheck/", json={})
+        client.healthcheck()
+        assert m.request_history[0].headers["User-Agent"] == USER_AGENT
+
+
+def test_user_agent_sent_on_authenticated_requests(client):
+    """
+    The User-Agent must be present on authenticated calls, alongside the auth token.
+
+    It is not limited to anonymous requests.
+    """
+    client.token = "Token test-token"
+
+    with requests_mock.Mocker() as m:
+        m.get("http://test-server/api/runs/", json={"results": [], "next": None})
+        client.make_request("GET", "/api/runs/")
+        headers = m.request_history[0].headers
+        assert headers["User-Agent"] == USER_AGENT
+        assert headers["Authorization"] == "Token test-token"
+
+
+def test_401_does_not_retry_when_requires_authorization_is_false(client):
+    """
+    A 401 on an anonymous request must surface as-is, not trigger a re-auth retry.
+
+    `/api/users/admin-install/` returns 401 once any user exists -- the endpoint
+    is gated on "no user has been created yet" and DRF treats it as a normal
+    auth-required endpoint thereafter. Re-authing on that 401 would both
+    misdiagnose the failure ("login credentials are correct") and waste a
+    round-trip on a call the caller said doesn't need auth.
+    """
+    with requests_mock.Mocker() as m:
+        m.post(
+            "http://test-server/api/users/admin-install/",
+            status_code=401,
+            json={"detail": "Authentication credentials were not provided."},
+        )
+
+        with pytest.raises(DataMasqueApiError) as excinfo:
+            client.make_request(
+                "POST",
+                "/api/users/admin-install/",
+                data={"email": "x@y", "username": "x", "password": "p", "re_password": "p", "allowed_hosts": []},
+                requires_authorization=False,
+            )
+
+        assert excinfo.value.response.status_code == 401
+        # Exactly one request: no re-auth roundtrip to /api/auth/token/login/ and no replay.
+        assert m.call_count == 1
+        assert m.request_history[0].path == "/api/users/admin-install/"
+
+
 def test_token_source_callable_exception_propagates():
     """Errors from `token_source` are surfaced to the caller, not swallowed."""
 

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/tests/test_connections.py

@@ -9,7 +9,7 @@ from datamasque.client.models.connection import (
     ConnectionId,
     DatabaseConnectionConfig,
     DatabaseType,
-    DatabricksDeltaS3ConnectionConfig,
+    DatabricksConnectionConfig,
     DynamoConnectionConfig,
     MongoConnectionConfig,
     MountedShareConnectionConfig,
@@ -696,63 +696,67 @@ def test_s3_connection_model_validate_no_iam_role():
     assert conn.iam_role_arn is None
 
 
-def test_databricks_delta_s3_connection_model_validate():
+def test_databricks_connection_model_validate():
     payload = {
-        "id": "11223344-5566-7788-99aa-bbccddeeff00",
-        "name": "delta_s3",
-        "mask_type": "file",
-        "type": "databricks_delta_s3_connection",
-        "base_directory": "delta/",
-        "is_file_mask_source": True,
-        "is_file_mask_destination": False,
-        "bucket": "my-delta-bucket",
-        "iam_role_arn": "arn:aws:iam::111122223333:role/delta-role",
+        "id": "db-id-1",
+        "name": "databricks",
+        "mask_type": "database",
+        "db_type": "databricks",
+        "server_hostname": "adb-1234.azuredatabricks.net",
+        "http_path": "/sql/1.0/warehouses/abcd1234",
+        "access_token": "dapi1234",
+        "catalog": "main",
+        "schema": "default",
+        "is_read_only": False,
     }
 
-    conn = DatabricksDeltaS3ConnectionConfig.model_validate(payload)
+    conn = DatabricksConnectionConfig.model_validate(payload)
 
-    assert isinstance(conn, DatabricksDeltaS3ConnectionConfig)
-    assert conn.id == "11223344-5566-7788-99aa-bbccddeeff00"
-    assert conn.name == "delta_s3"
-    assert conn.bucket == "my-delta-bucket"
-    assert conn.base_directory == "delta/"
-    assert conn.is_file_mask_source is True
-    assert conn.is_file_mask_destination is False
-    assert conn.iam_role_arn == "arn:aws:iam::111122223333:role/delta-role"
+    assert isinstance(conn, DatabricksConnectionConfig)
+    assert conn.id == "db-id-1"
+    assert conn.server_hostname == "adb-1234.azuredatabricks.net"
+    assert conn.http_path == "/sql/1.0/warehouses/abcd1234"
+    assert conn.access_token == "dapi1234"
+    assert conn.catalog == "main"
+    assert conn.db_schema == "default"
+    assert conn.database_type is DatabaseType.databricks
 
 
-def test_databricks_delta_s3_connection_model_validate_no_iam_role():
+def test_databricks_connection_model_validate_blanks_encrypted_token():
     payload = {
-        "id": "id-delta",
-        "name": "delta_s3",
-        "mask_type": "file",
-        "type": "databricks_delta_s3_connection",
-        "base_directory": "",
-        "is_file_mask_source": True,
-        "is_file_mask_destination": False,
-        "bucket": "my-delta-bucket",
+        "id": "db-id-2",
+        "name": "databricks",
+        "mask_type": "database",
+        "db_type": "databricks",
+        "server_hostname": "adb-1234.azuredatabricks.net",
+        "http_path": "/sql/1.0/warehouses/abcd1234",
+        "access_token_encrypted": "some_base64_here",
+        "catalog": "main",
+        "is_read_only": False,
     }
 
-    conn = DatabricksDeltaS3ConnectionConfig.model_validate(payload)
-    assert conn.iam_role_arn is None
+    conn = DatabricksConnectionConfig.model_validate(payload)
+
+    assert isinstance(conn, DatabricksConnectionConfig)
+    assert conn.access_token is None
 
 
-def test_validate_connection_dispatches_databricks_delta_s3():
+def test_validate_connection_dispatches_databricks():
     payload = {
-        "id": "aabb-ccdd",
-        "name": "delta",
-        "mask_type": "file",
-        "type": "databricks_delta_s3_connection",
-        "base_directory": "",
-        "is_file_mask_source": False,
-        "is_file_mask_destination": True,
-        "bucket": "delta-bucket",
+        "id": "db-id-3",
+        "name": "databricks",
+        "mask_type": "database",
+        "db_type": "databricks",
+        "server_hostname": "adb-1234.azuredatabricks.net",
+        "http_path": "/sql/1.0/warehouses/abcd1234",
+        "catalog": "main",
+        "is_read_only": False,
     }
 
     conn = validate_connection(payload)
 
-    assert isinstance(conn, DatabricksDeltaS3ConnectionConfig)
-    assert conn.bucket == "delta-bucket"
+    assert isinstance(conn, DatabricksConnectionConfig)
+    assert conn.catalog == "main"
 
 
 def test_azure_connection_model_validate_blanks_encrypted_connection_string():

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/tests/test_ifm.py

@@ -12,6 +12,7 @@ from datamasque.client import (
     RulesetPlanPartialUpdateRequest,
     RulesetPlanUpdateRequest,
 )
+from datamasque.client.base import USER_AGENT
 from datamasque.client.exceptions import DataMasqueApiError, DataMasqueUserError
 
 ADMIN = "http://admin.test"
@@ -63,11 +64,24 @@ def test_authenticate_via_jwt_login(ifm_config):
             status_code=200,
         )
         client.authenticate()
+        assert m.request_history[0].headers["User-Agent"] == USER_AGENT
 
     assert client.access_token == "ACC"
     assert client.refresh_token == "REF"
 
 
+def test_ifm_request_carries_user_agent(authed_ifm_client):
+    """
+    Every IFM call must identify the SDK in the User-Agent header.
+
+    Covers login, refresh, and authenticated requests.
+    """
+    with requests_mock.Mocker() as m:
+        m.get(f"{IFM}/health/", json={"status": "ok"})
+        authed_ifm_client._make_request("GET", "/health/")
+        assert m.request_history[0].headers["User-Agent"] == USER_AGENT
+
+
 def test_authenticate_failure_raises_ifm_auth_error(ifm_config):
     client = DataMasqueIfmClient(ifm_config)
 

{datamasque_python-1.0.2 → datamasque_python-1.0.4}/uv.lock

@@ -428,7 +428,7 @@ toml = [
 
 [[package]]
 name = "datamasque-python"
-version = "1.0.2"
+version = "1.0.4"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },