logging-module 0.2.0__py3-none-any.whl

logging_module/__init__.py

@@ -0,0 +1,32 @@
+"""
+Logging Module - A comprehensive logging and file utility package.
+
+This module provides:
+- Logging configuration and management
+- File utilities for logging operations
+- Tracing and debug capabilities
+"""
+
+from .my_logging import Logger
+from .config import GLOBAL_LOGGING_ENABLED, GLOBAL_LOG_TRACING_ENABLED
+from .file_utils import (
+    FileUtilsError,
+    FileExecutionError,
+    FileOperator,
+    file_verify_path,
+    file_verify_file,
+)
+
+__version__ = "0.2.0"
+__author__ = "Nathan T Nguyen"
+
+__all__ = [
+    "Logger",
+    "GLOBAL_LOGGING_ENABLED",
+    "GLOBAL_LOG_TRACING_ENABLED",
+    "FileUtilsError",
+    "FileExecutionError",
+    "FileOperator",
+    "file_verify_path",
+    "file_verify_file",
+]

logging_module/config.py

@@ -0,0 +1,10 @@
+#######################################################################
+#                          
+# Logging Module Configuration
+#
+# Configuration for logging and tracing
+#
+#######################################################################
+
+GLOBAL_LOGGING_ENABLED = True
+GLOBAL_LOG_TRACING_ENABLED = True

logging_module/file_utils.py

@@ -0,0 +1,108 @@
+#######################################################################
+#
+# File Utils
+#
+# Utility functions for file and directory operations
+# Handles path verification and error management
+#
+#######################################################################
+
+import os
+from enum import Enum
+
+
+class FileUtilsError(str, Enum):
+    # Directory related errors
+    OUTSIDE_WORKING_DIR = "Error: Cannot list {directory} as it is outside the permitted working directory"
+    NOT_A_DIRECTORY = "Error: {directory} is not a directory"
+    # Read file errors
+    FILE_READ_OUTSIDE_WORKING_DIR = "Error: Cannot read {file_path} as it is outside the permitted working directory"
+    FILE_READ_NOT_FOUND_OR_NOT_REGULAR = 'Error: File not found or is not a regular file: "{file_path}"'
+    # Write file errors
+    FILE_WRITE_OUTSIDE_WORKING_DIR = 'Error: Cannot write to "{file_path}" as it is outside the permitted working directory'
+    FILE_WRITE_NOT_FOUND_OR_NOT_REGULAR = 'Error: File not found or is not a regular file: "{file_path}"\n    Create the file before writing to it.'
+    # Executable file errors
+    FILE_EXECUTE_OUTSIDE_WORKING_DIR = 'Error: Cannot execute "{file_path}" as it is outside the permitted working directory'
+    FILE_EXECUTE_NOT_FOUND_OR_NOT_REGULAR = 'Error: File "{file_path}" not found.'
+    FILE_EXECUTE_NOT_PYTHON = 'Error: File "{file_path}" is not a Python file.'
+
+
+class FileExecutionError(str, Enum):
+    EXECUTION_FAILED = "Error: executing Python file: {error_message}"
+    EXECUTION_TIMEOUT = 'Error: Execution of file "{file_path}" timed out after {timeout} seconds.'
+
+
+class FileOperator(str, Enum):
+    READ_FILE = "read_file"
+    WRITE_FILE = "write_file"
+    EXECUTE_FILE = "execute_file"
+
+
+def file_verify_path(working_directory: str, directory: str) -> str:
+    """
+    Verify that *directory* (relative to *working_directory*) exists and is
+    inside the working directory.
+
+    Returns the resolved path on success, or a ``FileUtilsError`` string on
+    failure.
+    """
+    path_to_directory = os.path.join(working_directory, directory)
+    if (
+        not path_to_directory.startswith(working_directory)
+        or ".." in os.path.relpath(path_to_directory, working_directory)
+    ):
+        return FileUtilsError.OUTSIDE_WORKING_DIR.value.format(directory=directory)
+
+    if not os.path.isdir(path_to_directory):
+        return FileUtilsError.NOT_A_DIRECTORY.value.format(directory=directory)
+
+    return path_to_directory
+
+
+def file_verify_file(working_directory: str, file: str, options: FileOperator | None = None) -> str:
+    """
+    Verify that *file* (relative to *working_directory*) is valid for the
+    requested *options* operation.
+
+    Returns the resolved path on success, or a ``FileUtilsError`` string on
+    failure.
+
+    Raises
+    ------
+    ValueError
+        If *options* is not a recognised ``FileOperator`` value.
+    """
+    path_to_file = os.path.join(working_directory, file)
+
+    def _is_outside() -> bool:
+        return (
+            not path_to_file.startswith(working_directory)
+            or ".." in os.path.relpath(path_to_file, working_directory)
+        )
+
+    match options:
+        case FileOperator.READ_FILE:
+            if _is_outside():
+                return FileUtilsError.FILE_READ_OUTSIDE_WORKING_DIR.value.format(file_path=path_to_file)
+            if not os.path.isfile(path_to_file):
+                return FileUtilsError.FILE_READ_NOT_FOUND_OR_NOT_REGULAR.value.format(file_path=path_to_file)
+
+        case FileOperator.WRITE_FILE:
+            if _is_outside():
+                return FileUtilsError.FILE_WRITE_OUTSIDE_WORKING_DIR.value.format(file_path=path_to_file)
+            # Write operations may target a not-yet-existing file; the caller is
+            # responsible for creating any missing parent directories. We only
+            # validate the path is inside the working directory and return it.
+
+        case FileOperator.EXECUTE_FILE:
+            if _is_outside():
+                return FileUtilsError.FILE_EXECUTE_OUTSIDE_WORKING_DIR.value.format(file_path=file)
+            if not os.path.isfile(path_to_file):
+                return FileUtilsError.FILE_EXECUTE_NOT_FOUND_OR_NOT_REGULAR.value.format(file_path=file)
+            if not path_to_file.endswith(".py"):
+                return FileUtilsError.FILE_EXECUTE_NOT_PYTHON.value.format(file_path=file)
+
+        case _:
+            raise ValueError(f"Invalid file operation option provided: {options!r}")
+
+    return path_to_file  # reached by all arms that don't return early

logging_module/my_logging.py

@@ -0,0 +1,207 @@
+#######################################################################
+#
+# My Logging Module
+#
+# Provides logging functionality with timestamping and caller info
+# Supports configurable logging and tracing options
+#
+#######################################################################
+
+import os
+import threading
+from datetime import datetime
+from logging_module.file_utils import FileUtilsError, file_verify_path
+from inspect import getframeinfo, stack
+from logging_module.config import GLOBAL_LOGGING_ENABLED, GLOBAL_LOG_TRACING_ENABLED
+
+
+# ---------------------------------------------------------------------------
+# Frame-filtering constants
+# ---------------------------------------------------------------------------
+
+# Prefixes of filenames/paths to always skip (logger internals, frozen frames)
+_IGNORED_PREFIXES = (
+    "<frozen",
+    "<string>",
+)
+
+# Basenames of framework/infra files to skip (blocklist fallback mode)
+_IGNORED_FILES = {
+    "spawn.py",
+    "process.py",
+    "_subprocess.py",
+    "server.py",
+    "runners.py",
+    "config.py",
+    "importer.py",
+    "__init__.py",
+    "cli.py",
+    "discover.py",
+    "my_logging.py",  # skip this file itself
+}
+
+# ---------------------------------------------------------------------------
+# Logger
+# ---------------------------------------------------------------------------
+
+class Logger:
+    """
+    Lightweight file logger with optional call-stack tracing.
+
+    Usage
+    -----
+        log = Logger()
+        log("Something happened")
+        log.log("Something happened", print_to_console=True, console_message="Hey!")
+
+    Parameters
+    ----------
+    log_dir : str
+        Directory (relative or absolute) where log files are written.
+        Defaults to ``./logs``.
+    project_dir : str | None
+        Root of your project source tree. When supplied, only frames whose
+        absolute path starts with this directory (and are not inside
+        ``site-packages``) are considered "your code". When ``None`` the
+        module falls back to the blocklist defined by ``_IGNORED_FILES`` /
+        ``_IGNORED_PREFIXES``.
+    """
+
+    DEFAULT_LOG_DIR = "logs"
+
+    def __init__(
+        self,
+        log_dir: str = DEFAULT_LOG_DIR,
+        project_dir: str | None = None,
+    ):
+        self._enable: bool = True
+        self._enable_log_tracing: bool = False
+        self._log_dir: str = log_dir
+        self._project_dir: str | None = (
+            os.path.abspath(project_dir) if project_dir is not None else None
+        )
+        self._lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def __call__(
+        self,
+        message: str,
+        print_to_console: bool = False,
+        console_message: str = "",
+    ) -> None:
+        self.log(message, print_to_console=print_to_console, console_message=console_message)
+
+    def log(
+        self,
+        message: str,
+        print_to_console: bool = False,
+        console_message: str = "",
+    ) -> None:
+        if not GLOBAL_LOGGING_ENABLED or not self._enable:
+            return
+
+        now = datetime.now()
+        date = now.strftime("%Y-%m-%d")
+        time_str = now.strftime("%H:%M:%S")
+        timestamp = f"{date} {time_str}"
+
+        logistic_data = f"[{timestamp}][{self.get_caller_info()}]"
+        padded_space = "".rjust(len(logistic_data) + 1)
+        formatted_message = str(message).replace("\n", f"\n{padded_space}")
+        log_entry = f"{logistic_data} {formatted_message}\n"
+
+        self._write_to_file(log_entry, date, time_str)
+
+        if print_to_console:
+            print(message if console_message == "" else console_message)
+
+    def enable_logging(self, enable_logging: bool) -> None:
+        self._enable = enable_logging
+
+    def enable_log_tracing(self, enable_log_tracing: bool) -> None:
+        self._enable_log_tracing = enable_log_tracing
+
+    # ------------------------------------------------------------------
+    # Caller info
+    # ------------------------------------------------------------------
+
+    def get_caller_info(self) -> str:
+        tracing_active = GLOBAL_LOG_TRACING_ENABLED and self._enable_log_tracing
+        frames = self._collect_project_frames()
+
+        if not frames:
+            return "unknown:0"
+
+        if not tracing_active:
+            return frames[0]
+
+        return ">".join(frames)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _is_project_frame(self, filename: str) -> bool:
+        """
+        Return True when *filename* belongs to project code.
+
+        Allowlist mode (project_dir set):
+            Frame must live inside the project directory and not inside
+            a ``site-packages`` folder.
+
+        Blocklist mode (project_dir is None):
+            Frame must not match any entry in ``_IGNORED_FILES`` or
+            ``_IGNORED_PREFIXES``.
+        """
+        # Always skip frozen / string pseudo-files regardless of mode
+        if any(filename.startswith(prefix) for prefix in _IGNORED_PREFIXES):
+            return False
+
+        if self._project_dir is not None:
+            abs_filename = os.path.abspath(filename)
+            return (
+                abs_filename.startswith(self._project_dir)
+                and "site-packages" not in abs_filename
+            )
+
+        # Blocklist fallback
+        return os.path.basename(filename) not in _IGNORED_FILES
+
+    def _collect_project_frames(self) -> list[str]:
+        """Walk the call stack and return frame strings for project code only."""
+        frames: list[str] = []
+        for frame_record in stack():
+            try:
+                info = getframeinfo(frame_record[0])
+                if self._is_project_frame(info.filename):
+                    frames.append(f"{os.path.basename(info.filename)}:{info.lineno}")
+            except (IndexError, TypeError):
+                # IndexError: stack shorter than expected
+                # TypeError: frame_record is not subscriptable (e.g. test mocks using None)
+                continue
+        return frames
+
+    def _write_to_file(self, log_entry: str, date: str, time_str: str) -> None:
+        """Create the log directory/file if needed, then append *log_entry*."""
+        log_dir_path = os.path.join("./", self._log_dir)
+
+        # Ensure the log directory exists
+        file_path = file_verify_path("./", self._log_dir)
+        if file_path == FileUtilsError.NOT_A_DIRECTORY.value.format(directory=self._log_dir):
+            os.makedirs(log_dir_path, exist_ok=True)
+            file_path = file_verify_path("./", self._log_dir)  # re-verify after creation
+
+        # Bail out if the path is still an error (e.g. outside working dir)
+        if not isinstance(file_path, str) or file_path.startswith("Error"):
+            return
+
+        file_name = os.path.join(file_path, f"{date}_logging.txt")
+        with self._lock:
+            with open(file_name, "a") as log_file:
+                # Write a header only on the very first entry (empty file)
+                if log_file.tell() == 0:
+                    log_file.write(f"Log file created on {date} at {time_str}\n")
+                log_file.write(log_entry)

logging_module-0.2.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: logging-module
+Version: 0.2.0
+Summary: A comprehensive logging and file utility module for Python applications
+Author-email: Nathan T Nguyen <nhatnguyen2807@gmail.com>
+License-Expression: MIT
+Project-URL: CreatorGithub, https://github.com/NhatNguyen5
+Project-URL: Homepage, https://test.pypi.org/project/logging-module/
+Project-URL: Documentation, https://github.com/NhatNguyen5/logging_module/wiki/Instructions
+Project-URL: Repository, https://github.com/NhatNguyen5/logging-module.git
+Project-URL: Issues, https://github.com/NhatNguyen5/logging_module/issues
+Keywords: logging,file-utilities,tracing,debugging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: bump2version; extra == "dev"
+Dynamic: license-file
+
+# Logging Module
+
+A comprehensive Python logging and file utility module designed for easy integration into FastAPI projects and other Python applications.
+
+## Features
+
+- **Flexible Logging**: Timestamp-based logging with caller information
+- **File Utilities**: Safe file operations with error handling
+- **Configuration**: Easy-to-configure logging and tracing options
+- **Error Management**: Comprehensive error tracking and reporting
+
+## Installation
+
+### From PyPI (when published)
+```bash
+pip install logging-module
+```
+
+### From Local Directory
+```bash
+pip install ./logging_module
+# or in editable mode for development
+pip install -e ./logging_module
+```
+
+## Quick Start
+
+```python
+from logging_module import Logger
+
+# Create a logger instance
+app_logger = Logger()
+
+# Basic logging
+app_logger.log("Application started")
+
+# Log with console output
+app_logger.log("Important message", print_to_console=True)
+
+# Log with custom console message
+app_logger.log("Debug info", print_to_console=True, console_message="DEBUG: Debug info")
+
+# Use as a callable (shortcut for log())
+app_logger("Quick log message")
+
+# Control logging behavior
+app_logger.enable_logging(False)  # Disable this logger instance
+app_logger.enable_log_tracing(True)  # Enable detailed tracing for this instance
+
+# Configure custom log directory
+custom_logger = Logger(log_dir="my_logs")
+
+# Configure project directory for better frame filtering
+project_logger = Logger(project_dir="/path/to/project")
+```
+
+## Configuration
+
+### Logging Config (`config.py`)
+- `GLOBAL_LOGGING_ENABLED`: Enable/disable logging (default: `True`)
+- `GLOBAL_LOG_TRACING_ENABLED`: Enable/disable detailed tracing (default: `True`)
+
+```python
+from logging_module.config import GLOBAL_LOGGING_ENABLED, GLOBAL_LOG_TRACING_ENABLED
+```
+
+## Modules
+
+### Logger (`my_logging.py`)
+Main logging class providing timestamped, structured logging with caller information.
+
+**Key Features:**
+- Automatic timestamping and file logging
+- Caller information tracking with configurable frame filtering
+- Configurable log directory and project directory
+- Thread-safe file operations
+- Configurable tracing depth
+- Console output options
+- Instance-level enable/disable controls
+
+### File Utilities (`file_utils.py`)
+Safe file operations with comprehensive error handling:
+- Path verification with security checks
+- File verification for different operations (read/write/execute)
+- Directory operations with working directory constraints
+
+### Configuration (`config.py`)
+Global configuration settings for logging behavior:
+- `GLOBAL_LOGGING_ENABLED`: Master switch for all logging
+- `GLOBAL_LOG_TRACING_ENABLED`: Master switch for tracing features
+
+## Development
+
+### Prerequisites
+- Python 3.10+
+
+### Installing in Development Mode
+```bash
+cd logging_module
+pip install -e .
+```
+
+### Running Tests
+```bash
+# Install test dependencies
+pip install -e ".[dev]"
+
+# Run all tests
+pytest
+
+# Run with verbose output
+pytest -v
+
+# Run specific test file
+pytest tests/test_my_logging.py
+```
+
+## License
+
+MIT
+
+## Author
+
+Nathan T Nguyen

logging_module-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+logging_module/__init__.py,sha256=0RiE90B-839VDopobP3SsHyAPf3WCKAnJji3YVIvbSM,709
+logging_module/config.py,sha256=K8Y3CcKjD4w24A_Tz8depSmcYjMY_QzxWkt4av9D8so,312
+logging_module/file_utils.py,sha256=BVLG5e-Nl67Ml8zs8lJOfn-hoH0CVKK9fd1hgVvPFsE,4546
+logging_module/my_logging.py,sha256=6Bgxn6XlQpM7c2gizzxcH1HmNqUDy9e6qqvAlWEOv1E,7346
+logging_module-0.2.0.dist-info/licenses/LICENSE,sha256=83ihdQApyBWzHY6UZnYrOcepnw6WC_E1jwoEpz9ygVs,1072
+logging_module-0.2.0.dist-info/METADATA,sha256=dJhXYn2wa76ON5E6ne2wjBycf9llj1W_bp791dhnNXA,4257
+logging_module-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+logging_module-0.2.0.dist-info/top_level.txt,sha256=CgIjeGmYeHkbeuqIPkKaakc32MnVsoaJncFXLTwn5sQ,15
+logging_module-0.2.0.dist-info/RECORD,,

logging_module-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

logging_module-0.2.0.dist-info/licenses/LICENSE

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

logging_module-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+logging_module