python-json-logger 3.0.1__py3-none-any.whl → 3.2.0__py3-none-any.whl

python_json_logger-3.2.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.1
+Name: python-json-logger
+Version: 3.2.0
+Summary: JSON Log Formatter for the Python Logging Package
+Author-email: Zakaria Zajac <zak@madzak.com>, Nicholas Hairs <info+python-json-logger@nicholashairs.com>
+Maintainer-email: Nicholas Hairs <info+python-json-logger@nicholashairs.com>
+License: BSD-2-Clause License
+Project-URL: Homepage, https://nhairs.github.io/python-json-logger
+Project-URL: GitHub, https://github.com/nhairs/python-json-logger
+Classifier: Development Status :: 6 - Mature
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: typing_extensions; python_version < "3.10"
+Provides-Extra: dev
+Requires-Dist: orjson; implementation_name != "pypy" and extra == "dev"
+Requires-Dist: msgspec; (implementation_name != "pypy" and python_version < "3.13") and extra == "dev"
+Requires-Dist: msgspec-python313-pre; (implementation_name != "pypy" and python_version == "3.13") and extra == "dev"
+Requires-Dist: validate-pyproject[all]; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: freezegun; extra == "dev"
+Requires-Dist: backports.zoneinfo; python_version < "3.9" and extra == "dev"
+Requires-Dist: tzdata; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: mkdocs; extra == "dev"
+Requires-Dist: mkdocs-material>=8.5; extra == "dev"
+Requires-Dist: mkdocs-awesome-pages-plugin; extra == "dev"
+Requires-Dist: mdx_truly_sane_lists; extra == "dev"
+Requires-Dist: mkdocstrings[python]; extra == "dev"
+Requires-Dist: mkdocs-gen-files; extra == "dev"
+Requires-Dist: mkdocs-literate-nav; extra == "dev"
+Requires-Dist: mike; extra == "dev"
+
+<!-- [![PyPi](https://img.shields.io/pypi/v/python-json-logger.svg)](https://pypi.python.org/pypi/python-json-logger/)
+[![PyPI - Status](https://img.shields.io/pypi/status/python-json-logger)](https://pypi.python.org/pypi/python-json-logger/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/python-json-logger.svg)](https://github.com/nhairs/python-json-logger) -->
+[![License](https://img.shields.io/github/license/nhairs/python-json-logger.svg)](https://github.com/nhairs/python-json-logger)
+![Build Status](https://github.com/nhairs/python-json-logger/actions/workflows/test-suite.yml/badge.svg)
+#
+# Python JSON Logger
+
+Python JSON Logger enables you produce JSON logs when using Python's `logging` package.
+
+JSON logs are machine readable allowing for much easier parsing and ingestion into log aggregation tools.
+
+
+### 🚨 Important 🚨
+
+This repository is a maintained fork of [madzak/python-json-logger](https://github.com/madzak/python-json-logger) pending [a PEP 541 request](https://github.com/pypi/support/issues/3607) for the PyPI package.  The future direction of the project is being discussed [here](https://github.com/nhairs/python-json-logger/issues/1).
+
+## Documentation
+
+- [Documentation](https://nhairs.github.io/python-json-logger/latest/)
+- [Quickstart Guide](https://nhairs.github.io/python-json-logger/latest/quickstart/)
+- [Change Log](https://nhairs.github.io/python-json-logger/latest/changelog/)
+- [Contributing](https://nhairs.github.io/python-json-logger/latest/contributing/)
+
+## License
+
+This project is licensed under the BSD 2 Clause License - see [`LICENSE`](https://github.com/nhairs/python-json-logger/blob/main/LICENSE)
+
+## Authors and Maintainers
+
+This project was originally authored by [Zakaria Zajac](https://github.com/madzak) and our wonderful [contributors](https://github.com/nhairs/python-json-logger/graphs/contributors)
+
+It is currently maintained by:
+
+- [Nicholas Hairs](https://github.com/nhairs) - [nicholashairs.com](https://www.nicholashairs.com)

python_json_logger-3.2.0.dist-info/NOTICE

@@ -0,0 +1,5 @@
+This software includes the following licenced software:
+  - mkdocstrings-python
+    Copyright (c) 2021, Timothée Mazzucotelli
+    Licenced under ISC Licence
+    Source: https://github.com/mkdocstrings/python

python_json_logger-3.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pythonjsonlogger/__init__.py,sha256=mvnVMTGrh32otHxVE7-MsxT9kBvmMyS6I3NCQDe55LY,898
+pythonjsonlogger/core.py,sha256=zrf2vBMPVjPv5ornwWs2TOi68FbWDnuhj_DrcUiuBG0,13328
+pythonjsonlogger/defaults.py,sha256=-XgxIj8ioq7CsnBBMsQhTRpU-lKbLrpQLJTCaT3iH38,6577
+pythonjsonlogger/exception.py,sha256=r3DXDk7TThscnMVNPpVRaRSFHTnY-ygea6nn-FgjwsI,804
+pythonjsonlogger/json.py,sha256=TsKD_1-TDjaeMUg6la_aVzIWd7GBxgAntY6zWzVe7lU,4165
+pythonjsonlogger/msgspec.py,sha256=M5kiIX4RLr1PwvWKx21N8sgk05LCFymBAWM4cRR3VNA,2161
+pythonjsonlogger/orjson.py,sha256=HVhIHo7CrTwj9pZuZzUmj1qsW0coNdVmDKSDycDs-pM,2357
+pythonjsonlogger/py.typed,sha256=4RLptUHQuSqzK6CDbigff8uvWQjwPPQMxikWPkV4OtA,80
+pythonjsonlogger/utils.py,sha256=qr04nb61TkVw7cJTXAtLBfyH_NBvyYUlR_mehH76-RM,1126
+python_json_logger-3.2.0.dist-info/LICENSE,sha256=GOqVF546Xg4k62zhbED7--IxM8JQKTOi91-KPhoFW1Q,1329
+python_json_logger-3.2.0.dist-info/METADATA,sha256=5eZGCDrb3mmrvVyiug9EYBtzaD_PDzZmHw_UUy4dlKc,4357
+python_json_logger-3.2.0.dist-info/NOTICE,sha256=uRQnFcGZCwuIBR2AIHVvhKi9w1KkiI_vAyralfxCsk4,209
+python_json_logger-3.2.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+python_json_logger-3.2.0.dist-info/top_level.txt,sha256=9G-OsTkbwPgM8t-bXKPmWDBRZv9cbzLIiEDE5EnGk2I,17
+python_json_logger-3.2.0.dist-info/RECORD,,

{python_json_logger-3.0.1.dist-info → python_json_logger-3.2.0.dist-info}/WHEEL

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

pythonjsonlogger/__init__.py

@@ -0,0 +1,29 @@
+### IMPORTS
+### ============================================================================
+## Future
+
+## Standard Library
+import warnings
+
+## Installed
+
+## Application
+import pythonjsonlogger.json
+import pythonjsonlogger.utils
+
+### CONSTANTS
+### ============================================================================
+ORJSON_AVAILABLE = pythonjsonlogger.utils.package_is_available("orjson")
+MSGSPEC_AVAILABLE = pythonjsonlogger.utils.package_is_available("msgspec")
+
+
+### DEPRECATED COMPATIBILITY
+### ============================================================================
+def __getattr__(name: str):
+    if name == "jsonlogger":
+        warnings.warn(
+            "pythonjsonlogger.jsonlogger has been moved to pythonjsonlogger.json",
+            DeprecationWarning,
+        )
+        return pythonjsonlogger.json
+    raise AttributeError(f"module {__name__} has no attribute {name}")

pythonjsonlogger/core.py

@@ -0,0 +1,370 @@
+"""Core functionality shared by all JSON loggers"""
+
+### IMPORTS
+### ============================================================================
+## Future
+from __future__ import annotations
+
+## Standard Library
+from datetime import datetime, timezone
+import importlib
+import logging
+import re
+import sys
+from typing import Optional, Union, Callable, List, Dict, Container, Any, Sequence
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+## Installed
+
+## Application
+
+
+### CONSTANTS
+### ============================================================================
+RESERVED_ATTRS: List[str] = [
+    "args",
+    "asctime",
+    "created",
+    "exc_info",
+    "exc_text",
+    "filename",
+    "funcName",
+    "levelname",
+    "levelno",
+    "lineno",
+    "module",
+    "msecs",
+    "message",
+    "msg",
+    "name",
+    "pathname",
+    "process",
+    "processName",
+    "relativeCreated",
+    "stack_info",
+    "thread",
+    "threadName",
+]
+"""Default reserved attributes.
+
+These come from the [default attributes of `LogRecord` objects](http://docs.python.org/library/logging.html#logrecord-attributes).
+
+Note:
+    Although considered a constant, this list is dependent on the Python version due to
+    different `LogRecord` objects having different attributes in different Python versions.
+
+*Changed in 3.0*: `RESERVED_ATTRS` is now `list[str]` instead of `tuple[str, ...]`.
+"""
+
+if sys.version_info >= (3, 12):
+    # taskName added in python 3.12
+    RESERVED_ATTRS.append("taskName")
+    RESERVED_ATTRS.sort()
+
+
+STYLE_STRING_TEMPLATE_REGEX = re.compile(r"\$\{(.+?)\}", re.IGNORECASE)  # $ style
+STYLE_STRING_FORMAT_REGEX = re.compile(r"\{(.+?)\}", re.IGNORECASE)  # { style
+STYLE_PERCENT_REGEX = re.compile(r"%\((.+?)\)", re.IGNORECASE)  # % style
+
+## Type Aliases
+## -----------------------------------------------------------------------------
+OptionalCallableOrStr: TypeAlias = Optional[Union[Callable, str]]
+"""Type alias"""
+
+LogRecord: TypeAlias = Dict[str, Any]
+"""Type alias"""
+
+
+### FUNCTIONS
+### ============================================================================
+def str_to_object(obj: Any) -> Any:
+    """Import strings to an object, leaving non-strings as-is.
+
+    Args:
+        obj: the object or string to process
+
+    *New in 3.1*
+    """
+
+    if not isinstance(obj, str):
+        return obj
+
+    module_name, attribute_name = obj.rsplit(".", 1)
+    return getattr(importlib.import_module(module_name), attribute_name)
+
+
+def merge_record_extra(
+    record: logging.LogRecord,
+    target: Dict,
+    reserved: Container[str],
+    rename_fields: Optional[Dict[str, str]] = None,
+) -> Dict:
+    """
+    Merges extra attributes from LogRecord object into target dictionary
+
+    Args:
+        record: logging.LogRecord
+        target: dict to update
+        reserved: dict or list with reserved keys to skip
+        rename_fields: an optional dict, used to rename field names in the output.
+            e.g. Rename `levelname` to `log.level`: `{'levelname': 'log.level'}`
+
+    *Changed in 3.1*: `reserved` is now `Container[str]`.
+    """
+    if rename_fields is None:
+        rename_fields = {}
+    for key, value in record.__dict__.items():
+        # this allows to have numeric keys
+        if key not in reserved and not (hasattr(key, "startswith") and key.startswith("_")):
+            target[rename_fields.get(key, key)] = value
+    return target
+
+
+### CLASSES
+### ============================================================================
+class BaseJsonFormatter(logging.Formatter):
+    """Base class for all formatters
+
+    Must not be used directly.
+
+    *New in 3.1*
+
+    *Changed in 3.2*: `defaults` argument is no longer ignored.
+    """
+
+    _style: Union[logging.PercentStyle, str]  # type: ignore[assignment]
+
+    ## Parent Methods
+    ## -------------------------------------------------------------------------
+    # pylint: disable=too-many-arguments,super-init-not-called
+    def __init__(
+        self,
+        fmt: Optional[str] = None,
+        datefmt: Optional[str] = None,
+        style: str = "%",
+        validate: bool = True,
+        *,
+        prefix: str = "",
+        rename_fields: Optional[Dict[str, str]] = None,
+        rename_fields_keep_missing: bool = False,
+        static_fields: Optional[Dict[str, Any]] = None,
+        reserved_attrs: Optional[Sequence[str]] = None,
+        timestamp: Union[bool, str] = False,
+        defaults: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Args:
+            fmt: string representing fields to log
+            datefmt: format to use when formatting `asctime` field
+            style: how to extract log fields from `fmt`
+            validate: validate `fmt` against style, if implementing a custom `style` you
+                must set this to `False`.
+            defaults: a dictionary containing default fields that are added before all other fields and
+                may be overridden. The supplied fields are still subject to `rename_fields`.
+            prefix: an optional string prefix added at the beginning of
+                the formatted string
+            rename_fields: an optional dict, used to rename field names in the output.
+                Rename `message` to `@message`: `{'message': '@message'}`
+            rename_fields_keep_missing: When renaming fields, include missing fields in the output.
+            static_fields: an optional dict, used to add fields with static values to all logs
+            reserved_attrs: an optional list of fields that will be skipped when
+                outputting json log record. Defaults to [all log record attributes][pythonjsonlogger.core.RESERVED_ATTRS].
+            timestamp: an optional string/boolean field to add a timestamp when
+                outputting the json log record. If string is passed, timestamp will be added
+                to log record using string as key. If True boolean is passed, timestamp key
+                will be "timestamp". Defaults to False/off.
+
+        *Changed in 3.1*:
+
+        - you can now use custom values for style by setting validate to `False`.
+          The value is stored in `self._style` as a string. The `parse` method will need to be
+          overridden in order to support the new style.
+        - Renaming fields now preserves the order that fields were added in and avoids adding
+          missing fields. The original behaviour, missing fields have a value of `None`, is still
+          available by setting `rename_fields_keep_missing` to `True`.
+        """
+        ## logging.Formatter compatibility
+        ## ---------------------------------------------------------------------
+        # Note: validate added in 3.8, defaults added in 3.10
+        if style in logging._STYLES:
+            _style = logging._STYLES[style][0](fmt)  # type: ignore[operator]
+            if validate:
+                _style.validate()
+            self._style = _style
+            self._fmt = _style._fmt
+
+        elif not validate:
+            self._style = style
+            self._fmt = fmt
+
+        else:
+            raise ValueError(f"Style must be one of: {','.join(logging._STYLES.keys())}")
+
+        self.datefmt = datefmt
+
+        ## JSON Logging specific
+        ## ---------------------------------------------------------------------
+        self.prefix = prefix
+        self.rename_fields = rename_fields if rename_fields is not None else {}
+        self.rename_fields_keep_missing = rename_fields_keep_missing
+        self.static_fields = static_fields if static_fields is not None else {}
+        self.reserved_attrs = set(reserved_attrs if reserved_attrs is not None else RESERVED_ATTRS)
+        self.timestamp = timestamp
+
+        self._required_fields = self.parse()
+        self._skip_fields = set(self._required_fields)
+        self._skip_fields.update(self.reserved_attrs)
+        self.defaults = defaults if defaults is not None else {}
+        return
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Formats a log record and serializes to json
+
+        Args:
+            record: the record to format
+        """
+        message_dict: Dict[str, Any] = {}
+        # TODO: logging.LogRecord.msg and logging.LogRecord.message in typeshed
+        #        are always type of str. We shouldn't need to override that.
+        if isinstance(record.msg, dict):
+            message_dict = record.msg
+            record.message = ""
+        else:
+            record.message = record.getMessage()
+
+        # only format time if needed
+        if "asctime" in self._required_fields:
+            record.asctime = self.formatTime(record, self.datefmt)
+
+        # Display formatted exception, but allow overriding it in the
+        # user-supplied dict.
+        if record.exc_info and not message_dict.get("exc_info"):
+            message_dict["exc_info"] = self.formatException(record.exc_info)
+        if not message_dict.get("exc_info") and record.exc_text:
+            message_dict["exc_info"] = record.exc_text
+
+        # Display formatted record of stack frames
+        # default format is a string returned from :func:`traceback.print_stack`
+        if record.stack_info and not message_dict.get("stack_info"):
+            message_dict["stack_info"] = self.formatStack(record.stack_info)
+
+        log_record: LogRecord = {}
+        self.add_fields(log_record, record, message_dict)
+        log_record = self.process_log_record(log_record)
+
+        return self.serialize_log_record(log_record)
+
+    ## JSON Formatter Specific Methods
+    ## -------------------------------------------------------------------------
+    def parse(self) -> List[str]:
+        """Parses format string looking for substitutions
+
+        This method is responsible for returning a list of fields (as strings)
+        to include in all log messages.
+
+        You can support custom styles by overriding this method.
+
+        Returns:
+            list of fields to be extracted and serialized
+        """
+        if isinstance(self._style, logging.StringTemplateStyle):
+            formatter_style_pattern = STYLE_STRING_TEMPLATE_REGEX
+
+        elif isinstance(self._style, logging.StrFormatStyle):
+            formatter_style_pattern = STYLE_STRING_FORMAT_REGEX
+
+        elif isinstance(self._style, logging.PercentStyle):
+            # PercentStyle is parent class of StringTemplateStyle and StrFormatStyle
+            # so it must be checked last.
+            formatter_style_pattern = STYLE_PERCENT_REGEX
+
+        else:
+            raise ValueError(f"Style {self._style!r} is not supported")
+
+        if self._fmt:
+            return formatter_style_pattern.findall(self._fmt)
+
+        return []
+
+    def serialize_log_record(self, log_record: LogRecord) -> str:
+        """Returns the final representation of the log record.
+
+        Args:
+            log_record: the log record
+        """
+        return self.prefix + self.jsonify_log_record(log_record)
+
+    def add_fields(
+        self,
+        log_record: Dict[str, Any],
+        record: logging.LogRecord,
+        message_dict: Dict[str, Any],
+    ) -> None:
+        """Extract fields from a LogRecord for logging
+
+        This method can be overridden to implement custom logic for adding fields.
+
+        Args:
+            log_record: data that will be logged
+            record: the record to extract data from
+            message_dict: dictionary that was logged instead of a message. e.g
+                `logger.info({"is_this_message_dict": True})`
+        """
+        for field in self.defaults:
+            log_record[self._get_rename(field)] = self.defaults[field]
+
+        for field in self._required_fields:
+            log_record[self._get_rename(field)] = record.__dict__.get(field)
+
+        for data_dict in [self.static_fields, message_dict]:
+            for key, value in data_dict.items():
+                log_record[self._get_rename(key)] = value
+
+        merge_record_extra(
+            record,
+            log_record,
+            reserved=self._skip_fields,
+            rename_fields=self.rename_fields,
+        )
+
+        if self.timestamp:
+            key = self.timestamp if isinstance(self.timestamp, str) else "timestamp"
+            log_record[self._get_rename(key)] = datetime.fromtimestamp(
+                record.created, tz=timezone.utc
+            )
+
+        if self.rename_fields_keep_missing:
+            for field in self.rename_fields.values():
+                if field not in log_record:
+                    log_record[field] = None
+        return
+
+    def _get_rename(self, key: str) -> str:
+        return self.rename_fields.get(key, key)
+
+    # Child Methods
+    # ..........................................................................
+    def jsonify_log_record(self, log_record: LogRecord) -> str:
+        """Convert this log record into a JSON string.
+
+        Child classes MUST override this method.
+
+        Args:
+            log_record: the data to serialize
+        """
+        raise NotImplementedError()
+
+    def process_log_record(self, log_record: LogRecord) -> LogRecord:
+        """Custom processing of the log record.
+
+        Child classes can override this method to alter the log record before it
+        is serialized.
+
+        Args:
+            log_record: incoming data
+        """
+        return log_record