Skip to content

io

io

Save PII replacement plans and configurations with comments for review.

Functions:

Name Description
save_plan

Save replace_pii.replacement_plan as a standalone YAML file for review and reuse.

save_config

Save a complete NSS configuration.

save_plan(plan, path, *, sampler, locale)

Save replace_pii.replacement_plan as a standalone YAML file for review and reuse.

The file starts with a header naming the sampler and locale the plan was written for, and each section is preceded by a short comment. The header only informs the reader: each run checks the plan against its own replace_pii.sampler and replace_pii.locale.

Parameters:

Name Type Description Default
plan PiiReplacementPlan

Replacement plan to save.

required
path str | Path

Destination YAML file; parent directories are created.

required
sampler PiiSamplerConfig

Sampler the plan was written for.

required
locale str

Locale the plan was written for.

required

Returns:

Type Description
Path

The path written.

Source code in src/nemo_safe_synthesizer/pii_replacer/planning/io.py
def save_plan(plan: PiiReplacementPlan, path: str | Path, *, sampler: PiiSamplerConfig, locale: str) -> Path:
    """Save ``replace_pii.replacement_plan`` as a standalone YAML file for review and reuse.

    The file starts with a header naming the sampler and locale the plan was
    written for, and each section is preceded by a short comment. The header
    only informs the reader: each run checks the plan against its own
    ``replace_pii.sampler`` and ``replace_pii.locale``.

    Args:
        plan: Replacement plan to save.
        path: Destination YAML file; parent directories are created.
        sampler: Sampler the plan was written for.
        locale: Locale the plan was written for.

    Returns:
        The path written.
    """
    plan_path = Path(path)
    plan_path.parent.mkdir(parents=True, exist_ok=True)
    header = (
        f"# PII replacement plan for this dataset, written for the {sampler.backend.value} sampler in locale "
        f"{locale}.\n# Review and edit it, then name this file in replace_pii.replacement_plan to reuse it.\n"
        f"# Plan format: {_PLAN_DOCS_URL}\n"
        f"# Patterns: {_PLAN_DOCS_URL}#patterns\n\n"
    )
    text = yaml.safe_dump(_plan_document(plan), sort_keys=False)
    plan_path.write_text(header + _with_key_comments(text, _plan_section_comments(())))
    return plan_path

save_config(config, path, *, plan_path=None)

Save a complete NSS configuration.

With plan_path and an inline plan, replace_pii.replacement_plan is written to that file by save_plan, and the configuration names it by a path relative to the configuration's directory when the file is inside it, or by its absolute path otherwise, so loading the configuration reads the file back. Otherwise the plan is written inline, and the output matches config.to_yaml(path, exclude_unset=False) apart from the same plan comments.

Parameters:

Name Type Description Default
config SafeSynthesizerParameters

Configuration to save.

required
path str | Path

Destination YAML file; parent directories are created.

required
plan_path str | Path | None

Separate file for replace_pii.replacement_plan.

None

Returns:

Type Description
Path

The path written.

Source code in src/nemo_safe_synthesizer/pii_replacer/planning/io.py
def save_config(
    config: SafeSynthesizerParameters,
    path: str | Path,
    *,
    plan_path: str | Path | None = None,
) -> Path:
    """Save a complete NSS configuration.

    With ``plan_path`` and an inline plan, ``replace_pii.replacement_plan`` is
    written to that file by ``save_plan``, and the configuration names it by a
    path relative to the configuration's directory when the file is inside it,
    or by its absolute path otherwise, so loading the configuration reads the
    file back. Otherwise the plan is written inline, and the output matches
    ``config.to_yaml(path, exclude_unset=False)`` apart from the same plan
    comments.

    Args:
        config: Configuration to save.
        path: Destination YAML file; parent directories are created.
        plan_path: Separate file for ``replace_pii.replacement_plan``.

    Returns:
        The path written.
    """
    config_path = Path(path)
    config_path.parent.mkdir(parents=True, exist_ok=True)
    document = json.loads(config.model_dump_json(exclude_unset=False))
    comments: dict[tuple[str, ...], list[str]] = {}
    replace_pii = config.replace_pii
    plan = replace_pii.inline_plan if replace_pii is not None else None
    if replace_pii is not None and plan is not None and plan_path is not None:
        written = save_plan(plan, plan_path, sampler=replace_pii.sampler, locale=replace_pii.locale)
        document["replace_pii"]["replacement_plan"] = _path_from(config_path.parent, written)
    else:
        comments = _plan_section_comments(("replace_pii", "replacement_plan"))
    config_path.write_text(_with_key_comments(yaml.safe_dump(document), comments))
    return config_path