ls-logging 0.1.0__py3-none-any.whl

ls_logging/__init__.py

@@ -0,0 +1,6 @@
+"""Логи служб lightmaster в journald."""
+from ls_logging._django import django_logging
+from ls_logging._setup import setup_logging
+
+
+__all__ = ["django_logging", "setup_logging"]

ls_logging/_django.py

@@ -0,0 +1,45 @@
+"""Настройки логирования для `LOGGING` в `settings.py` Django."""
+from typing import Any, Dict, Union
+
+from ls_logging._setup import resolve_level
+
+
+def django_logging(service: str, level: Union[str, int]) -> Dict[str, Any]:
+    """Собирает словарь для `LOGGING` в `settings.py` Django.
+
+    Словарь ставит на корневой логгер один обработчик. Если `JOURNAL_STREAM`
+    совпадает с устройством и inode stderr, обработчик пишет в `/dev/log`
+    под именем `service`. Иначе он пишет в stderr со временем в начале строки.
+    Логгер `django` остается без своих обработчиков.
+    Поэтому обработчики `console` и `mail_admins` из настроек Django по умолчанию не работают.
+    Словарь не вызывает `captureWarnings` и не ставит `sys.excepthook` и `threading.excepthook`.
+
+    Args:
+        service: Имя службы, под которым записи видны в journald.
+        level: Уровень корневого логгера: число, имя уровня в любом регистре
+            или `Enum` со строковым значением. Имя `WARN` понимается как
+            `WARNING`.
+
+    Returns:
+        Словарь в формате `logging.config.dictConfig`.
+
+    Raises:
+        ValueError: Если уровень не распознан.
+    """
+    return {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "handlers": {
+            "ls_logging": {
+                "()": "ls_logging._output.build_handler",
+                "service": service,
+            },
+        },
+        "root": {
+            "handlers": ["ls_logging"],
+            "level": resolve_level(level),
+        },
+        "loggers": {
+            "django": {"handlers": [], "level": "NOTSET", "propagate": True},
+        },
+    }

ls_logging/_output.py

@@ -0,0 +1,52 @@
+"""Выбор вывода логов: journald через syslog или stderr."""
+import logging
+import logging.handlers
+import os
+import sys
+
+
+SYSLOG_ADDRESS = "/dev/log"
+JOURNAL_FORMAT = "[%(levelname)s] %(name)s: %(message)s"
+TERMINAL_FORMAT = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+
+
+def stderr_is_journal() -> bool:
+    """Проверяет, что stderr процесса подключен к journald.
+
+    Returns:
+        True, если `JOURNAL_STREAM` задана и ее `устройство:inode` совпадают
+        с `st_dev` и `st_ino` дескриптора 2, иначе False. Испорченное значение
+        переменной и недоступный дескриптор тоже дают False.
+    """
+    value = os.environ.get("JOURNAL_STREAM")
+    if value is None:
+        return False
+    try:
+        device, inode = value.split(":")
+        expected = (int(device), int(inode))
+        st = os.fstat(2)
+    except (ValueError, OSError):
+        return False
+    return expected == (st.st_dev, st.st_ino)
+
+
+def build_handler(service: str) -> logging.Handler:
+    """Создает обработчик логов под текущее окружение с готовым форматтером.
+
+    Под journald уровень сообщения доходит до журнала как его приоритет.
+    Иначе сообщения пишутся в `sys.stderr` со временем.
+
+    Args:
+        service: Имя службы, под которым записи видны в journald.
+
+    Returns:
+        Обработчик `SysLogHandler` под journald, иначе `StreamHandler`.
+    """
+    if stderr_is_journal():
+        handler: logging.Handler = logging.handlers.SysLogHandler(address=SYSLOG_ADDRESS)
+        handler.ident = f"{service}: "  # type: ignore[attr-defined]
+        handler.setFormatter(logging.Formatter(JOURNAL_FORMAT))
+        return handler
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter(TERMINAL_FORMAT))
+    return handler

ls_logging/_setup.py

@@ -0,0 +1,109 @@
+"""Настройка логирования службы и обработчики необработанных исключений."""
+import logging
+import sys
+import threading
+from enum import Enum
+from types import TracebackType
+from typing import Optional, Tuple, Type, Union, cast
+
+from ls_logging._output import build_handler
+
+
+_logger = logging.getLogger("ls_logging")
+
+
+def resolve_level(level: Union[str, int]) -> int:
+    """Переводит уровень логирования в число.
+
+    Args:
+        level: Число, имя уровня в любом регистре или `Enum` со значением-именем.
+            Имя `WARN` понимается как `WARNING`.
+
+    Returns:
+        Числовой уровень модуля `logging`.
+
+    Raises:
+        ValueError: Если уровень не распознан. Исходное значение входит в текст ошибки.
+    """
+    value = level.value if isinstance(level, Enum) else level
+    resolved = logging.getLevelName(value.upper()) if isinstance(value, str) else value
+    if not isinstance(resolved, int):
+        raise ValueError(f"Unknown log level: {level!r}")
+    return resolved
+
+
+def _log_critical(
+    exc_info: Tuple[Type[BaseException], BaseException, Optional[TracebackType]],
+    msg: str,
+    *args: object,
+) -> None:
+    # dictConfig и fileConfig с настройками по умолчанию отключают уже созданные логгеры.
+    # Падение службы не должно пропасть из-за такого чужого вызова.
+    _logger.disabled = False
+    if _logger.isEnabledFor(logging.CRITICAL):
+        _logger.critical(msg, *args, exc_info=exc_info)
+    else:
+        # Уровень запрещен через logging.disable, трассировку печатает стандартный обработчик.
+        # threading.__excepthook__ появился только в Python 3.10.
+        sys.__excepthook__(*exc_info)
+
+
+def _log_uncaught(
+    exc_type: Type[BaseException],
+    exc_value: BaseException,
+    exc_traceback: Optional[TracebackType],
+) -> None:
+    if issubclass(exc_type, KeyboardInterrupt):
+        sys.__excepthook__(exc_type, exc_value, exc_traceback)
+        return
+    _log_critical((exc_type, exc_value, exc_traceback), "Uncaught exception")
+
+
+def _log_uncaught_in_thread(args: "threading.ExceptHookArgs") -> None:
+    if issubclass(args.exc_type, SystemExit):
+        return
+    name = args.thread.name if args.thread is not None else "<unknown>"
+    # threading передает exc_value всегда, хотя в типах он Optional.
+    exc_value = cast(BaseException, args.exc_value)
+    _log_critical(
+        (args.exc_type, exc_value, args.exc_traceback),
+        "Uncaught exception in thread %s",
+        name,
+    )
+
+
+def setup_logging(service: str, level: Union[str, int]) -> None:
+    """Настраивает логирование службы под journald или терминал.
+
+    Заменяет все обработчики корневого логгера одним новым. Старые обработчики
+    не закрываются. Если `JOURNAL_STREAM` совпадает с устройством и inode
+    stderr, записи уходят в `/dev/log` под именем `service`. Иначе они идут
+    в stderr со временем в начале строки. Предупреждения `warnings` тоже
+    попадают в логирование.
+
+    Ставит `sys.excepthook` и `threading.excepthook`. Они пишут необработанное
+    исключение с трассировкой уровнем CRITICAL в логгер `ls_logging`. Если
+    другая настройка логирования отключила этот логгер, обработчики снова
+    включают его. Если уровень CRITICAL запрещен через `logging.disable`,
+    трассировку печатает `sys.__excepthook__`. `KeyboardInterrupt` передается
+    в `sys.__excepthook__`. `SystemExit` в потоке пропускается. Если службе
+    нужен свой `threading.excepthook`, она ставит его после вызова.
+
+    Args:
+        service: Имя службы, под которым записи видны в journald.
+        level: Уровень корневого логгера: число, имя уровня в любом регистре
+            или `Enum` со строковым значением. Имя `WARN` понимается как
+            `WARNING`.
+
+    Raises:
+        ValueError: Если уровень не распознан. Настройка при этом не меняется.
+    """
+    numeric_level = resolve_level(level)
+    root = logging.getLogger()
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+    root.addHandler(build_handler(service))
+    root.setLevel(numeric_level)
+    logging.captureWarnings(True)
+    sys.excepthook = _log_uncaught
+    threading.excepthook = _log_uncaught_in_thread

ls_logging-0.1.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: ls-logging
+Version: 0.1.0
+Summary: Логи служб lightmaster в journald
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: django; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

ls_logging-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ls_logging/__init__.py,sha256=mYyk4TFP0CPHhXeZ1QLhmnHH61gRVh2prXZrNCUyRgU,189
+ls_logging/_django.py,sha256=smZyaiaPg_8Sz4EjciZslZGGiAcfx0GCwsPN96qWewI,2068
+ls_logging/_output.py,sha256=67TPeCtryIMmyYwcZsdKcxcBIcMJl6X1P-ZSDB8Jghg,2108
+ls_logging/_setup.py,sha256=nTcqdwh5U56X55an-YMhJy65XpS0t4piKhXX9kamj2c,5236
+ls_logging/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ls_logging-0.1.0.dist-info/METADATA,sha256=bt1NMHfqnX3dqucXyO2puZbiofxD_OHOL1mjqtLNp9A,344
+ls_logging-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ls_logging-0.1.0.dist-info/licenses/LICENSE,sha256=pAyjtZTnBzDV8HMMaz3QbwL82-pfO39qH_3nreod1XY,1070
+ls_logging-0.1.0.dist-info/RECORD,,

ls_logging-0.1.0.dist-info/WHEEL

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

ls_logging-0.1.0.dist-info/licenses/LICENSE

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