jacl4py 0.0.1__py3-none-any.whl

jacl4py/__init__.py

@@ -0,0 +1,3 @@
+"""jacl4py standalone logging package."""
+
+__version__ = "0.0.1"

jacl4py/exceptions.py

@@ -0,0 +1,5 @@
+"""Exceptions raised by logger lifecycle operations."""
+
+
+class ResourceNotInitializedError(RuntimeError):
+    """Raised when a deleted logger is used to log a message."""

jacl4py/logger.py

@@ -0,0 +1,260 @@
+"""
+Logging utilities: ``JacLogger`` subclass with project-specific levels and
+a ``get_logger`` factory that attaches console + rotating file handlers.
+"""
+import logging
+import os
+import re
+import tempfile
+import warnings
+from enum import Enum
+from functools import wraps
+from logging.handlers import TimedRotatingFileHandler
+from pathlib import Path
+from threading import RLock
+from uuid import uuid4
+
+import coloredlogs
+
+from . import __version__ as _package_version
+from .exceptions import ResourceNotInitializedError
+
+__version__ = _package_version
+
+INTERNAL_DEBUG = 5
+INTERNAL_INFO = 7
+logging.addLevelName(INTERNAL_DEBUG, "INTERNAL_DEBUG")
+logging.addLevelName(INTERNAL_INFO, "INTERNAL_INFO")
+
+
+class LogDir(Enum):
+    """Special log directory settings."""
+
+    DEFAULT = "default"
+
+
+class JacLogger(logging.Logger):
+    """Logger subclass that adds INTERNAL_INFO (7) and INTERNAL_DEBUG (5) levels below DEBUG."""
+
+    _deleted: bool = False
+
+    def isEnabledFor(self, level: int) -> bool:
+        """Check the level, raising ResourceNotInitializedError after deletion."""
+        if self._deleted:
+            raise ResourceNotInitializedError(
+                f"Logger '{self.name}' has been deleted. "
+                "Obtain a new logger with get_logger() before logging."
+            )
+        return super().isEnabledFor(level)
+
+    def iinfo(self, message, *args, **kwargs):
+        """Log at INTERNAL_INFO level (7) --- framework lifecycle events, below DEBUG."""
+        if self.isEnabledFor(INTERNAL_INFO):
+            self._log(INTERNAL_INFO, message, args, **kwargs)
+
+    def idebug(self, message, *args, **kwargs):
+        """
+        Log at INTERNAL_DEBUG level (5) --- fine-grained framework tracing, below INTERNAL_INFO.
+        """
+        if self.isEnabledFor(INTERNAL_DEBUG):
+            self._log(INTERNAL_DEBUG, message, args, **kwargs)
+
+
+_manager = logging.Manager(logging.root)
+_manager.setLoggerClass(JacLogger)
+_lifecycle_lock = RLock()
+
+
+def _after_fork() -> None:
+    global _manager, _lifecycle_lock  # pylint: disable=global-statement
+    for logger in _manager.loggerDict.values():
+        if isinstance(logger, JacLogger):
+            logger._deleted = True  # pylint: disable=protected-access
+            logger.disabled = True
+    _manager = logging.Manager(logging.root)
+    _manager.setLoggerClass(JacLogger)
+    _lifecycle_lock = RLock()
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_after_fork)
+
+
+def _synchronized(function):
+    """Serialize package logger lifecycle operations."""
+    @wraps(function)
+    def wrapped(*args, **kwargs):
+        """Run the operation while holding the lifecycle lock."""
+        with _lifecycle_lock:
+            return function(*args, **kwargs)
+    return wrapped
+
+
+def _create_log_path(name: str, log_dir: str | Path | LogDir) -> Path:
+    """Reserve a unique sanitized log path without reusing an existing writer."""
+    safe_name = re.sub(r"[^A-Za-z0-9_.-]", "_", name).strip(".")[:64] or "logger"
+    if log_dir is not LogDir.DEFAULT:
+        directory = Path(log_dir)
+        directory.mkdir(parents=True, exist_ok=True)
+    while True:
+        identifier = safe_name + uuid4().hex[:8]
+        try:
+            if log_dir is LogDir.DEFAULT:
+                directory = Path(tempfile.gettempdir()) / identifier
+                directory.mkdir(mode=0o700)
+                return directory / f"{safe_name}.log"
+            filename = directory / f"{identifier}.log"
+            with filename.open("x", encoding="utf-8"):
+                pass
+            return filename
+        except FileExistsError:
+            continue
+
+
+@_synchronized
+def delete_logger(name: str = "default") -> bool:
+    """Close and unregister a package logger, keeping existing log files.
+
+    Return False if no named logger exists. Deleted JacLogger references
+    raise ResourceNotInitializedError when used to log;
+    package child loggers remain usable. Standard logging loggers are untouched.
+    """
+    manager = _manager
+    logger = manager.loggerDict.get(name)
+    if not isinstance(logger, logging.Logger):
+        return False
+
+    if isinstance(logger, JacLogger):
+        logger._deleted = True  # pylint: disable=protected-access
+    logger.disabled = True
+    for handler in list(logger.handlers):
+        logger.removeHandler(handler)
+        handler.close()
+    del manager.loggerDict[name]
+    for child in list(manager.loggerDict.values()):
+        if isinstance(child, logging.Logger) and child.parent is logger:
+            manager._fixupParents(child)  # pylint: disable=protected-access
+    return True
+
+
+@_synchronized
+def get_logger(  # pylint: disable=too-many-arguments
+    name: str = "default",
+    *,
+    console_log_level: int | None = logging.INFO,
+    log_dir: str | Path | LogDir | None = LogDir.DEFAULT,
+    file_log_level: int | None = INTERNAL_DEBUG,
+    use_colored_output: bool = True,
+    reinit_if_exists: bool = False
+) -> JacLogger:
+    """
+    Get or create a configured logger instance.
+
+    Parameters
+    ----------
+    name : str
+        Logger name (default: "default")
+    console_log_level : int | None
+        Console handler level. Set to None to disable console logging.
+    log_dir : str | Path | LogDir | None
+        Directory for log files. LogDir.DEFAULT uses the system temp directory
+        under the sanitized name plus eight UUID4 hex characters. Explicit
+        directories use a unique filename. Set to None to disable file logging.
+    file_log_level : int | None
+        File handler level. Set to None to disable file logging.
+    use_colored_output : bool
+        Whether to use colored console output (default: True)
+    reinit_if_exists : bool
+        Delete an existing named logger and apply new settings (default: False).
+        Existing log files are preserved.
+
+    Returns
+    -------
+    JacLogger
+        Configured package-owned logger, separate from logging.getLogger(name).
+        After fork, obtain a fresh logger in the child with get_logger().
+    """
+    if not isinstance(name, str) or not name:
+        raise ValueError("Logger name must be a non-empty string.")
+    if reinit_if_exists:
+        delete_logger(name)
+    logger = _manager.getLogger(name)
+
+    # Avoid adding handlers multiple times
+    if logger.handlers:
+        warnings.warn(
+            f"Logger '{name}' already configured; returning cached logger "\
+                "and ignoring new settings.",
+            stacklevel=2
+        )
+        return logger
+
+    # Logger level must be INTERNAL to allow file handler to capture everything
+    # Individual handlers control their own output levels
+    logger.setLevel(INTERNAL_DEBUG)
+    logger.propagate = False
+
+    # Create file formatter
+    file_formatter = logging.Formatter(
+        "%(asctime)s.%(msecs)03d - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S"
+    )
+
+    # Console handler with coloredlogs
+    if console_log_level is not None:
+        if use_colored_output:
+            # coloredlogs installs directly on the logger with field-level colors
+            coloredlogs.install(
+                level=console_log_level,
+                logger=logger,
+                fmt="%(asctime)s.%(msecs)03d %(hostname)s %(name)s[%(process)d] "\
+                    "%(levelname)s %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+                level_styles={
+                    "internal_debug": {"color": "blue"},
+                    "internal_info": {"color": "white"},
+                    "debug": {"color": "cyan"},
+                    "info": {"color": "green"},
+                    "warning": {"color": "yellow", "bold": True},
+                    "error": {"color": "red", "bold": True},
+                    "critical": {"color": "red", "bold": True, "background": "white"}
+                },
+                field_styles={
+                    "asctime": {"color": "white", "bold": True},
+                    "hostname": {"color": "magenta"},
+                    "levelname": {"color": "white", "bold": True},
+                    "name": {"color": "cyan"},
+                    "programname": {"color": "cyan"},
+                    "process": {"color": "magenta"}
+                }
+            )
+        else:
+            console_handler = logging.StreamHandler()
+            console_handler.setLevel(console_log_level)
+            console_handler.setFormatter(file_formatter)
+            logger.addHandler(console_handler)
+
+    # File handler with rotation
+    if log_dir is not None and file_log_level is not None:
+        try:
+            log_filename = _create_log_path(name, log_dir)
+            file_handler = TimedRotatingFileHandler(
+                log_filename,
+                when="midnight",
+                interval=1,
+                backupCount=30,
+                encoding="utf-8"
+            )
+            file_handler.setLevel(file_log_level)
+            file_handler.setFormatter(file_formatter)
+            logger.addHandler(file_handler)
+            logger.info("Logging files to %s", log_filename.parent)
+
+        except (PermissionError, OSError) as e:
+            warnings.warn(
+                f"Could not create log file for '{name}' in {log_dir!r}: {e}. "
+                "File logging disabled.",
+                stacklevel=2
+            )
+
+    return logger

jacl4py-0.0.1.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: jacl4py
+Version: 0.0.1
+Summary: Just another custom logger for Python.
+Author-Email: Fabian Krumm <ghub_fk@gmx.de>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Requires-Dist: coloredlogs>=15.0
+Description-Content-Type: text/markdown
+
+# jacl4py
+
+Just another custom logger for Python.
+
+`jacl4py` is a standalone package containing the custom Python logger previously
+used by pookiepy.
+
+## Release Status
+
+Releases before `1.0.0` are testing versions and may introduce breaking changes
+without a major version increment. Semantic versioning will begin with `1.0.0`.
+
+## Installation
+
+Install from PyPI:
+
+```powershell
+pip install jacl4py
+```
+
+Or install the local package with uv:
+
+```powershell
+uv pip install .
+```
+
+## Usage
+
+```python
+from jacl4py.logger import INTERNAL_INFO, get_logger
+
+logger = get_logger("service")
+logger.iinfo("framework lifecycle event")
+logger.log(INTERNAL_INFO, "another internal event")
+logger.info("service started")
+```
+
+Only `get_logger()` is needed to configure a logger. Package loggers use their
+own registry, so importing the module does not replace Python's global logger
+class. `logging.getLogger("service")` and `get_logger("service")` are separate
+objects and do not change each other's handlers. The `INTERNAL_DEBUG` and
+`INTERNAL_INFO` level names are registered with `logging`.
+
+The console handler defaults to `INFO`; the file handler defaults to
+`INTERNAL_DEBUG`. The default `log_dir=LogDir.DEFAULT` writes log files under the
+system temporary directory in `<safe-name><uuid8>/<safe-name>.log`. For example,
+`get_logger("test")` might write to `test12345678/test.log` under the temporary
+directory. The suffix is the first eight hexadecimal characters of UUID4;
+existing paths are never reused on a collision. Names are restricted to ASCII
+letters, digits, dots, underscores, and hyphens for filesystem use, with other
+characters replaced by underscores and the name component limited to 64
+characters. The original logger name is preserved in log records.
+
+Each writer has one stable active filename. Files rotate daily and retain up to
+30 backups for that writer, not necessarily 30 calendar days. Reinitialization
+and new processes receive fresh paths. Old run directories and file families
+are preserved, not automatically pruned. The custom `iinfo()` and `idebug()`
+methods emit at levels 7 and 5 respectively.
+
+Pass `log_dir=None` to disable file logging, or a string or `Path` for a custom
+directory. An explicit directory is used as given, with a unique filename
+`<safe-name><uuid8>.log` inside it. Pass `None` for `console_log_level` or
+`file_log_level` to disable that handler. Use an application-owned directory
+when file permissions or durable retention matter.
+
+```python
+from jacl4py.logger import LogDir, get_logger
+
+logger = get_logger("service", log_dir=LogDir.DEFAULT)
+console_only = get_logger("console", log_dir=None)
+```
+
+`JacLogger.setLevel()` follows standard logging behavior: it changes only the
+logger threshold, preserving independent console and file handler levels.
+Reusing a configured name returns the cached logger, emits a warning, and
+ignores new configuration arguments. Initialization and deletion are serialized
+across threads; ordinary log calls do not acquire the package lifecycle lock.
+
+Pass `reinit_if_exists=True` to replace an existing logger and apply new settings
+without the cached-logger warning:
+
+```python
+from jacl4py.logger import delete_logger, get_logger
+
+log = get_logger("my_test11", reinit_if_exists=True)
+delete_logger("my_test11")
+```
+
+`delete_logger(name)` closes and removes the package logger's handlers and
+unregisters it without touching standard loggers. It returns `True` if a package
+logger was deleted, otherwise `False`. Existing log
+files are preserved. Logging through a deleted `JacLogger` reference raises
+`ResourceNotInitializedError`, a subclass of `RuntimeError`, even for messages
+below the configured level. Import it from `jacl4py.logger` or
+`jacl4py.exceptions`. Use the new object returned by `get_logger()` after
+reinitialization. Package child loggers remain usable and reconnect when the
+named logger is recreated. Use `get_logger()` for child names too.
+
+In each worker process, call `get_logger()` to obtain a separate writer. After
+`fork`, inherited package logger references are invalidated automatically; do
+not continue logging through an inherited reference. No queue or listener is
+required. Logging is synchronous, including disk writes and rollover, so it can
+block application threads or an async event loop. Configure or replace loggers
+before starting work rather than while other threads are emitting records.
+
+The version is available from the imported logger module:
+
+```python
+from jacl4py import logger
+
+print(logger.__version__)
+```
+
+For a release, edit only `__version__` in `jacl4py/__init__.py`. PDM reads that
+constant for wheel and source-distribution metadata; `jacl4py.__version__` and
+`jacl4py.logger.__version__` expose the same value.
+
+## Development
+
+This standalone repository targets Python 3.10 or newer. It is authored by
+Fabian Krumm and distributed under the BSD 3-Clause License from the original
+project.
+
+Run the unit tests with uv:
+
+```powershell
+uv pip install -r requirements.txt
+uv run --with-requirements requirements.txt python -m unittest discover -s tests -p "test_*.py"
+```
+
+Install development tools, including Pylint and coverage:
+
+```powershell
+uv pip install -r requirements-dev.txt
+```
+
+Run the same Pylint check as the push and pull request workflow:
+
+```powershell
+uv run --with-requirements requirements-dev.txt python -m pylint --jobs=1 jacl4py tests
+```
+
+Check test coverage, including branches and missing lines:
+
+```powershell
+uv run --with-requirements requirements-dev.txt python -m coverage run --branch --source=jacl4py -m unittest discover -s tests -p "test_*.py"
+uv run --with-requirements requirements-dev.txt python -m coverage report -m
+```
+
+Build with:
+
+```powershell
+uv build
+```
+
+`requirements.txt` contains runtime-only dependencies and mirrors
+`pyproject.toml` project dependencies. The workflows use it before tests, build,
+and publication preflight; the requirements guard test detects drift, so update
+both files together. PDM's declared build backend supplies `uv build` build
+dependencies, while the generated wheel and source-distribution metadata causes
+pip installs to resolve runtime dependencies automatically. The requirements
+files are included in source distributions. `requirements-dev.txt` includes
+the runtime requirements and adds development-only tools. PDM includes the package source and
+test/workflow sources directly, so a `MANIFEST.in` file is unnecessary.
+
+## Publishing
+
+GitHub Actions discovers workflows only from the repository root's
+`.github/workflows` directory; workflows nested under `logger-package` are not
+run automatically in this monorepo. When this package is published from its own
+repository, keep these workflow files at that repository root.
+
+`pypi_publish.yml` runs on pushes to `master`, not GitHub Release publication. A
+read-only build job runs preflight unit tests, builds wheel and sdist, checks
+them with Twine, smoke-tests each installed artifact, and uploads the validated
+distributions. Only then does the `pypi-release` environment job publish those
+artifacts through PyPI Trusted Publishing (OIDC, no stored API token), with
+`skip-existing: true`, `print-hash: false`, and `attestations: true`.
+
+After successful publication, it creates an annotated `v<version>` tag from
+`jacl4py/__init__.py`. An existing tag on the same commit is an idempotent no-op;
+a tag on another commit is never moved and causes failure. Edit the local
+version constant manually before a new release: neither tags nor commit messages
+infer or automatically bump the version. PDM reads that constant for metadata.
+
+Configure the PyPI trusted publisher for project `jacl4py`, your GitHub
+owner/repository, workflow filename `pypi_publish.yml`, and environment `pypi-release`.
+Keep that filename to preserve the trusted publisher identity and retain the
+environment URL `https://pypi.org/project/jacl4py/`. Confirm project availability
+and choose an unpublished version before pushing. Skipping existing files allows
+retries; it does not permit replacing a published version.
+
+Publication depends on its own build job, not a mandatory CI `needs` barrier.
+Protect `master` with required supported-version tests, lint, build and workflow
+audit checks; protect the environment with reviewers and branch restrictions.
+Floating `3.x` probes are nonblocking, not support guarantees. CI runs Python
+3.10-3.14 on five runners, reports coverage without a minimum, and uses Pylint
+3.2.6 with the default fail-under of 10 and no disabled messages or custom
+threshold. See [.github/CI.md](.github/CI.md) for the matrix, weekly
+checks, reference differences, and repository settings.
+
+# todos
+
+## ai findings
+
+- [ ] Medium (#6): Benchmark synchronous logging under representative load.
+	Document an optional bounded queue/listener recipe only if needed, including
+	overflow behavior and flushing at shutdown. UUID paths isolate writers but do
+	not remove I/O latency.
+- [ ] Medium (#7): Make intentionally disabled outputs silent with a
+	`NullHandler`; track configuration independently of handler presence so
+	Python's `lastResort` handler cannot unexpectedly emit to stderr.
+- [ ] Medium (#8): Validate replacement settings and build handlers before
+	invalidating the working logger. Finish cleanup if one handler fails to close,
+	and consider an opt-in strict policy for required file logging.
+- [ ] Medium (#9): Increment `stacklevel` in `iinfo()` and `idebug()` so caller
+	metadata identifies application code rather than the wrapper.
+- [ ] Medium (#10): Extend regression coverage for output silence, caller
+	attribution, custom global logger factories, and file open/write/close
+	failures; add branch coverage reporting in CI. High-severity regression tests
+	have been added but still need execution.
+- [ ] Medium (#11): Pin the PyPI publishing action to a reviewed commit; lock
+	release tooling, automate dependency updates and vulnerability audits, and
+	verify the release tag against built metadata. Keep consumer dependency ranges
+	separate from release-tool reproducibility.
+- [ ] Low (#12): Add real project/support URLs, tested Python classifiers,
+	contribution and private security-reporting guidance, and a compatibility and
+	deprecation policy. Expand privacy, permissions, and application integration
+	guidance as the public API settles.
+- [ ] Retention follow-up: Define opt-in cleanup of completed runs if total
+	disk usage must be bounded. Per-writer rotation does not delete older UUID
+	directories or file families; do not delete other writers' files implicitly.

jacl4py-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+jacl4py-0.0.1.dist-info/METADATA,sha256=QMvS8Uexhh38Yz4CHeIDcPasmBRnDYDHPbDLobuIfww,10959
+jacl4py-0.0.1.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
+jacl4py-0.0.1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+jacl4py-0.0.1.dist-info/licenses/LICENSE,sha256=D5tHuFx3CsUmFQTursu3R7LmOAgCWqlytpquqGKWXdY,1499
+jacl4py/__init__.py,sha256=aMADOnze8GsUON5ijtJD51SYZjnvFQQ6rz2uOOlp3M0,65
+jacl4py/exceptions.py,sha256=9I1nP9oute88E6j0C6CTYhWd15urC6OAREv6tCRros8,172
+jacl4py/logger.py,sha256=5mBE1Ve__XmhnmjloZDC5mWZ9SU7whCKwLL6nmRpF08,9339
+jacl4py-0.0.1.dist-info/RECORD,,

jacl4py-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.5.0)
+Root-Is-Purelib: true
+Tag: py3-none-any

jacl4py-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+

jacl4py-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Fabian Krumm
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.