datamasque-python 1.2.0__py3-none-any.whl → 1.2.2__py3-none-any.whl

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/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/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

datamasque/client/discovery_configs.py

@@ -75,15 +75,20 @@ class DiscoveryConfigClient(BaseClient):
         Creates a new discovery config on the server.
 
         Sets the config's server-assigned fields
-        (`id`, `is_valid`, `validation_error`, `created`, `modified`) and returns the config.
+        (`id`, `is_valid`, `validation_error`, `validation_error_details`, `created`, `modified`)
+        and returns the config.
         """
 
+        if not config.yaml:
+            raise ValueError("Cannot create a discovery config without YAML content (yaml is empty)")
+
         data = config.model_dump(exclude_none=True, by_alias=True, mode="json")
         response = self.make_request("POST", "/api/discovery/configs/", data=data)
         created = DiscoveryConfig.model_validate(response.json())
         config.id = created.id
         config.is_valid = created.is_valid
         config.validation_error = created.validation_error
+        config.validation_error_details = created.validation_error_details
         config.created = created.created
         config.modified = created.modified
         logger.info('Creation of discovery config "%s" successful', config.name)
@@ -94,17 +99,24 @@ class DiscoveryConfigClient(BaseClient):
         Performs a full update of the discovery config.
 
         The config must have its `id` set
-        (i.e., it must have been previously created or retrieved from the server).
+        and its `yaml` content present.
         """
 
         if config.id is None:
             raise ValueError("Cannot update a discovery config that has not been created yet (id is None)")
 
+        if not config.yaml:
+            raise ValueError(
+                "Cannot update a discovery config without YAML content (yaml is empty or unset); "
+                "list results omit YAML, so fetch the full config with `get_discovery_config` first"
+            )
+
         data = config.model_dump(exclude_none=True, by_alias=True, mode="json")
         response = self.make_request("PUT", f"/api/discovery/configs/{config.id}/", data=data)
         updated = DiscoveryConfig.model_validate(response.json())
         config.is_valid = updated.is_valid
         config.validation_error = updated.validation_error
+        config.validation_error_details = updated.validation_error_details
         config.modified = updated.modified
         logger.debug('Update of discovery config "%s" successful', config.name)
         return config

datamasque/client/dmclient.py

@@ -5,6 +5,7 @@ from datamasque.client.discovery_config_libraries import DiscoveryConfigLibraryC
 from datamasque.client.discovery_configs import DiscoveryConfigClient
 from datamasque.client.files import FileClient
 from datamasque.client.license import LicenseClient
+from datamasque.client.rg_configs import RGConfigClient
 from datamasque.client.ruleset_libraries import RulesetLibraryClient
 from datamasque.client.rulesets import RulesetClient
 from datamasque.client.runs import RunClient
@@ -26,6 +27,7 @@ class DataMasqueClient(
     DiscoveryConfigClient,
     DiscoveryConfigLibraryClient,
     TableReferenceClient,
+    RGConfigClient,
     UserClient,
     SettingsClient,
 ):

datamasque/client/exceptions.py

@@ -58,6 +58,14 @@ class DiscoveryConfigNotFoundError(FailedToStartError):
     """
 
 
+class RGConfigNotFoundError(DataMasqueApiError):
+    """
+    Raised when ruleset generation references an RG config that cannot be found.
+
+    The config does not exist, or has been deleted.
+    """
+
+
 class DataMasqueTransportError(DataMasqueException):
     """
     Raised when a request to the DataMasque server fails before any response is received.

datamasque/client/models/discovery.py

@@ -9,6 +9,7 @@ from datamasque.client.models.connection import ConnectionConfig, ConnectionId,
 from datamasque.client.models.data_selection import HashColumnsTableConfig, Locator, UserSelection
 from datamasque.client.models.discovery_config import DiscoveryConfig, DiscoveryConfigId, unwrap_discovery_config_id
 from datamasque.client.models.pagination import Page
+from datamasque.client.models.rg_config import RGConfig, RGConfigId, unwrap_rg_config_id
 from datamasque.client.models.runs import RunConnectionRef
 from datamasque.client.models.safe_data_preview import (
     SafeDataPreview,
@@ -106,12 +107,13 @@ class SchemaDiscoveryFromConfigRequest(BaseModel):
 
 class RulesetGenerationRequest(BaseModel):
     """
-    Request body for `POST /api/generate-ruleset/v2/`.
+    Request body for `POST /api/generate-ruleset/v2/` (generation with the default RG config).
 
     `connection` accepts either a `ConnectionId` or a full `ConnectionConfig` returned by an earlier client call.
     `selected_columns` is the same nested `schema -> table -> [column, ...]` mapping
     used by `SelectedColumns.columns`,
     and `hash_columns` follows the `HashColumnsTableConfig` shape.
+    This request does not accept an `rg_config`.
     """
 
     model_config = ConfigDict(extra="forbid")
@@ -125,6 +127,45 @@ class RulesetGenerationRequest(BaseModel):
     def _unwrap_connection(cls, value: Any) -> Any:
         return unwrap_connection_id(value)
 
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_rg_config(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "rg_config" in data:
+            raise ValueError(
+                "`rg_config` is not accepted by `RulesetGenerationRequest`; "
+                "use `generate_ruleset_with_rg_config` with a `RulesetGenerationWithRGConfigRequest` "
+                "to generate with a selected RG config."
+            )
+        return data
+
+
+class RulesetGenerationWithRGConfigRequest(BaseModel):
+    """
+    Request body for `POST /api/generate-ruleset/v3/` (generation with a selected RG config).
+
+    `connection` accepts either a `ConnectionId` or a full `ConnectionConfig` returned by an earlier client call.
+    `selected_columns` and `hash_columns` follow the same shapes as `RulesetGenerationRequest`.
+    `rg_config` is required: pass an `RGConfigId`, a full `RGConfig`,
+    or `None` to generate with the server's default RG config.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    connection: Union[ConnectionId, ConnectionConfig]
+    selected_columns: dict[str, dict[str, list[str]]]
+    rg_config: Optional[Union[RGConfigId, RGConfig]]
+    hash_columns: Optional[dict[str, dict[str, HashColumnsTableConfig]]] = None
+
+    @field_validator("connection", mode="before")
+    @classmethod
+    def _unwrap_connection(cls, value: Any) -> Any:
+        return unwrap_connection_id(value)
+
+    @field_validator("rg_config", mode="before")
+    @classmethod
+    def _unwrap_rg_config(cls, value: Any) -> Any:
+        return unwrap_rg_config_id(value)
+
 
 class FileFilterMatchAgainst(Enum):
     """Which part of a file's path an `include`/`skip` filter is matched against."""
@@ -236,9 +277,10 @@ class FileDataDiscoveryFromConfigRequest(BaseModel):
 
 class FileRulesetGenerationRequest(BaseModel):
     """
-    Request body for `POST /api/generate-file-ruleset/`.
+    Request body for `POST /api/generate-file-ruleset/` (generation with the default RG config).
 
     `connection` accepts either a `ConnectionId` or a full `ConnectionConfig` returned by an earlier client call.
+    This request does not accept an `rg_config`.
     """
 
     model_config = ConfigDict(extra="forbid")
@@ -251,6 +293,43 @@ class FileRulesetGenerationRequest(BaseModel):
     def _unwrap_connection(cls, value: Any) -> Any:
         return unwrap_connection_id(value)
 
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_rg_config(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "rg_config" in data:
+            raise ValueError(
+                "`rg_config` is not accepted by `FileRulesetGenerationRequest`; "
+                "use `generate_file_ruleset_with_rg_config` with a `FileRulesetGenerationWithRGConfigRequest` "
+                "to generate with a selected RG config."
+            )
+        return data
+
+
+class FileRulesetGenerationWithRGConfigRequest(BaseModel):
+    """
+    Request body for `POST /api/generate-file-ruleset/v2/` (generation with a selected RG config).
+
+    `connection` accepts either a `ConnectionId` or a full `ConnectionConfig` returned by an earlier client call.
+    `rg_config` is required: pass an `RGConfigId`, a full `RGConfig`,
+    or `None` to generate with the server's default RG config.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    connection: Union[ConnectionId, ConnectionConfig]
+    selected_data: list[UserSelection]
+    rg_config: Optional[Union[RGConfigId, RGConfig]]
+
+    @field_validator("connection", mode="before")
+    @classmethod
+    def _unwrap_connection(cls, value: Any) -> Any:
+        return unwrap_connection_id(value)
+
+    @field_validator("rg_config", mode="before")
+    @classmethod
+    def _unwrap_rg_config(cls, value: Any) -> Any:
+        return unwrap_rg_config_id(value)
+
 
 class DiscoveryMatch(BaseModel):
     """A single match found by schema or file discovery."""

datamasque/client/models/discovery_config.py

@@ -2,9 +2,9 @@ import enum
 from datetime import datetime
 from typing import Any, NewType, Optional
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import AliasChoices, AliasPath, BaseModel, ConfigDict, Field
 
-from datamasque.client.models.status import ValidationStatus
+from datamasque.client.models.status import ValidationErrorDetails, ValidationStatus
 
 DiscoveryConfigId = NewType("DiscoveryConfigId", str)
 
@@ -49,5 +49,14 @@ class DiscoveryConfig(BaseModel):
     """Validation status; may be `in_progress` briefly after creating a large config."""
     validation_error: Optional[str] = Field(default=None, exclude=True)
     """Human-readable validation error, or `None` when valid."""
+    # Deliberately not `validation_errors`:
+    # this is a different shape to `Ruleset.validation_errors`,
+    # and would sit one character from `validation_error` above.
+    validation_error_details: list[ValidationErrorDetails] = Field(
+        default_factory=list,
+        exclude=True,
+        validation_alias=AliasChoices(AliasPath("errors", "config_yaml"), "validation_error_details"),
+    )
+    """Structured, positional validation errors."""
     created: Optional[datetime] = Field(default=None, exclude=True)
     modified: Optional[datetime] = Field(default=None, exclude=True)

datamasque/client/models/discovery_config_library.py

@@ -27,5 +27,7 @@ class DiscoveryConfigLibrary(BaseModel):
     """Validation status; libraries are validated synchronously on create/update."""
     validation_error: Optional[str] = Field(default=None, exclude=True)
     """Human-readable validation error, or `None` when valid."""
+    usage_count: Optional[int] = Field(default=None, exclude=True)
+    """Number of active discovery configs that import this library."""
     created: Optional[datetime] = Field(default=None, exclude=True)
     modified: Optional[datetime] = Field(default=None, exclude=True)

datamasque/client/models/rg_config.py

@@ -0,0 +1,49 @@
+from datetime import datetime
+from typing import Any, NewType, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from datamasque.client.models.status import ValidationErrorDetails, ValidationStatus
+
+RGConfigId = NewType("RGConfigId", str)
+
+
+def unwrap_rg_config_id(value: Any) -> Any:
+    """
+    Coerce an `RGConfig` to its `id`; pass other values through unchanged.
+
+    Used by request-model validators and the generate methods
+    that accept either an `RGConfigId` or a full `RGConfig` for user convenience.
+    Raises `ValueError` if the config has no `id`
+    (i.e. the caller hasn't yet created it on the server).
+    """
+
+    if isinstance(value, RGConfig):
+        if value.id is None:
+            raise ValueError("RG config has not been created yet (id is None)")
+        return value.id
+
+    return value
+
+
+class RGConfig(BaseModel):
+    """
+    Represents a named, persisted YAML ruleset-generation (RG) configuration.
+
+    An RG config maps discovered labels to masks;
+    ruleset generation applies it to a discovery run's results.
+    Unlike discovery configs, RG configs are untyped —
+    the same config serves both database and file ruleset generation.
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    name: str
+    yaml: Optional[str] = Field(default=None, alias="config_yaml")
+
+    # Server-populated read-only fields, excluded from request bodies.
+    id: Optional[RGConfigId] = Field(default=None, exclude=True)
+    is_valid: Optional[ValidationStatus] = Field(default=None, exclude=True)
+    validation_errors: list[ValidationErrorDetails] = Field(default_factory=list, exclude=True)
+    created: Optional[datetime] = Field(default=None, exclude=True)
+    modified: Optional[datetime] = Field(default=None, exclude=True)

datamasque/client/rg_configs.py

@@ -0,0 +1,155 @@
+import logging
+from typing import Iterator, Optional
+
+from datamasque.client.base import BaseClient
+from datamasque.client.exceptions import DataMasqueApiError
+from datamasque.client.models.pagination import Page
+from datamasque.client.models.rg_config import RGConfig, RGConfigId
+
+logger = logging.getLogger(__name__)
+
+
+class RGConfigClient(BaseClient):
+    """Ruleset-generation (RG) config CRUD API methods. Mixed into `DataMasqueClient`."""
+
+    def iter_rg_configs(self) -> Iterator[RGConfig]:
+        """Lazily iterate all RG configs via the paginated endpoint."""
+
+        return self._iter_paginated("/api/ruleset-generation-configs/", model=RGConfig)
+
+    def list_rg_configs(self) -> list[RGConfig]:
+        """
+        Lists all RG configs.
+
+        Note: the YAML content is not included in the list response for performance.
+        Use `get_rg_config` to retrieve the full config with its YAML body.
+        """
+
+        return list(self.iter_rg_configs())
+
+    def get_rg_config(self, config_id: RGConfigId) -> RGConfig:
+        """Retrieves a single RG config by ID."""
+
+        response = self.make_request("GET", f"/api/ruleset-generation-configs/{config_id}/")
+        return RGConfig.model_validate(response.json())
+
+    def _get_rg_config_id_by_name(self, name: str) -> Optional[RGConfigId]:
+        """Return the id of the config matching the name via a single list request, or `None`."""
+
+        response = self.make_request(
+            "GET",
+            "/api/ruleset-generation-configs/",
+            params={"name_exact": name, "limit": 1},
+        )
+        page = Page[RGConfig].model_validate(response.json())
+        if not page.results:
+            return None
+
+        config_id = page.results[0].id
+        if config_id is None:
+            raise DataMasqueApiError(
+                "Server returned an RG config list entry without an `id`.",
+                response=response,
+            )
+
+        return config_id
+
+    def get_rg_config_by_name(self, name: str) -> Optional[RGConfig]:
+        """
+        Looks for an RG config matching the given name (case-sensitive, exact match).
+
+        RG configs are untyped and their names are unique, so the name alone identifies a single config.
+        Returns it if found, otherwise `None`.
+        """
+
+        config_id = self._get_rg_config_id_by_name(name)
+        if config_id is None:
+            return None
+
+        return self.get_rg_config(config_id)
+
+    def create_rg_config(self, config: RGConfig) -> RGConfig:
+        """
+        Creates a new RG config on the server.
+
+        Sets the config's server-assigned fields
+        (`id`, `is_valid`, `validation_errors`, `created`, `modified`) and returns the config.
+        """
+
+        data = config.model_dump(exclude_none=True, by_alias=True, mode="json")
+        response = self.make_request("POST", "/api/ruleset-generation-configs/", data=data)
+        created = RGConfig.model_validate(response.json())
+        config.id = created.id
+        config.is_valid = created.is_valid
+        config.validation_errors = created.validation_errors
+        config.created = created.created
+        config.modified = created.modified
+        logger.info('Creation of RG config "%s" successful', config.name)
+        return config
+
+    def update_rg_config(self, config: RGConfig) -> RGConfig:
+        """
+        Performs a full update of the RG config.
+
+        The config must have its `id` set
+        (i.e., it must have been previously created or retrieved from the server)
+        and its `yaml` content present.
+        """
+
+        if config.id is None:
+            raise ValueError("Cannot update an RG config that has not been created yet (id is None)")
+
+        if config.yaml is None:
+            raise ValueError(
+                "Cannot update an RG config without YAML content (yaml is None); "
+                "list results omit YAML, so fetch the full config with `get_rg_config` first"
+            )
+
+        data = config.model_dump(exclude_none=True, by_alias=True, mode="json")
+        response = self.make_request("PUT", f"/api/ruleset-generation-configs/{config.id}/", data=data)
+        updated = RGConfig.model_validate(response.json())
+        config.is_valid = updated.is_valid
+        config.validation_errors = updated.validation_errors
+        config.modified = updated.modified
+        logger.debug('Update of RG config "%s" successful', config.name)
+        return config
+
+    def create_or_update_rg_config(self, config: RGConfig) -> RGConfig:
+        """
+        Creates the config if it doesn't exist, or updates it if one with the same name already exists.
+
+        Sets the config's `id` property.
+        """
+
+        existing_id = self._get_rg_config_id_by_name(config.name)
+        if existing_id is not None:
+            config.id = existing_id
+            return self.update_rg_config(config)
+
+        return self.create_rg_config(config)
+
+    def delete_rg_config_by_id_if_exists(self, config_id: RGConfigId) -> None:
+        """
+        Deletes the RG config with the given ID.
+
+        No-op if the config does not exist.
+        """
+
+        self._delete_if_exists(f"/api/ruleset-generation-configs/{config_id}/")
+
+    def delete_rg_config_by_name_if_exists(self, name: str) -> None:
+        """
+        Deletes the RG config with the given name.
+
+        No-op if no such config exists.
+        """
+
+        config_id = self._get_rg_config_id_by_name(name)
+        if config_id is not None:
+            self.delete_rg_config_by_id_if_exists(config_id)
+
+    def get_default_rg_config_yaml(self) -> str:
+        """Returns the server's built-in default RG configuration as a YAML string."""
+
+        response = self.make_request("GET", "/api/ruleset-generation-configs/defaults/")
+        return response.content.decode("utf-8")

datamasque/client/ruleset_libraries.py

@@ -119,8 +119,9 @@ class RulesetLibraryClient(BaseClient):
 
         No-op if the library does not exist.
 
-        If the library is imported by any rulesets,
+        If the library is imported by any rulesets or RG configs,
         the server will return 409 Conflict unless `force=True` is passed.
+        Forcing the deletion marks those dependents' validation state as invalid.
         """
 
         params = {"force": "true"} if force else None
@@ -152,6 +153,8 @@ class RulesetLibraryClient(BaseClient):
         """
         Lists rulesets that import the given library.
 
+        Only rulesets are listed; RG configs that import the library are not included.
+
         Note: The YAML content is not included in the response for performance.
         Each returned Ruleset will have an empty string for `yaml`.
         """

{datamasque_python-1.2.0.dist-info → datamasque_python-1.2.2.dist-info}/METADATA

@@ -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.0.dist-info → datamasque_python-1.2.2.dist-info}/RECORD

@@ -1,16 +1,17 @@
-datamasque/client/__init__.py,sha256=Tq3xY-x3yQj5E05q5YJFxXzpYYEu_eOiKSGmX-IINHI,8323
+datamasque/client/__init__.py,sha256=2PVF5FrXkPAv51EMxSvfpYelJpbOg_Tlx-Wo7p2-0jo,8661
 datamasque/client/base.py,sha256=cXU4dluL9e1N1F2pV48iIvebv6OHt7Kh4Ka2y9vkOPo,14296
 datamasque/client/connections.py,sha256=EFinx8fJRme0mTxuWY3d29UnmUFbsQhMaUQT0Ma2PK4,2885
-datamasque/client/discovery.py,sha256=MTDiif6YWkv64hHXZ8YJxtRhoeKIvQVfjNYvjCIZCXE,21261
-datamasque/client/discovery_config_libraries.py,sha256=bwuBTCnJUSnOyTz_I-_D6uS3wcRJh3ZRtfv2AOyMnmY,7024
-datamasque/client/discovery_configs.py,sha256=G-W-X_KizjjQLa-Rb6ixLjlkxbkCe4WGCOfYZrGtxIk,6420
-datamasque/client/dmclient.py,sha256=w8aloPHL8YGKfESUzn62G9XrVovDoGlqrktX_KuDL7U,1864
-datamasque/client/exceptions.py,sha256=YpM_vhnl31_02KQmx-NPP2AxR3gKYcmcxyb_35G9HVw,3755
+datamasque/client/discovery.py,sha256=xidiAj5LdVSGQy6pjta_2Z_aJmuPPohblyNDfua_Mxk,28859
+datamasque/client/discovery_config_libraries.py,sha256=K6kFi7kL4SGIPKNIg1TBMIwHUeyfXI3Lyg5sknMMCD4,7285
+datamasque/client/discovery_configs.py,sha256=-iSDi7g8PAYXJ8aGCusGOVtE1UWD4D_pNxf68IdRei4,6967
+datamasque/client/dmclient.py,sha256=0W6s26gUl9EZRL1kdk0R_7hgZSAOesY3H5wd-tN-QIE,1940
+datamasque/client/exceptions.py,sha256=3JI_LU8K3P2BCJDjGewzj3yg6oMd_7KuQ-zwSLR8Bfs,3956
 datamasque/client/files.py,sha256=vc2tZgT8RdwuCObIQ7H-Qjb80H1PBFqD0nG5Y1tOA_o,3503
 datamasque/client/ifm.py,sha256=uIMxpLIPvDiDO1m4bxezixNIUFIFY0MXWRMQNvTbpTA,11858
 datamasque/client/license.py,sha256=pluYaSU168OC6_laB9bM9H3Vuuxs8wa9gujCJvtoJCk,1392
 datamasque/client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-datamasque/client/ruleset_libraries.py,sha256=s--iZKB8EAC7bNYrU3ZI0olSWU-mXJoyUBOgJPfQ0xQ,7091
+datamasque/client/rg_configs.py,sha256=jcrbw-oMhj6o3Wsf8xy3peVo7DzeQ8EhhAsfcEwC3lc,5816
+datamasque/client/ruleset_libraries.py,sha256=dQthTFS5N9vFYN_qK1ZSnHnJGLmhwzKNQrKonItK85w,7275
 datamasque/client/rulesets.py,sha256=gzxn9mR7PhCySRUUB1cyl4aLmEfuDKj8BvQUq8OgLH8,2563
 datamasque/client/runs.py,sha256=l_JpYgelqsDKW_O6LtsHC60IMXHG9ak_RwVnuvJKE1I,7703
 datamasque/client/settings.py,sha256=Ui8AyR2XdoW8MZ9FIrGn2jm8DLzUGWIL8i2DOTvu7hc,2898
@@ -20,15 +21,16 @@ datamasque/client/users.py,sha256=VCUo2CJyOw4-aO_3mp_w_0BcSoa6-h1HcReMcAMyumw,37
 datamasque/client/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 datamasque/client/models/connection.py,sha256=loLy4RCiIfY9kvBFspSqJSRhHqhcJxm_mQzXwMRS4VU,17529
 datamasque/client/models/data_selection.py,sha256=406yyUZ5NmLBSql2lYM1gsTWY5GWmnutmF-DjznAoLc,1904
-datamasque/client/models/discovery.py,sha256=w3DXPux15BDMVs5urTpU2DM8pnWUzS3LFzCr6ctymxk,13517
-datamasque/client/models/discovery_config.py,sha256=1CHMgSxMXuarPGfRcz9wX7jeZLn1SDw0UEe-L5naE54,1917
-datamasque/client/models/discovery_config_library.py,sha256=NW4bhrlpps_SyJcX07W-dfQ_i9C0OH3O0b9TQcXPl1w,1298
+datamasque/client/models/discovery.py,sha256=Ejtrmja_wjHRxCWZel5Q5nZz4M20F2zdtBsdhWI1BnA,16791
+datamasque/client/models/discovery_config.py,sha256=8sqs9x_X0H_hR1fJDEFmOdJyGRDwgbdb3eddEAe98WE,2420
+datamasque/client/models/discovery_config_library.py,sha256=m0wI51Q4aHysLNHyNTWH3KrDLV_rxtoLNeKQsF9RYFk,1436
 datamasque/client/models/dm_instance.py,sha256=6h0WNlI1qt6jkrYFapIvuSJFkhRCcwbpx0PLG5NsrGw,2219
 datamasque/client/models/files.py,sha256=7hG3Q1-XYb1PF88l3ppsmBp2tjNtvQvv-RNTrOa7Nts,2784
 datamasque/client/models/git.py,sha256=F0KdMFe2vMyL-9tp3SGKGeOlbD1gbcjQn0jpOzNzybc,1782
 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/rg_config.py,sha256=g6g0qMTeR6OcM4Ji8fHrDOnOM5fsz1UYxntn_mv_k88,1792
 datamasque/client/models/ruleset.py,sha256=FDnvewJQvbeH73LpZiwYg3BG9Ya4yhmKKGmO1BKZQPk,1549
 datamasque/client/models/ruleset_library.py,sha256=Pw6Udr7pMgPt1AcG2ZhUXOPBS7tTvpw13UZNLILhZbQ,1003
 datamasque/client/models/runs.py,sha256=UtPMGCJFLFP1f2nyVGAbl3A5_wAONrRNJ63y43Hbpi0,6213
@@ -36,7 +38,7 @@ datamasque/client/models/safe_data_preview.py,sha256=BiI9d13KdQrTin2JfbjiRiODjns
 datamasque/client/models/status.py,sha256=WiSMEy_YxdcIA46ioYpAEu8OK8UNDoXpV1W7IUhhyVY,3219
 datamasque/client/models/table_reference.py,sha256=55fKdHjC2TQnUmbp0XiWqfeFGXqcq4wXjbWgMaN3p3c,3835
 datamasque/client/models/user.py,sha256=UGAUzgJkf78m24_zFXXoA99zdut48BXkX_ivV8yq1Vc,2043
-datamasque_python-1.2.0.dist-info/METADATA,sha256=9PUXw1BVSYhSjvPC6YaRVwSlCDrdG0GITMsRw6JA2FE,4497
-datamasque_python-1.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-datamasque_python-1.2.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-datamasque_python-1.2.0.dist-info/RECORD,,
+datamasque_python-1.2.2.dist-info/METADATA,sha256=ir-yTNm-rFL887aT4tQN1iTe6Ll10VNBUvy2n7JTF3k,4497
+datamasque_python-1.2.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+datamasque_python-1.2.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+datamasque_python-1.2.2.dist-info/RECORD,,