aa-toolkit-log 0.1.0a1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Aaron Aco
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,128 @@
1
+ Metadata-Version: 2.4
2
+ Name: aa-toolkit-log
3
+ Version: 0.1.0a1
4
+ Summary: Ready-made logging for apps, on top of Python's logging.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.14
8
+ Description-Content-Type: text/markdown
9
+
10
+ # aa-toolkit-log
11
+
12
+ Ready-made logging for apps, on top of Python's built-in logging. It has no dependencies.
13
+
14
+ An app gets clean, lined-up columns in a terminal and JSON lines when a tool or an agent runs it, and it can save its logs to a file that can't fill the disk.
15
+
16
+ ## Install
17
+
18
+ Install it from the toolkit's GitHub repo, pinned to a version tag:
19
+
20
+ ```bash
21
+ uv add "aa-toolkit-log @ git+https://github.com/aaronaco/aa-toolkit@log-v0.1.0#subdirectory=packages/aa-toolkit-log"
22
+ ```
23
+
24
+ ## Use
25
+
26
+ Call `configure_logging()` once when the app starts. Every file gets its logger from `get_logger(__name__)` and logs with the usual methods, because it's a standard Python logger.
27
+
28
+ ```python
29
+ from aa_log import configure_logging, get_logger
30
+
31
+ log = get_logger(__name__)
32
+
33
+
34
+ def main() -> None:
35
+ configure_logging()
36
+ log.info("fetched", extra={"url": "https://example.com", "code": 200})
37
+ ```
38
+
39
+ In a terminal that prints:
40
+
41
+ ```text
42
+ 14:03:21 INFO __main__ fetched url=https://example.com code=200
43
+ ```
44
+
45
+ When stderr isn't a terminal, it prints:
46
+
47
+ ```json
48
+ {"time": "2026-11-09T14:03:21.482+08:00", "level": "info", "logger": "__main__", "message": "fetched", "url": "https://example.com", "code": 200}
49
+ ```
50
+
51
+ Logs go to stderr, so stdout stays free for the app's own output. Logs from installed packages appear in the same format. Calling `configure_logging()` again replaces the earlier settings, and handlers it didn't add stay attached. If you never call it, Python's normal behavior applies, and warnings and errors still show.
52
+
53
+ Only an app calls `configure_logging()`. A library should log through Python's `logging` and leave the setup to the app.
54
+
55
+ ### Arguments
56
+
57
+ `configure_logging(level=..., file=..., redact=...)` takes three optional arguments:
58
+
59
+ - `level`: the lowest level to show, as a name like `"DEBUG"` or a number like `logging.DEBUG`. The default is `INFO`.
60
+ - `file`: a path to save logs to. A relative path is relative to the current folder. By default no file is written.
61
+ - `redact`: a function that cleans every log line before it's written, see [Hiding secrets](#hiding-secrets). By default nothing is cleaned.
62
+
63
+ ### Environment variables
64
+
65
+ A variable that is set wins over the matching argument. An empty one counts as not set.
66
+
67
+ | Variable | Values | What it does |
68
+ |---|---|---|
69
+ | `AA_LOG_LEVEL` | `DEBUG`, `INFO`, `WARN`, `ERROR`, `CRIT` | Sets the lowest level to show. |
70
+ | `AA_LOG_FORMAT` | `text`, `json` | Forces the style on screen. Without it, a terminal gets `text` and anything else gets `json`. |
71
+ | `AA_LOG_FILE` | a path | Saves logs to that file. |
72
+
73
+ A bad `AA_LOG_LEVEL` gives a warning and the `level` argument is used, which is `INFO` unless the app passes another level. A bad `AA_LOG_FORMAT` gives a warning and the style is chosen as if it weren't set. A log file that can't be opened gives a warning and logs stay on screen. Neither stops the app.
74
+
75
+ ## Saving to a file
76
+
77
+ The file always holds JSON lines in UTF-8, with the same messages as the screen. Its folder is created when it's missing. At 10 MB a new file starts and the last 3 old ones are kept. Only one copy of an app should write to a log file at a time: on Windows, starting a new file can fail when two copies share one, and some lines can be lost.
78
+
79
+ Add `*.log` and `*.log.[1-3]` to your `.gitignore`, so a log file and its old copies aren't committed by accident.
80
+
81
+ ## Hiding secrets
82
+
83
+ By default, logs don't hide secrets: whatever you log is shown on screen and saved to the file as it is. The best fix is not to log passwords, tokens or keys at all. For the ones you don't see coming, such as a token in an error message from another package, pass a function as `redact`.
84
+
85
+ The redaction library, [`aa-toolkit-redact`](../aa-toolkit-redact/README.md), gives you one. Install it as its README shows, then pass a `Redactor`:
86
+
87
+ ```python
88
+ from aa_log import configure_logging, get_logger
89
+ from aa_redact import Redactor
90
+
91
+ log = get_logger(__name__)
92
+
93
+
94
+ def main() -> None:
95
+ configure_logging(redact=Redactor())
96
+ log.info("signed up %s", "ann@example.com", extra={"password": "hunter2"})
97
+ ```
98
+
99
+ That prints:
100
+
101
+ ```text
102
+ 14:03:21 INFO __main__ signed up [EMAIL] password=[REDACTED]
103
+ ```
104
+
105
+ Every line is cleaned the same way on screen and in the file: the message after its values are filled in, tracebacks, stack information and every `extra` value. Logs from installed packages are cleaned too. The time, level and logger name are left alone. There is no environment variable for it, so a stray setting can't turn it on or off.
106
+
107
+ If the function fails, the line shows only the time, level, logger and `[REDACTION FAILED]`, and the app carries on. The same happens when a log call's values don't fit its message, such as `log.info("%d", "text")`. A `redact` that can't be called gives a warning, and every line after it shows `[REDACTION FAILED]`.
108
+
109
+ Only the handlers `configure_logging()` adds are cleaned. A handler your app adds itself gets the raw lines.
110
+
111
+ `redact` can be any function. It gets one dictionary and returns one of the same shape:
112
+
113
+ ```python
114
+ {
115
+ "message": "signed up ann@example.com",
116
+ "exception": None,
117
+ "stack": None,
118
+ "extra": {"password": "hunter2"},
119
+ }
120
+ ```
121
+
122
+ `exception` and `stack` are text or `None`, and `extra` holds the `extra` values by name. The dictionaries, lists, sets and tuples it gets are copies, so changing them leaves the app's own record alone. It shouldn't change any other object it gets.
123
+
124
+ ## Names you can't use in `extra`
125
+
126
+ Python raises an error when `extra` uses a name it reserves: `args`, `asctime`, `created`, `exc_info`, `exc_text`, `filename`, `funcName`, `levelname`, `levelno`, `lineno`, `message`, `module`, `msecs`, `msg`, `name`, `pathname`, `process`, `processName`, `relativeCreated`, `stack_info`, `taskName`, `thread` and `threadName`.
127
+
128
+ `extra` can use `time`, `level` and `logger`, but in JSON the real values keep those fields and the `extra` values are dropped.
@@ -0,0 +1,119 @@
1
+ # aa-toolkit-log
2
+
3
+ Ready-made logging for apps, on top of Python's built-in logging. It has no dependencies.
4
+
5
+ An app gets clean, lined-up columns in a terminal and JSON lines when a tool or an agent runs it, and it can save its logs to a file that can't fill the disk.
6
+
7
+ ## Install
8
+
9
+ Install it from the toolkit's GitHub repo, pinned to a version tag:
10
+
11
+ ```bash
12
+ uv add "aa-toolkit-log @ git+https://github.com/aaronaco/aa-toolkit@log-v0.1.0#subdirectory=packages/aa-toolkit-log"
13
+ ```
14
+
15
+ ## Use
16
+
17
+ Call `configure_logging()` once when the app starts. Every file gets its logger from `get_logger(__name__)` and logs with the usual methods, because it's a standard Python logger.
18
+
19
+ ```python
20
+ from aa_log import configure_logging, get_logger
21
+
22
+ log = get_logger(__name__)
23
+
24
+
25
+ def main() -> None:
26
+ configure_logging()
27
+ log.info("fetched", extra={"url": "https://example.com", "code": 200})
28
+ ```
29
+
30
+ In a terminal that prints:
31
+
32
+ ```text
33
+ 14:03:21 INFO __main__ fetched url=https://example.com code=200
34
+ ```
35
+
36
+ When stderr isn't a terminal, it prints:
37
+
38
+ ```json
39
+ {"time": "2026-11-09T14:03:21.482+08:00", "level": "info", "logger": "__main__", "message": "fetched", "url": "https://example.com", "code": 200}
40
+ ```
41
+
42
+ Logs go to stderr, so stdout stays free for the app's own output. Logs from installed packages appear in the same format. Calling `configure_logging()` again replaces the earlier settings, and handlers it didn't add stay attached. If you never call it, Python's normal behavior applies, and warnings and errors still show.
43
+
44
+ Only an app calls `configure_logging()`. A library should log through Python's `logging` and leave the setup to the app.
45
+
46
+ ### Arguments
47
+
48
+ `configure_logging(level=..., file=..., redact=...)` takes three optional arguments:
49
+
50
+ - `level`: the lowest level to show, as a name like `"DEBUG"` or a number like `logging.DEBUG`. The default is `INFO`.
51
+ - `file`: a path to save logs to. A relative path is relative to the current folder. By default no file is written.
52
+ - `redact`: a function that cleans every log line before it's written, see [Hiding secrets](#hiding-secrets). By default nothing is cleaned.
53
+
54
+ ### Environment variables
55
+
56
+ A variable that is set wins over the matching argument. An empty one counts as not set.
57
+
58
+ | Variable | Values | What it does |
59
+ |---|---|---|
60
+ | `AA_LOG_LEVEL` | `DEBUG`, `INFO`, `WARN`, `ERROR`, `CRIT` | Sets the lowest level to show. |
61
+ | `AA_LOG_FORMAT` | `text`, `json` | Forces the style on screen. Without it, a terminal gets `text` and anything else gets `json`. |
62
+ | `AA_LOG_FILE` | a path | Saves logs to that file. |
63
+
64
+ A bad `AA_LOG_LEVEL` gives a warning and the `level` argument is used, which is `INFO` unless the app passes another level. A bad `AA_LOG_FORMAT` gives a warning and the style is chosen as if it weren't set. A log file that can't be opened gives a warning and logs stay on screen. Neither stops the app.
65
+
66
+ ## Saving to a file
67
+
68
+ The file always holds JSON lines in UTF-8, with the same messages as the screen. Its folder is created when it's missing. At 10 MB a new file starts and the last 3 old ones are kept. Only one copy of an app should write to a log file at a time: on Windows, starting a new file can fail when two copies share one, and some lines can be lost.
69
+
70
+ Add `*.log` and `*.log.[1-3]` to your `.gitignore`, so a log file and its old copies aren't committed by accident.
71
+
72
+ ## Hiding secrets
73
+
74
+ By default, logs don't hide secrets: whatever you log is shown on screen and saved to the file as it is. The best fix is not to log passwords, tokens or keys at all. For the ones you don't see coming, such as a token in an error message from another package, pass a function as `redact`.
75
+
76
+ The redaction library, [`aa-toolkit-redact`](../aa-toolkit-redact/README.md), gives you one. Install it as its README shows, then pass a `Redactor`:
77
+
78
+ ```python
79
+ from aa_log import configure_logging, get_logger
80
+ from aa_redact import Redactor
81
+
82
+ log = get_logger(__name__)
83
+
84
+
85
+ def main() -> None:
86
+ configure_logging(redact=Redactor())
87
+ log.info("signed up %s", "ann@example.com", extra={"password": "hunter2"})
88
+ ```
89
+
90
+ That prints:
91
+
92
+ ```text
93
+ 14:03:21 INFO __main__ signed up [EMAIL] password=[REDACTED]
94
+ ```
95
+
96
+ Every line is cleaned the same way on screen and in the file: the message after its values are filled in, tracebacks, stack information and every `extra` value. Logs from installed packages are cleaned too. The time, level and logger name are left alone. There is no environment variable for it, so a stray setting can't turn it on or off.
97
+
98
+ If the function fails, the line shows only the time, level, logger and `[REDACTION FAILED]`, and the app carries on. The same happens when a log call's values don't fit its message, such as `log.info("%d", "text")`. A `redact` that can't be called gives a warning, and every line after it shows `[REDACTION FAILED]`.
99
+
100
+ Only the handlers `configure_logging()` adds are cleaned. A handler your app adds itself gets the raw lines.
101
+
102
+ `redact` can be any function. It gets one dictionary and returns one of the same shape:
103
+
104
+ ```python
105
+ {
106
+ "message": "signed up ann@example.com",
107
+ "exception": None,
108
+ "stack": None,
109
+ "extra": {"password": "hunter2"},
110
+ }
111
+ ```
112
+
113
+ `exception` and `stack` are text or `None`, and `extra` holds the `extra` values by name. The dictionaries, lists, sets and tuples it gets are copies, so changing them leaves the app's own record alone. It shouldn't change any other object it gets.
114
+
115
+ ## Names you can't use in `extra`
116
+
117
+ Python raises an error when `extra` uses a name it reserves: `args`, `asctime`, `created`, `exc_info`, `exc_text`, `filename`, `funcName`, `levelname`, `levelno`, `lineno`, `message`, `module`, `msecs`, `msg`, `name`, `pathname`, `process`, `processName`, `relativeCreated`, `stack_info`, `taskName`, `thread` and `threadName`.
118
+
119
+ `extra` can use `time`, `level` and `logger`, but in JSON the real values keep those fields and the `extra` values are dropped.
@@ -0,0 +1,16 @@
1
+ [project]
2
+ name = "aa-toolkit-log"
3
+ version = "0.1.0a1"
4
+ description = "Ready-made logging for apps, on top of Python's logging."
5
+ readme = "README.md"
6
+ requires-python = ">=3.14"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ dependencies = []
10
+
11
+ [build-system]
12
+ requires = ["uv_build>=0.13.7,<0.14"]
13
+ build-backend = "uv_build"
14
+
15
+ [tool.uv.build-backend]
16
+ module-name = "aa_log"
@@ -0,0 +1,16 @@
1
+ [project]
2
+ name = "aa-toolkit-log"
3
+ version = "0.1.0a1"
4
+ description = "Ready-made logging for apps, on top of Python's logging."
5
+ readme = "README.md"
6
+ requires-python = ">=3.14"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ dependencies = []
10
+
11
+ [build-system]
12
+ requires = ["uv_build>=0.13.7,<0.14"]
13
+ build-backend = "uv_build"
14
+
15
+ [tool.uv.build-backend]
16
+ module-name = "aa_log"
@@ -0,0 +1,5 @@
1
+ """Ready-made logging for apps, on top of Python's logging."""
2
+
3
+ from aa_log._setup import configure_logging, get_logger
4
+
5
+ __all__ = ["configure_logging", "get_logger"]
@@ -0,0 +1,107 @@
1
+ """How a log record looks on the way out."""
2
+
3
+ import json
4
+ import logging
5
+ from datetime import datetime
6
+
7
+ _LABELS = {
8
+ logging.DEBUG: "DEBUG",
9
+ logging.INFO: "INFO",
10
+ logging.WARNING: "WARN",
11
+ logging.ERROR: "ERROR",
12
+ logging.CRITICAL: "CRIT",
13
+ }
14
+ _LEVEL_WIDTH = 5
15
+ _LOGGER_WIDTH = 24
16
+
17
+ _YELLOW = "\x1b[33m"
18
+ _RED = "\x1b[31m"
19
+ _RESET = "\x1b[0m"
20
+
21
+ _ESCAPED_LINE_BREAKS = str.maketrans({0x85: r"\u0085", 0x2028: r"\u2028", 0x2029: r"\u2029"})
22
+
23
+ STANDARD_FIELDS = frozenset(vars(logging.makeLogRecord({}))) | {"message", "asctime"}
24
+
25
+
26
+ def _label(record: logging.LogRecord) -> str:
27
+ return _LABELS.get(record.levelno, record.levelname)
28
+
29
+
30
+ def extra(record: logging.LogRecord) -> dict[str, object]:
31
+ return {key: value for key, value in vars(record).items() if key not in STANDARD_FIELDS}
32
+
33
+
34
+ def _text(value: object) -> str:
35
+ """Turn a value into text, even one whose own ``__str__`` fails."""
36
+ try:
37
+ return str(value)
38
+ except Exception:
39
+ return f"<unprintable {type(value).__name__}>"
40
+
41
+
42
+ def _json_value(value: object) -> object:
43
+ """Keep a value JSON can hold, and turn any other into text."""
44
+ try:
45
+ json.dumps(value, default=str, allow_nan=False)
46
+ except Exception:
47
+ return _text(value)
48
+ return value
49
+
50
+
51
+ class _Formatter(logging.Formatter):
52
+ def _details(self, record: logging.LogRecord) -> str | None:
53
+ """Return the error details and stack of a record, if it has any."""
54
+ parts = []
55
+ if record.exc_info:
56
+ parts.append(self.formatException(record.exc_info))
57
+ elif record.exc_text:
58
+ parts.append(record.exc_text)
59
+ if record.stack_info:
60
+ parts.append(self.formatStack(record.stack_info))
61
+ return "\n".join(parts) or None
62
+
63
+
64
+ class TextFormatter(_Formatter):
65
+ """Lined-up columns of time, level, logger name and message, for a person."""
66
+
67
+ def __init__(self, *, color: bool) -> None:
68
+ super().__init__()
69
+ self._color = color
70
+
71
+ def _level(self, record: logging.LogRecord) -> str:
72
+ label = _label(record)
73
+ padding = " " * (_LEVEL_WIDTH - len(label))
74
+ if self._color and record.levelno >= logging.ERROR:
75
+ return f"{_RED}{label}{_RESET}{padding}"
76
+ if self._color and record.levelno >= logging.WARNING:
77
+ return f"{_YELLOW}{label}{_RESET}{padding}"
78
+ return f"{label}{padding}"
79
+
80
+ def format(self, record: logging.LogRecord) -> str:
81
+ pairs = [f"{key}={_text(value)}" for key, value in extra(record).items()]
82
+ text = " ".join([record.getMessage(), *pairs])
83
+ time = self.formatTime(record, "%H:%M:%S")
84
+ line = f"{time} {self._level(record)} {record.name:<{_LOGGER_WIDTH}} {text}"
85
+ details = self._details(record)
86
+ return f"{line}\n{details}" if details else line
87
+
88
+
89
+ class JsonFormatter(_Formatter):
90
+ """One complete JSON object per record, on one line."""
91
+
92
+ def format(self, record: logging.LogRecord) -> str:
93
+ when = datetime.fromtimestamp(record.created).astimezone()
94
+ payload: dict[str, object] = {
95
+ "time": when.isoformat(timespec="milliseconds"),
96
+ "level": _label(record).lower(),
97
+ "logger": record.name,
98
+ "message": record.getMessage(),
99
+ }
100
+ details = self._details(record)
101
+ if details:
102
+ payload["exception"] = details
103
+ for key, value in extra(record).items():
104
+ payload.setdefault(key, _json_value(value))
105
+ return json.dumps(payload, ensure_ascii=False, default=_text).translate(
106
+ _ESCAPED_LINE_BREAKS
107
+ )
@@ -0,0 +1,133 @@
1
+ """Cleaning each log record with the app's own function before it's formatted (ADR 0005)."""
2
+
3
+ import copy
4
+ import logging
5
+ from collections.abc import Callable, Mapping
6
+
7
+ from aa_log._format import STANDARD_FIELDS, extra
8
+
9
+ Redact = Callable[[dict[str, object]], object]
10
+
11
+ FAILED = "[REDACTION FAILED]"
12
+ _FIELDS = frozenset({"message", "exception", "stack", "extra"})
13
+ _TRACEBACKS = logging.Formatter()
14
+
15
+
16
+ class _WrongShape(Exception):
17
+ """The redact function returned something other than the mapping it was given."""
18
+
19
+
20
+ def _exception(record: logging.LogRecord) -> str | None:
21
+ if record.exc_info:
22
+ return _TRACEBACKS.formatException(record.exc_info)
23
+ return record.exc_text
24
+
25
+
26
+ def _text_or_none(value: object) -> str | None:
27
+ if value is None or isinstance(value, str):
28
+ return value
29
+ raise _WrongShape
30
+
31
+
32
+ def _detached(value: object, copies: dict[int, object]) -> object:
33
+ """Copy the dicts, lists, sets and tuples in a value, and keep every other object as it is.
34
+
35
+ `copies` maps each container already copied to its copy, so shared and circular parts
36
+ stay that way.
37
+ """
38
+ if id(value) in copies:
39
+ return copies[id(value)]
40
+ if isinstance(value, dict):
41
+ copied_dict = copies[id(value)] = copy.copy(value)
42
+ for key, item in value.items():
43
+ copied_dict[key] = _detached(item, copies)
44
+ return copied_dict
45
+ if isinstance(value, list):
46
+ copied_list = copies[id(value)] = copy.copy(value)
47
+ copied_list[:] = [_detached(item, copies) for item in value]
48
+ return copied_list
49
+ if isinstance(value, set):
50
+ copied_set = copies[id(value)] = copy.copy(value)
51
+ return copied_set
52
+ if isinstance(value, tuple):
53
+ items = [_detached(item, copies) for item in value]
54
+ if id(value) in copies:
55
+ return copies[id(value)]
56
+ unchanged = all(new is old for new, old in zip(items, value, strict=True))
57
+ copied_tuple = copies[id(value)] = value if unchanged else tuple.__new__(type(value), items)
58
+ return copied_tuple
59
+ return value
60
+
61
+
62
+ def _checked(result: object) -> tuple[str, str | None, str | None, dict[str, object]]:
63
+ """Return the fields of a redact result, or raise when it isn't the shape it was given."""
64
+ if not isinstance(result, Mapping) or set(result) != _FIELDS:
65
+ raise _WrongShape
66
+ message, extras = result["message"], result["extra"]
67
+ if not isinstance(message, str) or not isinstance(extras, Mapping):
68
+ raise _WrongShape
69
+ cleaned_extras: dict[str, object] = {}
70
+ for key, value in extras.items():
71
+ if not isinstance(key, str) or key in STANDARD_FIELDS:
72
+ raise _WrongShape
73
+ cleaned_extras[key] = value
74
+ return (
75
+ message,
76
+ _text_or_none(result["exception"]),
77
+ _text_or_none(result["stack"]),
78
+ cleaned_extras,
79
+ )
80
+
81
+
82
+ def _failed(record: logging.LogRecord) -> logging.LogRecord:
83
+ """A record with only the time, level and logger of `record`, and FAILED as its message."""
84
+ failed = logging.makeLogRecord(
85
+ {"name": record.name, "levelno": record.levelno, "levelname": record.levelname}
86
+ )
87
+ failed.created, failed.msecs = record.created, record.msecs
88
+ failed.relativeCreated = record.relativeCreated
89
+ failed.msg = FAILED
90
+ return failed
91
+
92
+
93
+ class Redaction(logging.Filter):
94
+ """A handler filter that passes on a redacted copy of each record, and never raises."""
95
+
96
+ def __init__(self, redact: Redact) -> None:
97
+ super().__init__()
98
+ self._redact = redact
99
+ self.let_through: list[logging.LogRecord] = []
100
+
101
+ def filter(self, record: logging.LogRecord) -> logging.LogRecord | bool:
102
+ if any(record is allowed for allowed in self.let_through):
103
+ return True
104
+ try:
105
+ return self._clean(record)
106
+ except Exception:
107
+ try:
108
+ return _failed(record)
109
+ except Exception:
110
+ return False
111
+
112
+ def _clean(self, record: logging.LogRecord) -> logging.LogRecord:
113
+ raw_extras = extra(record)
114
+ message, exception, stack, cleaned_extras = _checked(
115
+ self._redact(
116
+ {
117
+ "message": record.getMessage(),
118
+ "exception": _exception(record),
119
+ "stack": record.stack_info,
120
+ "extra": _detached(raw_extras, {}),
121
+ }
122
+ )
123
+ )
124
+ clean = copy.copy(record)
125
+ for key in raw_extras:
126
+ delattr(clean, key)
127
+ clean.msg = clean.message = message
128
+ clean.args = ()
129
+ clean.exc_info = None
130
+ clean.exc_text = exception
131
+ clean.stack_info = stack
132
+ vars(clean).update(cleaned_extras)
133
+ return clean
@@ -0,0 +1,178 @@
1
+ """Turning logging on for an app."""
2
+
3
+ import contextlib
4
+ import logging
5
+ import os
6
+ import sys
7
+ from logging.handlers import RotatingFileHandler
8
+ from pathlib import Path
9
+ from typing import TextIO
10
+
11
+ from aa_log._format import JsonFormatter, TextFormatter
12
+ from aa_log._redact import FAILED, Redact, Redaction
13
+
14
+ _LEVELS = {
15
+ "DEBUG": logging.DEBUG,
16
+ "INFO": logging.INFO,
17
+ "WARN": logging.WARNING,
18
+ "WARNING": logging.WARNING,
19
+ "ERROR": logging.ERROR,
20
+ "CRIT": logging.CRITICAL,
21
+ "CRITICAL": logging.CRITICAL,
22
+ }
23
+ _MAX_FILE_BYTES = 10 * 1024 * 1024
24
+ _OLD_FILES_KEPT = 3
25
+ _ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
26
+
27
+ _installed: list[logging.Handler] = []
28
+
29
+
30
+ def _env(name: str) -> str | None:
31
+ """Return an environment variable, counting an empty one as not set."""
32
+ return os.environ.get(name, "").strip() or None
33
+
34
+
35
+ def _parse_level(value: int | str) -> int | None:
36
+ if isinstance(value, int):
37
+ return value
38
+ return _LEVELS.get(str(value).strip().upper())
39
+
40
+
41
+ def _choose_level(level: int | str, problems: list[str]) -> int:
42
+ chosen = _parse_level(level)
43
+ if chosen is None:
44
+ problems.append(f"level={level!r} is not a log level, using INFO")
45
+ chosen = logging.INFO
46
+ value = _env("AA_LOG_LEVEL")
47
+ if value is None:
48
+ return chosen
49
+ from_env = _parse_level(value)
50
+ if from_env is None:
51
+ name = logging.getLevelName(chosen)
52
+ problems.append(f"AA_LOG_LEVEL is {value!r}, which is not a log level, using {name}")
53
+ return chosen
54
+ return from_env
55
+
56
+
57
+ def _is_terminal(stream: TextIO) -> bool:
58
+ try:
59
+ return stream.isatty()
60
+ except AttributeError, ValueError: # no stderr at all, or a closed one
61
+ return False
62
+
63
+
64
+ def _enable_color(stream: TextIO) -> None:
65
+ """Make a Windows console act on color codes instead of printing them as text."""
66
+ if sys.platform != "win32":
67
+ return
68
+ import ctypes
69
+ import msvcrt
70
+ from ctypes import wintypes
71
+
72
+ try:
73
+ handle = wintypes.HANDLE(msvcrt.get_osfhandle(stream.fileno()))
74
+ except AttributeError, OSError, ValueError: # a stream that only acts like a terminal
75
+ return
76
+ kernel32 = ctypes.windll.kernel32
77
+ mode = wintypes.DWORD()
78
+ if kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
79
+ kernel32.SetConsoleMode(handle, mode.value | _ENABLE_VIRTUAL_TERMINAL_PROCESSING)
80
+
81
+
82
+ def _screen_formatter(stream: TextIO, problems: list[str]) -> logging.Formatter:
83
+ terminal = _is_terminal(stream)
84
+ automatic = "text" if terminal else "json"
85
+ style = _env("AA_LOG_FORMAT") or automatic
86
+ if style.lower() not in ("text", "json"):
87
+ problems.append(f"AA_LOG_FORMAT is {style!r}, which is not text or json, using {automatic}")
88
+ style = automatic
89
+ if style.lower() == "json":
90
+ return JsonFormatter()
91
+ if terminal:
92
+ _enable_color(stream)
93
+ return TextFormatter(color=terminal)
94
+
95
+
96
+ def _file_handler(path: str | os.PathLike[str]) -> logging.Handler:
97
+ Path(path).parent.mkdir(parents=True, exist_ok=True)
98
+ handler = RotatingFileHandler(
99
+ path,
100
+ maxBytes=_MAX_FILE_BYTES,
101
+ backupCount=_OLD_FILES_KEPT,
102
+ encoding="utf-8",
103
+ errors="backslashreplace",
104
+ )
105
+ handler.setFormatter(JsonFormatter())
106
+ return handler
107
+
108
+
109
+ def _attach(handler: logging.Handler, redaction: Redaction | None) -> None:
110
+ if redaction is not None:
111
+ handler.addFilter(redaction)
112
+ logging.getLogger().addHandler(handler)
113
+ _installed.append(handler)
114
+
115
+
116
+ def get_logger(name: str) -> logging.Logger:
117
+ """Return the standard Python logger for ``name``. Safe at the top of a file."""
118
+ return logging.getLogger(name)
119
+
120
+
121
+ def configure_logging(
122
+ level: int | str = logging.INFO,
123
+ file: str | os.PathLike[str] | None = None,
124
+ redact: Redact | None = None,
125
+ ) -> None:
126
+ """Set up logging for the whole app. Call it once when the app starts.
127
+
128
+ ``AA_LOG_LEVEL`` and ``AA_LOG_FILE`` override the arguments, and ``AA_LOG_FORMAT``
129
+ forces the screen style. ``redact`` cleans every line written by these handlers: it gets
130
+ a dict of ``message``, ``exception``, ``stack`` and ``extra`` and returns the same shape.
131
+ Calling it again replaces the earlier settings. A problem with any setting is reported
132
+ as a warning and never stops the app.
133
+ """
134
+ root = logging.getLogger()
135
+ problems: list[str] = []
136
+ for handler in _installed:
137
+ root.removeHandler(handler)
138
+ try:
139
+ handler.close()
140
+ except (OSError, ValueError) as error:
141
+ problems.append(f"could not close the earlier log file: {error}")
142
+ _installed.clear()
143
+
144
+ redaction = None if redact is None else Redaction(redact)
145
+
146
+ screen = logging.StreamHandler(sys.stderr)
147
+ screen.setFormatter(_screen_formatter(sys.stderr, problems))
148
+ _attach(screen, redaction)
149
+ path = _env("AA_LOG_FILE") or file
150
+ if path is not None:
151
+ try:
152
+ _attach(_file_handler(path), redaction)
153
+ except (OSError, TypeError, ValueError) as error:
154
+ problems.append(f"could not open the log file {path}, logging to screen only: {error}")
155
+ root.setLevel(_choose_level(level, problems))
156
+
157
+ # Straight to the handlers, so the warnings still show when the app's level would hide them.
158
+ setup_log = logging.getLogger("aa_log")
159
+
160
+ def warning(problem: str) -> logging.LogRecord:
161
+ message = " ".join(problem.splitlines())
162
+ return setup_log.makeRecord(setup_log.name, logging.WARNING, __file__, 0, message, (), None)
163
+
164
+ warnings = [warning(problem) for problem in problems]
165
+ if redaction is not None and not callable(redact):
166
+ uncallable = warning(
167
+ f"redact= takes a function, and a {type(redact).__name__} can't be called,"
168
+ f" so every log line shows {FAILED}"
169
+ )
170
+ warnings.insert(0, uncallable)
171
+ redaction.let_through = [uncallable]
172
+ try:
173
+ with contextlib.suppress(ValueError):
174
+ for record in warnings:
175
+ setup_log.handle(record)
176
+ finally:
177
+ if redaction is not None:
178
+ redaction.let_through = []
File without changes