Python SDK /

Installation

$ pip install euredact

The core install has no dependencies. The optional euredact[fast] extra adds an RE2 scan prefilter: one DFA pass per 1 KB window reports which patterns can match there, so the rest are skipped. Measured at ~2.0x on a 2,000-character page. Output is unchanged by construction — the prefilter only decides which patterns are worth running, and each survivor is then run over the whole text.

If you installed euredact[fast] at 0.3.1, upgrade. In that release the windowed scan could miss SECRET patterns wider than the window — a PEM private key passed through unmasked. The pure-Python default and the Node.js package were never affected. Fixed in 0.3.2.

redact()

Main entry point. Detects and redacts PII from a text string. Returns a RedactResult with the cleaned text and a list of detections.

def redact(
    text: str,
    *,
    countries: list[str] | None = None,
    mode: str = "rules",
    referential_integrity: bool = False,
    detect_dates: bool = False,
    cache: bool = True,
) -> RedactResult

Example

import euredact

result = euredact.redact(
    "Mijn BSN is 111222333 en IBAN NL91ABNA0417164300.",
    countries=["NL"],
)

print(result.redacted_text)
# "Mijn BSN is [NATIONAL_ID] en IBAN [BANK_ACCOUNT]."

print(result.detections)

countries takes a list. Since 0.3.3 a bare string raises TypeError, on every entry point, in both SDKs. Before that, countries="NL" was iterated character by character into the codes "N" and "L"; neither resolves, so the call declared nothing and every detection came back flagged out_of_scope while the redacted text still looked correct. A pipeline filtering on that field — which these docs tell you to do — kept none of them. A wrong country code still only warns; a wrong type has no correct reading to fall back on.

redact_batch()

Batch redaction. More efficient than calling redact() in a loop because it loads configs once.

def redact_batch(
    texts: list[str],
    **kwargs,
) -> list[RedactResult]

Example

import euredact

texts = [
    "BSN 111222333",
    "IBAN NL91ABNA0417164300",
]

results = euredact.redact_batch(texts, countries=["NL"])
for r in results:
    print(r.redacted_text)

aredact()

Async version of redact(). Offloads CPU work to a thread pool. Same keyword arguments and return type.

async def aredact(
    text: str,
    **kwargs,
) -> RedactResult

Example

import asyncio
import euredact

async def main():
    result = await euredact.aredact("BSN 111222333")
    print(result.redacted_text)

asyncio.run(main())

aredact_batch()

Async batch redaction with controlled concurrency.

async def aredact_batch(
    texts: list[str],
    *,
    max_concurrency: int = 4,
    **kwargs,
) -> list[RedactResult]

redact_iter()

Lazy iterator for large datasets. Yields results one at a time without loading everything into memory.

def redact_iter(
    texts: Iterable[str],
    **kwargs,
) -> Iterator[RedactResult]

Example

import euredact

texts = ["BSN 111222333", "IBAN DE89370400440532013000"]

for result in euredact.redact_iter(texts):
    print(result.redacted_text)

add_custom_pattern()

Register a custom regex pattern. Matches are reported with the given name as the entity type.

def add_custom_pattern(
    name: str,
    pattern: str,
) -> None

available_countries()

Returns a sorted list of supported ISO country codes.

import euredact

print(euredact.available_countries())  # ["AT", "BE", "BG", ...]

EuRedact class

For isolated instances with separate caches and custom patterns. Useful when different parts of your application need different configurations.

from euredact import EuRedact

instance = EuRedact()
instance.add_custom_pattern("CASE_REF", r"CASE-\d{8}")

result = instance.redact(
    "See CASE-20260401",
    countries=["NL", "BE"],
)

print(result.redacted_text)
# "See [CASE_REF]"

The EuRedact instance exposes the same methods: redact(), redact_batch(), aredact(), aredact_batch(), redact_iter(), and add_custom_pattern().

Return Types

RedactResult

A dataclass returned by all redaction functions.

Detection

A frozen dataclass (immutable and hashable) representing a single PII detection.

CountryEvidence

One signal supporting a country attribution. New in 0.3.2.

DocumentContext

New in 0.3.2. Country inference reads signals out of the text, so a document processed in chunks loses accuracy at exactly the chunks that carry no signal of their own — a page of bare reference numbers between two pages full of Dutch addresses. A DocumentContext carries the evidence across chunks so the whole document is scored as one.

from euredact import DocumentContext, redact

ctx = DocumentContext()
offset = 0
for chunk in chunks:
    result = redact(chunk, context=ctx, chunk_offset=offset)
    offset += len(chunk)
    print(result.redacted_text)

# Every signal the document produced, spans pointing into the full text.
print(ctx.evidence())

Pass chunk_offset or the evidence spans will all point into the start of the text. Caching is disabled while a context is in use, since the result depends on the document rather than on the chunk alone.

Reuse a context only across chunks of the same document. A context shared between unrelated documents mixes their countries, which cannot cause a miss — a context influences scoring only, never which spans are found — but can attribute a value to the wrong national scheme.

Custom Patterns

Register custom regex patterns to detect domain-specific identifiers. Custom patterns are always active regardless of the countries parameter.

import euredact

euredact.add_custom_pattern("EMPLOYEE_ID", r"EMP-\d{6}")

result = euredact.redact("Contact EMP-123456 for details")
print(result.redacted_text)
# "Contact [EMPLOYEE_ID] for details"

Secret Detection

euRedact automatically detects secrets and API keys using two strategies.

Known-prefix detection

Matches tokens with recognized prefixes from common services:

Entropy-based detection

Flags 32+ character high-entropy strings found near context keywords such as key, token, secret, password, and their translations in 12 EU languages.

Performance

0.3.6 is about 13% slower than 0.3.2 per page, and about 14% slower per record. The extra work is rule and vocabulary growth from 0.3.5 and 0.3.6 — support-desk terms in nine languages, wider currency lists, more month spellings. The record figure moves more than the page figure because 0.3.5 began treating a value that fills an entire field of a delimited row as context, and a 300-character record is exactly that shape.

If you are coming from 0.3.3, you will find this faster. 0.3.3 fixed a real defect — Python’s \bis Unicode-aware where JavaScript’s is ASCII-only, so a national ID written against a non-ASCII letter (ЕГН7523169263, PESELŁ44051401359) was redacted by the Node SDK and silently missed by Python — but it paid for the fix by rewriting every \bin all 303 patterns into a three-branch union, which cost roughly 4×. 0.3.4 chose the boundary per occurrence instead and gave the time back without giving back the recall.

For throughput, install euredact[fast]: the RE2 prefilter roughly halves per-page latency. Node is unaffected by any of this at ~1.6 ms per page — its \b always behaved this way.