Skip to content

Commit 42107cd

Browse files
nhairsnhairs
authored
Move documentation to mkdocs (#14)
This pull request moves the existing documentation to `mkdocs` for generation. This includes setting links for use with GitHub Pages. ## Test Plan View the docs locally using `mkdocs serve`.
1 parent 1160ae8 commit 42107cd

18 files changed

+840
-265
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,6 @@ env
1616
# IDE
1717
.vscode
1818
.idea
19+
20+
# generated docs
21+
site

‎NOTICE

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
This software includes the following licenced software:
2+
- mkdocstrings-python
3+
Copyright (c) 2021, Timothée Mazzucotelli
4+
Licenced under ISC Licence
5+
Source: https://github.com/mkdocstrings/python

‎README.md

Lines changed: 13 additions & 202 deletions
Original file line numberDiff line numberDiff line change
@@ -1,215 +1,26 @@
1+
<!-- [![PyPi](https://img.shields.io/pypi/v/python-json-logger.svg)](https://pypi.python.org/pypi/python-json-logger/)
2+
[![PyPI - Status](https://img.shields.io/pypi/status/python-json-logger)](https://pypi.python.org/pypi/python-json-logger/)
3+
[![Python Versions](https://img.shields.io/pypi/pyversions/python-json-logger.svg)](https://github.com/nhairs/python-json-logger) -->
4+
[![License](https://img.shields.io/github/license/nhairs/python-json-logger.svg)](https://github.com/nhairs/python-json-logger)
15
![Build Status](https://github.com/nhairs/python-json-logger/actions/workflows/test-suite.yml/badge.svg)
2-
[![License](https://img.shields.io/pypi/l/python-json-logger.svg)](https://pypi.python.org/pypi/python-json-logger/)
3-
[![Version](https://img.shields.io/pypi/v/python-json-logger.svg)](https://pypi.python.org/pypi/python-json-logger/)
4-
6+
#
57
# Python JSON Logger
68

7-
This library is provided to allow standard python logging to output log data as json objects. With JSON we can make our logs more readable by machines and we can stop writing custom parsers for syslog type records.
9+
Python JSON Logger enables you produce JSON logs when using Python's `logging` package.
10+
11+
JSON logs are machine readable allowing for much easier parsing and ingestion into log aggregation tools.
812

913

1014
### 🚨 Important 🚨
1115

1216
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).
1317

14-
[**Changelog**](https://github.com/nhairs/python-json-logger/blob/main/CHANGELOG.md)
15-
16-
## Installation
17-
18-
Note: All versions of this fork use version `>=3.0.0` - to use pre-fork versions use `python-json-logger<3.0.0`.
19-
20-
### Install via pip
21-
22-
Until the PEP 541 request is complete you will need to install directly from github.
23-
24-
#### Install from GitHub
25-
26-
To install from releases:
27-
28-
```shell
29-
# e.g. 3.0.0 wheel
30-
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'
31-
```
32-
33-
To install from head:
34-
35-
```shell
36-
pip install 'python-json-logger@git+https://github.com/nhairs/python-json-logger.git'
37-
```
38-
39-
To install a specific version from a tag:
40-
41-
```shell
42-
# Last released version before forking
43-
pip install 'python-json-logger@git+https://github.com/nhairs/python-json-logger.git@v2.0.7'
44-
```
45-
46-
#### Install from Source
47-
48-
```shell
49-
git clone https://github.com/nhairs/python-json-logger.git
50-
cd python-json-logger
51-
pip install -e .
52-
```
53-
54-
## Usage
55-
56-
Python JSON Logger provides `logging.Formatter`s that encode the logged message into JSON. Although a variety of JSON encoders are supported, in the following examples we will use the `pythonjsonlogger.json.JsonFormatter` which uses the the `json` module from the standard library.
57-
58-
### Integrating with Python's logging framework
59-
60-
To produce JSON output, attach the formatter to a logging handler:
61-
62-
```python
63-
import logging
64-
from pythonjsonlogger.json import JsonFormatter
65-
66-
logger = logging.getLogger()
67-
68-
logHandler = logging.StreamHandler()
69-
formatter = JsonFormatter()
70-
logHandler.setFormatter(formatter)
71-
logger.addHandler(logHandler)
72-
```
73-
74-
### Output fields
75-
76-
You can control the logged fields by setting the `fmt` argument when creating the formatter. By default formatters will follow the same `style` of `fmt` as the `logging` module: `%`, `$`, and `{`. All [`LogRecord` attributes](https://docs.python.org/3/library/logging.html#logrecord-attributes) can be output using their name.
77-
78-
```python
79-
formatter = JsonFormatter("{message}{asctime}{exc_info}", style="{")
80-
```
81-
82-
You can also add extra fields to your json output by specifying a dict in place of message, as well as by specifying an `extra={}` argument.
83-
84-
Contents of these dictionaries will be added at the root level of the entry and may override basic fields.
85-
86-
You can also use the `add_fields` method to add to or generally normalize the set of default set of fields, it is called for every log event. For example, to unify default fields with those provided by [structlog](http://www.structlog.org/) you could do something like this:
87-
88-
```python
89-
class CustomJsonFormatter(JsonFormatter):
90-
def add_fields(self, log_record, record, message_dict):
91-
super().add_fields(log_record, record, message_dict)
92-
if not log_record.get('timestamp'):
93-
# this doesn't use record.created, so it is slightly off
94-
now = datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%S.%fZ')
95-
log_record['timestamp'] = now
96-
if log_record.get('level'):
97-
log_record['level'] = log_record['level'].upper()
98-
else:
99-
log_record['level'] = record.levelname
100-
return
101-
102-
formatter = CustomJsonFormatter('%(timestamp)s %(level)s %(name)s %(message)s')
103-
```
104-
105-
Items added to the log record will be included in *every* log message, no matter what the format requires.
106-
107-
You can also override the `process_log_record` method to modify fields before they are serialized to JSON.
108-
109-
```python
110-
class SillyFormatter(JsonFormatter):
111-
def process_log_record(log_record):
112-
new_record = {k[::-1]: v for k, v in log_record.items()}
113-
return new_record
114-
```
115-
116-
#### Supporting custom styles
117-
118-
It is possible to support custom `style`s by setting `validate=False` and overriding the `parse` method.
119-
120-
For example:
121-
122-
```python
123-
class CommaSupport(JsonFormatter):
124-
def parse(self) -> list[str]:
125-
if isinstance(self._style, str) and self._style == ",":
126-
return self._fmt.split(",")
127-
return super().parse()
128-
129-
formatter = CommaSupport("message,asctime", style=",", validate=False)
130-
```
131-
132-
### Custom object serialization
133-
134-
Most formatters support `json_default` which is used to control how objects are serialized.
135-
136-
For custom handling of object serialization you can specify default json object translator or provide a custom encoder
137-
138-
```python
139-
def my_default(obj):
140-
if isinstance(obj, MyClass):
141-
return {"special": obj.special}
142-
143-
formatter = JsonFormatter(json_default=my_default)
144-
```
145-
146-
### Using a Config File
147-
148-
To use the module with a config file using the [`fileConfig` function](https://docs.python.org/3/library/logging.config.html#logging.config.fileConfig), use the class `pythonjsonlogger.json.JsonFormatter`. Here is a sample config file.
149-
150-
```ini
151-
[loggers]
152-
keys = root,custom
153-
154-
[logger_root]
155-
handlers =
156-
157-
[logger_custom]
158-
level = INFO
159-
handlers = custom
160-
qualname = custom
161-
162-
[handlers]
163-
keys = custom
164-
165-
[handler_custom]
166-
class = StreamHandler
167-
level = INFO
168-
formatter = json
169-
args = (sys.stdout,)
170-
171-
[formatters]
172-
keys = json
173-
174-
[formatter_json]
175-
format = %(message)s
176-
class = pythonjsonlogger.jsonlogger.JsonFormatter
177-
```
178-
179-
### Alternate JSON Encoders
180-
181-
The following JSON encoders are also supported:
182-
183-
- [orjson](https://github.com/ijl/orjson) - `pythonjsonlogger.orjon.OrjsonFormatter`
184-
- [msgspec](https://github.com/jcrist/msgspec) - `pythonjsonlogger.msgspec.MsgspecFormatter`
185-
186-
## Example Output
187-
188-
Sample JSON with a full formatter (basically the log message from the unit test). Every log message will appear on 1 line like a typical logger.
18+
## Documentation
18919

190-
```json
191-
{
192-
"threadName": "MainThread",
193-
"name": "root",
194-
"thread": 140735202359648,
195-
"created": 1336281068.506248,
196-
"process": 41937,
197-
"processName": "MainProcess",
198-
"relativeCreated": 9.100914001464844,
199-
"module": "tests",
200-
"funcName": "testFormatKeys",
201-
"levelno": 20,
202-
"msecs": 506.24799728393555,
203-
"pathname": "tests/tests.py",
204-
"lineno": 60,
205-
"asctime": "12-05-05 22:11:08,506248",
206-
"message": "testing logging format",
207-
"filename": "tests.py",
208-
"levelname": "INFO",
209-
"special": "value",
210-
"run": 12
211-
}
212-
```
20+
- [Documentation](https://nhairs.github.io/python-json-logger/latest/)
21+
- [Quickstart Guide](https://nhairs.github.io/python-json-logger/latest/quickstart/)
22+
- [Change Log](https://nhairs.github.io/python-json-logger/latest/changelog/)
23+
- [Contributing](https://nhairs.github.io/python-json-logger/latest/contributing/)
21324

21425
## License
21526

‎SECURITY.md

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎SECURITY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs/security.md

‎CHANGELOG.md renamed to ‎docs/changelog.md

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Changelog
1+
# Change Log
22
All notable changes to this project will be documented in this file.
33

44
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
@@ -9,16 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99
This splits common funcitonality out to allow supporting other JSON encoders. Although this is a large refactor, backwards compatibility has been maintained.
1010

1111
### Added
12-
- `.core` - more details below.
13-
- `.defaults` module that provides many functions for handling unsupported types.
14-
- Orjson encoder support via `.orjson.OrjsonFormatter` with the following additions:
12+
- `pythonjsonlogger.core` - more details below.
13+
- `pythonjsonlogger.defaults` module that provides many functions for handling unsupported types.
14+
- Orjson encoder support via `pythonjsonlogger.orjson.OrjsonFormatter` with the following additions:
1515
- bytes are URL safe base64 encoded.
1616
- Exceptions are "pretty printed" using the exception name and message e.g. `"ValueError: bad value passed"`
1717
- Enum values use their value, Enum classes now return all values as a list.
1818
- Tracebacks are supported
1919
- Classes (aka types) are support
2020
- Will fallback on `__str__` if available, else `__repr__` if available, else will use `__could_not_encode__`
21-
- MsgSpec encoder support via `.msgspec.MsgspecFormatter` with the following additions:
21+
- MsgSpec encoder support via `pythonjsonlogger.msgspec.MsgspecFormatter` with the following additions:
2222
- Exceptions are "pretty printed" using the exception name and message e.g. `"ValueError: bad value passed"`
2323
- Enum classes now return all values as a list.
2424
- Tracebacks are supported
@@ -27,39 +27,44 @@ This splits common funcitonality out to allow supporting other JSON encoders. Al
2727
- Note: msgspec only supprts enum values of type `int` or `str` [jcrist/msgspec#680](https://github.com/jcrist/msgspec/issues/680)
2828

2929
### Changed
30-
- `.jsonlogger` has been moved to `.json` with core functionality moved to `.core`.
31-
- `.core.BaseJsonFormatter` properly supports all `logging.Formatter` arguments:
30+
- `pythonjsonlogger.jsonlogger` has been moved to `pythonjsonlogger.json` with core functionality moved to `pythonjsonlogger.core`.
31+
- `pythonjsonlogger.core.BaseJsonFormatter` properly supports all `logging.Formatter` arguments:
3232
- `fmt` is unchanged.
3333
- `datefmt` is unchanged.
3434
- `style` can now support non-standard arguments by setting `validate` to `False`
3535
- `validate` allows non-standard `style` arguments or prevents calling `validate` on standard `style` arguments.
3636
- `default` is ignored.
37-
- `.json.JsonEncoder` default encodings changed:
37+
- `pythonjsonlogger.json.JsonFormatter` default encodings changed:
3838
- bytes are URL safe base64 encoded.
3939
- Exception formatting detected using `BaseException` instead of `Exception`. Now "pretty prints" the exception using the exception name and message e.g. `"ValueError: bad value passed"`
4040
- Dataclasses are now supported
4141
- Enum values now use their value, Enum classes now return all values as a list.
4242
- Will fallback on `__str__` if available, else `__repr__` if available, else will use `__could_not_encode__`
43-
- Renaming fields now preserves order (#7) and ignores missing fields (#6).
43+
- Renaming fields now preserves order ([#7](https://github.com/nhairs/python-json-logger/issues/7)) and ignores missing fields ([#6](https://github.com/nhairs/python-json-logger/issues/6)).
44+
- Documentation
45+
- Generated documentation using `mkdocs` is stored in `docs/`
46+
- Documentation within `README.md` has been moved to `docs/index.md` and `docs/qucikstart.md`.
47+
- `CHANGELOG.md` has been moved to `docs/change-log.md`
48+
- `SECURITY.md` has been moved and replaced with a symbolic link to `docs/security.md`.
4449

4550
### Deprecated
46-
- `.jsonlogger` is now `.json`
47-
- `.jsonlogger.RESERVED_ATTRS` is now `.core.RESERVED_ATTRS`.
48-
- `.jsonlogger.merge_record_extra` is now `.core.merge_record_extra`.
51+
- `pythonjsonlogger.jsonlogger` is now `pythonjsonlogger.json`
52+
- `pythonjsonlogger.jsonlogger.RESERVED_ATTRS` is now `pythonjsonlogger.core.RESERVED_ATTRS`.
53+
- `pythonjsonlogger.jsonlogger.merge_record_extra` is now `pythonjsonlogger.core.merge_record_extra`.
4954

5055
### Removed
5156
- Python 3.7 support dropped
52-
- `.jsonlogger.JsonFormatter._str_to_fn` replaced with `.core.str_to_object`.
57+
- `pythonjsonlogger.jsonlogger.JsonFormatter._str_to_fn` replaced with `pythonjsonlogger.core.str_to_object`.
5358

5459
## [3.0.1](https://github.com/nhairs/python-json-logger/compare/v3.0.0...v3.0.1) - 2023-04-01
5560

5661
### Fixes
5762

58-
- Fix spelling of parameter `json_serialiser` -> `json_serializer` (#8) - @juliangilbey
63+
- Fix spelling of parameter `json_serialiser` -> `json_serializer` ([#8](https://github.com/nhairs/python-json-logger/issues/8)) - @juliangilbey
5964

6065
## [3.0.0](https://github.com/nhairs/python-json-logger/compare/v2.0.7...v3.0.0) - 2024-03-25
6166

62-
Note: using new major version to seperate changes from this fork and the original (upstream). See #1 for details.
67+
Note: using new major version to seperate changes from this fork and the original (upstream). See [#1](https://github.com/nhairs/python-json-logger/issues/1) for details.
6368

6469
### Changes
6570
- Update supported Python versions - @nhairs

0 commit comments

Comments
 (0)