safir-logging 6.3.0__tar.gz

safir_logging-6.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Association of Universities for Research in Astronomy, Inc. (AURA)
+
+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.

safir_logging-6.3.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.1
+Name: safir-logging
+Version: 6.3.0
+Summary: Logging for the Rubin Observatory SQuaRE framework, Safir.
+Author-email: "Association of Universities for Research in Astronomy, Inc. (AURA)" <sqre-admin@lists.lsst.org>
+License: MIT License
+        
+        Copyright (c) 2020 Association of Universities for Research in Astronomy, Inc. (AURA)
+        
+        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.
+        
+Project-URL: Homepage, https://safir.lsst.io
+Project-URL: Source, https://github.com/lsst-sqre/safir
+Project-URL: Change log, https://safir.lsst.io/changelog.html
+Project-URL: Issue tracker, https://github.com/lsst-sqre/safir/issues
+Keywords: rubin,lsst
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: structlog!=23.3.0,>=21.2.0
+
+# safir-logging
+
+safir-logging is a subpackage of Safir, Rubin Observatory's library for building [FastAPI](https://fastapi.tiangolo.com/) services for the [Rubin Science Platform (Phalanx)](https://github.com/lsst-sqre/phalanx) and [Roundtable](https://github.com/lsst-sqre/roundtable) Kubernetes clusters.
+It is a separate PyPI module so that it can be used as a dependency in contexts where the full Safir dependency is undesirable.
+
+safir-logging is available from [PyPI](https://pypi.org/project/safir-logging/):
+
+```sh
+pip install safir-logging
+```
+
+safir-logging is developed and tested in conjunction with Safir.
+Read more about Safir at https://safir.lsst.io.

safir_logging-6.3.0/README.md

@@ -0,0 +1,13 @@
+# safir-logging
+
+safir-logging is a subpackage of Safir, Rubin Observatory's library for building [FastAPI](https://fastapi.tiangolo.com/) services for the [Rubin Science Platform (Phalanx)](https://github.com/lsst-sqre/phalanx) and [Roundtable](https://github.com/lsst-sqre/roundtable) Kubernetes clusters.
+It is a separate PyPI module so that it can be used as a dependency in contexts where the full Safir dependency is undesirable.
+
+safir-logging is available from [PyPI](https://pypi.org/project/safir-logging/):
+
+```sh
+pip install safir-logging
+```
+
+safir-logging is developed and tested in conjunction with Safir.
+Read more about Safir at https://safir.lsst.io.

safir_logging-6.3.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+# https://packaging.python.org/en/latest/specifications/declaring-project-metadata/
+name = "safir-logging"
+description = "Logging for the Rubin Observatory SQuaRE framework, Safir."
+license = {file = "LICENSE"}
+readme= "README.md"
+keywords = [
+    "rubin",
+    "lsst",
+]
+# https://pypi.org/classifiers/
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: POSIX",
+    "Typing :: Typed",
+]
+requires-python = ">=3.11"
+dependencies = [
+    # 23.3.0 excluded due to https://github.com/hynek/structlog/issues/584
+    "structlog>=21.2.0,!=23.3.0",
+]
+dynamic = ["version"]
+
+[[project.authors]]
+name = "Association of Universities for Research in Astronomy, Inc. (AURA)"
+email = "sqre-admin@lists.lsst.org"
+
+[project.urls]
+Homepage = "https://safir.lsst.io"
+Source = "https://github.com/lsst-sqre/safir"
+"Change log" = "https://safir.lsst.io/changelog.html"
+"Issue tracker" = "https://github.com/lsst-sqre/safir/issues"
+
+[build-system]
+requires = [
+    "setuptools>=61",
+    "wheel",
+    "setuptools_scm[toml]>=6.2"
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+root = ".."

safir_logging-6.3.0/setup.cfg

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

safir_logging-6.3.0/src/safir/logging/__init__.py

@@ -0,0 +1,13 @@
+"""Utilities for configuring structlog-based logging."""
+
+from ._models import LogLevel, Profile
+from ._structlog import add_log_severity, configure_logging
+from ._uvicorn import configure_uvicorn_logging
+
+__all__ = [
+    "LogLevel",
+    "Profile",
+    "add_log_severity",
+    "configure_logging",
+    "configure_uvicorn_logging",
+]

safir_logging-6.3.0/src/safir/logging/_models.py

@@ -0,0 +1,46 @@
+"""Models for structlog-based logging."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Self
+
+__all__ = [
+    "LogLevel",
+    "Profile",
+]
+
+
+class Profile(Enum):
+    """Logging profile for the application."""
+
+    production = "production"
+    """Log messages in JSON."""
+
+    development = "development"
+    """Log messages in a format intended for human readability."""
+
+
+class LogLevel(Enum):
+    """Python logging level.
+
+    Any case variation is accepted when converting a string to an enum value
+    via the class constructor.
+    """
+
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+    @classmethod
+    def _missing_(cls, value: Any) -> Self | None:
+        """Allow strings in any case to be used to create the enum."""
+        if not isinstance(value, str):
+            return None
+        value = value.upper()
+        for member in cls:
+            if member.value == value:
+                return member
+        return None

safir_logging-6.3.0/src/safir/logging/_structlog.py

@@ -0,0 +1,171 @@
+"""Utilities for configuring structlog-based logging."""
+
+from __future__ import annotations
+
+import logging
+import logging.config
+import sys
+from typing import Any
+
+import structlog
+from structlog.stdlib import add_log_level
+from structlog.types import EventDict
+
+try:
+    from safir.dependencies import logger as logger_dependency
+
+    _UPDATE_DEPENDENCY = True
+except Exception:
+    _UPDATE_DEPENDENCY = False
+
+from ._models import LogLevel, Profile
+
+__all__ = [
+    "add_log_severity",
+    "configure_logging",
+]
+
+
+def add_log_severity(
+    logger: logging.Logger, method_name: str, event_dict: EventDict
+) -> EventDict:
+    """Add the log level to the event dict as ``severity``.
+
+    Intended for use as a structlog processor.
+
+    This is the same as `structlog.stdlib.add_log_level` except that it
+    uses the ``severity`` key rather than ``level`` for compatibility with
+    Google Log Explorer and its automatic processing of structured logs.
+
+    Parameters
+    ----------
+    logger
+        The wrapped logger object.
+    method_name
+        The name of the wrapped method (``warning`` or ``error``, for
+        example).
+    event_dict
+        Current context and current event. This parameter is also modified in
+        place, matching the normal behavior of structlog processors.
+
+    Returns
+    -------
+    ``structlog.types.EventDict``
+        The modified ``structlog.types.EventDict`` with the added key.
+    """
+    severity = add_log_level(logger, method_name, {})["level"]
+    event_dict["severity"] = severity
+    return event_dict
+
+
+def configure_logging(
+    *,
+    name: str,
+    profile: Profile | str = Profile.production,
+    log_level: LogLevel | str = LogLevel.INFO,
+    add_timestamp: bool = False,
+) -> None:
+    """Configure logging and structlog.
+
+    Parameters
+    ----------
+    name
+        Name of the logger, which is typically the name of your application's
+        root namespace.
+    profile
+        The name of the application profile:
+
+        development
+            Log messages are formatted for easier reading on the terminal.
+        production
+            Log messages are formatted as JSON objects.
+
+        May be given as a `Profile` enum value (preferred) or a string.
+    log_level
+        The Python log level. May be given as a `LogLevel` enum (preferred)
+        or a case-insensitive string.
+    add_timestamp
+        Whether to add an ISO-format timestamp to each log message.
+
+    Notes
+    -----
+    This function helps you configure a useful logging set up for your
+    application that's based on structlog_.
+
+    First, it configures the logger for your application to log to STDOUT.
+    Second, it configures the formatting of your log messages through
+    structlog.
+
+    In development mode, messages are key-value formatted, like this:
+
+    .. code-block:: text
+
+       [info     ] Hello world                    [myapp] answer=42
+
+    Here, "Hello world" is the message. ``answer=42`` is a value bound to the
+    logger.
+
+    In production mode, messages are formatted as JSON objects:
+
+    .. code-block:: text
+
+       {"answer": 42, "event": "Hello world", "logger": "myapp",
+       "severity": "info"}
+
+    Examples
+    --------
+    .. code-block:: python
+
+       import structlog
+       from safir.logging import configure_logging
+
+
+       configure_logging(name="mybot")
+       logger = structlog.get_logger("mybot")
+       logger.info("Hello world")
+    """
+    if not isinstance(log_level, LogLevel):
+        log_level = LogLevel[log_level.upper()]
+    if not isinstance(profile, Profile):
+        profile = Profile[profile]
+
+    stream_handler = logging.StreamHandler(stream=sys.stdout)
+    stream_handler.setFormatter(logging.Formatter("%(message)s"))
+    logger = logging.getLogger(name)
+    logger.handlers = []
+    logger.addHandler(stream_handler)
+    logger.setLevel(log_level.value)
+
+    processors: list[Any] = [
+        structlog.stdlib.filter_by_level,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.PositionalArgumentsFormatter(),
+    ]
+    if add_timestamp:
+        processors.append(structlog.processors.TimeStamper(fmt="iso"))
+    processors.extend(
+        [
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.UnicodeDecoder(),
+        ]
+    )
+    if profile == Profile.production:
+        # JSON-formatted logging
+        processors.append(add_log_severity)
+        processors.append(structlog.processors.format_exc_info)
+        processors.append(structlog.processors.JSONRenderer())
+    else:
+        # Key-value formatted logging
+        processors.append(structlog.stdlib.add_log_level)
+        processors.append(structlog.dev.ConsoleRenderer())
+
+    structlog.configure(
+        processors=processors,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        wrapper_class=structlog.stdlib.BoundLogger,
+        cache_logger_on_first_use=True,
+    )
+
+    # Set the configured name for the global logger.
+    if _UPDATE_DEPENDENCY:
+        logger_dependency._logger_name = name  # noqa: SLF001

safir_logging-6.3.0/src/safir/logging/_uvicorn.py

@@ -0,0 +1,143 @@
+"""Utilities for configuring uvicorn to use structlog."""
+
+from __future__ import annotations
+
+import logging
+import logging.config
+import re
+
+import structlog
+from structlog.types import EventDict
+
+from ._models import LogLevel
+from ._structlog import add_log_severity
+
+__all__ = ["configure_uvicorn_logging"]
+
+_UVICORN_ACCESS_REGEX = re.compile(r'^[0-9.]+:[0-9]+ - "([^"]+)" ([0-9]+)$')
+"""Regex to parse Uvicorn access logs."""
+
+
+def _process_uvicorn_access_log(
+    logger: logging.Logger, method_name: str, event_dict: EventDict
+) -> EventDict:
+    """Parse a Uvicorn access log entry into key/value pairs.
+
+    Intended for use as a structlog processor.
+
+    This checks whether the log message is a Uvicorn access log entry and, if
+    so, parses the message into key/value pairs for JSON logging so that the
+    details can be programmatically extracted.  ``remoteIp`` is intentionally
+    omitted since it isn't aware of ``X-Forwarded-For`` and will therefore
+    always point to an uninteresting in-cluster IP.
+
+    Parameters
+    ----------
+    logger
+        The wrapped logger object.
+    method_name
+        The name of the wrapped method (``warning`` or ``error``, for
+        example).
+    event_dict
+        Current context and current event. This parameter is also modified in
+        place, matching the normal behavior of structlog processors.
+
+    Returns
+    -------
+    EventDict
+        The modified `~structlog.types.EventDict` with the added key.
+    """
+    match = _UVICORN_ACCESS_REGEX.match(event_dict["event"])
+    if not match:
+        return event_dict
+    request = match.group(1)
+    method, rest = request.split(" ", 1)
+    url, protocol = rest.rsplit(" ", 1)
+    if "httpRequest" not in event_dict:
+        event_dict["httpRequest"] = {}
+    event_dict["httpRequest"]["protocol"] = protocol
+    event_dict["httpRequest"]["requestMethod"] = method
+    event_dict["httpRequest"]["requestUrl"] = url
+    event_dict["httpRequest"]["status"] = match.group(2)
+    return event_dict
+
+
+def configure_uvicorn_logging(
+    log_level: LogLevel | str = LogLevel.INFO,
+) -> None:
+    """Set up logging.
+
+    This configures Uvicorn to use structlog for output formatting and
+    installs a custom processor to parse its access log messages into
+    additional log context that matches the format of Google log messages.
+    This helps Google's Cloud Logging system understand the logs. Access logs
+    are sent to standard output and all other logs are sent to standard
+    error.
+
+    Parameters
+    ----------
+    log_level
+        The Python log level. May be given as a `LogLevel` enum (preferred)
+        or a case-insensitive string.
+
+    Notes
+    -----
+    This method should normally be called during FastAPI app creation, either
+    during Python module import or inside the function that creates and
+    returns the FastAPI app that Uvicorn will run. This ensures the logging
+    setup is complete before Uvicorn logs its first message.
+    """
+    if not isinstance(log_level, LogLevel):
+        log_level = LogLevel[log_level.upper()]
+
+    processors = [
+        structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+        structlog.processors.format_exc_info,
+        structlog.processors.JSONRenderer(),
+    ]
+    logging.config.dictConfig(
+        {
+            "version": 1,
+            "disable_existing_loggers": False,
+            "formatters": {
+                "json-access": {
+                    "()": structlog.stdlib.ProcessorFormatter,
+                    "processors": processors,
+                    "foreign_pre_chain": [
+                        add_log_severity,
+                        _process_uvicorn_access_log,
+                    ],
+                },
+                "json": {
+                    "()": structlog.stdlib.ProcessorFormatter,
+                    "processors": processors,
+                    "foreign_pre_chain": [add_log_severity],
+                },
+            },
+            "handlers": {
+                "uvicorn.access": {
+                    "level": log_level.value,
+                    "class": "logging.StreamHandler",
+                    "formatter": "json-access",
+                    "stream": "ext://sys.stdout",
+                },
+                "uvicorn.default": {
+                    "level": log_level.value,
+                    "class": "logging.StreamHandler",
+                    "formatter": "json",
+                },
+            },
+            "loggers": {
+                "uvicorn.error": {
+                    "handlers": ["uvicorn.default"],
+                    "level": log_level.value,
+                    "propagate": False,
+                },
+                "uvicorn.access": {
+                    "handlers": ["uvicorn.access"],
+                    "level": log_level.value,
+                    "propagate": False,
+                },
+            },
+        }
+    )

safir_logging-6.3.0/src/safir_logging.egg-info/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.1
+Name: safir-logging
+Version: 6.3.0
+Summary: Logging for the Rubin Observatory SQuaRE framework, Safir.
+Author-email: "Association of Universities for Research in Astronomy, Inc. (AURA)" <sqre-admin@lists.lsst.org>
+License: MIT License
+        
+        Copyright (c) 2020 Association of Universities for Research in Astronomy, Inc. (AURA)
+        
+        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.
+        
+Project-URL: Homepage, https://safir.lsst.io
+Project-URL: Source, https://github.com/lsst-sqre/safir
+Project-URL: Change log, https://safir.lsst.io/changelog.html
+Project-URL: Issue tracker, https://github.com/lsst-sqre/safir/issues
+Keywords: rubin,lsst
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: structlog!=23.3.0,>=21.2.0
+
+# safir-logging
+
+safir-logging is a subpackage of Safir, Rubin Observatory's library for building [FastAPI](https://fastapi.tiangolo.com/) services for the [Rubin Science Platform (Phalanx)](https://github.com/lsst-sqre/phalanx) and [Roundtable](https://github.com/lsst-sqre/roundtable) Kubernetes clusters.
+It is a separate PyPI module so that it can be used as a dependency in contexts where the full Safir dependency is undesirable.
+
+safir-logging is available from [PyPI](https://pypi.org/project/safir-logging/):
+
+```sh
+pip install safir-logging
+```
+
+safir-logging is developed and tested in conjunction with Safir.
+Read more about Safir at https://safir.lsst.io.

safir_logging-6.3.0/src/safir_logging.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/safir/logging/__init__.py
+src/safir/logging/_models.py
+src/safir/logging/_structlog.py
+src/safir/logging/_uvicorn.py
+src/safir/logging/py.typed
+src/safir_logging.egg-info/PKG-INFO
+src/safir_logging.egg-info/SOURCES.txt
+src/safir_logging.egg-info/dependency_links.txt
+src/safir_logging.egg-info/requires.txt
+src/safir_logging.egg-info/top_level.txt

safir_logging-6.3.0/src/safir_logging.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

safir_logging-6.3.0/src/safir_logging.egg-info/requires.txt

@@ -0,0 +1 @@
+structlog!=23.3.0,>=21.2.0

safir_logging-6.3.0/src/safir_logging.egg-info/top_level.txt

@@ -0,0 +1 @@
+safir