codex-core 0.1.0__tar.gz → 0.1.1__tar.gz

{codex_core-0.1.0 → codex_core-0.1.1}/.gitignore

@@ -194,6 +194,9 @@ gen/
 .cursorignore
 .cursorindexingignore
 
+# Claude Code
+.claude/
+
 # Marimo
 marimo/_static/
 marimo/_lsp/

{codex_core-0.1.0 → codex_core-0.1.1}/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.1] - 2025-02-12
+
+### Added
+- **Declarative PII Registry**: Introduced `PIIRegistry` class in `pii.py` for explicit sensitive field name tracking, complementing the heuristic keyword-based matching.
+- **Enhanced Documentation**:
+  - Comprehensive Google-style docstrings added to all core modules: `log_context`, `loguru_setup`, `phone`, `text`, `base_dto`, `exceptions`, and `settings/base`.
+  - Added localized (EN/RU) documentation links and PyPI/License badges to `README.md`.
+- **Dependency Management**: Added `loguru` as an explicit optional dependency in `pyproject.toml`.
+
+### Changed
+- **PII Masking Logic**: Refined `is_pii_field` and `mask_value` to prioritize explicit registry matches over heuristic keyword search.
+- **Project Configuration**: Updated `.gitignore` to include `.claude/` for modern AI tool support.
+
 ## [0.1.0] - 2024-05-24
 
 ### Added

{codex_core-0.1.0 → codex_core-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-core
-Version: 0.1.0
+Version: 0.1.1
 Summary: Core utilities, schemas and settings for Codex WaaS toolkit
 Project-URL: Homepage, https://github.com/codexdlc/codex-core
 Project-URL: Documentation, https://codexdlc.github.io/codex-core/
@@ -35,14 +35,24 @@ Requires-Dist: mkdocs-include-markdown-plugin; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: loguru
+Requires-Dist: loguru>=0.7.0; extra == 'loguru'
 Description-Content-Type: text/markdown
 
 # codex-core
 
 **Core utilities, schemas, and settings for the Codex WaaS toolkit.**
 
+[![PyPI](https://img.shields.io/pypi/v/codex-core)](https://pypi.org/project/codex-core/)
+[![Python](https://img.shields.io/pypi/pyversions/codex-core)](https://pypi.org/project/codex-core/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/codexdlc/codex-core/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-codexdlc.github.io-blue)](https://codexdlc.github.io/codex-core/)
+
 This library provides the foundational building blocks used by all other Codex tools. It focuses on Pydantic-based data models, structured logging, and configuration management.
 
+> **Documentation:**
+> [EN](https://codexdlc.github.io/codex-core/en_EN/) · [RU](https://codexdlc.github.io/codex-core/ru_RU/) · [API Reference](https://codexdlc.github.io/codex-core/api/) · [Changelog](https://codexdlc.github.io/codex-core/changelog/)
+
 ## 🚀 Key Features
 
 *   **Core Interfaces**: Base classes and protocols for Codex components.
@@ -66,4 +76,4 @@ logger.info("Codex Core is ready!")
 ```
 
 ---
-*Part of the [Codex WaaS](https://github.com/codexdlc) ecosystem.*
+*Part of the [Codex WaaS](https://github.com/codexdlc) ecosystem. · [EN Docs](https://codexdlc.github.io/codex-core/en_EN/) · [RU Docs](https://codexdlc.github.io/codex-core/ru_RU/) · [API](https://codexdlc.github.io/codex-core/api/) · [Changelog](https://codexdlc.github.io/codex-core/changelog/) · [Source](https://github.com/codexdlc/codex-core)*

codex_core-0.1.1/README.md

@@ -0,0 +1,38 @@
+# codex-core
+
+**Core utilities, schemas, and settings for the Codex WaaS toolkit.**
+
+[![PyPI](https://img.shields.io/pypi/v/codex-core)](https://pypi.org/project/codex-core/)
+[![Python](https://img.shields.io/pypi/pyversions/codex-core)](https://pypi.org/project/codex-core/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/codexdlc/codex-core/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-codexdlc.github.io-blue)](https://codexdlc.github.io/codex-core/)
+
+This library provides the foundational building blocks used by all other Codex tools. It focuses on Pydantic-based data models, structured logging, and configuration management.
+
+> **Documentation:**
+> [EN](https://codexdlc.github.io/codex-core/en_EN/) · [RU](https://codexdlc.github.io/codex-core/ru_RU/) · [API Reference](https://codexdlc.github.io/codex-core/api/) · [Changelog](https://codexdlc.github.io/codex-core/changelog/)
+
+## 🚀 Key Features
+
+*   **Core Interfaces**: Base classes and protocols for Codex components.
+*   **Common Utilities**: Logger setup (Loguru), phone number validation, text processing, and caching.
+*   **Schemas**: Shared Pydantic models for cross-service communication.
+*   **Settings**: Modern configuration management using `pydantic-settings`.
+
+## 📦 Installation
+
+```bash
+pip install codex-core
+```
+
+## 🛠️ Quick Start
+
+```python
+from codex_tools.common.logger import setup_logger
+
+logger = setup_logger("my-app")
+logger.info("Codex Core is ready!")
+```
+
+---
+*Part of the [Codex WaaS](https://github.com/codexdlc) ecosystem. · [EN Docs](https://codexdlc.github.io/codex-core/en_EN/) · [RU Docs](https://codexdlc.github.io/codex-core/ru_RU/) · [API](https://codexdlc.github.io/codex-core/api/) · [Changelog](https://codexdlc.github.io/codex-core/changelog/) · [Source](https://github.com/codexdlc/codex-core)*

{codex_core-0.1.0 → codex_core-0.1.1}/pyproject.toml

@@ -33,6 +33,7 @@ Changelog = "https://github.com/codexdlc/codex-core/blob/main/CHANGELOG.md"
 Issues = "https://github.com/codexdlc/codex-core/issues"
 
 [project.optional-dependencies]
+loguru = ["loguru>=0.7.0"]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",

codex_core-0.1.1/src/codex_core/common/log_context.py

@@ -0,0 +1,140 @@
+"""Structured logging context bound to a named task or worker.
+
+Provides :class:`TaskLogContext` — a thin, stateful wrapper around
+``logging.Logger`` that automatically enriches every log record with
+a fixed set of structured fields (task name, worker name, arbitrary
+extras).
+
+This module intentionally avoids any dependency on Loguru so that it
+works with any log sink: standard-library ``logging``, Loguru (via
+:class:`~codex_core.common.loguru_setup.InterceptHandler`), JSON
+formatters, ELK, or Loki.
+
+Example:
+    ```python
+    from codex_core.common.log_context import TaskLogContext
+
+    log = TaskLogContext("send_booking_notification", worker="notification_worker")
+    log.info("Processing appointment", extra={"appointment_id": 123})
+    # LogRecord contains: task="send_booking_notification",
+    #   worker="notification_worker", appointment_id=123
+    ```
+"""
+
+import logging
+from typing import Any
+
+
+class TaskLogContext:
+    """Structured logging adapter that binds context fields to every record.
+
+    Wraps a standard ``logging.Logger`` and automatically merges a
+    fixed ``_base_extra`` dict (built at construction time) with any
+    per-call ``extra`` dict before forwarding the record.  This
+    eliminates repetitive ``extra={"task": ...}`` boilerplate in
+    worker loops.
+
+    The class is **stateful** in the sense that ``_base_extra`` is
+    set once at construction and shared across all log calls.  It is
+    **not** thread-safe to mutate ``_base_extra`` after construction;
+    create a new instance per task if context must change.
+
+    Args:
+        task_name: Logical name of the current operation
+            (e.g. ``"send_booking_notification"``).  Stored as
+            ``task`` in every log record's ``extra``.
+        logger_name: Name passed to ``logging.getLogger()``.
+            Defaults to *task_name* when omitted.
+        **extra: Arbitrary keyword arguments added to ``_base_extra``
+            alongside ``task`` (e.g. ``worker="notification_worker"``).
+
+    Example:
+        ```python
+        log = TaskLogContext(
+            "slot_calculation",
+            logger_name="codex.booking",
+            worker="slot_worker",
+            tenant_id=42,
+        )
+        log.debug("Starting slot search")
+        log.error("Slot not found", extra={"slot_id": 7})
+        ```
+    """
+
+    def __init__(self, task_name: str, logger_name: str | None = None, **extra: Any) -> None:
+        self._logger = logging.getLogger(logger_name or task_name)
+        self._base_extra = {"task": task_name, **extra}
+
+    def _merge_extra(self, extra: dict[str, Any] | None) -> dict[str, Any]:
+        """Merge per-call extra fields with the base context.
+
+        Args:
+            extra: Optional per-call fields.  Keys in *extra* take
+                precedence over identically named keys in
+                ``_base_extra``.
+
+        Returns:
+            A new ``dict`` containing the merged fields.
+        """
+        if extra:
+            return {**self._base_extra, **extra}
+        return self._base_extra
+
+    def debug(self, msg: str, *args: Any, extra: dict[str, Any] | None = None, **kwargs: Any) -> None:
+        """Emit a ``DEBUG`` record enriched with the bound context fields.
+
+        Args:
+            msg: Log message format string.
+            *args: Positional arguments passed to ``Logger.debug``.
+            extra: Per-call structured fields merged with ``_base_extra``.
+            **kwargs: Additional keyword arguments forwarded to ``Logger.debug``.
+        """
+        self._logger.debug(msg, *args, extra=self._merge_extra(extra), **kwargs)
+
+    def info(self, msg: str, *args: Any, extra: dict[str, Any] | None = None, **kwargs: Any) -> None:
+        """Emit an ``INFO`` record enriched with the bound context fields.
+
+        Args:
+            msg: Log message format string.
+            *args: Positional arguments passed to ``Logger.info``.
+            extra: Per-call structured fields merged with ``_base_extra``.
+            **kwargs: Additional keyword arguments forwarded to ``Logger.info``.
+        """
+        self._logger.info(msg, *args, extra=self._merge_extra(extra), **kwargs)
+
+    def warning(self, msg: str, *args: Any, extra: dict[str, Any] | None = None, **kwargs: Any) -> None:
+        """Emit a ``WARNING`` record enriched with the bound context fields.
+
+        Args:
+            msg: Log message format string.
+            *args: Positional arguments passed to ``Logger.warning``.
+            extra: Per-call structured fields merged with ``_base_extra``.
+            **kwargs: Additional keyword arguments forwarded to ``Logger.warning``.
+        """
+        self._logger.warning(msg, *args, extra=self._merge_extra(extra), **kwargs)
+
+    def error(self, msg: str, *args: Any, extra: dict[str, Any] | None = None, **kwargs: Any) -> None:
+        """Emit an ``ERROR`` record enriched with the bound context fields.
+
+        Args:
+            msg: Log message format string.
+            *args: Positional arguments passed to ``Logger.error``.
+            extra: Per-call structured fields merged with ``_base_extra``.
+            **kwargs: Additional keyword arguments forwarded to ``Logger.error``.
+        """
+        self._logger.error(msg, *args, extra=self._merge_extra(extra), **kwargs)
+
+    def exception(self, msg: str, *args: Any, extra: dict[str, Any] | None = None, **kwargs: Any) -> None:
+        """Emit an ``ERROR`` record with exception traceback and bound context.
+
+        Equivalent to :meth:`error` but always captures the current
+        exception info (``exc_info=True`` is implicit).  Call inside an
+        ``except`` block.
+
+        Args:
+            msg: Log message format string.
+            *args: Positional arguments passed to ``Logger.exception``.
+            extra: Per-call structured fields merged with ``_base_extra``.
+            **kwargs: Additional keyword arguments forwarded to ``Logger.exception``.
+        """
+        self._logger.exception(msg, *args, extra=self._merge_extra(extra), **kwargs)

codex_core-0.1.1/src/codex_core/common/loguru_setup.py

@@ -0,0 +1,345 @@
+"""Application-level Loguru configuration helpers (optional dependency).
+
+Provides opinionated, zero-boilerplate Loguru setup for codex_tools
+applications.  The codex_core *library* itself never calls these
+helpers; it uses the standard ``logging`` module exclusively so that
+consumers retain full control over their log infrastructure.
+
+Three configurable sinks are created by both setup functions:
+
+1. **stdout** — colourised, human-readable format for local development.
+2. **debug.log** — rotating plain-text file, ``enqueue=True`` for
+   async-safe writing.
+3. **errors.json** — rotating JSON-serialised file capturing ``ERROR``
+   and above; suitable for ingestion by ELK / Loki pipelines.
+
+Standard-library ``logging`` records are bridged via
+:class:`InterceptHandler` so that third-party libraries (SQLAlchemy,
+httpx, aiogram, etc.) are automatically captured by Loguru.
+
+Availability:
+    ``loguru`` is an **optional** dependency.  Both :func:`setup_logging`
+    and :func:`setup_universal_logging` raise :exc:`ImportError` with an
+    actionable message when ``loguru`` is not installed.
+"""
+
+import logging
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+try:
+    from loguru import logger
+except ImportError:
+    logger = None  # type: ignore
+
+
+if TYPE_CHECKING:
+    from types import FrameType
+
+
+class InterceptHandler(logging.Handler):
+    """Bridge standard-library ``logging`` records to the Loguru sink.
+
+    Install this handler on the root logger (or any named logger) to
+    forward all ``logging``-based records into Loguru transparently.
+    The handler resolves the correct call-stack depth so that Loguru
+    reports the *original* call site rather than the handler frame.
+
+    This class is stateless and thread-safe; a single instance may be
+    shared across all intercepted loggers.
+
+    Example:
+        ```python
+        import logging
+        from codex_core.common.loguru_setup import InterceptHandler
+
+        logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+        ```
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Forward a single ``logging.LogRecord`` to the active Loguru logger.
+
+        Resolves the Loguru level name from the record's level name,
+        falls back to the integer level when the name is unknown, then
+        walks up the call stack to find the frame that originally issued
+        the log call — ensuring Loguru displays the correct source
+        location instead of the handler internals.
+
+        Args:
+            record: The log record produced by the standard-library
+                logging infrastructure.
+
+        Note:
+            If ``loguru`` is not installed (``logger is None``), this
+            method returns silently to avoid masking the original
+            ``ImportError``.
+        """
+        if logger is None:
+            return
+
+        level: str | int
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        frame: FrameType | None = logging.currentframe()
+        depth = 6
+        while frame and frame.f_code.co_filename == logging.__file__:
+            frame = frame.f_back
+            depth += 1
+
+        logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
+
+
+def setup_universal_logging(
+    log_dir: Path,
+    service_name: str = "App",
+    console_level: str = "INFO",
+    file_level: str = "DEBUG",
+    rotation: str = "10 MB",
+    is_debug: bool = False,
+) -> None:
+    """Configure Loguru with three sinks and standard-library interception.
+
+    Intended for applications that do not use
+    :class:`~codex_core.settings.BaseCommonSettings` but still want the
+    full codex_core logging stack.  Callers supply raw configuration
+    values directly rather than a settings object.
+
+    Sink layout after the call:
+
+    - **stdout** — colourised, ``console_level`` threshold.
+    - **<log_dir>/debug.log** — rotating plain text, ``file_level``
+      threshold, ``backtrace`` / ``diagnose`` enabled when
+      ``is_debug=True``.
+    - **<log_dir>/errors.json** — rotating JSON, ``ERROR`` threshold,
+      async-enqueued.
+    - **Root logger** — intercepted via :class:`InterceptHandler`.
+
+    Args:
+        log_dir: Directory where log files are created.  Created
+            recursively if it does not exist.
+        service_name: Label embedded in the console format string to
+            distinguish output from multiple co-running services.
+        console_level: Minimum level for stdout output (e.g. ``"INFO"``).
+        file_level: Minimum level for the debug log file
+            (e.g. ``"DEBUG"``).
+        rotation: Loguru rotation threshold string (e.g. ``"10 MB"`` or
+            ``"1 day"``).
+        is_debug: When ``True``, enables full ``backtrace`` and
+            ``diagnose`` output in the debug file sink.
+
+    Raises:
+        ImportError: If ``loguru`` is not installed in the environment.
+
+    Example:
+        ```python
+        from pathlib import Path
+        from codex_core.common.loguru_setup import setup_universal_logging
+
+        setup_universal_logging(
+            log_dir=Path("/var/log/myapp"),
+            service_name="booking-worker",
+            is_debug=True,
+        )
+        ```
+    """
+    if logger is None:
+        raise ImportError(
+            "loguru is not installed. Please install it manually: "
+            "pip install loguru"
+        )
+
+    logger.remove()
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1. Console output
+    logger.add(
+        sink=sys.stdout,
+        level=console_level,
+        colorize=True,
+        format=(
+            "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+            "<level>{level: <8}</level> | "
+            f"<magenta>{service_name}</magenta> | "
+            "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
+            "<level>{message}</level>"
+        ),
+    )
+
+    # 2. Debug file
+    logger.add(
+        sink=str(log_dir / "debug.log"),
+        level=file_level,
+        rotation=rotation,
+        compression="zip",
+        format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}",
+        enqueue=True,
+        backtrace=is_debug,
+        diagnose=is_debug,
+    )
+
+    # 3. Errors file (JSON)
+    logger.add(
+        sink=str(log_dir / "errors.json"),
+        level="ERROR",
+        serialize=True,
+        rotation=rotation,
+        compression="zip",
+        enqueue=True,
+    )
+
+    # 4. Intercept standard logging
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+    logger.info(f"Loguru setup complete for {service_name}. Logs: {log_dir}")
+
+
+@runtime_checkable
+class LoggingSettingsProtocol(Protocol):
+    """Structural protocol describing the logging-related subset of settings.
+
+    Any settings object that exposes these five attributes satisfies this
+    protocol and can be passed to :func:`setup_logging` without explicit
+    inheritance.  :class:`~codex_core.settings.BaseCommonSettings`
+    satisfies this protocol out of the box when its subclass adds the
+    required logging fields.
+
+    Attributes:
+        log_level_console: Minimum Loguru level for stdout
+            (e.g. ``"INFO"``).
+        log_level_file: Minimum Loguru level for the rotating debug
+            file (e.g. ``"DEBUG"``).
+        log_rotation: Loguru rotation threshold
+            (e.g. ``"10 MB"`` or ``"1 day"``).
+        log_dir: Base directory for log files.  A service-name
+            subdirectory is appended automatically by
+            :func:`setup_logging`.
+        debug: When ``True``, enables ``backtrace`` and ``diagnose``
+            in the file sink.
+    """
+
+    log_level_console: str
+    log_level_file: str
+    log_rotation: str
+    log_dir: str
+    debug: bool
+
+
+def setup_logging(
+    settings: LoggingSettingsProtocol,
+    service_name: str,
+    intercept_loggers: list[str] | None = None,
+    log_levels: dict[str, int] | None = None,
+) -> None:
+    """Configure Loguru from a settings object conforming to :class:`LoggingSettingsProtocol`.
+
+    Preferred entry-point for applications that use
+    :class:`~codex_core.settings.BaseCommonSettings`.  Configuration
+    is read from *settings* rather than raw arguments, enabling
+    environment-driven log levels without code changes.
+
+    PII masking is **not** handled here; it is the responsibility of
+    :class:`~codex_core.core.base_dto.BaseDTO.__repr__` at the DTO
+    level.  Do not log raw user input through this logger.
+
+    Side effects:
+        - Removes all existing Loguru handlers (``logger.remove()``).
+        - Creates ``<settings.log_dir>/<service_name>/`` directory tree.
+        - Replaces the root ``logging`` handler with
+          :class:`InterceptHandler`.
+        - Optionally replaces handlers on loggers listed in
+          *intercept_loggers*.
+        - Optionally sets log levels on loggers listed in *log_levels*.
+
+    Args:
+        settings: Any object satisfying :class:`LoggingSettingsProtocol`.
+            Typically a subclass of
+            :class:`~codex_core.settings.BaseCommonSettings`.
+        service_name: Identifies the service in log output and is used
+            as the leaf directory name under ``settings.log_dir``.
+        intercept_loggers: Optional list of logger names whose handlers
+            should be replaced with :class:`InterceptHandler`
+            (e.g. ``["aiogram", "sqlalchemy.engine"]``).
+        log_levels: Optional mapping of ``{logger_name: level_int}``
+            for silencing verbose third-party libraries
+            (e.g. ``{"httpx": logging.WARNING}``).
+
+    Raises:
+        ImportError: If ``loguru`` is not installed in the environment.
+
+    Example:
+        ```python
+        import logging
+        from codex_core.common.loguru_setup import setup_logging
+
+        setup_logging(
+            settings=app_settings,
+            service_name="api",
+            intercept_loggers=["uvicorn", "sqlalchemy.engine"],
+            log_levels={"httpx": logging.WARNING},
+        )
+        ```
+    """
+    if logger is None:
+        raise ImportError(
+            "loguru is not installed. Please install it manually: "
+            "pip install loguru"
+        )
+
+    logger.remove()
+
+    log_dir = Path(settings.log_dir) / service_name
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    # Console
+    logger.add(
+        sink=sys.stdout,
+        level=settings.log_level_console,
+        colorize=True,
+        format=(
+            "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+            "<level>{level: <8}</level> | "
+            f"<magenta>{service_name}</magenta> | "
+            "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
+            "<level>{message}</level>"
+        ),
+    )
+
+    # Debug file
+    logger.add(
+        sink=str(log_dir / "debug.log"),
+        level=settings.log_level_file,
+        rotation=settings.log_rotation,
+        compression="zip",
+        format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}",
+        enqueue=True,
+        backtrace=settings.debug,
+        diagnose=settings.debug,
+    )
+
+    # Errors file (JSON)
+    logger.add(
+        sink=str(log_dir / "errors.json"),
+        level="ERROR",
+        serialize=True,
+        rotation=settings.log_rotation,
+        compression="zip",
+        enqueue=True,
+    )
+
+    # Intercept standard logging
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+    # Intercept specified loggers
+    if intercept_loggers:
+        for name in intercept_loggers:
+            logging.getLogger(name).handlers = [InterceptHandler()]
+
+    # Set levels for noisy libraries
+    if log_levels:
+        for name, level in log_levels.items():
+            logging.getLogger(name).setLevel(level)

codex_core-0.1.1/src/codex_core/common/phone.py

@@ -0,0 +1,75 @@
+"""Utilities for normalizing phone numbers to a canonical digit-only format.
+
+Framework-agnostic (zero Django / framework dependencies).  Suitable
+for use in any Python 3.10+ environment including async workers.
+
+The module intentionally does not validate that the resulting number is
+reachable (no libphonenumber dependency); it only ensures a consistent
+digit-only representation that can be safely stored, compared, and
+passed to SMS / telephony APIs.
+"""
+
+
+def normalize_phone(phone: str, default_country: str = "49") -> str:
+    """Normalize a phone number to a digit-only international string.
+
+    Handles the three most common input variants encountered in
+    European / German-locale data:
+
+    1. **International ``+`` prefix** — ``+49 151 1234567``
+    2. **International ``00`` prefix** — ``0049 151 1234567``
+    3. **Local ``0`` prefix** — ``0151 1234567`` (expanded using
+       *default_country*)
+    4. **Already normalized** — ``491511234567`` (returned as-is)
+
+    Non-digit, non-plus characters (spaces, hyphens, parentheses) are
+    stripped before prefix detection.
+
+    Args:
+        phone: Raw phone string in any common format.  Empty string or
+            strings containing no digits/plus return ``""``.
+        default_country: ITU-T country code (digits only, no ``+``)
+            prepended when a local ``0``-prefix number is detected.
+            Defaults to ``"49"`` (Germany).
+
+    Returns:
+        Digit-only string representing the international phone number,
+        or an empty string if the input is blank or contains no
+        recognizable digits.
+
+    Note:
+        No length or reachability validation is performed.  The caller
+        is responsible for validating that the result conforms to the
+        expected E.164 length for the target country.
+
+    Example:
+        ```python
+        normalize_phone("0151 1234567")          # → "491511234567"
+        normalize_phone("+49 151 1234567")        # → "491511234567"
+        normalize_phone("0049 151 1234567")       # → "491511234567"
+        normalize_phone("+1-800-555-0100", "1")   # → "18005550100"
+        normalize_phone("")                        # → ""
+        ```
+    """
+    if not phone:
+        return ""
+
+    # Keep only digits and plus (if present at start)
+    cleaned = "".join(c for c in phone if c.isdigit() or c == "+")
+    if not cleaned:
+        return ""
+
+    # 1. Already has '+' -> remove it and return
+    if cleaned.startswith("+"):
+        return cleaned.replace("+", "")
+
+    # 2. Starts with '00' (European international format)
+    if cleaned.startswith("00"):
+        return cleaned[2:]
+
+    # 3. Starts with a single '0' (local format, e.g. German)
+    if cleaned.startswith("0"):
+        return default_country + cleaned[1:]
+
+    # 4. Already normalized number without plus (e.g. 49151...)
+    return cleaned