Metadata-Version: 2.4
Name: safe-logs
Version: 0.1.0
Summary: 
Author: alien1403
Author-email: hanghicelrazvanmihai@gmail.com
Requires-Python: >=3.12
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Description-Content-Type: text/markdown

# safe-logs

A lightweight, zero-dependency Python library that automatically scrubs sensitive information (PII, secrets, API keys) from your logs.

## Why use `safe-logs`?

Keeping sensitive information out of your logs is critical for security and compliance. Log files are often aggregated and stored in centralized systems where multiple developers or third-party services might have access to them. Leaking emails, phone numbers, credit cards, or API tokens can lead to severe security breaches. `safe-logs` acts as a safety net, ensuring these secrets are masked before they ever hit the output stream.

## Installation

You can install `safe-logs` via pip:

```bash
pip install safe-logs
```

Or using poetry:

```bash
poetry add safe-logs
```

## Usage

### 1. The Quickest Way (Convenience Function)

The easiest way to start logging safely is to use the `get_safe_logger` function. This returns a standard Python `logging.Logger` with our scrubbing formatter already attached.

```python
from safe_logs import get_safe_logger

logger = get_safe_logger("my_app")

# Outputs: 2026-06-12 12:00:00,000 - my_app - INFO - User [MASKED_EMAIL] has signed in.
logger.info("User test@example.com has signed in.")
```

### 2. Using with an Existing Logger (ScrubbingFormatter)

If you already have a complex logging setup, you can simply swap out your standard formatter for the `ScrubbingFormatter`.

```python
import logging
from safe_logs import ScrubbingFormatter

logger = logging.getLogger("custom_app")
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler()
formatter = ScrubbingFormatter(fmt='%(levelname)s: %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)

logger.debug("API request with token='super-secret-token'")
# Outputs: DEBUG: API request with token='[MASKED_SECRET]'
```

### 3. Direct String & Structured Data Scrubbing (LogScrubber)

If you just need to scrub data independent of the `logging` module, you can use the `LogScrubber` class directly. It recursively scrubs strings, lists, and dictionaries.

```python
from safe_logs import LogScrubber

scrubber = LogScrubber()

data = {
    "user_id": 123,
    "email": "user@domain.com",
    "password": "my_super_secret_password"
}

clean_data = scrubber.scrub(data)
print(clean_data)
# Outputs: {'user_id': 123, 'email': '[MASKED_EMAIL]', 'password': '[MASKED]'}
```
*Note: Any dictionary key matching "password", "secret", "token", etc., is automatically scrubbed entirely, regardless of its value's format.*

## Advanced Features

### Partial Masking (Obfuscation)
Sometimes for debugging, you want to see the last 4 digits of a credit card or API key instead of replacing the entire string.

```python
from safe_logs import LogScrubber, keep_last_n_chars

scrubber = LogScrubber(mask_templates={
    "credit_card": keep_last_n_chars(4, '*'),
    "api_key": keep_last_n_chars(4, '*')
})

# Outputs: "Card: ****************3456"
print(scrubber.scrub("Card: 1234-5678-9012-3456"))
```

### Adding Custom Patterns
You can easily add your own regex patterns to the scrubber:

```python
scrubber = LogScrubber()

# Add a Social Security Number pattern
scrubber.add_pattern("ssn", r"\b\d{3}-\d{2}-\d{4}\b", "[MASKED_SSN]")

# Outputs: "SSN: [MASKED_SSN]"
print(scrubber.scrub("SSN: 123-45-6789"))
```


