feat: add force_color support for Docker and non-TTY environments

Add force_color parameter and FORCE_COLOR environment variable support to enable
colored output in Docker containers and CI/CD pipelines where stdout is not a TTY.

Changes:
- Add force_color parameter to get_logger() function with auto-detection from FORCE_COLOR env var
- Pass force_color to ColoredFormatter to enable ANSI color codes in non-TTY environments
- Update README.md with usage examples for both environment variable and parameter approaches
- Add CLAUDE.md with comprehensive codebase documentation for AI-assisted development

Author: myakove

CLAUDE.md

@@ -0,0 +1,132 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**python-simple-logger** is a Python logging library providing colored console/file logging with duplicate log filtering and sensitive data masking. Built on top of `colorlog`, it extends Python's standard logging with custom log levels (SUCCESS, HASH, STEP) and filters.
+
+## Development Commands
+
+### Testing
+
+```bash
+# Run tests across all Python versions (3.9, 3.10, 3.11, 3.12, 3.13)
+tox
+
+# Run tests for current environment only
+uv run pytest simple_logger/tests
+
+# Run tests with coverage (auto-configured via pytest.ini)
+uv run pytest simple_logger/tests -v
+```
+
+**Coverage Requirements:**
+- Minimum coverage: 93% (enforced in pyproject.toml)
+- Coverage report: HTML output in `.tests_coverage/`
+- Test files excluded from coverage (see `tool.coverage.run.omit`)
+
+### Code Quality
+
+```bash
+# Format code (ruff auto-fix enabled)
+uv run ruff format .
+
+# Lint code
+uv run ruff check .
+
+# Type checking
+uv run mypy simple_logger/
+```
+
+**Quality Standards:**
+- Line length: 120 characters
+- Type hints required (mypy strict mode: disallow_untyped_defs, disallow_incomplete_defs)
+- Ruff preview mode enabled with auto-fix
+
+## Architecture
+
+### Core Components
+
+**`simple_logger/logger.py`** - Single-file library with four main components:
+
+1. **`SimpleLogger`** (lines 60-79)
+   - Custom logger class extending Python's `logging.Logger`
+   - Adds custom log levels: SUCCESS (32), HASH (33), STEP (34)
+   - Provides convenience methods: `.success()`, `.step()`, `.hash()`
+   - Set as default logger class via `logging.setLoggerClass(SimpleLogger)` (line 82)
+
+2. **`WrapperLogFormatter`** (lines 55-57)
+   - Extends `colorlog.ColoredFormatter`
+   - Overrides `formatTime()` to use ISO 8601 timestamps
+   - Configured with color mapping for all log levels
+
+3. **Filters**
+   - `DuplicateFilter` (lines 18-37): Suppresses repeated logs, appends count summary
+   - `RedactingFilter` (lines 40-52): Masks sensitive patterns with regex
+
+4. **`get_logger()`** (lines 85-166)
+   - Factory function returning singleton loggers (cached in `LOGGERS` dict)
+   - Handles both console and file handlers with rotation
+   - Auto-detects `FORCE_COLOR` env var for non-TTY environments (Docker/CI)
+
+### Key Design Patterns
+
+**Singleton Logger Pattern:**
+```python
+if LOGGERS.get(name):
+    return LOGGERS[name]  # Return cached logger
+```
+Ensures one logger instance per name.
+
+**Force Color Detection (lines 119-123):**
+```python
+if force_color is None:
+    force_color_env = os.environ.get("FORCE_COLOR", "").lower()
+    force_color = force_color_env in ("1", "true")
+```
+Critical for Docker logs - passes `force_color` to ColoredFormatter to enable ANSI codes in non-TTY environments.
+
+## Important Implementation Details
+
+### Adding New Features
+
+When modifying `get_logger()`:
+- Parameters must be added to function signature
+- Update docstring with new parameter
+- Consider singleton behavior - changes affect all future logger creations, not existing ones
+- Update README.md with usage examples
+
+### Color Output
+
+The `force_color` parameter/env var is essential for Docker environments where `sys.stdout.isatty()` returns False. Without it, colorlog disables colors even though Docker can display ANSI codes.
+
+### Testing
+
+Tests use pytest fixtures for logger instances (`basic_logger`, `logger_with_mask`). When adding features:
+- Test both parameter and environment variable paths
+- Use `tmp_log_file` fixture for file output tests
+- Verify both console and file handler behavior
+
+## Release Process
+
+This project uses `release-it` for versioning and releases:
+
+```bash
+# Prerequisites (one-time setup)
+export GITHUB_TOKEN=<token>
+sudo npm install --global release-it
+
+# Create release
+git pull
+release-it  # Interactive prompts guide the process
+```
+
+Version is managed in `pyproject.toml` (currently 2.0.17).
+
+## Build System
+
+- **Package manager:** uv (with lock file)
+- **Build backend:** hatchling
+- **Distribution:** PyPI at `python-simple-logger`
+- **Include:** Only `simple_logger/` directory in builds

README.md

@@ -57,4 +57,13 @@ hashed_logger.info(er = get"This is my secret -> sec1234abc")
 >>> This is my token *****
 >>> This is my apikey *****
 >>> This is my secret *****
+
+# Force colored output in non-TTY environments (Docker, CI/CD)
+# Option 1: Use FORCE_COLOR environment variable
+import os
+os.environ["FORCE_COLOR"] = "1"  # or set in Dockerfile/docker-compose.yml
+logger = get_logger(name=__name__)
+
+# Option 2: Use force_color parameter
+logger = get_logger(name=__name__, force_color=True)
 ```

simple_logger/logger.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+import os
 import re
 from datetime import datetime
 from logging.handlers import RotatingFileHandler
@@ -91,6 +92,7 @@ def get_logger(
     mask_sensitive: bool = False,
     duplicate_filter: bool = True,
     mask_sensitive_patterns: list[str] | None = None,
+    force_color: bool | None = None,
 ) -> logging.Logger:
     """
     Get logger object for logging.
@@ -104,6 +106,8 @@ def get_logger(
         file_backup_count (int): max number of log files to keep
         mask_sensitive (bool): whether to mask sensitive information
         mask_sensitive_patterns (list[str]): list of patterns to mask
+        force_color (bool or None): force colored output even in non-TTY environments.
+            If None, will check FORCE_COLOR environment variable.
 
     Returns:
         Logger: logger object
@@ -112,6 +116,12 @@ def get_logger(
     if LOGGERS.get(name):
         return LOGGERS[name]
 
+    # Determine force_color setting
+    if force_color is None:
+        # Check FORCE_COLOR environment variable
+        force_color_env = os.environ.get("FORCE_COLOR", "").lower()
+        force_color = force_color_env in ("1", "true")
+
     logger_obj = logging.getLogger(name)
     log_formatter = WrapperLogFormatter(
         fmt="%(asctime)s %(name)s %(log_color)s%(levelname)s%(reset)s %(message)s",
@@ -126,6 +136,7 @@ def get_logger(
             "STEP": "bold_cyan",
         },
         secondary_log_colors={},
+        force_color=force_color,
     )
 
     if console: