datamasque-python 1.2.0__tar.gz → 1.2.2__tar.gz

{datamasque_python-1.2.0 → datamasque_python-1.2.2}/HISTORY.rst

@@ -2,6 +2,22 @@
 History
 =======
 
+1.2.2 (2026-07-31)
+------------------
+
+* Added ``validation_error_details`` to ``DiscoveryConfig``.
+* Added ``usage_count`` to ``DiscoveryConfigLibrary``.
+* ``create_discovery_config``, ``update_discovery_config``, ``create_discovery_config_library``, and
+  ``update_discovery_config_library`` now raise ``ValueError`` when the passed entity has no ``yaml``
+  content, instead of sending a request the server rejects.
+
+Requires server version 3.26.14
+
+1.2.1 (2026-07-30)
+------------------
+
+* Added ruleset generation configuration
+
 1.2.0 (2026-07-27)
 ------------------
 

{datamasque_python-1.2.0 → datamasque_python-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datamasque-python
-Version: 1.2.0
+Version: 1.2.2
 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.2.2/RELEASING.rst

@@ -0,0 +1,223 @@
+=========
+Releasing
+=========
+
+For DataMasque staff / maintainers of this project.
+Covers production releases to PyPI, dev releases to TestPyPI, and how downstream projects pin ``datamasque-python``.
+
+The assumed starting point is that you have a ``datamasque-python`` feature/fix PR in progress,
+and want to know how to get it pushed up to PyPI once merged,
+or how to build a test release / pin to a particular commit so you can test before merging the PR.
+
+Version numbers live in two places
+==================================
+
+Every release must update both, or CI will reject the tag.
+As part of your PR, update:
+
+1. ``pyproject.toml`` — ``[project] version``.
+   This is the version the built sdist/wheel carries,
+   and the one ``release.yml`` checks the git tag against.
+2. ``uv.lock`` — the ``version`` field of the ``datamasque-python`` package entry.
+   CI runs ``uv sync --frozen``, so a stale lock fails every job.
+
+Edit ``pyproject.toml`` by hand, then run ``uv lock`` to update the lock entry.
+Don't hand-edit ``uv.lock``.
+
+Don't update ``datamasque.client.__version__`` or ``docs/conf.py``.
+These read the installed package metadata.
+
+Updating the changelog
+======================
+
+Do this as part of your PR.
+
+``HISTORY.rst`` needs a new entry for each release to pypi.
+Add a new entry at the top, under the ``History`` heading, with the new version and today's date.
+Use short summaries of additions and changes, written with past tense and worded for a customer consumer of this library.
+For example::
+
+       1.2.2 (2026-08-05)
+       ------------------
+
+       * Added ``get_all_widgets`` API.
+       * Fixed issue where ``list_frobs`` would incorrectly raise a ``ValueError`` when using the filtering options.
+
+       Requires server version 3.26.14.
+
+Call out breaking changes explicitly,
+and note the minimum DataMasque server version if the release requires one.
+
+Releasing to PyPI
+=================
+
+1. Get your PR approved and merged.
+2. Tag the merge commit on ``main`` and push the tag::
+
+       git checkout main
+       git pull --ff-only
+       git tag v1.2.2  # or whatever is your version number
+       git push origin v1.2.2
+
+   The tag must be ``v`` + the exact ``pyproject.toml`` version.
+   ``release.yml`` triggers on ``v*.*.*`` and fails the build if the two disagree.
+   Tag only after the PR has merged, so the tag points at a commit on ``main``.
+3. The admins of the repo will get an automated email asking them to approve the deployment.
+   They can do this by visiting the Workflows page or by clicking the link in the email.
+4. Once approved, the build will appear on PyPI very quickly (around 1 minute).
+   You can verify that the release appears at https://pypi.org/project/datamasque-python/,
+   and Read the Docs has built the new tag
+   at https://datamasque-python.readthedocs.io/.
+5. Create the GitHub Release (see below).
+
+Creating the GitHub Release
+===========================
+
+Do this after the PyPI publish has succeeded,
+so the release never points at a version nobody can install.
+
+1. On the repository home page,
+   find **Releases** in the right-hand sidebar under the *About* box,
+   and click it,
+   then **Draft a new release**.
+2. **Choose a tag** — pick the existing tag you pushed as part of releasing to PyPI.
+   Don't let GitHub create a new one; the tag should already exist from the release flow.
+3. Set the target to ``main``.
+4. Title it the same as the tag, e.g. ``v1.2.2``.
+5. Paste the ``HISTORY.rst`` entry for this version into the body, converted to Markdown.
+   **Generate release notes** is a reasonable starting point for the commit list,
+   but the hand-written changelog is what users read.
+6. Leave *Set as a pre-release* unticked for a normal release.
+7. Click **Publish release**.
+
+Creating releases can also be done from the ``gh`` CLI::
+
+    gh release create v1.2.2 --title v1.2.2 --notes-file notes.md
+
+Releasing a dev build to TestPyPI
+=================================
+
+Use this to let a downstream project try an unreleased change.
+It builds from any ref and never touches PyPI.
+
+1. Push the branch you want to publish.
+   Nothing needs to be merged first.
+2. Go to *Actions* → *Release (TestPyPI)* → **Run workflow**.
+3. Fill in the inputs:
+
+   - **ref** — the branch to build from.
+   - **dev_version** — the version to publish, for example ``1.3.0.dev1``.
+
+   Use a ``.devN`` suffix.
+   The input is validated, so a plain release version like ``1.3.0`` is rejected.
+
+   **Note:** Version numbers cannot be reused. Ensure you increment the suffix each time.
+
+4. No approval is needed — unlike a PyPI release, the build publishes as soon as it passes.
+5. Verify at https://test.pypi.org/project/datamasque-python/.
+
+**Note:** Do **not** create a git tag or a GitHub Release for a TestPyPI build.
+
+Pointing a project at a release
+===============================
+
+Three ways to depend on ``datamasque-python``, depending on what you need.
+
+A released version on PyPI
+--------------------------
+
+The usual case.
+In the consuming project's ``pyproject.toml``::
+
+    dependencies = [
+        "datamasque-python==1.2.2",
+    ]
+
+Always give a version specifier.
+An unpinned ``"datamasque-python"`` means "whatever is newest at the moment this resolves",
+which is prone to breaking when someone releases a ``datamasque-python`` change before the corresponding server release.
+
+Pin exactly (``==1.2.2``) when you want every upgrade to be a deliberate, reviewed change.
+A bounded range (``>=1.2.2,<2``) is acceptable where you need a floor for a specific feature,
+but note that this project does sometimes ship breaking changes
+(e.g. 1.2.0 removed ``config_type`` from the discovery config library APIs),
+so read the ``HISTORY.rst`` entries between your current version and the new one before raising the floor.
+
+A dev build on TestPyPI
+-----------------------
+
+TestPyPI is a separate index, so it must be declared as well as pinned.
+Pin the exact dev version — TestPyPI content is disposable.
+
+**Note:** Always replace a TestPyPI pin with a real PyPI version before merging the consuming project —
+TestPyPI is not a durable index,
+and the downstream project should always use a "proper" (normal PyPI) version of ``datamasque-python`` once merged.
+
+With ``uv``::
+
+    [project]
+    dependencies = [
+        "datamasque-python==1.3.0.dev1",
+    ]
+
+    [[tool.uv.index]]
+    name = "testpypi"
+    url = "https://test.pypi.org/simple/"
+    explicit = true
+
+    [tool.uv.sources]
+    datamasque-python = { index = "testpypi" }
+
+**Note:** Be sure to include the ``explicit = true``:
+without it, ``uv`` will resolve *every* dependency against TestPyPI, which mirrors PyPI only partially.
+
+With Poetry::
+
+    [[tool.poetry.source]]
+    name = "testpypi"
+    url = "https://test.pypi.org/simple/"
+    priority = "explicit"
+
+    [tool.poetry.dependencies]
+    datamasque-python = { version = "1.3.0.dev1", source = "testpypi" }
+
+Ad hoc, without editing anything::
+
+    pip install \
+        --index-url https://test.pypi.org/simple/ \
+        --extra-index-url https://pypi.org/simple/ \
+        datamasque-python==1.3.0.dev1
+
+
+A branch or commit on GitHub
+----------------------------
+
+For testing an unmerged change without publishing anything at all.
+Prefer a commit SHA over a branch name — a branch ref can change under you, and a lockfile pinned to one is not reproducible.
+
+**Note:** Always replace a git pin with a PyPI version before merging the consuming project,
+for the same reasons as above, plus the fact git dependencies break any downstream install that lacks repository access.
+
+``uv`` sources form, which keeps the version constraint readable::
+
+    [project]
+    dependencies = [
+        "datamasque-python",
+    ]
+
+    [tool.uv.sources]
+    datamasque-python = { git = "https://github.com/datamasque/datamasque-python.git", rev = "ab12cd34" }
+
+With Poetry::
+
+    [tool.poetry.dependencies]
+    datamasque-python = { git = "https://github.com/datamasque/datamasque-python.git", rev = "ab12cd34" }
+
+Use ``git+ssh://git@github.com/...`` instead of ``https`` if the consumer builds somewhere without an HTTPS credential for the repository.
+
+PEP 508 direct reference,
+which ``pip`` and ``uv`` both understand::
+
+    dependencies = [
+        "datamasque-python @ git+https://github.com/datamasque/datamasque-python.git@ab12cd34",
+    ]

{datamasque_python-1.2.0 → datamasque_python-1.2.2}/datamasque/client/__init__.py

@@ -23,6 +23,7 @@ from datamasque.client.exceptions import (
     InvalidDiscoveryConfigError,
     InvalidLibraryError,
     InvalidRulesetError,
+    RGConfigNotFoundError,
     RunNotCancellableError,
 )
 from datamasque.client.ifm import DataMasqueIfmClient
@@ -67,11 +68,13 @@ from datamasque.client.models.discovery import (
     FileFilter,
     FileFilterMatchAgainst,
     FileRulesetGenerationRequest,
+    FileRulesetGenerationWithRGConfigRequest,
     ForeignKeyRef,
     InDataDiscoveryConfig,
     InDataDiscoveryRule,
     ReferencingForeignKey,
     RulesetGenerationRequest,
+    RulesetGenerationWithRGConfigRequest,
     SchemaDiscoveryColumn,
     SchemaDiscoveryFromConfigRequest,
     SchemaDiscoveryPage,
@@ -105,6 +108,7 @@ from datamasque.client.models.ifm import (
     RulesetPlanUpdateRequest,
 )
 from datamasque.client.models.license import LicenseInfo, SwitchableLicenseMetadata
+from datamasque.client.models.rg_config import RGConfig, RGConfigId
 from datamasque.client.models.ruleset import Ruleset, RulesetId, RulesetType
 from datamasque.client.models.ruleset_library import RulesetLibrary, RulesetLibraryId
 from datamasque.client.models.runs import (
@@ -214,6 +218,7 @@ __all__ = [
     "FileId",
     "FileOrContent",
     "FileRulesetGenerationRequest",
+    "FileRulesetGenerationWithRGConfigRequest",
     "FirstCharsStatistics",
     "ForeignKeyRef",
     "GitSnapshot",
@@ -252,9 +257,13 @@ __all__ = [
     "PatternComposition",
     "PatternEntry",
     "PatternsStatistics",
+    "RGConfig",
+    "RGConfigId",
+    "RGConfigNotFoundError",
     "ReferencingForeignKey",
     "Ruleset",
     "RulesetGenerationRequest",
+    "RulesetGenerationWithRGConfigRequest",
     "RulesetId",
     "RulesetLibrary",
     "RulesetLibraryId",

{datamasque_python-1.2.0 → datamasque_python-1.2.2}/datamasque/client/discovery.py

@@ -13,6 +13,7 @@ from datamasque.client.exceptions import (
     DiscoveryConfigNotFoundError,
     FailedToStartError,
     InvalidDiscoveryConfigError,
+    RGConfigNotFoundError,
 )
 from datamasque.client.models.connection import ConnectionId
 from datamasque.client.models.data_selection import (
@@ -25,12 +26,15 @@ from datamasque.client.models.discovery import (
     FileDataDiscoveryRequest,
     FileDiscoveryResult,
     FileRulesetGenerationRequest,
+    FileRulesetGenerationWithRGConfigRequest,
     RulesetGenerationRequest,
+    RulesetGenerationWithRGConfigRequest,
     SchemaDiscoveryFromConfigRequest,
     SchemaDiscoveryPage,
     SchemaDiscoveryRequest,
     SchemaDiscoveryResult,
 )
+from datamasque.client.models.rg_config import RGConfig, RGConfigId, unwrap_rg_config_id
 from datamasque.client.models.ruleset import Ruleset
 from datamasque.client.models.runs import RunId
 from datamasque.client.models.status import AsyncRulesetGenerationTaskStatus
@@ -41,21 +45,12 @@ logger = logging.getLogger(__name__)
 class DiscoveryClient(BaseClient):
     """Schema-discovery and ruleset-generation API methods. Mixed into `DataMasqueClient`."""
 
-    def start_async_ruleset_generation(self, connection_id: ConnectionId, selected_data: SelectedData) -> None:
-        """
-        Starts async ruleset generation using the most recent discovery results on the given connection.
-
-        If the connection is a database connection, `selected_data` should be of type `SelectedColumns`.
-        If the connection is a file connection, `selected_data` should be of type `SelectedFileData`.
-
-        Generation runs asynchronously on the server.
-        Poll `get_async_ruleset_generation_task_status` until it returns
-        `AsyncRulesetGenerationTaskStatus.finished`,
-        then call `get_generated_rulesets` to retrieve the resulting `Ruleset`.
-        """
+    @staticmethod
+    def _selected_data_payload(selected_data: SelectedData) -> dict:
+        """Build the async-generation request-body fields for a column or file selection, validating its shape."""
 
         if not selected_data:
-            raise ValueError("`selected_data` is a required argument to `start_async_ruleset_generation`.")
+            raise ValueError("`selected_data` is a required argument to async ruleset generation.")
 
         data: dict = {}
         if isinstance(selected_data, SelectedColumns):
@@ -75,12 +70,56 @@ class DiscoveryClient(BaseClient):
             data["selected_data"] = [s.model_dump() for s in selected_data.user_selections]
         else:
             raise TypeError(
-                f"The argument `selected_data` to `start_async_ruleset_generation` was of an invalid type, "
+                f"The `selected_data` argument to async ruleset generation was of an invalid type, "
                 f"expected `SelectedColumns` or `SelectedFileData`, got {type(selected_data)}."
             )
 
+        return data
+
+    def start_async_ruleset_generation(self, connection_id: ConnectionId, selected_data: SelectedData) -> None:
+        """
+        Starts async ruleset generation using the most recent discovery results on the given connection.
+
+        Masks are assigned from the server's default RG config;
+        use `start_async_ruleset_generation_with_rg_config` to generate with a saved RG config.
+
+        If the connection is a database connection, `selected_data` should be of type `SelectedColumns`.
+        If the connection is a file connection, `selected_data` should be of type `SelectedFileData`.
+
+        Generation runs asynchronously on the server.
+        Poll `get_async_ruleset_generation_task_status` until it returns `AsyncRulesetGenerationTaskStatus.finished`,
+        then call `get_generated_rulesets` to retrieve the resulting `Ruleset`.
+        """
+
+        data = self._selected_data_payload(selected_data)
         self.make_request(method="POST", path=f"/api/async-generate-ruleset/{connection_id}/", data=data)
 
+    def start_async_ruleset_generation_with_rg_config(
+        self,
+        connection_id: ConnectionId,
+        selected_data: SelectedData,
+        rg_config: Optional[Union[RGConfigId, RGConfig]],
+    ) -> None:
+        """
+        Starts async ruleset generation with a selected RG config mapping discovered labels to masks.
+
+        Like `start_async_ruleset_generation`,
+        but posts to the v2 endpoint with a required `rg_config`:
+        a saved RG config (`RGConfigId` or `RGConfig`),
+        or `None` for the server's default RG config.
+
+        Raises `RGConfigNotFoundError` if the selected RG config does not exist on the server.
+
+        Generation runs asynchronously on the server.
+        Poll `get_async_ruleset_generation_task_status` until it returns `AsyncRulesetGenerationTaskStatus.finished`,
+        then call `get_generated_rulesets` to retrieve the resulting `Ruleset`.
+        """
+
+        data = self._selected_data_payload(selected_data)
+        # The server requires `rg_config` to be present; an explicit null selects the default RG config.
+        data["rg_config"] = unwrap_rg_config_id(rg_config)
+        self._post_with_rg_config(f"/api/async-generate-ruleset/v2/{connection_id}/", data)
+
     def start_async_ruleset_generation_from_csv(
         self,
         connection_id: ConnectionId,
@@ -103,11 +142,57 @@ class DiscoveryClient(BaseClient):
         otherwise it is uploaded as CSV.
 
         Generation runs asynchronously on the server.
-        Poll `get_async_ruleset_generation_task_status` until it returns
-        `AsyncRulesetGenerationTaskStatus.finished`,
+        Poll `get_async_ruleset_generation_task_status` until it returns `AsyncRulesetGenerationTaskStatus.finished`,
         then call `get_generated_rulesets` to retrieve the resulting `Ruleset` objects.
         """
 
+        self.make_request(
+            method="POST",
+            path=f"/api/async-generate-ruleset/{connection_id}/from-csv/",
+            data={"target_size_bytes": target_size_bytes} if target_size_bytes is not None else None,
+            files=self._csv_upload_files(csv_content),
+        )
+
+    def start_async_ruleset_generation_from_csv_with_rg_config(
+        self,
+        connection_id: ConnectionId,
+        csv_content: Union[str, bytes, TextIOBase, BufferedIOBase],
+        rg_config: Optional[Union[RGConfigId, RGConfig]],
+        target_size_bytes: Optional[int] = None,
+    ) -> None:
+        """
+        Generate ruleset(s) from a schema discovery CSV report with a selected RG config.
+
+        Like `start_async_ruleset_generation_from_csv`,
+        but posts to the v2 endpoint with a required `rg_config`:
+        a saved RG config (`RGConfigId` or `RGConfig`),
+        or `None` for the server's default RG config.
+
+        Raises `RGConfigNotFoundError` if the selected RG config does not exist on the server.
+
+        Generation runs asynchronously on the server.
+        Poll `get_async_ruleset_generation_task_status` until it returns `AsyncRulesetGenerationTaskStatus.finished`,
+        then call `get_generated_rulesets` to retrieve the resulting `Ruleset` objects.
+        """
+
+        rg_config_id = unwrap_rg_config_id(rg_config)
+        # The upload is a multipart form, whose fields cannot carry a JSON null;
+        # the server reads an empty string as null for this nullable field,
+        # selecting the default RG config.
+        data: dict = {"rg_config": rg_config_id if rg_config_id is not None else ""}
+        if target_size_bytes is not None:
+            data["target_size_bytes"] = target_size_bytes
+
+        self._post_with_rg_config(
+            f"/api/async-generate-ruleset/v2/{connection_id}/from-csv/",
+            data,
+            files=self._csv_upload_files(csv_content),
+        )
+
+    @staticmethod
+    def _csv_upload_files(csv_content: Union[str, bytes, TextIOBase, BufferedIOBase]) -> list[UploadFile]:
+        """Normalise CSV-or-zip report content into the `csv_or_zip_file` multipart upload."""
+
         content: BufferedIOBase
         if isinstance(csv_content, str):
             content = BytesIO(csv_content.encode())
@@ -125,7 +210,7 @@ class DiscoveryClient(BaseClient):
         filename = "ruleset.zip" if is_zip else "ruleset.csv"
         content_type = "application/zip" if is_zip else "text/csv"
 
-        files = [
+        return [
             UploadFile(
                 field_name="csv_or_zip_file",
                 filename=filename,
@@ -134,13 +219,6 @@ class DiscoveryClient(BaseClient):
             ),
         ]
 
-        self.make_request(
-            method="POST",
-            path=f"/api/async-generate-ruleset/{connection_id}/from-csv/",
-            data={"target_size_bytes": target_size_bytes} if target_size_bytes is not None else None,
-            files=files,
-        )
-
     def get_async_ruleset_generation_task_status(self, connection_id: ConnectionId) -> AsyncRulesetGenerationTaskStatus:
         """Queries the status of an async ruleset generation task."""
 
@@ -381,7 +459,7 @@ class DiscoveryClient(BaseClient):
         if not (errors := run_data.get(cls.DISCOVERY_CONFIG_ERROR_FIELD)):
             return
 
-        detail = cls._format_discovery_config_error(errors)
+        detail = cls._format_config_error(errors)
         if cls.MISSING_DISCOVERY_CONFIG_SIGNATURE in detail:
             raise DiscoveryConfigNotFoundError(
                 f"{run_kind} run failed to start: the referenced discovery config could not be found: {detail}",
@@ -394,14 +472,61 @@ class DiscoveryClient(BaseClient):
         )
 
     @staticmethod
-    def _format_discovery_config_error(errors: object) -> str:
-        """Render the first server error, handling both string and `{message, ...}` dict items."""
+    def _format_config_error(errors: object) -> str:
+        """Render the first server error for a config field, handling both string and `{message, ...}` dict items."""
         first = errors[0] if isinstance(errors, list) and errors else errors
         if isinstance(first, dict) and "message" in first:
             return str(first["message"])
 
         return str(first)
 
+    # Server key for an error that names the selected RG config.
+    RG_CONFIG_ERROR_FIELD = "rg_config"
+
+    # The phrase the server uses when the config id cannot be resolved
+    # (the config does not exist, or has been archived).
+    MISSING_RG_CONFIG_SIGNATURE = "object does not exist"
+
+    def _post_with_rg_config(
+        self,
+        path: str,
+        data: dict,
+        files: Optional[list[UploadFile]] = None,
+    ) -> Response:
+        """Post a generation request carrying an `rg_config`, classifying a rejected config on failure."""
+
+        response = self.make_request("POST", path, data=data, files=files, require_status_check=False)
+        self._maybe_raise_rg_config_not_found(response)
+        self._raise_for_status(response, request_data=data)
+        return response
+
+    @classmethod
+    def _maybe_raise_rg_config_not_found(cls, response: Response) -> None:
+        """Raise `RGConfigNotFoundError` if the server's error body says the selected RG config does not exist."""
+
+        if response.ok:
+            return
+
+        try:
+            body = response.json()
+        except ValueError:
+            return
+
+        if not isinstance(body, dict):
+            return
+
+        if not (errors := body.get(cls.RG_CONFIG_ERROR_FIELD)):
+            return
+
+        detail = cls._format_config_error(errors)
+        if cls.MISSING_RG_CONFIG_SIGNATURE not in detail:
+            return
+
+        raise RGConfigNotFoundError(
+            f"The referenced RG config could not be found: {detail}",
+            response=response,
+        )
+
     def iter_schema_discovery_results(self, run_id: RunId) -> Iterator[SchemaDiscoveryResult]:
         """Lazily iterate all schema discovery results for a run via the paginated v2 endpoint."""
 
@@ -433,6 +558,9 @@ class DiscoveryClient(BaseClient):
         """
         Generates database-masking ruleset YAML from the most recent discovery run on the given connection.
 
+        Masks are assigned from the server's default RG config;
+        use `generate_ruleset_with_rg_config` to generate with a saved RG config.
+
         `generation_request` is a `RulesetGenerationRequest`.
         """
 
@@ -440,10 +568,26 @@ class DiscoveryClient(BaseClient):
         response = self.make_request("POST", "/api/generate-ruleset/v2/", data=data)
         return response.content.decode("utf-8")
 
+    def generate_ruleset_with_rg_config(self, generation_request: RulesetGenerationWithRGConfigRequest) -> str:
+        """
+        Generates database-masking ruleset YAML with a selected RG config mapping discovered labels to masks.
+
+        `generation_request` is a `RulesetGenerationWithRGConfigRequest`;
+        its required `rg_config` selects the saved RG config to use
+        (`None` for the server's default RG config).
+
+        Raises `RGConfigNotFoundError` if the selected RG config does not exist on the server.
+        """
+
+        return self._generate_ruleset_with_rg_config(generation_request, "/api/generate-ruleset/v3/")
+
     def generate_file_ruleset(self, generation_request: FileRulesetGenerationRequest) -> str:
         """
         Generates file-masking ruleset YAML from the most recent file-data-discovery run on the given connection.
 
+        Masks are assigned from the server's default RG config;
+        use `generate_file_ruleset_with_rg_config` to generate with a saved RG config.
+
         `generation_request` is a `FileRulesetGenerationRequest`.
         """
 
@@ -451,6 +595,33 @@ class DiscoveryClient(BaseClient):
         response = self.make_request("POST", "/api/generate-file-ruleset/", data=data)
         return response.content.decode("utf-8")
 
+    def generate_file_ruleset_with_rg_config(self, generation_request: FileRulesetGenerationWithRGConfigRequest) -> str:
+        """
+        Generates file-masking ruleset YAML with a selected RG config mapping discovered labels to masks.
+
+        `generation_request` is a `FileRulesetGenerationWithRGConfigRequest`;
+        its required `rg_config` selects the saved RG config to use
+        (`None` for the server's default RG config).
+
+        Raises `RGConfigNotFoundError` if the selected RG config does not exist on the server.
+        """
+
+        return self._generate_ruleset_with_rg_config(generation_request, "/api/generate-file-ruleset/v2/")
+
+    def _generate_ruleset_with_rg_config(
+        self,
+        generation_request: Union[RulesetGenerationWithRGConfigRequest, FileRulesetGenerationWithRGConfigRequest],
+        path: str,
+    ) -> str:
+        """Post a with-RG-config generation request and return the generated ruleset YAML."""
+
+        data = generation_request.model_dump(exclude_none=True, mode="json")
+        # The server requires `rg_config` to be present; a null selects its default RG config,
+        # so send it explicitly rather than letting `exclude_none` drop a None.
+        data.setdefault("rg_config", None)
+        response = self._post_with_rg_config(path, data)
+        return response.content.decode("utf-8")
+
     def get_file_data_discovery_report(self, run_id: RunId) -> list[FileDiscoveryResult]:
         """Returns the file-data-discovery results for the specified run."""
 

{datamasque_python-1.2.0 → datamasque_python-1.2.2}/datamasque/client/discovery_config_libraries.py

@@ -76,15 +76,19 @@ class DiscoveryConfigLibraryClient(BaseClient):
         Creates a new discovery config library on the server.
 
         Sets the library's server-assigned fields
-        (`id`, `is_valid`, `validation_error`, `created`, `modified`) and returns the library.
+        (`id`, `is_valid`, `validation_error`, `usage_count`, `created`, `modified`) and returns the library.
         """
 
+        if not library.yaml:
+            raise ValueError("Cannot create a discovery config library without YAML content (yaml is empty)")
+
         data = library.model_dump(exclude_none=True, by_alias=True, mode="json")
         response = self.make_request("POST", "/api/discovery/config-libraries/", data=data)
         created = DiscoveryConfigLibrary.model_validate(response.json())
         library.id = created.id
         library.is_valid = created.is_valid
         library.validation_error = created.validation_error
+        library.usage_count = created.usage_count
         library.created = created.created
         library.modified = created.modified
         logger.info('Creation of discovery config library "%s" successful', library.name)
@@ -101,9 +105,9 @@ class DiscoveryConfigLibraryClient(BaseClient):
         if library.id is None:
             raise ValueError("Cannot update a discovery config library that has not been created yet (id is None)")
 
-        if library.yaml is None:
+        if not library.yaml:
             raise ValueError(
-                "Cannot update a discovery config library without YAML content (yaml is None); "
+                "Cannot update a discovery config library without YAML content (yaml is empty or unset); "
                 "list results omit YAML, so fetch the full library with `get_discovery_config_library` first"
             )
 
@@ -112,6 +116,7 @@ class DiscoveryConfigLibraryClient(BaseClient):
         updated = DiscoveryConfigLibrary.model_validate(response.json())
         library.is_valid = updated.is_valid
         library.validation_error = updated.validation_error
+        library.usage_count = updated.usage_count
         library.modified = updated.modified
         logger.debug('Update of discovery config library "%s" successful', library.name)
         return library