chu4hel-plogger 0.1.0__tar.gz

chu4hel_plogger-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chu4hel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chu4hel_plogger-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: chu4hel-plogger
+Version: 0.1.0
+Summary: PLogger: A Python logging utility for CSV files with intelligent, metric-based rotation strategies to preserve significant data.
+License: MIT
+License-File: LICENSE
+Author: Chu4hel
+Author-email: 106600877+Chu4hel@users.noreply.github.com
+Requires-Python: >=3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Description-Content-Type: text/markdown
+
+# PLogger: An Intelligent Logger for Preserving What Matters Most
+
+[Русская версия README](docs/README_RU.md)
+
+**PLogger** is a universal Python logger designed for collecting and analyzing performance metrics, experimental
+results, or any other structured data. Its main feature is intelligent rotation strategies that allow you to preserve
+the most unique and interesting records (outliers) while removing redundant data.
+
+Unlike standard loggers that simply delete old entries, PLogger analyzes the data and retains those that stand out most
+from the rest.
+
+## Key Features
+
+- **Intelligent Rotation**: Built-in strategies (`by_metric`, `by_group_metric`) to preserve the most significant data
+  when the log limit is reached.
+- **Thread-Safety**: Secure logging from multiple threads without the risk of data corruption.
+- **Ease of Use**: A concise API for quick integration into any project.
+- **CSV Logging**: Data is stored in a universal and easily readable CSV format.
+- **Zero Configuration**: Automatic creation of log directories and files.
+
+## Installation
+
+```bash
+pip install plogger
+```
+
+*(Note: After you publish the package to PyPI)*
+
+## Basic Usage
+
+```python
+from pathlib import Path
+from plogger import PLogger
+
+# Initialize the logger
+# Retain up to 100 entries, then remove the "least interesting" based on 'latency_ms' metric
+logger = PLogger(
+    log_path=Path("performance_logs.csv"),
+    header=["request_id", "latency_ms", "status_code"],
+    max_entries=100,
+    rotation_strategy='by_metric',
+    metric_column='latency_ms'
+)
+
+# Log regular requests
+logger.log({"request_id": "abc-123", "latency_ms": 52, "status_code": 200})
+logger.log({"request_id": "def-456", "latency_ms": 55, "status_code": 200})
+
+# ...after many entries...
+
+# Log an unusually long request.
+# Thanks to the 'by_metric' strategy, this record is highly likely
+# to be preserved in the log even after rotation.
+logger.log({"request_id": "xyz-789", "latency_ms": 5300, "status_code": 500})
+```
+
+## Rotation Strategies
+
+- `fifo`: Standard "first-in, first-out" strategy. Removes the oldest entry.
+- `by_metric`: Finds a pair of entries with the smallest difference in a numerical metric (`metric_column`) and removes
+  the older one from that pair. Ideal for preserving outliers and unique values.
+- `by_group_metric`: First finds the largest group of entries (by `group_column`), and then applies the `by_metric`
+  logic within that group. Useful when you need to analyze anomalies within the context of a specific category.
+
+## License
+
+The project is distributed under the [MIT License](LICENSE).
+

chu4hel_plogger-0.1.0/README.md

@@ -0,0 +1,67 @@
+# PLogger: An Intelligent Logger for Preserving What Matters Most
+
+[Русская версия README](docs/README_RU.md)
+
+**PLogger** is a universal Python logger designed for collecting and analyzing performance metrics, experimental
+results, or any other structured data. Its main feature is intelligent rotation strategies that allow you to preserve
+the most unique and interesting records (outliers) while removing redundant data.
+
+Unlike standard loggers that simply delete old entries, PLogger analyzes the data and retains those that stand out most
+from the rest.
+
+## Key Features
+
+- **Intelligent Rotation**: Built-in strategies (`by_metric`, `by_group_metric`) to preserve the most significant data
+  when the log limit is reached.
+- **Thread-Safety**: Secure logging from multiple threads without the risk of data corruption.
+- **Ease of Use**: A concise API for quick integration into any project.
+- **CSV Logging**: Data is stored in a universal and easily readable CSV format.
+- **Zero Configuration**: Automatic creation of log directories and files.
+
+## Installation
+
+```bash
+pip install plogger
+```
+
+*(Note: After you publish the package to PyPI)*
+
+## Basic Usage
+
+```python
+from pathlib import Path
+from plogger import PLogger
+
+# Initialize the logger
+# Retain up to 100 entries, then remove the "least interesting" based on 'latency_ms' metric
+logger = PLogger(
+    log_path=Path("performance_logs.csv"),
+    header=["request_id", "latency_ms", "status_code"],
+    max_entries=100,
+    rotation_strategy='by_metric',
+    metric_column='latency_ms'
+)
+
+# Log regular requests
+logger.log({"request_id": "abc-123", "latency_ms": 52, "status_code": 200})
+logger.log({"request_id": "def-456", "latency_ms": 55, "status_code": 200})
+
+# ...after many entries...
+
+# Log an unusually long request.
+# Thanks to the 'by_metric' strategy, this record is highly likely
+# to be preserved in the log even after rotation.
+logger.log({"request_id": "xyz-789", "latency_ms": 5300, "status_code": 500})
+```
+
+## Rotation Strategies
+
+- `fifo`: Standard "first-in, first-out" strategy. Removes the oldest entry.
+- `by_metric`: Finds a pair of entries with the smallest difference in a numerical metric (`metric_column`) and removes
+  the older one from that pair. Ideal for preserving outliers and unique values.
+- `by_group_metric`: First finds the largest group of entries (by `group_column`), and then applies the `by_metric`
+  logic within that group. Useful when you need to analyze anomalies within the context of a specific category.
+
+## License
+
+The project is distributed under the [MIT License](LICENSE).

chu4hel_plogger-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[tool.poetry]
+name = "chu4hel-plogger"
+version = "0.1.0"
+description = "PLogger: A Python logging utility for CSV files with intelligent, metric-based rotation strategies to preserve significant data."
+authors = ["Chu4hel <106600877+Chu4hel@users.noreply.github.com>"]
+license = "MIT"
+packages = [{ include = "plogger", from = "src" }]
+readme = "README.md"
+exclude = [
+    "tests/",
+    "site/",
+    "examples/",
+    "docs/",
+    ".github/",
+    ".idea/",
+    "__pycache__/",
+    "*.pyc",
+    "*.log",
+    "*.egg-info/",
+    ".vscode/",
+    ".ruff_cache/",
+    "coverage.xml",
+    ".coverage",
+    "PUBLISHING.md",
+    "project.txt",
+    "changelog.txt",
+]
+
+
+[tool.poetry.dependencies]
+python = ">=3.10"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src"
+]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.0.2"
+pytest-cov = "^5.0.0"
+pytest-mock = "^3.14.0"

chu4hel_plogger-0.1.0/src/plogger/__init__.py

@@ -0,0 +1,48 @@
+"""
+PLogger - A Universal Performance Logging Utility for Python.
+
+Provides the `PLogger` class for thread-safe logging to CSV files with
+intelligent, metric-based rotation strategies. Ideal for collecting
+performance metrics, experimental results, or any structured data
+where it's important to preserve unique values (outliers) while
+managing log size.
+
+Key Features:
+- Thread-safe writes for use in concurrent applications.
+- Multiple rotation strategies:
+  - `fifo`: Standard first-in, first-out.
+  - `by_metric`: Keeps outliers by removing entries with the smallest metric difference to their neighbors.
+  - `by_group_metric`: Applies `by_metric` logic within the largest group of entries.
+- Simple, dictionary-based logging.
+- Automatic creation of log files and directories.
+
+Basic Usage:
+------------
+from pathlib import Path
+from plogger import PLogger
+
+# Initialize the logger
+logger = PLogger(
+    log_path=Path("performance_logs.csv"),
+    header=["request_id", "latency_ms"],
+    max_entries=100,
+    rotation_strategy='by_metric',
+    metric_column='latency_ms'
+)
+
+# Log data
+logger.log({"request_id": "abc-123", "latency_ms": 150.5})
+"""
+from importlib import metadata
+
+from .plogger import PLogger
+
+try:
+    # This will read the version from the installed package's metadata
+    __version__ = metadata.version("plogger")
+except metadata.PackageNotFoundError:
+    # This happens when the package is not installed, e.g., when running tests
+    # or in a development environment.
+    __version__ = "0.0.0-dev"
+
+__all__ = ["PLogger"]

chu4hel_plogger-0.1.0/src/plogger/plogger.py

@@ -0,0 +1,184 @@
+"""Универсальный модуль для логирования метрик производительности.
+
+Этот модуль предоставляет класс `PLogger` для сбора и записи метрик
+производительности в CSV файлы с поддержкой потокобезопасной записи
+и настраиваемых стратегий ротации логов.
+"""
+import csv
+import threading
+from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Callable
+
+
+class PLogger:
+    """
+    Универсальный сервис для сбора и записи метрик производительности в один CSV файл.
+    Обеспечивает потокобезопасную запись и интеллектуальную ротацию логов.
+    """
+
+    def __init__(
+            self,
+            log_path: Path,
+            header: List[str],
+            max_entries: int,
+            rotation_strategy: str = 'fifo',  # 'fifo', 'by_metric', 'by_group_metric'
+            metric_column: Optional[str] = None,
+            group_column: Optional[str] = None
+    ):
+        """
+        Инициализирует логгер для одного файла.
+
+        Args:
+            log_path: Полный путь к файлу лога.
+            header: Список заголовков для CSV файла.
+            max_entries: Максимальное количество записей в логе перед ротацией.
+            rotation_strategy: Стратегия ротации ('fifo', 'by_metric', 'by_group_metric').
+            metric_column: Имя колонки, используемой для метрики при ротации.
+            group_column: Имя колонки, используемой для группировки при ротации.
+        """
+        self.log_path: Path = log_path
+        self.header: List[str] = ["timestamp"] + header
+        self._max_entries: int = max_entries
+        self.metric_column: Optional[str] = metric_column
+        self.group_column: Optional[str] = group_column
+        self._lock: threading.Lock = threading.Lock()
+
+        self._rotation_strategies: Dict[str, Callable] = {
+            'fifo': lambda h, lines: 0,
+            'by_metric': self.__get_index_to_discard_by_metric,
+            'by_group_metric': self.__get_index_to_discard_by_group_metric,
+        }
+        if rotation_strategy not in self._rotation_strategies:
+            raise ValueError(f"Unknown rotation strategy: {rotation_strategy}")
+        self._rotation_strategy: Callable = self._rotation_strategies[rotation_strategy]
+
+        self.log_path.parent.mkdir(exist_ok=True, parents=True)
+        self.__init_log_file()
+
+    @property
+    def max_entries(self) -> int:
+        return self._max_entries
+
+    @max_entries.setter
+    def max_entries(self, value: int) -> None:
+        with self._lock:
+            self._max_entries = value
+
+    def log(self, data: Dict[str, Any]) -> None:
+        """
+        Записывает одну строку данных в лог.
+
+        Args:
+            data: Словарь, где ключи - это имена колонок из `header` (кроме 'timestamp').
+        """
+        with self._lock:
+            try:
+                # Убираем None значения, чтобы не писать лишнего
+                clean_data = {k: v for k, v in data.items() if v is not None}
+
+                header, lines = self.__read_log_data()
+
+                # Формируем строку в правильном порядке
+                new_row = [datetime.now().isoformat()]
+                # Пропускаем 'timestamp' в header при сопоставлении
+                for col in self.header[1:]:
+                    new_row.append(str(clean_data.get(col, '')))
+
+                lines.append(new_row)
+
+                # Ротация
+                if 0 < self.max_entries < len(lines):
+                    lines = self.__rotate(lines, header)
+
+                self.__write_log_data(self.log_path, header, lines)
+            except Exception as e:
+                print(f"Ошибка при записи в лог {self.log_path.name}: {e}")
+
+    def __init_log_file(self) -> None:
+        """Проверяет наличие файла и создает его с заголовком, если он отсутствует."""
+        if not self.log_path.exists() or self.log_path.stat().st_size == 0:
+            with self.log_path.open('w', newline='', encoding='utf-8') as f:
+                writer = csv.writer(f)
+                writer.writerow(self.header)
+
+    def __rotate(self, lines: List[List[str]], header: List[str]) -> List[List[str]]:
+        """Применяет выбранную стратегию для удаления лишних записей."""
+        while len(lines) > self.max_entries:
+            idx = self._rotation_strategy(header, lines)
+            lines.pop(idx)
+        return lines
+
+    # --- Блок I/O ---
+    def __read_log_data(self) -> tuple[List[str], List[List[str]]]:
+        if self.log_path.exists() and self.log_path.stat().st_size > 0:
+            with self.log_path.open('r', newline='', encoding='utf-8') as f:
+                reader = csv.reader(f)
+                header = next(reader, [])
+                return header, list(reader)
+        return self.header, []
+
+    @staticmethod
+    def __write_log_data(file_path: Path, header: List[str], lines: List[List[str]]) -> None:
+        with file_path.open('w', newline='', encoding='utf-8') as f:
+            writer = csv.writer(f)
+            writer.writerow(header)
+            writer.writerows(lines)
+
+    # --- Блок алгоритмов ротации ---
+    def __get_index_to_discard_by_metric(self, header: List[str], lines: List[List[str]]) -> int:
+        """Находит индекс записи, метрика которой наиболее близка к соседу."""
+        if self.metric_column is None:
+            return 0  # Fallback to FIFO if no metric column is specified
+
+        try:
+            m_idx = header.index(self.metric_column)
+            indexed_metrics = []
+            for i, line in enumerate(lines):
+                try:
+                    indexed_metrics.append((float(line[m_idx]), i))
+                except (ValueError, IndexError):
+                    continue
+
+            if len(indexed_metrics) < 2:
+                return 0
+
+            indexed_metrics.sort()
+
+            min_diff = float('inf')
+            target_idx = 0
+            for i in range(len(indexed_metrics) - 1):
+                diff = indexed_metrics[i + 1][0] - indexed_metrics[i][0]
+                if diff < min_diff:
+                    min_diff = diff
+                    target_idx = min(indexed_metrics[i][1], indexed_metrics[i + 1][1])
+            return target_idx
+
+        except (ValueError, IndexError):
+            return 0
+
+    def __get_index_to_discard_by_group_metric(self, header: List[str], lines: List[List[str]]) -> int:
+        """Группирует по `group_column` и ищет близкие по `metric_column`."""
+        if self.group_column is None or self.metric_column is None:
+            return 0  # Fallback to FIFO
+
+        try:
+            name_idx = header.index(self.group_column)
+            groups = defaultdict(list)
+            for i, line in enumerate(lines):
+                groups[line[name_idx]].append(i)
+
+            largest_group_name = max(groups, key=lambda k: len(groups[k]))
+            group_indices = groups[largest_group_name]
+
+            if len(group_indices) < 2:
+                # Если в самой большой группе меньше 2х элементов, то просто удаляем самый старый из группы
+                return group_indices[0]
+
+            group_lines = [lines[i] for i in group_indices]
+            sub_idx = self.__get_index_to_discard_by_metric(header, group_lines)
+            return group_indices[sub_idx]
+
+        except (ValueError, IndexError):
+            return 0