yb-observability 0.1.0__py3-none-any.whl

yb_observability/config/__init__.py

@@ -0,0 +1,13 @@
+from yb_observability.config.exceptions import (
+    ConfigEnvironmentVariableError,
+    ConfigFileNotFoundError,
+    ConfigLoaderError,
+)
+from yb_observability.config.loader import ConfigLoader
+
+__all__ = [
+    "ConfigEnvironmentVariableError",
+    "ConfigFileNotFoundError",
+    "ConfigLoader",
+    "ConfigLoaderError",
+]

yb_observability/config/exceptions.py

@@ -0,0 +1,10 @@
+class ConfigLoaderError(Exception):
+    """Base exception for configuration loading errors."""
+
+
+class ConfigFileNotFoundError(ConfigLoaderError):
+    """Raised when the configuration file cannot be found."""
+
+
+class ConfigEnvironmentVariableError(ConfigLoaderError):
+    """Raised when a required environment variable is missing."""

yb_observability/config/loader.py

@@ -0,0 +1,72 @@
+from os import getenv
+from pathlib import Path
+from re import Match, compile
+from typing import Any
+
+from yaml import YAMLError, safe_load
+
+from yb_observability.config.exceptions import (
+    ConfigEnvironmentVariableError,
+    ConfigFileNotFoundError,
+    ConfigLoaderError,
+)
+
+_ENV_VAR_PATTERN = compile(r"\$\{([A-Za-z][A-Za-z0-9_]*)\}")
+
+
+class ConfigLoader:
+    """Load YAML configuration and resolve environment variables."""
+
+    def __init__(self, config_path: str | Path) -> None:
+        self.config_path = Path(config_path)
+
+    def load(self) -> dict[str, Any]:
+        """Load and resolve the configuration file."""
+
+        if not self.config_path.is_file():
+            raise ConfigFileNotFoundError(
+                f"Configuration file not found: {self.config_path}"
+            )
+
+        try:
+            content = self.config_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ConfigLoaderError(
+                f"Unable to read configuration file: {self.config_path}"
+            ) from exc
+
+        resolved_content = self._resolve_environment_variables(content)
+
+        try:
+            config = safe_load(resolved_content)
+        except YAMLError as exc:
+            raise ConfigLoaderError(
+                f"Invalid YAML configuration: {self.config_path}"
+            ) from exc
+
+        if config is None:
+            return {}
+
+        if not isinstance(config, dict):
+            raise ConfigLoaderError(
+                "The root of the configuration file must be a YAML mapping."
+            )
+
+        return config
+
+    @staticmethod
+    def _resolve_environment_variables(content: str) -> str:
+        """Resolve ${ENV_VAR} references using environment variables."""
+
+        def replace(match: Match[str]) -> str:
+            variable_name = match.group(1)
+            value = getenv(variable_name)
+
+            if value is None:
+                raise ConfigEnvironmentVariableError(
+                    f"Required environment variable is not set: {variable_name}"
+                )
+
+            return value
+
+        return _ENV_VAR_PATTERN.sub(replace, content)

yb_observability/logging/__init__.py

@@ -0,0 +1,3 @@
+from yb_observability.logging.manager import configure_logging
+
+__all__ = ["configure_logging"]

yb_observability/logging/manager.py

@@ -0,0 +1,51 @@
+from pathlib import Path
+
+from loguru import logger
+
+_LOG_FORMAT = (
+    "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
+    "<level>{level: <5}</level> | "
+    "<cyan>[{extra[service]: <10}]</cyan> | "
+    "<blue>{name}:{function}:{line}</blue>\n"
+    "<level>| {message}</level>"
+)
+
+
+def configure_logging(
+    service: str,
+    *,
+    log_directory: str | Path = "logs",
+) -> None:
+    """Configure application logging for a service.
+
+    Args:
+        service: Name identifying the application or service.
+        log_directory: Root directory used for log files.
+    """
+    if not service.strip():
+        raise ValueError("Service name cannot be empty.")
+
+    log_path = Path(log_directory) / service
+    log_path.mkdir(parents=True, exist_ok=True)
+
+    logger.remove()
+
+    logger.configure(
+        extra={"service": service.upper()},
+    )
+
+    logger.add(
+        sink=lambda message: print(message, end=""),
+        format=_LOG_FORMAT,
+        level="DEBUG",
+        colorize=True,
+    )
+
+    logger.add(
+        log_path / "{time:YYYY-MM-DD}.log",
+        format=_LOG_FORMAT,
+        level="DEBUG",
+        rotation="00:00",
+        retention="30 days",
+        encoding="utf-8",
+    )

yb_observability-0.1.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: yb-observability
+Version: 0.1.0
+Summary: Reusable Python infrastructure for application configuration and observability.
+Author: Yassine Bouali
+License-File: LICENSE
+Requires-Python: <3.15,>=3.14
+Requires-Dist: loguru<1.0.0,>=0.7.3
+Requires-Dist: pyyaml<7.0,>=6.0
+Description-Content-Type: text/markdown
+
+# yb-observability
+
+Reusable Python infrastructure for application configuration and observability.
+
+`yb-observability` provides common infrastructure that can be shared across Python applications without coupling the library to a specific application or architecture.
+
+The project currently focuses on configuration and logging, with additional observability capabilities planned for future releases.
+
+## Features
+
+### Configuration
+
+* YAML configuration loading.
+* Environment variable resolution.
+* Nested environment variable support.
+* Configuration validation.
+* Clear configuration-related exceptions.
+
+### Logging
+
+* Loguru-based logging.
+* Explicit application/service identity.
+* Consistent human-readable log format.
+* Console logging.
+* File logging.
+* Daily log rotation.
+* Configurable retention.
+* Per-service log directories.
+
+### Future
+
+The library is designed to grow with additional infrastructure such as:
+
+* Structured/JSON logging.
+* Request and correlation IDs.
+* Metrics.
+* Distributed tracing.
+* OpenTelemetry integrations.
+* Additional observability integrations.
+
+Features are introduced incrementally and remain independent where possible.
+
+## Installation
+
+Install the package from PyPI:
+
+```bash
+pip install yb-observability
+```
+
+With `uv`:
+
+```bash
+uv add yb-observability
+```
+
+## Basic Usage
+
+Configuration:
+
+```python
+from yb_observability.config import ConfigLoader
+
+config = ConfigLoader("config.yml").load()
+```
+
+Logging:
+
+```python
+from yb_observability.logging import configure_logging
+
+configure_logging(service="my-service")
+```
+
+The application remains responsible for deciding what should be logged. `yb-observability` is responsible for configuring the logging infrastructure and providing a consistent logging interface.
+
+## Design Goals
+
+### Reusable
+
+The library must not depend on a specific application, framework, infrastructure provider, or domain.
+
+### Explicit
+
+Applications should explicitly configure the behavior they require rather than relying on hidden conventions.
+
+### Consistent
+
+Applications using the library should receive consistent configuration and logging behavior.
+
+### Extensible
+
+New capabilities should be possible without breaking the existing public API.
+
+### Testable
+
+Core functionality should be covered by automated tests.
+
+### Production-oriented
+
+The library should be suitable for both local development and production applications.
+
+## Project Structure
+
+```text
+yb-observability/
+├── src/
+│   └── yb_observability/
+│       ├── config/
+│       └── logging/
+│
+├── tests/
+│   ├── config/
+│   └── logging/
+│
+├── docs/
+│   ├── architecture/
+│   ├── configuration/
+│   └── logging/
+│
+├── .github/
+│   └── workflows/
+│
+├── CHANGELOG.md
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── README.md
+├── SECURITY.md
+└── pyproject.toml
+```
+
+## Development
+
+The project uses:
+
+* Python 3.14
+* uv
+* Ruff
+* Pyright
+* Pytest
+* Loguru
+* PyYAML
+
+Install development dependencies:
+
+```bash
+uv sync
+```
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+Run linting:
+
+```bash
+uv run ruff check .
+```
+
+Check formatting:
+
+```bash
+uv run ruff format --check .
+```
+
+Run type checking:
+
+```bash
+uv run pyright
+```
+
+## Contributing
+
+Contributions are welcome.
+
+Before submitting a pull request, make sure that:
+
+* Tests pass.
+* Ruff checks pass.
+* Formatting checks pass.
+* Pyright checks pass.
+* New functionality includes appropriate tests.
+* Public API changes are documented.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and contribution guidelines.
+
+## License
+
+This project is licensed under the terms defined in [LICENSE](LICENSE).

yb_observability-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+yb_observability/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yb_observability/config/__init__.py,sha256=uQ3gLWWL0__YYRIn9Dit4mZ0YerKgCqgmvjFlfFzQw0,324
+yb_observability/config/exceptions.py,sha256=DUaxgVVOyveg5CcYqp115_FObDBu3sjRdZKvT6jGj-4,334
+yb_observability/config/loader.py,sha256=Ad9L4HxBOxlWNb7ic5I6qFnZr9jtx-0WfKDQslSQh3g,2132
+yb_observability/logging/__init__.py,sha256=bvTUA55YxHhw9z2Ba82REmPTHta7oyyHP9q7jFPhxZw,96
+yb_observability/logging/manager.py,sha256=1r-lXPmg7NX1fWrMKwVAg3X3Gh62EKF82UglCbhGMHk,1202
+yb_observability-0.1.0.dist-info/METADATA,sha256=i4vSmiLhyQ68xkuzT55VNpMO4Z2-NggeDiSTvucV5PI,4094
+yb_observability-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+yb_observability-0.1.0.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yb_observability-0.1.0.dist-info/RECORD,,

yb_observability-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any