logging-module 0.2.0__tar.gz

logging_module-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,124 @@
+# 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/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-0.2.0/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-0.2.0/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-0.2.0/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/logging_module.egg-info/PKG-INFO

@@ -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/logging_module.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+logging_module/__init__.py
+logging_module/config.py
+logging_module/file_utils.py
+logging_module/my_logging.py
+logging_module.egg-info/PKG-INFO
+logging_module.egg-info/SOURCES.txt
+logging_module.egg-info/dependency_links.txt
+logging_module.egg-info/requires.txt
+logging_module.egg-info/top_level.txt
+tests/test_config.py
+tests/test_file_utils.py
+tests/test_my_logging.py

logging_module-0.2.0/logging_module.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

logging_module-0.2.0/logging_module.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest
+bump2version

logging_module-0.2.0/logging_module.egg-info/top_level.txt

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

logging_module-0.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+# This tells build exactly which folders to treat as packages
+include = ["logging_module*"] 
+# This ensures the 'logs' folder is ignored
+exclude = ["logs*"]
+
+[project]
+name = "logging-module"
+version = "0.2.0"
+description = "A comprehensive logging and file utility module for Python applications"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    {name = "Nathan T Nguyen", email = "nhatnguyen2807@gmail.com"}
+]
+keywords = ["logging", "file-utilities", "tracing", "debugging"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "bump2version"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[project.urls]
+CreatorGithub = "https://github.com/NhatNguyen5"
+Homepage = "https://test.pypi.org/project/logging-module/"
+Documentation = "https://github.com/NhatNguyen5/logging_module/wiki/Instructions"
+Repository = "https://github.com/NhatNguyen5/logging-module.git"
+Issues = "https://github.com/NhatNguyen5/logging_module/issues"

logging_module-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

logging_module-0.2.0/tests/test_config.py

@@ -0,0 +1,14 @@
+import pytest
+from logging_module.config import GLOBAL_LOGGING_ENABLED, GLOBAL_LOG_TRACING_ENABLED
+
+
+def test_global_logging_enabled():
+    """Test that GLOBAL_LOGGING_ENABLED is a boolean."""
+    assert isinstance(GLOBAL_LOGGING_ENABLED, bool)
+    assert GLOBAL_LOGGING_ENABLED is True  # Default value
+
+
+def test_global_log_tracing_enabled():
+    """Test that GLOBAL_LOG_TRACING_ENABLED is a boolean."""
+    assert isinstance(GLOBAL_LOG_TRACING_ENABLED, bool)
+    assert GLOBAL_LOG_TRACING_ENABLED is True  # Default value

logging_module-0.2.0/tests/test_file_utils.py

@@ -0,0 +1,93 @@
+import os
+import tempfile
+import pytest
+from logging_module.file_utils import (
+    FileUtilsError,
+    FileExecutionError,
+    FileOperator,
+    file_verify_path,
+    file_verify_file,
+)
+
+
+class TestFileVerifyPath:
+    def test_valid_directory(self):
+        """Test verifying a valid directory."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            sub_dir = os.path.join(temp_dir, "test_dir")
+            os.makedirs(sub_dir)
+            result = file_verify_path(temp_dir, "test_dir")
+            assert result == sub_dir
+
+    def test_invalid_directory_not_exists(self):
+        """Test verifying a non-existent directory."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = file_verify_path(temp_dir, "nonexistent")
+            assert result == FileUtilsError.NOT_A_DIRECTORY.value.format(directory="nonexistent")
+
+    def test_outside_working_directory(self):
+        """Test verifying a directory outside working directory."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = file_verify_path(temp_dir, "../outside")
+            assert result == FileUtilsError.OUTSIDE_WORKING_DIR.value.format(directory="../outside")
+
+
+class TestFileVerifyFile:
+    def test_valid_read_file(self):
+        """Test verifying a valid file for reading."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            file_path = os.path.join(temp_dir, "test.txt")
+            with open(file_path, "w") as f:
+                f.write("test")
+            result = file_verify_file(temp_dir, "test.txt", FileOperator.READ_FILE)
+            assert result == file_path
+
+    def test_invalid_read_file_not_exists(self):
+        """Test verifying a non-existent file for reading."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = file_verify_file(temp_dir, "nonexistent.txt", FileOperator.READ_FILE)
+            assert result == FileUtilsError.FILE_READ_NOT_FOUND_OR_NOT_REGULAR.value.format(file_path=os.path.join(temp_dir, "nonexistent.txt"))
+
+    def test_outside_working_directory_read(self):
+        """Test verifying a file outside working directory for reading."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = file_verify_file(temp_dir, "../outside.txt", FileOperator.READ_FILE)
+            expected = FileUtilsError.FILE_READ_OUTSIDE_WORKING_DIR.value.format(file_path=os.path.join(temp_dir, "../outside.txt"))
+            assert result == expected
+
+    def test_valid_write_file_new(self):
+        """Test verifying a new file for writing."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = file_verify_file(temp_dir, "new.txt", FileOperator.WRITE_FILE)
+            assert result == os.path.join(temp_dir, "new.txt")
+
+    def test_outside_working_directory_write(self):
+        """Test verifying a file outside working directory for writing."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = file_verify_file(temp_dir, "../outside.txt", FileOperator.WRITE_FILE)
+            expected = FileUtilsError.FILE_WRITE_OUTSIDE_WORKING_DIR.value.format(file_path=os.path.join(temp_dir, "../outside.txt"))
+            assert result == expected
+
+    def test_valid_execute_file(self):
+        """Test verifying a valid Python file for execution."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            file_path = os.path.join(temp_dir, "test.py")
+            with open(file_path, "w") as f:
+                f.write("print('test')")
+            result = file_verify_file(temp_dir, "test.py", FileOperator.EXECUTE_FILE)
+            assert result == file_path
+
+    def test_invalid_execute_file_not_python(self):
+        """Test verifying a non-Python file for execution."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            file_path = os.path.join(temp_dir, "test.txt")
+            with open(file_path, "w") as f:
+                f.write("test")
+            result = file_verify_file(temp_dir, "test.txt", FileOperator.EXECUTE_FILE)
+            assert result == FileUtilsError.FILE_EXECUTE_NOT_PYTHON.value.format(file_path="test.txt")
+
+    def test_invalid_option(self):
+        """Test invalid file operation option."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            with pytest.raises(ValueError, match="Invalid file operation option provided"):
+                file_verify_file(temp_dir, "test.txt", "invalid")

logging_module-0.2.0/tests/test_my_logging.py

@@ -0,0 +1,152 @@
+import os
+import tempfile
+import pytest
+from unittest.mock import patch, MagicMock
+from datetime import datetime
+from logging_module.my_logging import Logger
+from logging_module.config import GLOBAL_LOGGING_ENABLED, GLOBAL_LOG_TRACING_ENABLED
+
+
+class TestLogger:
+    def setup_method(self):
+        """Setup before each test."""
+        self.Logger = Logger()
+
+    def test_init(self):
+        """Test Logger initialization."""
+        assert self.Logger._enable is True
+        assert self.Logger._enable_log_tracing is False
+
+    @patch('logging_module.my_logging.datetime')
+    @patch('logging_module.my_logging.file_verify_path')
+    @patch('builtins.open', new_callable=MagicMock)
+    def test_log_basic(self, mock_open, mock_verify_path, mock_datetime):
+        """Test basic logging functionality."""
+        # Setup mocks
+        mock_datetime.now.return_value = datetime(2023, 5, 15, 10, 30, 45)
+        mock_verify_path.return_value = "/tmp/logs"
+        
+        # Create a temporary directory for logs
+        with tempfile.TemporaryDirectory() as temp_dir:
+            with patch('os.path.join', return_value=os.path.join(temp_dir, "logs", "2023-05-15_logging.txt")):
+                with patch('os.path.isfile', return_value=False):
+                    with patch('os.makedirs'):
+                        self.Logger.log("Test message")
+                        
+                        # Check that open was called for writing
+                        assert mock_open.call_count >= 1  # Single open in append mode
+
+    @patch('logging_module.my_logging.datetime')
+    @patch('logging_module.my_logging.file_verify_path')
+    @patch('builtins.open', new_callable=MagicMock)
+    @patch('builtins.print')
+    def test_log_with_console_output(self, mock_print, mock_open, mock_verify_path, mock_datetime):
+        """Test logging with console output."""
+        mock_datetime.now.return_value = datetime(2023, 5, 15, 10, 30, 45)
+        mock_verify_path.return_value = "/tmp/logs"
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            with patch('os.path.join', return_value=os.path.join(temp_dir, "logs", "2023-05-15_logging.txt")):
+                with patch('os.path.isfile', return_value=True):
+                    self.Logger.log("Test message", print_to_console=True)
+                    
+                    # Check that print was called
+                    mock_print.assert_called_once_with("Test message")
+
+    @patch('logging_module.my_logging.datetime')
+    @patch('logging_module.my_logging.file_verify_path')
+    @patch('builtins.open', new_callable=MagicMock)
+    @patch('builtins.print')
+    def test_log_with_custom_console_message(self, mock_print, mock_open, mock_verify_path, mock_datetime):
+        """Test logging with custom console message."""
+        mock_datetime.now.return_value = datetime(2023, 5, 15, 10, 30, 45)
+        mock_verify_path.return_value = "/tmp/logs"
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            with patch('os.path.join', return_value=os.path.join(temp_dir, "logs", "2023-05-15_logging.txt")):
+                with patch('os.path.isfile', return_value=True):
+                    self.Logger.log("Test message", print_to_console=True, console_message="Custom message")
+                    
+                    # Check that print was called with custom message
+                    mock_print.assert_called_once_with("Custom message")
+
+    def test_log_disabled_globally(self):
+        """Test logging when globally disabled."""
+        with patch('logging_module.my_logging.GLOBAL_LOGGING_ENABLED', False):
+            with patch('builtins.open') as mock_open:
+                self.Logger.log("Test message")
+                mock_open.assert_not_called()
+
+    def test_log_disabled_locally(self):
+        """Test logging when locally disabled."""
+        self.Logger.enable_logging(False)
+        with patch('builtins.open') as mock_open:
+            self.Logger.log("Test message")
+            mock_open.assert_not_called()
+
+    @patch('logging_module.my_logging.getframeinfo')
+    @patch('logging_module.my_logging.stack')
+    def test_get_caller_info_basic(self, mock_stack, mock_getframeinfo):
+        """Test getting basic caller info."""
+        mock_frame = MagicMock()
+        mock_frame.filename = "/path/to/file.py"
+        mock_frame.lineno = 42
+        mock_getframeinfo.return_value = mock_frame
+        mock_stack.return_value = [None, None, None, mock_frame]  # calldepth = 3
+        
+        result = self.Logger.get_caller_info()
+        assert result == "file.py:42"
+
+    @patch('logging_module.my_logging.getframeinfo')
+    @patch('logging_module.my_logging.stack')
+    def test_get_caller_info_tracing_disabled(self, mock_stack, mock_getframeinfo):
+        """Test caller info when tracing is disabled."""
+        self.Logger.enable_log_tracing(False)
+        mock_frame = MagicMock()
+        mock_frame.filename = "/path/to/file.py"
+        mock_frame.lineno = 42
+        mock_getframeinfo.return_value = mock_frame
+        mock_stack.return_value = [None, None, None, mock_frame]
+        
+        result = self.Logger.get_caller_info()
+        assert result == "file.py:42"
+
+    @patch('logging_module.my_logging.getframeinfo')
+    @patch('logging_module.my_logging.stack')
+    def test_get_caller_info_tracing_enabled(self, mock_stack, mock_getframeinfo):
+        """Test caller info when tracing is enabled."""
+        self.Logger.enable_log_tracing(True)
+        with patch('logging_module.my_logging.GLOBAL_LOG_TRACING_ENABLED', True):
+            mock_frame1 = MagicMock()
+            mock_frame1.filename = "/path/to/file1.py"
+            mock_frame1.lineno = 10
+            mock_frame2 = MagicMock()
+            mock_frame2.filename = "/path/to/file2.py"
+            mock_frame2.lineno = 20
+            mock_getframeinfo.side_effect = [mock_frame1, mock_frame2]
+            mock_stack.return_value = [None, None, None, mock_frame1, mock_frame2]
+            
+            result = self.Logger.get_caller_info()
+            assert "file1.py:10>file2.py:20" in result
+
+    def test_enable_logging(self):
+        """Test enabling/disabling logging."""
+        self.Logger.enable_logging(False)
+        assert self.Logger._enable is False
+        
+        self.Logger.enable_logging(True)
+        assert self.Logger._enable is True
+
+    def test_enable_log_tracing(self):
+        """Test enabling/disabling log tracing."""
+        self.Logger.enable_log_tracing(True)
+        assert self.Logger._enable_log_tracing is True
+        
+        self.Logger.enable_log_tracing(False)
+        assert self.Logger._enable_log_tracing is False
+
+    def test_call_method(self):
+        """Test using Logger as callable."""
+        with patch.object(self.Logger, 'log') as mock_log:
+            self.Logger("Test message", print_to_console=True)
+            mock_log.assert_called_once_with("Test message", print_to_console=True, console_message="")