### Install development dependencies

Source: https://nhairs.github.io/python-json-logger/latest/contributing

Installs the project in editable mode with all development tools.

```bash
pip install -e '.[dev]'
```

--------------------------------

### Common setup for request ID logging

Source: https://nhairs.github.io/python-json-logger/latest/cookbook

Initialize the logger and stream handler required for the following request ID examples.

```python
## Common Setup
## -----------------------------------------------------------------------------
import logging
import uuid
from pythonjsonlogger.json import JsonFormatter

logger = logging.getLogger("test")
logger.setLevel(logging.INFO)
handler = logging.StreamHandler()
logger.addHandler(handler)
```

--------------------------------

### Install python-json-logger from GitHub

Source: https://nhairs.github.io/python-json-logger/latest/quickstart

Install a specific version of the library directly from a GitHub release wheel.

```bash
# e.g. 3.0.0 wheel
pip install 'python-json-logger@https://github.com/nhairs/python-json-logger/releases/download/v3.0.0/python_json_logger-3.0.0-py3-none-any.whl'

```

--------------------------------

### Install python-json-logger via pip

Source: https://nhairs.github.io/python-json-logger/latest/quickstart

Use this command to install the library using pip.

```bash
pip install python-json-logger

```

--------------------------------

### Configure JsonFormatter with different output formats

Source: https://nhairs.github.io/python-json-logger/latest/quickstart

Examples of configuring the JsonFormatter using standard library format strings, comma-separated format, and a sequence of strings.

```python
# Standard library format
formatter = JsonFormatter("{message}{asctime}{exc_info}", style="{")

# Comma format
formatter = JsonFormatter("message,asctime,exc_info", style=",")

# Sequence of strings format
formatter = JsonFormatter(["message", "asctime", "exc_info"])

```

--------------------------------

### Basic JSON Logging Setup

Source: https://nhairs.github.io/python-json-logger/latest

Use this snippet to set up basic JSON logging with the `python-json-logger`. Ensure the `logging` and `pythonjsonlogger.json.JsonFormatter` are imported. The logger level should be set appropriately, and a `StreamHandler` should be configured with the `JsonFormatter`.

```python
import logging
from pythonjsonlogger.json import JsonFormatter

logger = logging.getLogger()
logger.setLevel(logging.INFO)

handler = logging.StreamHandler()
handler.setFormatter(JsonFormatter())

logger.addHandler(handler)

logger.info("Logging using python-json-logger!", extra={"more_data": True})
# {"message": "Logging using python-json-logger!", "more_data": true}
```

--------------------------------

### Logging Expensive Data with LazyString

Source: https://nhairs.github.io/python-json-logger/latest/cookbook

This example utilizes the `lazy-string` library's `LazyString` to defer the computation of log message data until it is actually needed, improving performance for expensive operations.

```python
## Log Using lazy-string
## -------------------------------------
from lazy_string import LazyString as L

start = time.time()
logger.info(
    {
        "data": L("hello {}".format, L(expensive_to_compute))
    }
)
print(f"Logging INFO using LazyString took: {int(time.time() - start)}s")

start = time.time()
logger.debug(
    {
        "data": L("hello {}".format, L(expensive_to_compute))
    }
)
print(f"Logging DEBUG using LazyString took: {int(time.time() - start)}s")

```

--------------------------------

### Logging Expensive Data with isEnabledFor

Source: https://nhairs.github.io/python-json-logger/latest/cookbook

This example demonstrates how to use `logger.isEnabledFor` to conditionally log messages, preventing the execution of expensive computations when the log level is not enabled.

```python
import logging
import time

from pythonjsonlogger.json import JsonFormatter

def expensive_to_compute():
    time.sleep(5)
    return "world"

## Setup
## -------------------------------------
logger = logging.getLogger()
handler = logging.StreamHandler()
formatter = JsonFormatter()
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.setLevel(logging.INFO)

## Log Using isEnabledFor
## -------------------------------------
start = time.time()
if logger.isEnabledFor(logging.INFO):
    logger.info(
        {
            "data": "hello {}".format(expensive_to_compute())
        }
    )
print(f"Logging INFO using isEnabledFor took: {int(time.time() - start)}s")

start = time.time()
if logger.isEnabledFor(logging.DEBUG):
    logger.debug(
        {
            "data": "hello {}".format(expensive_to_compute())
        }
    )
print(f"Logging DEBUG using isEnabledFor took: {int(time.time() - start)}s")

```

--------------------------------

### Integrate JsonFormatter with Python logging

Source: https://nhairs.github.io/python-json-logger/latest/quickstart

Attach the JsonFormatter to a logging handler to produce JSON output. This example uses the standard library 'json' module.

```python
import logging
from pythonjsonlogger.json import JsonFormatter

logger = logging.getLogger()

logHandler = logging.StreamHandler()
formatter = JsonFormatter()
logHandler.setFormatter(formatter)
logger.addHandler(logHandler)

```

--------------------------------

### Rename fields in JsonFormatter output

Source: https://nhairs.github.io/python-json-logger/latest/quickstart

Rename log fields using the 'rename_fields' argument. This example renames 'levelname' to 'LEVEL'.

```python
formatter = JsonFormatter(
    "{message}{levelname}",
    style="{",
    rename_fields={"levelname": "LEVEL"},
)

```

--------------------------------

### Preview documentation locally

Source: https://nhairs.github.io/python-json-logger/latest/contributing

Commands to serve documentation or preview the README file.

```bash
mkdocs serve
# For README preview (after installing grip):
# grip
```

--------------------------------

### Run code quality and test tools

Source: https://nhairs.github.io/python-json-logger/latest/contributing

Executes formatting, linting, type checking, and unit tests required before submission.

```bash
# Format
black src tests

# Lint
pylint --output-format=colorized src
mypy src tests

# Tests
pytest
```

--------------------------------

### Include all fields in JSON logs

Source: https://nhairs.github.io/python-json-logger/latest/cookbook

Ensure all standard library fields are included by setting reserved_attrs to an empty list.

```python
all_fields_formatter = JsonFormatter(reserved_attrs=[])
```

--------------------------------

### Define a function with Google-style docstrings

Source: https://nhairs.github.io/python-json-logger/latest/style-guide

Use this structure for all public functions to ensure compatibility with mkdocstrings. Include version markers for tracking changes.

```python
def my_function(param1: str, param2: int) -> bool:
    """Does something interesting.

    Args:
        param1: The first parameter, a string.
        param2: The second parameter, an integer.

    Returns:
        True if successful, False otherwise.

    Raises:
        ValueError: If param2 is negative.

    *New in 3.1*
    """
    # ... function logic ...
    return True # See 'Return Statements'
```

--------------------------------

### Format Exception Information

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/msgspec

Formats and returns exception information. Returns an array of strings if `exc_info_as_array` is set to True.

```python
formatException(ei) -> str | list[str]

```

--------------------------------

### Version-Specific Logic in Python

Source: https://nhairs.github.io/python-json-logger/latest/style-guide

Use sys.version_info to implement compatibility logic for different Python versions. This ensures code runs correctly across supported Python releases.

```python
if sys.version_info >= (3, 10):
    # Python 3.10+ specific code
else:
    # Code for older versions

```

--------------------------------

### Log Formatting and Serialization Methods

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/core

Methods for formatting log records, handling exceptions, and serializing log data to JSON.

```APIDOC
## format

### Description
Formats a log record and serializes it to JSON.

### Parameters
- **record** (LogRecord) - Required - The record to format.

## formatException

### Description
Format and return the specified exception information. If exc_info_as_array is set to True, this method returns an array of strings.

## formatStack

### Description
Format and return the specified stack information. If stack_info_as_array is set to True, this method returns an array of strings.

## jsonify_log_record

### Description
Convert the log data into a JSON string. Child classes MUST override this method.

### Parameters
- **log_data** (LogData) - Required - The data to serialize.

## parse

### Description
Parses format string looking for substitutions. This method is responsible for returning a list of fields (as strings) to include in all log messages.

### Returns
- **list[str]** - List of fields to be extracted and serialized.

## process_log_record

### Description
Custom processing of the data to be logged. Child classes can override this method to alter the log record before it is serialized.

### Parameters
- **log_data** (LogData) - Required - Incoming data.

## serialize_log_record

### Description
Returns the final representation of the data to be logged.

### Parameters
- **log_data** (LogData) - Required - The data.
```

--------------------------------

### BaseJsonFormatter Class Initialization

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/core

Constructor for the BaseJsonFormatter class, used to configure how log records are formatted and serialized.

```APIDOC
## BaseJsonFormatter Initialization

### Description
Initializes the base class for all formatters. This class should not be used directly.

### Parameters
- **fmt** (str | Sequence[str] | None) - Optional - String format or Sequence of field names to log.
- **datefmt** (str | None) - Optional - Format to use when formatting asctime field.
- **style** (str) - Optional - How to extract log fields from fmt.
- **validate** (bool) - Optional - Validate fmt against style.
- **prefix** (str) - Optional - String prefix added at the beginning of the formatted string.
- **rename_fields** (dict[str, str] | None) - Optional - Dict used to rename field names in the output.
- **rename_fields_keep_missing** (bool) - Optional - Include missing fields in the output when renaming.
- **static_fields** (dict[str, Any] | None) - Optional - Dict used to add fields with static values to all logs.
- **reserved_attrs** (Sequence[str] | None) - Optional - List of fields to skip when outputting json log record.
- **timestamp** (bool | str) - Optional - Add a timestamp to the json log record.
- **defaults** (dict[str, Any] | None) - Optional - Dictionary containing default fields.
- **exc_info_as_array** (bool) - Optional - Break exc_info into a list of lines.
- **stack_info_as_array** (bool) - Optional - Break stack_info into a list of lines.
```

--------------------------------

### unknown_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Backup default function for any object type, attempting str or repr.

```APIDOC
## unknown_default

### Description
Backup default function for any object type. Will attempt to use `str` or `repr`. If both functions error will return the string `"__could_not_encode__"`.

### Parameters
- **obj** (Any) - Required - object to handle
```

--------------------------------

### datetime_any

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Handles the serialization of various datetime-related instances.

```APIDOC
## datetime_any

### Description
Converts time, date, or datetime objects into a string format.

### Parameters
#### Arguments
- **obj** (time | date) - Required - The datetime-related object to handle.

### Response
- **str** - The string representation of the object.
```

--------------------------------

### Initialize BaseJsonFormatter

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/core

Constructor for BaseJsonFormatter. Use this class as a base for custom formatters. It supports various options for customizing log output, including field renaming, static fields, and timestamp inclusion.

```python
BaseJsonFormatter(
    fmt: str | Sequence[str] | None = None,
    datefmt: str | None = None,
    style: str = "%",
    validate: bool = True,
    *,
    prefix: str = "",
    rename_fields: dict[str, str] | None = None,
    rename_fields_keep_missing: bool = False,
    static_fields: dict[str, Any] | None = None,
    reserved_attrs: Sequence[str] | None = None,
    timestamp: bool | str = False,
    defaults: dict[str, Any] | None = None,
    exc_info_as_array: bool = False,
    stack_info_as_array: bool = False
)

```

--------------------------------

### Implement add_fields

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/orjson

Method to extract fields from a LogRecord; override this to implement custom field addition logic.

```python
add_fields(
    log_data: dict[str, Any],
    record: LogRecord,
    message_dict: dict[str, Any],
) -> None
```

--------------------------------

### Utility Function: package_is_available

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/utils

Documentation for the `package_is_available` function, which checks if a given Python package can be imported.

```APIDOC
## `package_is_available` 

### Description
Determine if the given package is available for import.

### Method
N/A (This is a function, not an API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Function Signature
```python
package_is_available(
    name: str,
    *, 
    throw_error: bool = False,
    extras_name: str | None = None
) -> bool
```

### Parameters
- **name** (str) - Required - Import name of the package to check.
- **throw_error** (bool) - Optional - Throw an error if the package is unavailable. Defaults to `False`.
- **extras_name** (str | None) - Optional - Extra dependency name to use in `throw_error`'s message. Defaults to `None`.

### Raises
- **MissingPackageError** - When `throw_error` is `True` and the package is unavailable.

### Returns
- **bool** - `True` if the package is available for import, `False` otherwise.
```

--------------------------------

### Initialize JsonFormatter

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/json

Constructor for the JsonFormatter class, which handles JSON serialization of log records.

```python
JsonFormatter(
    *args,
    json_default: Callable | None = None,
    json_encoder: Callable | None = None,
    json_serializer: Callable = dumps,
    json_indent: int | str | None = None,
    json_ensure_ascii: bool = True,
    **kwargs
)

```

--------------------------------

### use_datetime_any

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default check function for datetime related instances.

```APIDOC
## use_datetime_any

### Description
Default check function for `datetime` related instances.

### Parameters
- **obj** (Any) - Required
```

--------------------------------

### Format Stack Information

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/msgspec

Formats and returns stack information. Returns an array of strings if `stack_info_as_array` is set to True.

```python
formatStack(stack_info) -> str | list[str]

```

--------------------------------

### Log messages as dictionaries

Source: https://nhairs.github.io/python-json-logger/latest/quickstart

Log messages using a dictionary instead of a string. Ensure the 'message' key is included if you want it to appear in the output.

```python
logger.info({
    "my_data": 1,
    "message": "if you don't include this it will be an empty string",
    "other_stuff": False,
})

```

--------------------------------

### use_datetime_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default check function for datetime.datetime instances.

```APIDOC
## use_datetime_default

### Description
Default check function for `datetime.datetime` instances.

### Parameters
- **obj** (Any) - Required
```

--------------------------------

### Initialize OrjsonFormatter

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/orjson

Constructor for the OrjsonFormatter class, which uses orjson for efficient JSON encoding.

```python
OrjsonFormatter(
    *args,
    json_default: Callable | None = orjson_default,
    json_indent: bool = False,
    **kwargs
)
```

--------------------------------

### use_traceback_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default check function for tracebacks.

```APIDOC
## use_traceback_default

### Description
Default check function for tracebacks.

### Parameters
- **obj** (Any) - Required
```

--------------------------------

### pythonjsonlogger.jsonlogger Module

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/jsonlogger

Documentation for the pythonjsonlogger.jsonlogger module, which is retained for compatibility and sends deprecation warnings.

```APIDOC
## pythonjsonlogger.jsonlogger

### Description
Stub module retained for compatibility. It retains access to old names whilst sending deprecation warnings.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Python Configuration for JsonFormatter

Source: https://nhairs.github.io/python-json-logger/latest/cookbook

This Python script defines custom JSON formatting logic, including a default handler for non-serializable objects and static fields like project name, version, and environment.

```python
import importlib.metadata
import os


class Dummy:
    pass


def my_json_default(obj: Any) -> Any:
    if isinstance(obj, Dummy):
        return "DUMMY"
    return obj


def get_version_metadata():
    # https://stackoverflow.com/a/78082532
    version = importlib.metadata.version(PROJECT_NAME)
    return version


PROJECT_NAME = 'test-api'
PROJECT_VERSION = get_version_metadata()
ENVIRONMENT = os.environ.get('ENVIRONMENT', 'dev')

```

--------------------------------

### datetime_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default function for datetime.datetime instances.

```APIDOC
## datetime_default

### Description
Default function for `datetime.datetime` instances.

### Parameters
- **obj** (datetime) - Required - object to handle
```

--------------------------------

### use_exception_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default check function for exception instances.

```APIDOC
## use_exception_default

### Description
Default check function for exception instances. Exception classes are not treated specially and should be handled by the `[use_]type_default` functions.

### Parameters
- **obj** (Any) - Required
```

--------------------------------

### parse

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/json

Parses the format string to identify substitutions and determine fields for log messages.

```APIDOC
## parse

### Description
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.

### Method
(Implicitly a method within a class, not a standalone API endpoint)

### Endpoint
(Not applicable for this function)

### Parameters
(None)

### Request Example
(Not applicable for this function)

### Response
#### Success Response (200)
- **list[str]** - A list of fields to be extracted and serialized.

#### Response Example
```json
["asctime", "levelname", "message"]
```
```

--------------------------------

### Parse Format String

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/msgspec

Parses the format string to identify substitutions and returns a list of fields to be extracted and serialized.

```python
parse() -> list[str]

```

--------------------------------

### use_bytes_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default check function for bytes.

```APIDOC
## use_bytes_default

### Description
Default check function for bytes.

### Parameters
- **obj** (Any) - Required
```

--------------------------------

### Set static fields for JsonFormatter

Source: https://nhairs.github.io/python-json-logger/latest/quickstart

Add static fields that are included in every log record, regardless of other configurations.

```python
formatter = JsonFormatter(
    static_fields={"True gets logged on every record?": True}
)

```

--------------------------------

### time_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default function for datetime.time instances.

```APIDOC
## time_default

### Description
Default function for `datetime.time` instances.

### Parameters
- **obj** (time) - Required - object to handle
```

--------------------------------

### Implement custom log styles

Source: https://nhairs.github.io/python-json-logger/latest/cookbook

Support custom styles by setting validate=False and overriding the parse method in a JsonFormatter subclass.

```python
class CommaSupport(JsonFormatter):
    def parse(self) -> list[str]:
        if isinstance(self._style, str) and self._style == ",":
            return self._fmt.split(",")
        return super().parse()

formatter = CommaSupport("message,asctime", style=",", validate=False)
```

--------------------------------

### YAML Configuration for JsonFormatter

Source: https://nhairs.github.io/python-json-logger/latest/cookbook

This YAML configuration sets up logging with `pythonjsonlogger.json.JsonFormatter`, including custom field renaming and static fields loaded from external modules.

```yaml
version: 1
disable_existing_loggers: False
formatters:
  default:
    "()": pythonjsonlogger.json.JsonFormatter
    format: "% (asctime)s %(levelname)s %(name)s %(module)s %(funcName)s %(lineno)s %(message)s"
    json_default: ext://logging_config.my_json_default
    rename_fields:
      "asctime": "timestamp"
      "levelname": "status"
    static_fields:
      "service": ext://logging_config.PROJECT_NAME
      "env": ext://logging_config.ENVIRONMENT
      "version": ext://logging_config.PROJECT_VERSION
      "app_log": "true"
handlers:
  default:
    formatter: default
    class: logging.StreamHandler
    stream: ext://sys.stderr
  access:
    formatter: default
    class: logging.StreamHandler
    stream: ext://sys.stdout
loggers:
  uvicorn.error:
    level: INFO
    handlers:
      - default
    propagate: no
  uvicorn.access:
    level: INFO
    handlers:
      - access
    propagate: no

```

--------------------------------

### traceback_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default function for tracebacks.

```APIDOC
## traceback_default

### Description
Default function for tracebacks.

### Parameters
- **obj** (TracebackType) - Required - object to handle
```

--------------------------------

### use_date_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default check function for date instances.

```APIDOC
## use_date_default

### Description
Default check function for `datetime.date` instances.

### Parameters
- **obj** (Any) - Required
```

--------------------------------

### Datetime Any Default Serialization

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Handles various `datetime` related instances, including `time` and `date`, by converting them into a string representation. This function provides a unified way to log date and time information.

```python
datetime_any(obj: time | date | date) -> str:


```

--------------------------------

### Process log record

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/orjson

Allows custom modification of log data before serialization.

```python
process_log_record(log_data: LogData) -> LogData
```

--------------------------------

### use_time_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default check function for time instances.

```APIDOC
## use_time_default

### Description
Default check function for `datetime.time` instances.

### Parameters
- **obj** (Any) - Required
```

--------------------------------

### exception_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default function for exception instances.

```APIDOC
## exception_default

### Description
Default function for exception instances.

### Parameters
- **obj** (BaseException) - Required - object to handle
```

--------------------------------

### Parse format string

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/orjson

Parses the format string to identify fields for inclusion in log messages.

```python
parse() -> list[str]
```

--------------------------------

### pythonjsonlogger.core

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/core

Core functionality shared by all JSON loggers.

```APIDOC
## CLASS BaseJsonFormatter

### Description
Base class for all formatters

### Methods
- **add_fields**(self, log_record, message, class_name)
- **format**(self, record)
- **formatException**(self, exc_info)
- **formatStack**(self, stack_info)
- **jsonify_log_record**(self, log_record)
- **parse**(self, s)
- **process_log_record**(self, log_record)
- **serialize_log_record**(self, log_record)

## FUNCTION merge_record_extra

### Description
Merges extra attributes from LogRecord object into target dictionary.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
None

### Response
#### Success Response (200)
- None

#### Response Example
None

## ATTRIBUTE LogData

### Description
Type alias for log data.

### Type
TypeAlias

### Details
_Changed in 4.0_ : renamed from `LogRecord` to `LogData`

## ATTRIBUTE RESERVED_ATTRS

### Description
Default reserved attributes.

### Type
list[str]

### Details
These come from the default attributes of `LogRecord` objects.
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, ...]`.
```

--------------------------------

### date_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Handles the serialization of datetime.date instances.

```APIDOC
## date_default

### Description
Converts datetime.date instances into a string format.

### Parameters
#### Arguments
- **obj** (date) - Required - The date object to handle.

### Response
- **str** - The string representation of the date.
```

--------------------------------

### Format log record

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/orjson

Formats a log record and serializes it to a JSON string.

```python
format(record: LogRecord) -> str
```

--------------------------------

### Exception Classes

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/exception

Documentation for the exception classes within the pythonjsonlogger.exception module.

```APIDOC
## `pythonjsonlogger.exception`

### Description
This module contains custom exception classes for the Python JSON Logger.

### Exception Classes

#### `MissingPackageError`

##### Description
A required package is missing.

##### Bases
`ImportError`, `PythonJsonLoggerError`

##### Usage
```python
MissingPackageError(name: str, extras_name: str | None = None)
```

#### `PythonJsonLoggerError`

##### Description
Generic base class for all Python JSON Logger exceptions.

##### Bases
`Exception`

```

--------------------------------

### Python JSON Logger Modules

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger

Overview of the core modules within the Python JSON Logger library.

```APIDOC
## Python JSON Logger Modules

### Description
This section provides a list of the primary modules available in the `pythonjsonlogger` library and a brief description of their functionality.

### Modules

- **`core`**: Core functionality shared by all JSON loggers.
- **`defaults`**: Collection of functions for building custom `json_default` functions.
- **`exception`**: Handles exception formatting.
- **`json`**: JSON formatter using the standard library's `json` for encoding.
- **`jsonlogger`**: Stub module retained for compatibility.
- **`msgspec`**: JSON Formatter using `msgspec`.
- **`orjson`**: JSON Formatter using `orjson`.
- **`utils`**: Utilities for Python JSON Logger.
```

--------------------------------

### Serialize log record

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/orjson

Returns the final serialized string representation of the log data.

```python
serialize_log_record(log_data: LogData) -> str
```

--------------------------------

### MissingPackageError Constructor

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/exception

Represents an error when a required package is not found. It inherits from ImportError and PythonJsonLoggerError.

```python
MissingPackageError(
    name: str, extras_name: str | None = None
)

```

--------------------------------

### dataclass_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Handles the serialization of dataclass instances.

```APIDOC
## dataclass_default

### Description
Converts dataclass instances into a dictionary representation.

### Parameters
#### Arguments
- **obj** (Any) - Required - The dataclass instance to handle.

### Response
- **dict[str, Any]** - The dictionary representation of the dataclass.
```

--------------------------------

### use_dataclass_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default check function for dataclass instances.

```APIDOC
## use_dataclass_default

### Description
Default check function for dataclass instances.

### Parameters
- **obj** (Any) - Required
```

--------------------------------

### add_fields Method

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/core

Extracts fields from a LogRecord for logging purposes.

```APIDOC
## add_fields

### Description
Extracts fields from a LogRecord for logging. This method can be overridden to implement custom logic for adding fields.

### Parameters
- **log_data** (dict[str, Any]) - Required - Data that will be logged.
- **record** (LogRecord) - Required - The record to extract data from.
- **message_dict** (dict[str, Any]) - Required - Dictionary that was logged instead of a message.
```

--------------------------------

### Format datetime objects

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/json

Method signature for formatting datetime objects within the custom encoder.

```python
format_datetime_obj(o: time | date | datetime) -> str

```

--------------------------------

### process_log_record

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/json

Allows for custom processing of log data before it is serialized.

```APIDOC
## process_log_record

### Description
Custom processing of the data to be logged. Child classes can override this method to alter the log record before it is serialized.

### Method
(Implicitly a method within a class, not a standalone API endpoint)

### Endpoint
(Not applicable for this function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
- **log_data** (LogData) - Required - Incoming log data to be processed. (Renamed from `log_record` in version 4.0)

### Request Example
(Not applicable for this function)

### Response
#### Success Response (200)
- **LogData** - The processed log data.

#### Response Example
```json
{
  "message": "Processed log entry",
  "timestamp": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Check Package Availability

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/utils

Use this function to check if a package can be imported. Set `throw_error` to `True` to raise a `MissingPackageError` if the package is not found.

```python
package_is_available(
    name: str,
    *, 
    throw_error: bool = False,
    extras_name: str | None = None
) -> bool


```

--------------------------------

### Set default fields for JsonFormatter

Source: https://nhairs.github.io/python-json-logger/latest/quickstart

Configure default fields that are added to every log record. These can be overridden by fields provided in the log message or 'extra' argument.

```python
formatter = JsonFormatter(
    defaults={"environment": "dev"}
)
# ...
logger.info("this message will have environment=dev by default")
logger.info("this overwrites the environment field", extra={"environment": "prod"})

```

--------------------------------

### use_enum_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default check function for enums.

```APIDOC
## use_enum_default

### Description
Default check function for enums. Supports both enum classes and enum values.

### Parameters
- **obj** (Any) - Required
```

--------------------------------

### Format Log Record to JSON

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/msgspec

Formats a log record and serializes it to a JSON string using the msgspec encoder.

```python
format(record: LogRecord) -> str

```

--------------------------------

### Inject request IDs via custom formatter

Source: https://nhairs.github.io/python-json-logger/latest/cookbook

Override process_log_record in a custom formatter to inject fields without modifying the original LogRecord.

```python
## Solution 3
## -----------------------------------------------------------------------------
# Reuse REQUEST_ID stuff from solution 2
class MyFormatter(JsonFormatter):
    def process_log_record(self, log_data):
        log_data["request_id"] = get_request_id()
        return log_data

handler.setFormatter(MyFormatter())

def main_3():
    print("========== MAIN 3 ==========")
    for i in range(3):
        generate_request_id()
        logger.info("loop start")
        logger.info(f"loop {i}")
        logger.info("loop end")
    return

main_3()
```

--------------------------------

### Serialize Log Record

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/msgspec

Returns the final string representation of the log data to be logged. The `log_record` parameter was renamed to `log_data` in version 4.0.

```python
serialize_log_record(log_data: LogData) -> str

```

--------------------------------

### use_uuid_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default check function for UUID instances.

```APIDOC
## use_uuid_default

### Description
Default check function for `uuid.UUID` instances.

### Parameters
- **obj** (Any) - Required
```

--------------------------------

### jsonify_log_record

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/msgspec

Returns a JSON string representation of the log data.

```python
jsonify_log_record(log_data: LogData) -> str

```

--------------------------------

### serialize_log_record

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/json

Generates the final string representation of the log data.

```APIDOC
## serialize_log_record

### Description
Returns the final representation of the data to be logged.

### Method
(Implicitly a method within a class, not a standalone API endpoint)

### Endpoint
(Not applicable for this function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
- **log_data** (LogData) - Required - The log data to be serialized. (Renamed from `log_record` in version 4.0)

### Request Example
(Not applicable for this function)

### Response
#### Success Response (200)
- **str** - The serialized string representation of the log data.

#### Response Example
```json
{
  "level": "INFO",
  "message": "Application started"
}
```
```

--------------------------------

### type_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default function for type objects.

```APIDOC
## type_default

### Description
Default function for `type` objects.

### Parameters
- **obj** (type) - Required - object to handle
```

--------------------------------

### Initialize MsgspecFormatter

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/msgspec

Initialize the MsgspecFormatter with an optional custom default encoder function for non-standard types. See BaseJsonFormatter for other parameters.

```python
MsgspecFormatter(
    *args,
    json_default: Callable | None = msgspec_default,
    **kwargs
)

```

--------------------------------

### bytes_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Handles the serialization of bytes or bytearray objects into base64 strings.

```APIDOC
## bytes_default

### Description
Converts bytes or bytearray objects into a base64 encoded string.

### Parameters
#### Arguments
- **obj** (bytes | bytearray) - Required - The object to handle.
- **url_safe** (bool) - Optional - Whether to use URL safe base64 character set. Default: True.

### Response
- **str** - The byte data as a base64 string.
```

--------------------------------

### Bytes Default Serialization

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Handles bytes and bytearray objects by encoding them as a base64 string. Use `url_safe=True` for URL-safe characters.

```python
bytes_default(
    obj: bytes | bytearray, url_safe: bool = True
) -> str:


```

--------------------------------

### Convert log record to JSON

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/orjson

Returns a JSON string representation of the provided log data.

```python
jsonify_log_record(log_data: LogData) -> str
```

--------------------------------

### Add extra fields to log messages

Source: https://nhairs.github.io/python-json-logger/latest/quickstart

Include additional fields in log messages using the 'extra' argument. This logs the same additional fields as logging a dictionary directly.

```python
logger.info(
    "this logs the same additional fields as above",
    extra={
        "my_data": 1,
        "other_stuff": False,
    },
)

```

--------------------------------

### uuid_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default function for UUID instances, formatting using hyphen format.

```APIDOC
## uuid_default

### Description
Default function for `uuid.UUID` instances. Formats the UUID using "hyphen" format.

### Parameters
- **obj** (UUID) - Required - object to handle
```

--------------------------------

### Inject request IDs via logging filter

Source: https://nhairs.github.io/python-json-logger/latest/cookbook

Use a custom logging filter to add request IDs to the LogRecord attributes automatically.

```python
## Solution 2
## -----------------------------------------------------------------------------
REQUEST_ID: str | None = None

def get_request_id() -> str:
    return REQUEST_ID

def generate_request_id():
    global REQUEST_ID
    REQUEST_ID = str(uuid.uuid4())

class RequestIdFilter(logging.Filter):
    def filter(self, record):
        record.request_id = get_request_id() # Add request_id to the LogRecord
        return True

request_id_filter = RequestIdFilter()
logger.addFilter(request_id_filter)

def main_2():
    print("========== MAIN 2 ==========")
    for i in range(3):
        generate_request_id()
        logger.info("loop start")
        logger.info(f"loop {i}")
        logger.info("loop end")
    return

main_2()

logger.removeFilter(request_id_filter)
```

--------------------------------

### Explicit Return Statement in Python Functions

Source: https://nhairs.github.io/python-json-logger/latest/style-guide

All functions and methods must have an explicit return statement. If a function does not logically return a value, use 'return None' or 'return' to maintain clarity and consistency.

```python
def process_data(data: dict) -> None:
    """Processes the given data."""
    # ... processing logic ...
    print(data)
    return # or return None

```

--------------------------------

### JsonFormatter API

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/json

Details the JsonFormatter class, which provides JSON formatting for log records using the standard library's json module.

```APIDOC
## JsonFormatter

### Description
JSON formatter using the standard library's `json` for encoding.

### Constructor
```python
JsonFormatter(
    *args,
    json_default: Callable | None = None,
    json_encoder: Callable | None = None,
    json_serializer: Callable = dumps,
    json_indent: int | str | None = None,
    json_ensure_ascii: bool = True,
    **kwargs
)
```

### Parameters
- **args** (see BaseJsonFormatter) - DEFAULT: `()`
- **json_default** (Callable | None) - a function for encoding non-standard objects. DEFAULT: `None`
- **json_encoder** (Callable | None) - custom JSON encoder. DEFAULT: `None`
- **json_serializer** (Callable) - a `json.dumps`-compatible callable that will be used to serialize the log record. DEFAULT: `dumps`
- **json_indent** (int | str | None) - indent parameter for the `json_serializer`. DEFAULT: `None`
- **json_ensure_ascii** (bool) - `ensure_ascii` parameter for the `json_serializer`. DEFAULT: `True`
- **kwargs** (see BaseJsonFormatter) - DEFAULT: `{}`

### Methods
#### add_fields
```python
add_fields(log_data: dict[str, Any], record: LogRecord, message_dict: dict[str, Any]) -> None
```

**Description:** Extract fields from a LogRecord for logging. This method can be overridden to implement custom logic for adding fields.

**Parameters:**
- **log_data** (dict[str, Any]) - data that will be logged.
- **record** (LogRecord) - the record to extract data from.
- **message_dict** (dict[str, Any]) - dictionary that was logged instead of a message. e.g `logger.info({"is_this_message_dict": True})`.
_Changed in 4.0_ : `log_record` renamed to `log_data`

#### format
```python
format(record: LogRecord) -> str
```

**Description:** Formats a log record and serializes to json.

**Parameters:**
- **record** (LogRecord) - the record to format.

#### formatException
```python
formatException(ei) -> str | list[str]
```

**Description:** Format and return the specified exception information. If exc_info_as_array is set to True, This method returns an array of strings.

#### formatStack
```python
formatStack(stack_info) -> str | list[str]
```

**Description:** Format and return the specified stack information. If stack_info_as_array is set to True, This method returns an array of strings.

#### jsonify_log_record
```python
jsonify_log_record() -> str
```

**Description:** Returns a json string of the log data.

#### parse
```python
parse() -> None
```

**Description:** Parses format string looking for substitutions.

#### process_log_record
```python
process_log_record(log_record: dict[str, Any]) -> dict[str, Any]
```

**Description:** Custom processing of the data to be logged.

**Parameters:**
- **log_record** (dict[str, Any]) - the data to process.

#### serialize_log_record
```python
serialize_log_record(log_record: dict[str, Any]) -> str
```

**Description:** Returns the final representation of the data to be logged.

**Parameters:**
- **log_record** (dict[str, Any]) - the data to serialize.
```

--------------------------------

### Inject request IDs via extra argument

Source: https://nhairs.github.io/python-json-logger/latest/cookbook

Pass request IDs explicitly to each log call using the extra parameter.

```python
## Solution 1
## -----------------------------------------------------------------------------
formatter = JsonFormatter()
handler.setFormatter(formatter)

def main_1():
    print("========== MAIN 1 ==========")
    for i in range(3):
        request_id = uuid.uuid4()
        logger.info("loop start", extra={"request_id": request_id})
        logger.info(f"loop {i}", extra={"request_id": request_id})
        logger.info("loop end", extra={"request_id": request_id})
    return

main_1()
```

--------------------------------

### orjson_default Function

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/orjson

Documentation for the orjson_default encoder function used for non-standard types.

```APIDOC
## orjson_default

### Description
orjson default encoder function for non-standard types.

### Parameters
- **obj** (Any) - Required - The object to be encoded.
```

--------------------------------

### use_type_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default check function for type objects (classes).

```APIDOC
## use_type_default

### Description
Default check function for `type` objects (aka classes).

### Parameters
- **obj** (Any) - Required
```

--------------------------------

### Define RESERVED_ATTRS list

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/core

Lists the default reserved attributes derived from Python LogRecord objects.

```python
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",
]

```

--------------------------------

### Custom object serialization with JsonFormatter

Source: https://nhairs.github.io/python-json-logger/latest/quickstart

Define a custom function for serializing objects that the default JSON encoder cannot handle. The custom function should handle specific types and can call the original default serializer.

```python
def my_default(obj):
    if isinstance(obj, MyClass):
        return {"special": obj.special}

formatter = JsonFormatter(json_default=my_default)

```

--------------------------------

### Date Default Serialization

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Serializes `datetime.date` objects into a string format. This is useful for ensuring dates are consistently represented in JSON logs.

```python
date_default(obj: date) -> str:


```

--------------------------------

### jsonify_log_record

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/json

Converts log data into a JSON string representation.

```APIDOC
## jsonify_log_record

### Description
Returns a json string of the log data.

### Method
(Implicitly a method within a class, not a standalone API endpoint)

### Endpoint
(Not applicable for this function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
- **log_data** (LogData) - Required - The data structure containing log information.

### Request Example
(Not applicable for this function)

### Response
#### Success Response (200)
- **str** - A JSON string representing the log data.

#### Response Example
```json
{
  "message": "Log entry processed successfully"
}
```
```

--------------------------------

### Add Fields to Log Data

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/msgspec

Override this method to implement custom logic for adding fields to the log data. The `log_data` parameter was renamed from `log_record` in version 4.0.

```python
add_fields(
    log_data: dict[str, Any],
    record: LogRecord,
    message_dict: dict[str, Any],
) -> None

```

--------------------------------

### Process Log Record

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/msgspec

Allows for custom processing of log data before serialization. Child classes can override this method to alter the log record. The `log_record` parameter was renamed to `log_data` in version 4.0.

```python
process_log_record(log_data: LogData) -> LogData

```

--------------------------------

### Define LogData type alias

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/core

Represents the type alias for log data dictionaries.

```python
LogData: TypeAlias = dict[str, Any]

```

--------------------------------

### OrjsonFormatter Class

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/orjson

The OrjsonFormatter class provides a JSON formatter that utilizes the orjson library for encoding log records.

```APIDOC
## OrjsonFormatter

### Description
JSON formatter using orjson for encoding.

### Class Signature
```python
OrjsonFormatter(
    *args,
    json_default: Callable | None = orjson_default,
    json_indent: bool = False,
    **kwargs
)
```

### Parameters
- `args`: see BaseJsonFormatter
- `json_default` (Callable | None): a function for encoding non-standard objects. Defaults to `orjson_default`.
- `json_indent` (bool): indent output with 2 spaces. Defaults to `False`.
- `kwargs`: see BaseJsonFormatter

### Methods
- `add_fields(log_data: dict[str, Any], record: 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.
- `format(record: LogRecord) -> str`: Formats a log record and serializes to json.
- `formatException(ei) -> str | list[str]`: Format and return the specified exception information. If `exc_info_as_array` is set to True, this method returns an array of strings.
- `formatStack(stack_info) -> str | list[str]`: Format and return the specified stack information. If `stack_info_as_array` is set to True, this method returns an array of strings.
- `jsonify_log_record(log_data: LogData) -> str`: Returns a json string of the log data.
- `parse() -> 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.
- `process_log_record(log_data: LogData) -> LogData`: Custom processing of the data to be logged. Child classes can override this method to alter the log record before it is serialized.
- `serialize_log_record(log_data: LogData) -> str`: Returns the final representation of the data to be logged.
```

--------------------------------

### enum_default

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Default function for enums, supporting both enum classes and enum values.

```APIDOC
## enum_default

### Description
Default function for enums. Supports both enum classes and enum values.

### Parameters
- **obj** (Enum | EnumMeta) - Required - object to handle
```

--------------------------------

### Modify logged data before serialization

Source: https://nhairs.github.io/python-json-logger/latest/cookbook

Override process_log_record to transform the log data dictionary before it is converted to JSON.

```python
class SillyFormatter(JsonFormatter):
    def process_log_record(self, log_data):
        new_record = {k[::-1]: v for k, v in log_data.items()}
        return new_record
```

--------------------------------

### Dataclass Default Serialization

Source: https://nhairs.github.io/python-json-logger/latest/reference/pythonjsonlogger/defaults

Serializes dataclass instances into a dictionary. This function is used by the logger to convert dataclass objects into a JSON-serializable format.

```python
dataclass_default(obj) -> dict[str, Any]:


```