hyperlog-tools 0.1.1__py3-none-any.whl

hyperlog/__init__.py

@@ -0,0 +1,13 @@
+from src.hyperlog.errors import (
+    get_log_file,
+    log_exception,
+    reset_logger,
+)
+
+__all__ = [
+    "get_log_file",
+    "log_exception",
+    "reset_logger",
+]
+
+__version__ = "0.1.1"

hyperlog/errors.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import logging
+import os
+import re
+import threading
+import traceback
+import uuid
+
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from types import TracebackType
+
+_LOGGER: logging.Logger | None = None
+_LOG_FILE: Path | None = None
+_LOCK = threading.RLock()
+
+_LOGGER_NAME = "hyperlog.errors"
+_MAX_LOG_SIZE = 5 * 1024 * 1024
+_BACKUP_COUNT = 5
+
+
+def _redact(text: str) -> str:
+    """Redact common secret values before writing logs."""
+    patterns = [
+        re.compile(r"""(?ix)
+            \b(
+                bot[_-]?token |
+                api[_-]?key |
+                password |
+                passwd |
+                secret |
+                authorization |
+                access[_-]?token |
+                refresh[_-]?token
+            )\b
+            (\s*[:=]\s*)
+            (["']?)[^\s,;'"&]+
+            """),
+        re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+"),
+    ]
+
+    for pattern in patterns:
+        if pattern.pattern.startswith("(?i)"):
+            text = pattern.sub("Bearer <REDACTED>", text)
+        else:
+            text = pattern.sub(r"\1\2<REDACTED>", text)
+
+    return text
+
+
+def _get_logger() -> logging.Logger:
+    """Initialize the logger once, safely across threads."""
+    global _LOGGER, _LOG_FILE
+
+    with _LOCK:
+        if _LOGGER is not None:
+            return _LOGGER
+
+        log_dir = Path(
+            os.getenv(
+                "HYPERLOG_LOG_DIR",
+                str(Path.cwd() / "logs"),
+            )
+        ).expanduser()
+
+        log_dir.mkdir(parents=True, exist_ok=True)
+
+        _LOG_FILE = log_dir / "errors.log"
+
+        logger = logging.getLogger(_LOGGER_NAME)
+        logger.setLevel(logging.ERROR)
+        logger.propagate = False
+
+        # Avoid duplicate handlers after repeated initialization.
+        for handler in logger.handlers[:]:
+            logger.removeHandler(handler)
+            handler.close()
+
+        formatter = logging.Formatter(
+            "%(asctime)s | %(levelname)s | %(name)s\n%(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+
+        file_handler = RotatingFileHandler(
+            _LOG_FILE,
+            maxBytes=_MAX_LOG_SIZE,
+            backupCount=_BACKUP_COUNT,
+            encoding="utf-8",
+        )
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
+        console_handler = logging.StreamHandler()
+        console_handler.setFormatter(formatter)
+        logger.addHandler(console_handler)
+
+        _LOGGER = logger
+        return logger
+
+
+def log_exception(
+    error: BaseException,
+    *,
+    context: str | None = None,
+) -> str:
+    """
+    Record an exception and return its unique error ID.
+
+    This function records the error but does not suppress,
+    re-raise, or otherwise handle the exception for the caller.
+    """
+    if not isinstance(error, BaseException):
+        raise TypeError("error must be an exception instance")
+
+    error_id = f"HL-{uuid.uuid4().hex[:12].upper()}"
+
+    tb: TracebackType | None = error.__traceback__
+    frames = traceback.extract_tb(tb) if tb else []
+
+    if frames:
+        # The last frame is the immediate location where the
+        # exception was raised.
+        frame = frames[-1]
+        filename = frame.filename
+        function = frame.name
+        line = frame.lineno
+    else:
+        filename = "<unknown>"
+        function = "<unknown>"
+        line = 0
+
+    message = str(error) or "<no error message>"
+
+    if tb is not None:
+        full_traceback = "".join(
+            traceback.format_exception(
+                type(error),
+                error,
+                tb,
+            )
+        )
+    else:
+        full_traceback = "Traceback unavailable: exception has no traceback."
+
+    details = [
+        "=" * 72,
+        f"Error ID: {error_id}",
+        f"Exception: {type(error).__name__}",
+        f"Message: {message}",
+        f"File: {filename}",
+        f"Function: {function}",
+        f"Line: {line}",
+    ]
+
+    if context:
+        details.append(f"Context: {context}")
+
+    details.extend(
+        [
+            "",
+            "Full Traceback:",
+            full_traceback.rstrip(),
+            "=" * 72,
+        ]
+    )
+
+    report = _redact("\n".join(details))
+
+    # Logging normally should not change the application's
+    # exception handling behavior.
+    try:
+        _get_logger().error("%s", report)
+    except OSError:
+        # Do not silently claim the log was saved. If logging
+        # fails, emit a minimal fallback to stderr.
+        import sys
+
+        print(
+            f"HyperLog could not write the log file. " f"Error ID: {error_id}",
+            file=sys.stderr,
+        )
+        print(report, file=sys.stderr)
+
+    return error_id
+
+
+def get_log_file() -> Path:
+    """Return the configured log file path."""
+    _get_logger()
+
+    if _LOG_FILE is None:
+        raise RuntimeError("HyperLog logger was not initialized")
+
+    return _LOG_FILE
+
+
+def reset_logger() -> None:
+    """
+    Close and remove this logger's handlers.
+
+    Intended for tests or controlled application shutdown.
+    The next logging call will initialize it again.
+    """
+    global _LOGGER, _LOG_FILE
+
+    with _LOCK:
+        logger = logging.getLogger(_LOGGER_NAME)
+
+        for handler in logger.handlers[:]:
+            logger.removeHandler(handler)
+            handler.close()
+
+        _LOGGER = None
+        _LOG_FILE = None

hyperlog/functions.py

@@ -0,0 +1,108 @@
+import asyncio
+import logging
+import re
+import secrets
+import time
+
+from collections.abc import Callable
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+# 1. Generate secure IDs
+def generate_id(length: int = 32) -> str:
+    if length < 1:
+        raise ValueError("length must be positive")
+
+    return secrets.token_hex((length + 1) // 2)[:length]
+
+
+# 2. Clean text
+def clean_text(text: str) -> str:
+    if not isinstance(text, str):
+        raise TypeError("text must be a string")
+
+    return re.sub(r"\s+", " ", text).strip()
+
+
+# 3. Retry synchronous operations
+def retry(
+    func: Callable[[], T],
+    attempts: int = 3,
+    delay: float = 1.0,
+    exceptions: tuple = (ConnectionError, TimeoutError),
+) -> T:
+    if attempts < 1:
+        raise ValueError("attempts must be at least 1")
+
+    if delay < 0:
+        raise ValueError("delay cannot be negative")
+
+    for attempt in range(attempts):
+        try:
+            return func()
+        except exceptions:
+            if attempt == attempts - 1:
+                raise
+
+            time.sleep(delay)
+
+    raise RuntimeError("Unexpected retry state")
+
+
+# 4. Retry asynchronous operations
+async def async_retry(
+    func: Callable,
+    attempts: int = 3,
+    delay: float = 1.0,
+    exceptions: tuple = (ConnectionError, TimeoutError),
+):
+    if attempts < 1:
+        raise ValueError("attempts must be at least 1")
+
+    if delay < 0:
+        raise ValueError("delay cannot be negative")
+
+    for attempt in range(attempts):
+        try:
+            return await func()
+        except exceptions:
+            if attempt == attempts - 1:
+                raise
+
+            await asyncio.sleep(delay)
+
+    raise RuntimeError("Unexpected retry state")
+
+
+# 5. Configure logging
+def setup_logging(
+    name: str = "hyperlog",
+    file: str = "hyperlog.log",
+    level: int = logging.INFO,
+) -> logging.Logger:
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    logger.propagate = False
+
+    if not logger.handlers:
+        formatter = logging.Formatter(
+            "%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+
+        console = logging.StreamHandler()
+        console.setFormatter(formatter)
+
+        logger.addHandler(console)
+
+        if file:
+            file_handler = logging.FileHandler(
+                file,
+                encoding="utf-8",
+            )
+            file_handler.setFormatter(formatter)
+            logger.addHandler(file_handler)
+
+    return logger

hyperlog_tools-0.1.1.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.5
+Name: hyperlog-tools
+Version: 0.1.1
+Summary: Reusable Python utilities by Hyper Source
+Author: Hyper Source
+License-Expression: MIT
+License-File: LICENSE
+Keywords: error-handling,hyperlog,logging,python,utilities
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Hyperlog
+
+Reusable Python utilities developed by Hyper Source.
+
+## Features
+
+- Detailed exception logging.
+- Unique error identifiers.
+- Full traceback recording.
+- Automatic log file creation.
+- Log rotation.
+- Common secret redaction.
+- Support for synchronous and asynchronous application errors.
+
+## Installation
+
+```bash
+pip install hyperlog
+```
+
+## Quick Start
+
+```python
+from hyperlog import log_exception
+
+try:
+    int("invalid")
+except ValueError as error:
+    error_id = log_exception(
+        error,
+        context="Input validation",
+    )
+    print(f"Error ID: {error_id}")
+```
+
+## License
+
+MIT License.

hyperlog_tools-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+hyperlog/__init__.py,sha256=5BjtKocx984nTebEqdllhbm4auzTu43QbIwbThyDWFA,203
+hyperlog/errors.py,sha256=ZhkZQre7F8rmB-5wF_7LH157CrtpWcWDv09W16NFhWs,5641
+hyperlog/functions.py,sha256=0rSJKb8NC5Jss-SKdInqBuczZri2l4sGcIxuu9dLjjs,2618
+hyperlog_tools-0.1.1.dist-info/METADATA,sha256=CvgImbjmkul1umlGcTy3E2-0oZgCArvF2u2XqPW7oSA,1314
+hyperlog_tools-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+hyperlog_tools-0.1.1.dist-info/licenses/LICENSE,sha256=I3S3F7wdGGX1Hx9XAYuDRQDZ59TTs_O8e70qBXQN4dA,1090
+hyperlog_tools-0.1.1.dist-info/RECORD,,

hyperlog_tools-0.1.1.dist-info/WHEEL

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

hyperlog_tools-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyper Source
+
+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.