datamasque-python 1.1.6__py3-none-any.whl → 1.1.8__py3-none-any.whl

datamasque/client/__init__.py

@@ -116,12 +116,51 @@ from datamasque.client.models.runs import (
     RunInfo,
     UnfinishedRun,
 )
+from datamasque.client.models.safe_data_preview import (
+    BooleanPreview,
+    BooleanStatistics,
+    ColumnKind,
+    ColumnPreview,
+    CommonStatistics,
+    FirstCharsStatistics,
+    LengthEntry,
+    LengthsStatistics,
+    MaskedFormEntry,
+    NumericBin,
+    NumericHistograms,
+    NumericPreview,
+    NumericStatistics,
+    NumericSummaries,
+    NumericTemporalDisclosureLevel,
+    PatternComposition,
+    PatternEntry,
+    PatternsStatistics,
+    SafeDataPreview,
+    SafeDataPreviewOptions,
+    StringDisclosureLevel,
+    StringPreview,
+    StringStatistics,
+    TemporalBin,
+    TemporalHistograms,
+    TemporalPreview,
+    TemporalStatistics,
+    TemporalSummaries,
+    UnsupportedPreview,
+    UnsupportedStatistics,
+)
 from datamasque.client.models.status import (
     AsyncRulesetGenerationTaskStatus,
     MaskingRunStatus,
+    ValidationErrorDetails,
     ValidationErrorType,
     ValidationStatus,
 )
+from datamasque.client.models.table_reference import (
+    TableReference,
+    TableReferenceFormat,
+    TableReferenceId,
+    TableReferenceOptions,
+)
 from datamasque.client.models.user import User, UserId, UserRole
 
 __version__ = version("datamasque-python")
@@ -130,6 +169,11 @@ __all__ = [
     "AsyncRulesetGenerationInProgressError",
     "AsyncRulesetGenerationTaskStatus",
     "AzureConnectionConfig",
+    "BooleanPreview",
+    "BooleanStatistics",
+    "ColumnKind",
+    "ColumnPreview",
+    "CommonStatistics",
     "ConnectionConfig",
     "ConnectionId",
     "ConstraintColumns",
@@ -170,6 +214,7 @@ __all__ = [
     "FileId",
     "FileOrContent",
     "FileRulesetGenerationRequest",
+    "FirstCharsStatistics",
     "ForeignKeyRef",
     "GitSnapshot",
     "HashColumnsTableConfig",
@@ -185,16 +230,28 @@ __all__ = [
     "InvalidLibraryError",
     "InvalidRulesetError",
     "JsonPath",
+    "LengthEntry",
+    "LengthsStatistics",
     "LicenseInfo",
     "Locator",
     "MaskType",
+    "MaskedFormEntry",
     "MaskingRunOptions",
     "MaskingRunRequest",
     "MaskingRunStatus",
     "MongoConnectionConfig",
     "MountedShareConnectionConfig",
     "MssqlLinkedServerConnectionConfig",
+    "NumericBin",
+    "NumericHistograms",
+    "NumericPreview",
+    "NumericStatistics",
+    "NumericSummaries",
+    "NumericTemporalDisclosureLevel",
     "OracleWalletFile",
+    "PatternComposition",
+    "PatternEntry",
+    "PatternsStatistics",
     "ReferencingForeignKey",
     "Ruleset",
     "RulesetGenerationRequest",
@@ -212,6 +269,8 @@ __all__ = [
     "RunInfo",
     "RunNotCancellableError",
     "S3ConnectionConfig",
+    "SafeDataPreview",
+    "SafeDataPreviewOptions",
     "SchemaDiscoveryColumn",
     "SchemaDiscoveryFromConfigRequest",
     "SchemaDiscoveryPage",
@@ -227,13 +286,28 @@ __all__ = [
     "SseConfig",
     "SseSelection",
     "SslZipFile",
+    "StringDisclosureLevel",
+    "StringPreview",
+    "StringStatistics",
     "SwitchableLicenseMetadata",
     "TableConstraints",
+    "TableReference",
+    "TableReferenceFormat",
+    "TableReferenceId",
+    "TableReferenceOptions",
+    "TemporalBin",
+    "TemporalHistograms",
+    "TemporalPreview",
+    "TemporalStatistics",
+    "TemporalSummaries",
     "UnfinishedRun",
+    "UnsupportedPreview",
+    "UnsupportedStatistics",
     "User",
     "UserId",
     "UserRole",
     "UserSelection",
+    "ValidationErrorDetails",
     "ValidationErrorType",
     "ValidationStatus",
 ]

datamasque/client/dmclient.py

@@ -9,6 +9,7 @@ from datamasque.client.ruleset_libraries import RulesetLibraryClient
 from datamasque.client.rulesets import RulesetClient
 from datamasque.client.runs import RunClient
 from datamasque.client.settings import SettingsClient
+from datamasque.client.table_references import TableReferenceClient
 from datamasque.client.users import UserClient
 
 __all__ = ["DataMasqueClient", "FileOrContent", "UploadFile"]
@@ -24,6 +25,7 @@ class DataMasqueClient(
     DiscoveryClient,
     DiscoveryConfigClient,
     DiscoveryConfigLibraryClient,
+    TableReferenceClient,
     UserClient,
     SettingsClient,
 ):

datamasque/client/models/connection.py

@@ -166,6 +166,7 @@ class MongoConnectionConfig(ConnectionConfig):
     tls_ca_file: str = ""
     tls_allow_invalid_certificates: bool = False
     direct_connection: bool = False
+    retry_writes: bool = True
     replica_set: str = ""
     is_read_only: bool = False
 
@@ -194,6 +195,8 @@ class MongoConnectionConfig(ConnectionConfig):
                 d.pop("tls_allow_invalid_certificates", None)
         if not d.get("direct_connection"):
             d.pop("direct_connection", None)
+        if d.get("retry_writes", True):
+            d.pop("retry_writes", None)
         if not d.get("replica_set"):
             d.pop("replica_set", None)
         if not d.get("user"):

datamasque/client/models/discovery.py

@@ -10,6 +10,10 @@ from datamasque.client.models.data_selection import HashColumnsTableConfig, Loca
 from datamasque.client.models.discovery_config import DiscoveryConfig, DiscoveryConfigId, unwrap_discovery_config_id
 from datamasque.client.models.pagination import Page
 from datamasque.client.models.runs import RunConnectionRef
+from datamasque.client.models.safe_data_preview import (
+    SafeDataPreview,
+    SafeDataPreviewOptions,
+)
 
 
 class InDataDiscoveryRule(BaseModel):
@@ -32,6 +36,7 @@ class InDataDiscoveryConfig(BaseModel):
     non_sensitive_rules: Optional[list[InDataDiscoveryRule]] = None
     ignore_rules: Optional[list[InDataDiscoveryRule]] = None
     force: Optional[bool] = None
+    safe_data_preview: Optional[SafeDataPreviewOptions] = None
 
 
 class SchemaDiscoveryRequest(BaseModel):
@@ -294,6 +299,7 @@ class SchemaDiscoveryColumn(BaseModel):
     unique_index_names: list[str]
     referencing_foreign_keys: list[ReferencingForeignKey]
     constraint: str  # Primary or Unique, or empty string if column does not participate in a PK/UK
+    safe_data_preview: Optional[SafeDataPreview] = None
 
 
 class SchemaDiscoveryResult(BaseModel):
@@ -324,6 +330,7 @@ class TableConstraints(BaseModel):
     primary_keys: Optional[list[ConstraintColumns]] = None
     unique_keys: Optional[list[ConstraintColumns]] = None
     foreign_keys: Optional[list[ConstraintColumns]] = None
+    row_count: Optional[int] = None
 
 
 class SchemaDiscoveryPage(Page[SchemaDiscoveryResult]):
@@ -356,6 +363,7 @@ class FileDiscoveryLocatorResult(BaseModel):
     locator: Locator
     matches: list[FileDiscoveryMatch]
     data_types: list[str]
+    safe_data_preview: Optional[SafeDataPreview] = None
 
 
 class FileDiscoveryFile(BaseModel):

datamasque/client/models/ruleset.py

@@ -4,7 +4,7 @@ from typing import Any, NewType, Optional
 from pydantic import Field
 
 from datamasque.client.models.git import GitTrackedEntity
-from datamasque.client.models.status import ValidationErrorType, ValidationStatus
+from datamasque.client.models.status import ValidationErrorDetails, ValidationStatus
 
 RulesetId = NewType("RulesetId", str)
 
@@ -44,7 +44,5 @@ class Ruleset(GitTrackedEntity):
     # Server-populated read-only fields, excluded from request bodies.
     id: Optional[RulesetId] = Field(default=None, exclude=True)
     is_valid: Optional[ValidationStatus] = Field(default=None, exclude=True)
-    validation_error: Optional[str] = Field(default=None, exclude=True)
-    """Human-readable validation error, or `None` when valid."""
-    validation_error_type: Optional[ValidationErrorType] = Field(default=None, exclude=True)
-    """Category of the validation failure, or `None` when valid."""
+    validation_errors: list[ValidationErrorDetails] = Field(default_factory=list, exclude=True)
+    """Validation errors surfaced by the server; empty when valid."""

datamasque/client/models/ruleset_library.py

@@ -4,7 +4,7 @@ from typing import NewType, Optional
 from pydantic import Field
 
 from datamasque.client.models.git import GitTrackedEntity
-from datamasque.client.models.status import ValidationStatus
+from datamasque.client.models.status import ValidationErrorDetails, ValidationStatus
 
 RulesetLibraryId = NewType("RulesetLibraryId", str)
 
@@ -19,7 +19,7 @@ class RulesetLibrary(GitTrackedEntity):
     # Server-populated read-only fields, excluded from request bodies.
     id: Optional[RulesetLibraryId] = Field(default=None, exclude=True)
     is_valid: Optional[ValidationStatus] = Field(default=None, exclude=True)
-    validation_error: Optional[str] = Field(default=None, exclude=True)
-    """Human-readable validation error, or `None` when valid."""
+    validation_errors: list[ValidationErrorDetails] = Field(default_factory=list, exclude=True)
+    """Validation errors surfaced by the server; empty when valid."""
     created: Optional[datetime] = Field(default=None, exclude=True)
     modified: Optional[datetime] = Field(default=None, exclude=True)

datamasque/client/models/safe_data_preview.py

@@ -0,0 +1,282 @@
+"""Typed request and response shapes for Safe Data Preview, part of In-Data Discovery."""
+
+from enum import Enum
+from typing import Annotated, Literal, Optional, Union
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+)
+
+
+class StringDisclosureLevel(Enum):
+    """How much detail a string Safe Data Preview reveals."""
+
+    lengths = "lengths"
+    patterns = "patterns"
+    first_chars = "first_chars"
+
+
+class NumericTemporalDisclosureLevel(Enum):
+    """How much detail a numeric or temporal Safe Data Preview reveals."""
+
+    summaries = "summaries"
+    histograms = "histograms"
+
+
+class SafeDataPreviewOptions(BaseModel):
+    """Configures whether Safe Data Preview runs and how much detail each column reveals."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: Optional[bool] = None
+    min_group_size: Optional[int] = None
+    string_level: Optional[StringDisclosureLevel] = None
+    numeric_level: Optional[NumericTemporalDisclosureLevel] = None
+    temporal_level: Optional[NumericTemporalDisclosureLevel] = None
+
+
+class ColumnKind(str, Enum):
+    """Which shape a column's Safe Data Preview takes."""
+
+    boolean = "boolean"
+    numeric = "numeric"
+    string = "string"
+    temporal = "temporal"
+    unsupported = "unsupported"
+
+
+class CommonStatistics(BaseModel):
+    """Row counts shared by every preview kind."""
+
+    model_config = ConfigDict(extra="allow")
+
+    count_row: int
+    count_null: int
+    count_distinct: Optional[int] = None
+
+
+class LengthEntry(BaseModel):
+    """A value length and how many sampled rows had it."""
+
+    model_config = ConfigDict(extra="allow")
+
+    length: int
+    count: int
+
+
+class LengthsStatistics(BaseModel):
+    """Distribution of value lengths."""
+
+    model_config = ConfigDict(extra="allow")
+
+    min: int
+    max: int
+    mean: float
+    median: float
+    most_common: list[LengthEntry]
+
+
+class PatternEntry(BaseModel):
+    """A masked character pattern and how many sampled rows matched it."""
+
+    model_config = ConfigDict(extra="allow")
+
+    pattern: str
+    count: int
+
+
+class PatternComposition(BaseModel):
+    """The proportion of letter, digit, and other characters across sampled values."""
+
+    model_config = ConfigDict(extra="allow")
+
+    letter: float
+    digit: float
+    other: float
+
+
+class PatternsStatistics(BaseModel):
+    """The most common character patterns and the overall character composition."""
+
+    model_config = ConfigDict(extra="allow")
+
+    top: list[PatternEntry]
+    composition: PatternComposition
+
+
+class MaskedFormEntry(BaseModel):
+    """A masked leading form of a value and how many sampled rows had it."""
+
+    model_config = ConfigDict(extra="allow")
+
+    masked: str
+    count: int
+
+
+class FirstCharsStatistics(BaseModel):
+    """The most common masked leading forms."""
+
+    model_config = ConfigDict(extra="allow")
+
+    top: list[MaskedFormEntry]
+
+
+class StringStatistics(BaseModel):
+    """String preview statistics; `patterns`/`first_chars` appear at or above certain disclosure levels."""
+
+    model_config = ConfigDict(extra="allow")
+
+    lengths: LengthsStatistics
+    patterns: Optional[PatternsStatistics] = None
+    first_chars: Optional[FirstCharsStatistics] = None
+
+
+class NumericSummaries(BaseModel):
+    """Numeric mean and percentile summary."""
+
+    model_config = ConfigDict(extra="allow")
+
+    mean: float
+    q1: float
+    q2: float
+    q3: float
+    p5: float
+    p95: float
+
+
+class NumericBin(BaseModel):
+    """One half-open interval `[lower_bound, upper_bound)` of a numeric histogram and its row count."""
+
+    model_config = ConfigDict(extra="allow")
+
+    lower_bound: float
+    upper_bound: float
+    count: int
+
+
+class NumericHistograms(BaseModel):
+    """The bins of a numeric histogram."""
+
+    model_config = ConfigDict(extra="allow")
+
+    bins: list[NumericBin]
+
+
+class NumericStatistics(BaseModel):
+    """Numeric preview statistics; `histograms` is present only at the histogram disclosure level."""
+
+    model_config = ConfigDict(extra="allow")
+
+    summaries: NumericSummaries
+    histograms: Optional[NumericHistograms] = None
+
+
+class TemporalSummaries(BaseModel):
+    """Temporal mean and percentile summary, each an ISO-formatted string."""
+
+    model_config = ConfigDict(extra="allow")
+
+    mean: str
+    q1: str
+    q2: str
+    q3: str
+    p5: str
+    p95: str
+
+
+class TemporalBin(BaseModel):
+    """One interval of a temporal histogram, with ISO-formatted bounds and a human-readable label."""
+
+    model_config = ConfigDict(extra="allow")
+
+    lower_bound: str
+    upper_bound: str
+    label: str
+    count: int
+
+
+class TemporalHistograms(BaseModel):
+    """The bins of a temporal histogram."""
+
+    model_config = ConfigDict(extra="allow")
+
+    bins: list[TemporalBin]
+
+
+class TemporalStatistics(BaseModel):
+    """Temporal preview statistics; `histograms` is present only at the histogram disclosure level."""
+
+    model_config = ConfigDict(extra="allow")
+
+    summaries: TemporalSummaries
+    histograms: Optional[TemporalHistograms] = None
+
+
+class BooleanStatistics(BaseModel):
+    """Counts of true and false values."""
+
+    model_config = ConfigDict(extra="allow")
+
+    count_true: int
+    count_false: int
+
+
+class UnsupportedStatistics(BaseModel):
+    """Why a column could not be previewed."""
+
+    model_config = ConfigDict(extra="allow")
+
+    reason: str
+
+
+class ColumnPreview(BaseModel):
+    """Fields present on every Safe Data Preview."""
+
+    model_config = ConfigDict(extra="allow")
+
+    # For grouped file discovery, the file whose sample produced this preview; None for database columns.
+    sampled_from: Optional[str] = None
+    statistics_common: CommonStatistics
+
+
+class StringPreview(ColumnPreview):
+    """A preview of a string column."""
+
+    kind: Literal[ColumnKind.string] = ColumnKind.string
+    statistics_kind: StringStatistics
+
+
+class NumericPreview(ColumnPreview):
+    """A preview of a numeric column."""
+
+    kind: Literal[ColumnKind.numeric] = ColumnKind.numeric
+    statistics_kind: NumericStatistics
+
+
+class TemporalPreview(ColumnPreview):
+    """A preview of a date/time column."""
+
+    kind: Literal[ColumnKind.temporal] = ColumnKind.temporal
+    statistics_kind: TemporalStatistics
+
+
+class BooleanPreview(ColumnPreview):
+    """A preview of a boolean column."""
+
+    kind: Literal[ColumnKind.boolean] = ColumnKind.boolean
+    statistics_kind: BooleanStatistics
+
+
+class UnsupportedPreview(ColumnPreview):
+    """A column the preview ran against but declined; `statistics_kind.reason` says why."""
+
+    kind: Literal[ColumnKind.unsupported] = ColumnKind.unsupported
+    statistics_kind: UnsupportedStatistics
+
+
+SafeDataPreview = Annotated[
+    Union[StringPreview, NumericPreview, TemporalPreview, BooleanPreview, UnsupportedPreview],
+    Field(discriminator="kind"),
+]

datamasque/client/models/status.py

@@ -1,4 +1,7 @@
 import enum
+from typing import Optional
+
+from pydantic import BaseModel
 
 
 class ValidationStatus(enum.Enum):
@@ -11,7 +14,7 @@ class ValidationStatus(enum.Enum):
 
 
 class ValidationErrorType(enum.Enum):
-    """Categorises why a ruleset failed validation (see `Ruleset.validation_error_type`)."""
+    """Categorises why validation failed (see `ValidationErrorDetails.validation_error_type`)."""
 
     ruleset = "ruleset"
     library_missing = "library_missing"
@@ -19,6 +22,15 @@ class ValidationErrorType(enum.Enum):
     expansion = "expansion"  # The ruleset is not valid once its library references are expanded.
 
 
+class ValidationErrorDetails(BaseModel):
+    """A single validation error, with its position in the YAML when available."""
+
+    message: str
+    validation_error_type: Optional[ValidationErrorType] = None
+    line_number: Optional[int] = None
+    column_number: Optional[int] = None
+
+
 class MaskingRunStatus(enum.Enum):
     """List of valid masking run statuses."""
 

datamasque/client/models/table_reference.py

@@ -0,0 +1,101 @@
+"""Table reference models for the DataMasque API."""
+
+import enum
+from datetime import datetime
+from typing import NewType, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from datamasque.client.models.connection import ConnectionConfig, ConnectionId, unwrap_connection_id
+
+TableReferenceId = NewType("TableReferenceId", str)
+
+
+class TableReferenceFormat(enum.Enum):
+    """
+    File format of the data a table reference points at.
+
+    Only meaningful for a table reference on a file connection,
+    and an explicit choice: the source path's suffix carries no meaning.
+    """
+
+    csv = "csv"
+    parquet = "parquet"
+
+
+class TableReferenceOptions(BaseModel):
+    """
+    Format and CSV parsing options for a table reference.
+
+    These apply to file connections only —
+    they are ignored for a table reference on a database connection,
+    and the CSV options are ignored when the `format` is `parquet`.
+
+    There is deliberately no header toggle:
+    a CSV identity map's columns must be addressable by name,
+    so the first row is always read as the header.
+
+    Every option has a default, and the server fills in any option omitted from a request,
+    so the values here are the same defaults the server applies.
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    format: TableReferenceFormat = TableReferenceFormat.csv
+    delimiter: str = ","
+    encoding: str = "utf-8"
+    quotechar: str = '"'
+    null_string: Optional[str] = None
+    """The string in the source data to read as a null value, or `None` to read no value as null."""
+
+
+class TableReference(BaseModel):
+    """
+    Represents a named, persisted reference to a table of identity data held outside DataMasque.
+
+    The data lives in the referenced connection —
+    a CSV or Parquet file in a file connection, or a table in a database connection —
+    so a ruleset can reference the identity map once, by name,
+    instead of re-declaring the source each time.
+
+    A table reference stores no credentials of its own; it borrows the referenced connection's.
+
+    `source` is interpreted according to that connection's own type:
+
+    * file connection — a path to the file within the connection's fileset.
+      The format comes from `options.format`, never from the path's suffix.
+    * database connection — a dotted, schema-qualified `schema.table` reference.
+
+    Names are unique across live table references (a deleted reference frees its name for reuse),
+    and the referenced connection must not be archived.
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    name: str
+    connection: Union[ConnectionId, ConnectionConfig]
+    """The connection the data lives in. Accepts a `ConnectionId` or a `ConnectionConfig` (its `id` is extracted)."""
+    source: str
+    options: Optional[TableReferenceOptions] = None
+    """Format and CSV parsing options; when `None`, the server applies its defaults on create."""
+
+    # Server-populated read-only fields, excluded from request bodies.
+    id: Optional[TableReferenceId] = Field(default=None, exclude=True)
+    created: Optional[datetime] = Field(default=None, exclude=True)
+    modified: Optional[datetime] = Field(default=None, exclude=True)
+
+    @field_validator("connection", mode="before")
+    @classmethod
+    def _unwrap_connection(cls, value: object) -> object:
+        return unwrap_connection_id(value)
+
+    @property
+    def connection_id(self) -> ConnectionId:
+        """
+        The ID of the referenced connection.
+
+        `connection` accepts a whole `ConnectionConfig` for convenience but always holds an ID
+        once validated, so this narrows the declared type back down for callers reading it.
+        """
+
+        return ConnectionId(unwrap_connection_id(self.connection))

datamasque/client/ruleset_libraries.py

@@ -64,7 +64,7 @@ class RulesetLibraryClient(BaseClient):
         Creates a new ruleset library on the server.
 
         Sets the library's server-assigned fields
-        (`id`, `is_valid`, `validation_error`, `git`, `created`, `modified`) and returns the library.
+        (`id`, `is_valid`, `validation_errors`, `git`, `created`, `modified`) and returns the library.
         """
 
         data = library.model_dump(exclude_none=True, by_alias=True, mode="json")
@@ -72,7 +72,7 @@ class RulesetLibraryClient(BaseClient):
         created_library = RulesetLibrary.model_validate(response.json())
         library.id = created_library.id
         library.is_valid = created_library.is_valid
-        library.validation_error = created_library.validation_error
+        library.validation_errors = created_library.validation_errors
         library.git = created_library.git
         library.created = created_library.created
         library.modified = created_library.modified
@@ -93,7 +93,7 @@ class RulesetLibraryClient(BaseClient):
         response = self.make_request("PUT", f"/api/ruleset-libraries/{library.id}/", data=data)
         updated_library = RulesetLibrary.model_validate(response.json())
         library.is_valid = updated_library.is_valid
-        library.validation_error = updated_library.validation_error
+        library.validation_errors = updated_library.validation_errors
         library.git = updated_library.git
         library.modified = updated_library.modified
         logger.debug('Update of ruleset library "%s" successful', library.name)

datamasque/client/rulesets.py

@@ -20,7 +20,7 @@ class RulesetClient(BaseClient):
         """
         Creates or updates a ruleset.
 
-        Populates the given ruleset's `id`, `is_valid`, `validation_error`, `validation_error_type`,
+        Populates the given ruleset's `id`, `is_valid`, `validation_errors`,
         and `git` fields from the server response, and returns the same ruleset instance for convenience.
         """
 
@@ -29,8 +29,7 @@ class RulesetClient(BaseClient):
         created = Ruleset.model_validate(response.json())
         ruleset.id = created.id
         ruleset.is_valid = created.is_valid
-        ruleset.validation_error = created.validation_error
-        ruleset.validation_error_type = created.validation_error_type
+        ruleset.validation_errors = created.validation_errors
         ruleset.git = created.git
 
         if response.status_code == 201:

datamasque/client/table_references.py

@@ -0,0 +1,144 @@
+import logging
+from typing import Optional
+
+from datamasque.client.base import BaseClient
+from datamasque.client.exceptions import DataMasqueApiError
+from datamasque.client.models.table_reference import TableReference, TableReferenceId
+
+logger = logging.getLogger(__name__)
+
+
+class TableReferenceClient(BaseClient):
+    """Table reference CRUD API methods. Mixed into `DataMasqueClient`."""
+
+    def list_table_references(self) -> list[TableReference]:
+        """
+        Lists all table references.
+
+        Unlike most list endpoints, this one is not paginated;
+        the server returns every table reference in a single response.
+        Deleted table references are archived rather than removed, and are not listed.
+        """
+
+        response = self.make_request("GET", "/api/table-references/")
+        return [TableReference.model_validate(item) for item in response.json()]
+
+    def get_table_reference(self, table_reference_id: TableReferenceId) -> TableReference:
+        """Retrieves a single table reference by ID."""
+
+        response = self.make_request("GET", f"/api/table-references/{table_reference_id}/")
+        return TableReference.model_validate(response.json())
+
+    def get_table_reference_by_name(self, name: str) -> Optional[TableReference]:
+        """
+        Looks for a table reference with the given name (case-sensitive, exact match).
+
+        Names are unique across live table references, so at most one can match.
+        Returns it if found, otherwise `None`.
+
+        The endpoint takes no name filter, so the match is made client-side over the full listing.
+        """
+
+        matches = [reference for reference in self.list_table_references() if reference.name == name]
+        if not matches:
+            return None
+
+        return matches[0]
+
+    def _get_table_reference_id_by_name(self, name: str) -> Optional[TableReferenceId]:
+        """Return the ID of the table reference with the given name, or `None` if there is none."""
+
+        response = self.make_request("GET", "/api/table-references/")
+        matches = [item for item in response.json() if item.get("name") == name]
+        if not matches:
+            return None
+
+        existing_id = matches[0].get("id")
+        if existing_id is None:
+            raise DataMasqueApiError(
+                f'Server returned a table reference named "{name}" without an `id`.',
+                response=response,
+            )
+
+        return TableReferenceId(existing_id)
+
+    def create_table_reference(self, table_reference: TableReference) -> TableReference:
+        """
+        Creates a new table reference on the server.
+
+        Sets the table reference's server-assigned fields (`id`, `created`, `modified`)
+        and its `options` as stored by the server (with any omitted option filled in with its default),
+        then returns the table reference.
+        """
+
+        data = table_reference.model_dump(by_alias=True, mode="json")
+        if data.get("options") is None:
+            data.pop("options", None)
+        response = self.make_request("POST", "/api/table-references/", data=data)
+        created = TableReference.model_validate(response.json())
+        table_reference.id = created.id
+        table_reference.options = created.options
+        table_reference.created = created.created
+        table_reference.modified = created.modified
+        logger.info('Creation of table reference "%s" successful', table_reference.name)
+        return table_reference
+
+    def update_table_reference(self, table_reference: TableReference) -> TableReference:
+        """
+        Performs a full update of the table reference.
+
+        The table reference must have its `id` set
+        (i.e., it must have been previously created or retrieved from the server).
+
+        `options` are replaced wholesale when set, so an option left at its model default
+        is sent as that default rather than keeping whatever the server had stored.
+        Leaving `options` as `None` sends none at all, which leaves the stored options untouched.
+        """
+
+        if table_reference.id is None:
+            raise ValueError("Cannot update a table reference that has not been created yet (id is None)")
+
+        data = table_reference.model_dump(by_alias=True, mode="json")
+        if data.get("options") is None:
+            data.pop("options", None)
+        response = self.make_request("PUT", f"/api/table-references/{table_reference.id}/", data=data)
+        updated = TableReference.model_validate(response.json())
+        table_reference.options = updated.options
+        table_reference.modified = updated.modified
+        logger.debug('Update of table reference "%s" successful', table_reference.name)
+        return table_reference
+
+    def create_or_update_table_reference(self, table_reference: TableReference) -> TableReference:
+        """
+        Creates the table reference, or updates the existing one with the same name.
+
+        Sets the table reference's `id` property.
+        """
+
+        existing_id = self._get_table_reference_id_by_name(table_reference.name)
+        if existing_id is not None:
+            table_reference.id = existing_id
+            return self.update_table_reference(table_reference)
+
+        return self.create_table_reference(table_reference)
+
+    def delete_table_reference_by_id_if_exists(self, table_reference_id: TableReferenceId) -> None:
+        """
+        Deletes the table reference with the given ID.
+
+        The server archives rather than removes it, which frees its name for reuse.
+        No-op if the table reference does not exist.
+        """
+
+        self._delete_if_exists(f"/api/table-references/{table_reference_id}/")
+
+    def delete_table_reference_by_name_if_exists(self, name: str) -> None:
+        """
+        Deletes the table reference with the given name.
+
+        No-op if no such table reference exists.
+        """
+
+        table_reference_id = self._get_table_reference_id_by_name(name)
+        if table_reference_id is not None:
+            self.delete_table_reference_by_id_if_exists(table_reference_id)

{datamasque_python-1.1.6.dist-info → datamasque_python-1.1.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datamasque-python
-Version: 1.1.6
+Version: 1.1.8
 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.1.6.dist-info → datamasque_python-1.1.8.dist-info}/RECORD

@@ -1,25 +1,26 @@
-datamasque/client/__init__.py,sha256=8GtJwv76dHgVDFGpE5YEMC0B2KIj6W8D3M3StwjvyXo,6551
+datamasque/client/__init__.py,sha256=Tq3xY-x3yQj5E05q5YJFxXzpYYEu_eOiKSGmX-IINHI,8323
 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=Ne8vzY9NDoY11O2HCSA8le9KiTlJPSoznKy3PL05lqY,7628
 datamasque/client/discovery_configs.py,sha256=G-W-X_KizjjQLa-Rb6ixLjlkxbkCe4WGCOfYZrGtxIk,6420
-datamasque/client/dmclient.py,sha256=rsQyc-awujpaWKr_CEYLeDDo7Y8zrb4pHxxs-AqV-Z4,1770
+datamasque/client/dmclient.py,sha256=w8aloPHL8YGKfESUzn62G9XrVovDoGlqrktX_KuDL7U,1864
 datamasque/client/exceptions.py,sha256=YpM_vhnl31_02KQmx-NPP2AxR3gKYcmcxyb_35G9HVw,3755
 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=bMUMBHdxjDyFOziw9LMRy5xChPvHvCjpjAUoVeTm1e0,7086
-datamasque/client/rulesets.py,sha256=Fsnsv-uAhF1DBnLI-pRpOrWJ7aCSZspcuU1r0RYTzUc,2655
+datamasque/client/ruleset_libraries.py,sha256=s--iZKB8EAC7bNYrU3ZI0olSWU-mXJoyUBOgJPfQ0xQ,7091
+datamasque/client/rulesets.py,sha256=gzxn9mR7PhCySRUUB1cyl4aLmEfuDKj8BvQUq8OgLH8,2563
 datamasque/client/runs.py,sha256=l_JpYgelqsDKW_O6LtsHC60IMXHG9ak_RwVnuvJKE1I,7703
 datamasque/client/settings.py,sha256=Ui8AyR2XdoW8MZ9FIrGn2jm8DLzUGWIL8i2DOTvu7hc,2898
 datamasque/client/spcs.py,sha256=geHrBQ6WLWsMGpSMV8hmK5SFAwftrOU0DXkrR2orOmo,7532
+datamasque/client/table_references.py,sha256=dPyB59Sz4iLuF1lc7xffgf9qeNTFA5srT55E8TnFLvk,6092
 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=CPT2wF1dVMs-N8Jca7hUhegtRk_mxPKU8XhWV43C0xE,17419
+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=WHSIkFebQ5m47K_BdxY1lvCeeF23q_BbZan7Ryuh5vY,13198
+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=5MLIe3SCQ6IbhWbZ_avDL9H65fW4O5h3HtjlgEfcFGg,1378
 datamasque/client/models/dm_instance.py,sha256=6h0WNlI1qt6jkrYFapIvuSJFkhRCcwbpx0PLG5NsrGw,2219
@@ -28,12 +29,14 @@ datamasque/client/models/git.py,sha256=F0KdMFe2vMyL-9tp3SGKGeOlbD1gbcjQn0jpOzNzy
 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=ZYv6SmcrONV5rLK0tKjhlKCwZiCU1dMYtH7olxI4l5A,1678
-datamasque/client/models/ruleset_library.py,sha256=5UbL_M47mgPedo8xt4q5crUh4aeOVoEMAEKbGO8CfiY,950
+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
-datamasque/client/models/status.py,sha256=UUEDHd3CQZA1Mf-1LyhAiE4COuCWvAz5oJx5ECVIwp4,2868
+datamasque/client/models/safe_data_preview.py,sha256=BiI9d13KdQrTin2JfbjiRiODjns_FipWmfcEyfQzN1E,6778
+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.1.6.dist-info/METADATA,sha256=5xb8jZEaGhZfMu2NOImE3tuTI2LBlV8O6JScm_Q-pBw,4497
-datamasque_python-1.1.6.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-datamasque_python-1.1.6.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-datamasque_python-1.1.6.dist-info/RECORD,,
+datamasque_python-1.1.8.dist-info/METADATA,sha256=_uqOykCTG6M-qHCHbFxWOIzY5hNpxh2L2GOYfrH4Zr0,4497
+datamasque_python-1.1.8.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+datamasque_python-1.1.8.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+datamasque_python-1.1.8.dist-info/RECORD,,