datamasque-python 1.0.0__py3-none-any.whl

datamasque/client/runs.py

@@ -0,0 +1,189 @@
+import logging
+import re
+
+from datamasque.client.base import BaseClient
+from datamasque.client.exceptions import (
+    FailedToStartError,
+    InvalidLibraryError,
+    InvalidRulesetError,
+    RunNotCancellableError,
+)
+from datamasque.client.models.runs import MaskingRunRequest, RunId, RunInfo, UnfinishedRun
+from datamasque.client.models.status import MaskingRunStatus
+
+logger = logging.getLogger(__name__)
+
+
+class RunClient(BaseClient):
+    """Masking-run and run-report API methods. Mixed into `DataMasqueClient`."""
+
+    def get_run_log(self, run_id: RunId) -> str:
+        """Returns the full log output of the specified run."""
+
+        response = self.make_request("GET", f"api/runs/{run_id}/log/")
+        return response.text
+
+    def get_sdd_report(self, run_id: RunId) -> str:
+        """Returns the sensitive-data-discovery report generated by the specified run."""
+
+        response = self.make_request("GET", f"api/runs/{run_id}/sdd-report/")
+        return response.text
+
+    def get_run_report(self, run_id: RunId) -> str:
+        """
+        Retrieves the run report for the specified run.
+
+        Args:
+            run_id: The ID of the run
+
+        Returns:
+            str: The run report content
+        """
+
+        response = self.make_request("GET", f"api/runs/{run_id}/run-report/")
+        return response.text
+
+    def get_db_discovery_result_report(self, run_id: RunId, include_selection_column: bool = True) -> str:
+        """
+        Returns the database-discovery result report for the specified run as CSV.
+
+        When `include_selection_column` is true (the default),
+        the CSV includes a `selected` column suitable for feeding back into ruleset generation.
+        """
+
+        url = f"api/runs/{run_id}/db-discovery-results/report/"
+        params = None if include_selection_column else {"include_selection_column": "false"}
+        response = self.make_request("GET", url, params=params)
+        return response.text
+
+    def get_unfinished_runs(self) -> dict[str, UnfinishedRun]:
+        """Queries the DM instance for unfinished runs, and returns them organised by connection name."""
+
+        unfinished_runs = {}
+        for status in (
+            MaskingRunStatus.queued,
+            MaskingRunStatus.running,
+            MaskingRunStatus.validating,
+            MaskingRunStatus.cancelling,
+        ):
+            response = self.make_request(
+                "GET",
+                "api/runs/",
+                params={
+                    "connection_ruleset_name": "",
+                    "ruleset_name": "",
+                    "run_status": status.value,
+                    "limit": 1,
+                    "offset": 0,
+                },
+            )
+            data = response.json()
+
+            for run in data.get("results", []):
+                unfinished_run = UnfinishedRun.model_validate(run)
+
+                unfinished_runs[unfinished_run.source_connection.name] = unfinished_run
+                if unfinished_run.destination_connection is not None:
+                    unfinished_runs[unfinished_run.destination_connection.name] = unfinished_run
+
+        return unfinished_runs
+
+    def start_masking_run(self, run_info: MaskingRunRequest) -> RunId:
+        """
+        Starts a masking run with the given configuration and returns its run ID.
+
+        Args:
+            run_info: A `MaskingRunRequest` describing the run configuration.
+
+        Raises:
+            InvalidRulesetError: the run failed to start because the ruleset is invalid.
+            InvalidLibraryError: the run failed to start because a referenced library is invalid.
+            FailedToStartError: the run failed to start for any other reason.
+        """
+
+        data = run_info.model_dump(exclude_none=True, mode="json")
+        response = self.make_request("POST", "/api/runs/", data=data, require_status_check=False)
+        run_data = response.json() if response.content else {}
+
+        if response.status_code == 201:
+            logger.info(
+                "Run %s started successfully using ruleset %s",
+                run_data["id"],
+                run_data["name"],
+            )
+            return RunId(run_data["id"])
+
+        if isinstance(run_data, dict) and "ruleset" in run_data:
+            logger.error("Run failed to start: %s", run_data)
+
+            try:
+                errors = run_data["ruleset"][0]
+            except (TypeError, IndexError, KeyError):
+                pass  # fall through to generic FailedToStartError below
+            else:
+                if errors.lower().startswith("cannot start run"):
+                    # Attempt to parse the library name out from a string like:
+                    # `Library "abc" is invalid.`
+                    # Trailing space is deliberate
+                    # to match the end of the library name and the start of the error description that follows.
+                    if matches := re.search(r'library "(.*)" ', errors, flags=re.IGNORECASE):
+                        raise InvalidLibraryError(
+                            f'Run failed to start due to invalid library named "{matches.group(1)}".',
+                            response=response,
+                        )
+                    elif "library" in errors.lower():
+                        raise InvalidLibraryError(
+                            "Run failed to start due to invalid library.",
+                            response=response,
+                        )
+
+                    raise InvalidRulesetError(
+                        f'Run failed to start due to invalid ruleset named "{data.get("name")}".',
+                        response=response,
+                    )
+
+        raise FailedToStartError(
+            f'Run failed to start using ruleset named "{data.get("name")}" '
+            f"(server responded with status {response.status_code}: {response.text}).",
+            response=response,
+        )
+
+    def get_run_info(self, run_id: RunId) -> RunInfo:
+        """Returns the full run record for the specified run ID."""
+
+        response = self.make_request("GET", f"/api/runs/{run_id}/")
+        return RunInfo.model_validate(response.json())
+
+    def cancel_run(self, run_id: RunId) -> RunInfo:
+        """
+        Requests cancellation of the specified run and returns the updated run record.
+
+        On success the run transitions to the `cancelling` status;
+        callers can poll `get_run_info` to observe the final `cancelled` status.
+
+        Args:
+            run_id: The ID of the run to cancel.
+
+        Returns:
+            The updated `RunInfo` for the run,
+            with `status` set to `cancelling`.
+
+        Raises:
+            RunNotCancellableError: the run is not in a state that can be cancelled
+                (typically because it is already finished, failed, or cancelling).
+            DataMasqueApiError: any other non-2xx response.
+        """
+
+        response = self.make_request(
+            "POST",
+            f"/api/runs/{run_id}/cancel/",
+            require_status_check=False,
+        )
+
+        if response.status_code == 400:
+            # The admin server returns 400 with a `RunLifecycleError` payload
+            # when the run cannot be cancelled in its current state.
+            raise RunNotCancellableError(f"Run {run_id} cannot be cancelled in its current state.")
+
+        self._raise_for_status(response)
+        return RunInfo.model_validate(response.json())

datamasque/client/settings.py

@@ -0,0 +1,76 @@
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+from datamasque.client.base import BaseClient
+from datamasque.client.exceptions import DataMasqueUserError
+
+
+class SettingsClient(BaseClient):
+    """Server-wide settings, log retrieval, and admin-install bootstrap. Mixed into `DataMasqueClient`."""
+
+    def retrieve_application_logs(self, output_path: Path) -> None:
+        """Downloads the DataMasque application logs archive to `output_path`."""
+
+        response = self.make_request("GET", path="/api/logs/download/", params={"log_service": "application"})
+
+        with open(output_path, "wb") as application_logs_output:
+            for chunk in response.iter_content(chunk_size=4096):
+                application_logs_output.write(chunk)
+
+    def set_locality(self, locality: str) -> None:
+        """Sets the server-wide locality used for ruleset generation and Jinja2 interpolation of ruleset YAML."""
+
+        self.make_request("PATCH", path="api/settings/", data={"locality": locality})
+
+    def admin_install(
+        self,
+        email: str,
+        username: str = "admin",
+        password: Optional[str] = None,
+        allowed_hosts: Optional[list[str]] = None,
+    ) -> None:
+        """
+        Performs the first-time admin-install bootstrap on a fresh DataMasque server.
+
+        Creates the initial admin account and configures the server's allowed-hosts list.
+        This endpoint is unauthenticated and can only be called once per server;
+        subsequent calls will fail.
+
+        If `password` is not given, the client's configured password is used.
+        If `allowed_hosts` is not given, it defaults to the following list:
+
+          - `localhost`
+          - `127.0.0.1`
+          - the client's configured hostname (from `base_url`).
+        """
+
+        if password is None:
+            password = self.password
+            if password is None:
+                # Clients constructed with `token_source` instead of a password
+                # have no fallback to use here; require an explicit `password` argument.
+                raise DataMasqueUserError(
+                    "`admin_install` requires a `password` argument when the client was constructed without one."
+                )
+
+        if allowed_hosts is None:
+            allowed_hosts = ["localhost", "127.0.0.1"]
+            dm_hostname = urlparse(self.base_url).hostname
+            if dm_hostname and dm_hostname not in allowed_hosts:
+                allowed_hosts.append(dm_hostname)
+
+        data = {
+            "email": email,
+            "username": username,
+            "password": password,
+            "re_password": password,
+            "allowed_hosts": allowed_hosts,
+        }
+
+        self.make_request(
+            "POST",
+            "/api/users/admin-install/",
+            data=data,
+            requires_authorization=False,
+        )

datamasque/client/users.py

@@ -0,0 +1,96 @@
+from typing import Optional
+
+from datamasque.client.base import BaseClient
+from datamasque.client.exceptions import DataMasqueException, DataMasqueUserError
+from datamasque.client.models.user import User, UserId, UserRole
+
+
+class UserClient(BaseClient):
+    """User CRUD API methods. Mixed into `DataMasqueClient`."""
+
+    def list_users(self) -> list[User]:
+        """Returns all active users configured on the server."""
+
+        users = []
+        for user_data in self.make_request("GET", "/api/users/").json():
+            if user_data.get("is_active", False):
+                users.append(User.model_validate(user_data))
+
+        return users
+
+    def create_or_update_user(self, user: User, new_password: Optional[str] = None) -> User:
+        """
+        Creates or updates the user.
+
+        An update will be performed if `user.id` is set, otherwise a create.
+        To also set the user's password,
+        put the old password in the user's `password` field (for an existing user)
+        and pass the new password in the `new_password` parameter.
+        Returns the same User object but with the id and password fields populated.
+        """
+
+        if not user.roles:
+            raise DataMasqueUserError("User must have at least one role")
+        if UserRole.ruleset_library_manager in user.roles and UserRole.mask_builder not in user.roles:
+            raise DataMasqueUserError("`ruleset_library_manager` role requires `mask_builder` role")
+
+        if user.id is None:
+            temp_password = User.generate_password()
+
+            data = user.model_dump(exclude_none=True, by_alias=True, mode="json") | {
+                "password": temp_password,
+                "re_password": temp_password,
+            }
+            resp = self.make_request("POST", "/api/users/", data=data).json()
+            user.id = resp["id"]
+            user.password = temp_password
+        else:
+            self.make_request(
+                "PATCH",
+                f"/api/users/{user.id}/",
+                data=user.model_dump(exclude_none=True, by_alias=True, mode="json"),
+            ).json()
+
+        if new_password:
+            self.make_request(
+                "PATCH",
+                f"/api/users/{user.id}/",
+                data={
+                    "current_password": user.password,
+                    "new_password": new_password,
+                    "re_new_password": new_password,
+                },
+            )
+            user.password = new_password
+
+        return user
+
+    def reset_password_for_user(self, user: User) -> str:
+        """
+        Resets the user's password.
+
+        The temporary password is stored on the User object and also returned.
+        """
+
+        if user.id is None:
+            raise DataMasqueUserError("User must be created first")
+
+        resp = self.make_request("POST", f"/api/users/{user.id}/reset-password/").json()
+        user.password = resp["password"]
+        return user.password
+
+    def delete_user_by_id_if_exists(self, user_id: UserId) -> None:
+        """Deletes the user with the given ID. No-op if the user does not exist."""
+
+        self._delete_if_exists(f"/api/users/{user_id}/")
+
+    def delete_user_by_username_if_exists(self, username: str) -> None:
+        """Deletes the user with the given username. No-op if the user does not exist."""
+
+        all_users = self.list_users()
+        users_matching_username = [u for u in all_users if u.username == username]
+        for user in users_matching_username:
+            if user.id is None:
+                raise DataMasqueException(f'Server returned a user named "{user.username}" without an `id`.')
+
+            self.delete_user_by_id_if_exists(user.id)

datamasque_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: datamasque-python
+Version: 1.0.0
+Summary: Official Python client for the DataMasque data-masking API.
+Project-URL: Homepage, https://datamasque.com/
+Project-URL: Documentation, https://datamasque-python.readthedocs.io/
+Project-URL: Repository, https://github.com/datamasque/datamasque-python
+Project-URL: Issues, https://github.com/datamasque/datamasque-python/issues
+Author: DataMasque Ltd
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: api-client,data-masking,data-privacy,datamasque,synthetic-data,test-data
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: requests>=2.31.0
+Description-Content-Type: text/x-rst
+
+=================
+datamasque-python
+=================
+
+Official Python client for the `DataMasque <https://datamasque.com/>`_ platform.
+
+DataMasque is a data masking platform that replaces sensitive data with realistic but non-production values,
+so teams can use production-shaped data in non-production environments without exposing PII.
+This package is a thin Python wrapper around the DataMasque server's HTTP API,
+covering connection management, ruleset and ruleset-library CRUD,
+masking run lifecycle, discovery results, user administration, and license management.
+
+Installation
+============
+
+.. code-block:: console
+
+    pip install datamasque-python
+
+Python 3.9 or newer is required.
+
+Quickstart
+==========
+
+.. code-block:: python
+
+    from datamasque.client import DataMasqueClient
+    from datamasque.client.models.dm_instance import DataMasqueInstanceConfig
+
+    config = DataMasqueInstanceConfig(
+        base_url="https://datamasque.example.com",
+        username="api_user",
+        password="api_password",
+    )
+    client = DataMasqueClient(config)
+    client.authenticate()
+
+    for connection in client.list_connections():
+        print(connection.name)
+
+Authentication is performed on the first request if ``authenticate()`` is not called explicitly,
+and is automatically retried once on a 401 response.
+``client.healthcheck()`` is available as a lightweight readiness probe that does not consume credentials.
+
+Error handling
+==============
+
+All methods raise subclasses of ``DataMasqueException`` on failure:
+
+- ``DataMasqueApiError`` —
+  the server responded with a non-2xx status (excluding 502).
+  The triggering ``Response`` is available on the ``.response`` attribute.
+- ``DataMasqueNotReadyError`` —
+  the server responded with 502,
+  typically because it is still starting up.
+- ``DataMasqueTransportError`` —
+  the request failed before any response was received
+  (connection refused, timeout, DNS failure, SSL handshake failure, etc.).
+- ``FailedToStartError`` / ``InvalidRulesetError`` / ``InvalidLibraryError`` —
+  raised by ``start_masking_run`` when the server rejects the run.
+- ``DataMasqueUserError`` —
+  raised by user-management methods when the input is invalid.
+
+Documentation
+=============
+
+- All classes and functions have docstrings and type hints.
+- Compiled docs are hosted at `Read the Docs: datamasque-python <https://datamasque-python.readthedocs.io/>`_.
+- Documentation for the DataMasque product, including a full API reference,
+  can be found on the `DataMasque portal <https://portal.datamasque.com/portal/documentation/>`_.
+
+Contributing
+============
+
+See `CONTRIBUTING.rst <CONTRIBUTING.rst>`_ for development setup, testing, and the pull request flow.
+
+License
+=======
+
+Apache License 2.0.
+See `LICENSE <LICENSE>`_.

datamasque_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+datamasque/client/__init__.py,sha256=jg4BxNWHon9V90a8-dhlzKldhkmlRPku6cFfk1IQ_Vs,5406
+datamasque/client/base.py,sha256=he-ObABs_rpXV_KSMmrtJ73D-9lb0giAK029lN5qB3Y,11817
+datamasque/client/connections.py,sha256=EFinx8fJRme0mTxuWY3d29UnmUFbsQhMaUQT0Ma2PK4,2885
+datamasque/client/discovery.py,sha256=uA8h6vRqsxSAzSAV9bebJwU47XINlaVy7V1nTYDiaCM,12634
+datamasque/client/dmclient.py,sha256=OPYMzc57gUHPs6iL_J2DYp06MfOaabpTlISmnNCpqS4,1553
+datamasque/client/exceptions.py,sha256=F9FYCxP-ERXkVD1L3yh_rWqcW3IsPL-c-Ic4qMYoGnw,2542
+datamasque/client/files.py,sha256=5Gzel4aLby8T7ncOIV6wtgVbFEk0eaEy7wxohh9u0zE,3468
+datamasque/client/ifm.py,sha256=K4n9q-8f2wsmxnKlE-jkn9zl40iC9RGAw2tRB0mAtyM,11737
+datamasque/client/license.py,sha256=pluYaSU168OC6_laB9bM9H3Vuuxs8wa9gujCJvtoJCk,1392
+datamasque/client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+datamasque/client/ruleset_libraries.py,sha256=tyN--cndzG0gwFnHY9fDtObTLzGsK0wrV5lxxjRP72g,6868
+datamasque/client/rulesets.py,sha256=2Zh6QUihZ8p3dNT6QbaWuxvMk-Whp67JUj8UxqeRYUY,2407
+datamasque/client/runs.py,sha256=ZPSkkuyqMiwy7dLbWZ1PAEKaesKLeNRX7xEJGfzieVg,7427
+datamasque/client/settings.py,sha256=Ui8AyR2XdoW8MZ9FIrGn2jm8DLzUGWIL8i2DOTvu7hc,2898
+datamasque/client/users.py,sha256=VCUo2CJyOw4-aO_3mp_w_0BcSoa6-h1HcReMcAMyumw,3701
+datamasque/client/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+datamasque/client/models/connection.py,sha256=HmpojGKQpL9BpDCkLGPNInyBwc98QTpeNKVnqcuHNOw,14680
+datamasque/client/models/data_selection.py,sha256=406yyUZ5NmLBSql2lYM1gsTWY5GWmnutmF-DjznAoLc,1904
+datamasque/client/models/discovery.py,sha256=BawKusPuhyt0gRRnWKYf-ZKF7V54GxkhgYIrEQ6XkOs,7283
+datamasque/client/models/dm_instance.py,sha256=yjjpHZJTFhJp3lAinTEffgKrxnadrJys1EuhO77wQcA,1561
+datamasque/client/models/files.py,sha256=OaWVD-AX77vvaN_qxB6Uzn2HRasb7wNo-6QAvRzV3og,2381
+datamasque/client/models/ifm.py,sha256=j0Ef2BZYTk6MNZO6HS6mW0qWs1_wWD9PlUP_Y6WyBQI,5563
+datamasque/client/models/license.py,sha256=OqIn4Sx3ATBStgt5KNiCOBChTTFYLBsyGj7inAl8oB4,2113
+datamasque/client/models/pagination.py,sha256=egg9aO2cf6KUDwDANPu5RxpJbdRKdwUdCQAtusnuf1c,651
+datamasque/client/models/ruleset.py,sha256=tf5j9ih3B0uEF4yPTnyCsLblFWzH-t9KnvJWuyJaiCs,1256
+datamasque/client/models/ruleset_library.py,sha256=gIqb6yn4-f9i2OydOLk1cd0zId9nGv5l_yUZwFHZ1aA,652
+datamasque/client/models/runs.py,sha256=oVYo9jp9s5LjWts0LKsYpX3HUBmrVwuuzDqFtQmTjvo,5673
+datamasque/client/models/status.py,sha256=rjH6YSwAHoOUaUCADwvMhuKd0ygT0c2w2Ek5SV8PWD8,1984
+datamasque/client/models/user.py,sha256=UGAUzgJkf78m24_zFXXoA99zdut48BXkX_ivV8yq1Vc,2043
+datamasque_python-1.0.0.dist-info/METADATA,sha256=XmCNVYLLUjAKQgad5KXfo-zC7Hp17g0w-urVdbxmgZ8,4187
+datamasque_python-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+datamasque_python-1.0.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+datamasque_python-1.0.0.dist-info/RECORD,,

datamasque_python-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any