pii-safe-logger for Python

Dependency-free PII-safe structured logging and redaction utilities for Python. It is the Python member of the pii-safe-logger ecosystem and follows the same privacy-first behavior as the JavaScript package.

Created by Luis Aneuris Tavarez De Jesus.

Features

• Redacts nested dictionaries, collections, exceptions, objects, and circular references.
• Detects emails, phones, SSNs, Luhn-valid payment cards, JWTs, bearer tokens, and secrets.
• Supports custom sensitive fields, regular-expression rules, and partial masks.
• Emits structured JSON with child context and transaction IDs.
• Integrates with Python's standard logging module.
• Zero runtime dependencies and fully typed.

Installation

pip install pii-safe-logger

Quick start

from pii_safe_logger import create_pii_safe_logger

logger = create_pii_safe_logger(service="payments-service").with_transaction()
logger.info(
    "Payment created for luis@example.com",
    {
        "cardNumber": "4111111111111111",
        "amount": 250,
        "authorization": "Bearer abc.def.ghi",
    },
)

Redact without logging

from pii_safe_logger import redact

safe = redact({
    "email": "luis@example.com",
    "profile": {"phone": "+1 809 555 1234"},
})

Partial masking

from pii_safe_logger import FieldMask, RedactionOptions, redact

options = RedactionOptions(mask_fields=(
    FieldMask("cardNumber", preserve_first=6, preserve_last=4, replacement="******"),
))

redact({"cardNumber": "4111111111111111"}, options)
# {"cardNumber": "411111******1111"}

Standard logging integration

import logging
from pii_safe_logger import PiiRedactingFilter

handler = logging.StreamHandler()
handler.addFilter(PiiRedactingFilter())

logger = logging.getLogger("payments")
logger.addHandler(handler)
logger.info("Customer: %s", "luis@example.com")

Development

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
ruff check .
mypy src
pytest
python -m build
python -m twine check dist/*

Security

Pattern matching cannot guarantee detection of every business-specific secret. Treat this package as defense in depth, add your own sensitive fields, and avoid intentionally passing credentials to logs. See SECURITY.md.

License

MIT