Skip to content

Latest commit

 

History

History
137 lines (101 loc) · 4.26 KB

python.mdx

File metadata and controls

137 lines (101 loc) · 4.26 KB
title Python
description Python functions, result objects, exceptions, and the asynchronous PrivacyManager.
icon python
python -m pip install datafog-core
import datafog_core
Migrating from the established `datafog` package? Start with [Migrate from datafog Python](/guides/migrating-from-datafog-python) before translating API calls.

Type checking

Starting with 0.3.1, the wheel includes PEP 561 typing metadata and stubs for all public functions, result objects, exceptions, and awaitable manager methods. Pyright and mypy can infer finding and result types and check configuration literals without a separate stub package.

Configuration and provider helper types in the stub are prefixed with _ and exist only for type checking. If you use them in annotations, import them inside if TYPE_CHECKING: and use postponed annotations (from __future__ import annotations); they are not runtime exports. Runtime validation still enforces value constraints such as recognized locale aliases, nonnegative ranges, and valid keys.

Synchronous functions

scan(text: str, config: dict | None = None) -> list[Finding]
transform(text: str, findings: list[Finding], config: dict) -> TransformResult
scan_and_transform(text: str, config: dict) -> TransformResult

transform uses explicit findings. scan_and_transform accepts the divided configuration envelope with scan and transform sections.

Result objects

Python exposes immutable objects with snake_case attributes:

  • TextRange(start, end)
  • Finding
  • Transformation
  • TransformResult
  • Restoration
  • RestoreResult
finding.entity_type
finding.matched_text
finding.byte_range.start
finding.codepoint_range.end

result.text
result.transformations

Asynchronous manager

PrivacyManager(provider=None, token_provider=None)

The manager exposes awaitable methods:

await manager.transform(text, findings, config, context=None)
await manager.scan_and_transform(text, config, context=None)
await manager.restore(text, context)

The key provider must implement:

async def resolve_key(key_ref: str, key_version: str | None) -> dict:
    ...

The token provider must implement:

async def tokenize_batch(scope: str, items: list[dict]) -> list[dict]:
    ...

async def restore_batch(scope: str, items: list[dict]) -> list[dict]:
    ...

Exceptions

  • DataFogConfigurationError
  • DataFogFindingError
  • DataFogKeyProviderError
  • DataFogInternalError

Exceptions expose stable code, optional reason, optional path, and optional finding_index attributes. See Errors.

Testing hook

panic_probe() forces a Rust panic through the detached-work path and raises DataFogInternalError (code internal_error, message including the panic text). Use it to check that your own error handling covers the Rust boundary.

Structured JSON and PERSON fields

Use discover_fields(data, config=None), scan_structured(data, config=None), transform_structured(data, findings, config), and scan_and_transform_structured(data, config). Results expose .mappings and .findings, or .data and .transformations. PrivacyManager also exposes transform_structured, scan_and_transform_structured, and restore_structured for provider-backed work.

Paths are JSON Pointers. All ranges, including JavaScript UTF-16 ranges, address the decoded string at that path. See person-field discovery for aliases, policy configuration, input limits, and examples.

German locale routing and the seven additional entity labels are documented in the German entity reference.

Capability discovery (0.4.0+)

Use capabilities() to inspect the runtime registry, including supported entities, default detectors, locale aliases, and activation settings. See the capabilities contract and generated inventory and 0.4.x compatibility policy.

Email source context

Use the optional scan format setting ("text", "env", or "sql") to delimit emails in environment assignments or standard SQL quoted strings. See email boundaries for examples and syntax limits.