Python

python -m pip install datafog-core

import datafog_core

Migrating from the established datafog package? Start with Migrate 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.

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.

Get started

Core concepts

Guides

Reference

Project

Type checking

Synchronous functions

Result objects

Asynchronous manager

Exceptions

Structured JSON and PERSON fields

Capability discovery (0.4.0+)

Email source context

​Type checking

​Synchronous functions

​Result objects

​Asynchronous manager

​Exceptions

​Structured JSON and PERSON fields

​Capability discovery (0.4.0+)

​Email source context

Type checking

Synchronous functions

Result objects

Asynchronous manager

Exceptions

Structured JSON and PERSON fields

Capability discovery (0.4.0+)

Email source context