Skip to content

Commit f63458c

Browse files
committed
fix(logging): keep propagating and stand down instead of taking over
- osw never sets propagate=False, so its records always reach the handlers the calling application configured - the default handler detaches itself once anything above the osw logger is listening, so nothing is written twice - the hand-over gives back the level osw picked, keeping one the caller asked for via set_log_level or OSW_LOG_LEVEL - osw attaches nothing when logging was configured before the import
1 parent 58a2c44 commit f63458c

3 files changed

Lines changed: 279 additions & 60 deletions

File tree

‎README.md‎

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,34 @@ osw.disable_logging() # detach the handler osw attached
5353
```
5454

5555
Set `OSW_LOG_LEVEL` to a level name, a level number, or `OFF` to choose the
56-
level before the package is imported. `disable_logging()` also restores
57-
propagation to the root logger, so an application that prefers to configure
58-
handlers itself can take over with `logging.basicConfig()`.
56+
level before the package is imported. `OFF` silences osw everywhere, including
57+
in your own handlers.
58+
59+
### Collecting osw's records in your application
60+
61+
Configure logging the way you normally would and osw's records arrive there,
62+
once:
63+
64+
```python
65+
import logging
66+
import osw
67+
68+
logging.basicConfig(level=logging.INFO, filename="app.log")
69+
```
70+
71+
The `osw` logger propagates at all times, so the records reach your handlers
72+
whatever else happens. osw's own handler notices that something above it is
73+
listening, detaches itself so nothing is written twice, and gives back the
74+
level it had picked, so your level applies from then on. It makes no difference
75+
whether you configure logging before or after importing osw.
76+
77+
A level you asked for is kept across that hand-over, so `set_log_level("DEBUG")`
78+
or `OSW_LOG_LEVEL=DEBUG` is how you pull osw's debug records into an aggregated
79+
setup while the rest of your application stays quieter.
80+
81+
One case osw cannot detect is a handler added to the `osw` logger itself, since
82+
that is indistinguishable from one of its own. Call `disable_logging()` first if
83+
you do that.
5984

6085
## Contributing
6186

‎src/osw/__init__.py‎

Lines changed: 129 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@
2323

2424
_DEFAULT_HANDLER_NAME = "osw-default"
2525
_logger = logging.getLogger(__name__)
26+
_level_is_ours = False
27+
"""Whether the level on the osw logger is the one osw picked for itself. A
28+
level the calling code asked for is left alone when osw hands over."""
2629

2730

2831
def _parse_level(value: str) -> int:
@@ -49,12 +52,80 @@ def _parse_level(value: str) -> int:
4952
return DEFAULT_LOG_LEVEL
5053

5154

55+
def _application_handles_records() -> bool:
56+
"""Whether the calling code already has somewhere for osw's records to go
57+
58+
Walks what logging.Logger.callHandlers walks above the osw logger. Any
59+
handler found up there belongs to the calling application, so osw writing
60+
its own copy would only duplicate what that handler already reports.
61+
"""
62+
if not _logger.propagate:
63+
# something is deliberately holding the records at the osw logger,
64+
# parallelize while it captures a batch among them
65+
return False
66+
current = _logger.parent
67+
while current:
68+
if current.handlers:
69+
return True
70+
if not current.propagate:
71+
return False
72+
current = current.parent
73+
return False
74+
75+
76+
class _DefaultHandler(logging.StreamHandler):
77+
"""The handler osw attaches while nothing else is listening
78+
79+
Steps aside the first time it finds that the calling application has
80+
configured logging of its own. The check belongs here rather than at import
81+
time because a script normally imports osw before it calls basicConfig().
82+
"""
83+
84+
def emit(self, record: logging.LogRecord):
85+
if _application_handles_records():
86+
_hand_over()
87+
return
88+
super().emit(record)
89+
90+
91+
def _detach():
92+
"""Removes the handler osw attached, leaving any other one in place
93+
94+
Rebinds the list instead of calling removeHandler, because this also runs
95+
from inside the handler's own emit, where callHandlers is iterating that
96+
very list.
97+
"""
98+
detached = [h for h in _logger.handlers if h.get_name() == _DEFAULT_HANDLER_NAME]
99+
_logger.handlers = [h for h in _logger.handlers if h not in detached]
100+
for handler in detached:
101+
handler.close()
102+
103+
104+
def _hand_over():
105+
"""Gives the application's own logging setup sole charge of osw's records
106+
107+
Drops osw's handler so nothing is written twice, and drops the level osw
108+
picked so the application's level applies. A level the calling code asked
109+
for, through set_log_level, enable_logging or the environment variable, is
110+
kept, since that is how one asks for osw's DEBUG records in an aggregated
111+
setup.
112+
"""
113+
global _level_is_ours
114+
_detach()
115+
if _level_is_ours:
116+
_logger.setLevel(logging.NOTSET)
117+
_level_is_ours = False
118+
119+
52120
def enable_logging(level=None, stream=None) -> logging.Handler:
53-
"""Attaches the default handler to the osw logger
121+
"""Attaches osw's own handler to the osw logger
122+
123+
Called on import when nothing else handles the records, so osw reports what
124+
it is doing without the calling code configuring anything. Call it again to
125+
take the output back after disable_logging(), or to send it elsewhere.
54126
55-
Called once on import, so osw reports what it is doing without the calling
56-
code configuring anything. Call it again to restore the handler after
57-
disable_logging(), or to send the records to another stream.
127+
The handler detaches itself as soon as the calling application configures
128+
logging, so records are never written twice.
58129
59130
Parameters
60131
----------
@@ -69,56 +140,79 @@ def enable_logging(level=None, stream=None) -> logging.Handler:
69140
-------
70141
the attached handler
71142
"""
143+
global _level_is_ours
144+
asked_for = level is not None or LOG_LEVEL_ENV_VAR in os.environ
72145
if level is None:
73146
level = _parse_level(os.environ.get(LOG_LEVEL_ENV_VAR, ""))
74-
disable_logging()
75-
handler = logging.StreamHandler(sys.stdout if stream is None else stream)
147+
_detach()
148+
handler = _DefaultHandler(sys.stdout if stream is None else stream)
76149
handler.setFormatter(logging.Formatter(LOG_FORMAT))
77150
handler.set_name(_DEFAULT_HANDLER_NAME)
78151
_logger.addHandler(handler)
79152
_logger.setLevel(level)
80-
# the records are handled here, so passing them to the root logger as well
81-
# would print everything twice for anyone who called basicConfig()
82-
_logger.propagate = False
153+
_level_is_ours = not asked_for
83154
return handler
84155

85156

86157
def disable_logging():
87-
"""Removes the default handler, leaving osw silent
88-
89-
Only the handler osw attached itself is removed, so a handler the calling
90-
code added to the 'osw' logger keeps receiving records. Records propagate
91-
to the root logger again, which is what a library is normally expected to
92-
do, and lets the calling code take over with basicConfig().
158+
"""Hands the osw logger over to the calling application
159+
160+
Removes the handler osw attached and the level it picked, so the records
161+
follow whatever the application configured, on the 'osw' logger or on the
162+
root logger above it. A handler the calling code added to the 'osw' logger
163+
is left in place.
164+
165+
Not needed in order to aggregate osw's records. They propagate to the root
166+
logger at all times, and osw's own handler steps aside by itself once
167+
anything else is listening. Call this to be explicit about it, or when a
168+
handler was added to the 'osw' logger directly, which osw cannot tell apart
169+
from one of its own callers.
93170
"""
94-
for handler in list(_logger.handlers):
95-
if handler.get_name() == _DEFAULT_HANDLER_NAME:
96-
_logger.removeHandler(handler)
97-
handler.close()
98-
_logger.propagate = True
171+
global _level_is_ours
172+
_detach()
173+
_logger.setLevel(logging.NOTSET)
174+
_level_is_ours = False
99175

100176

101177
def set_log_level(level):
102178
"""Sets how much osw reports
103179
180+
The level survives a hand-over to the application's own logging setup, so
181+
this is also how to ask for osw's DEBUG records in an aggregated setup.
182+
104183
Parameters
105184
----------
106185
level
107186
a level name or number, e.g. 'DEBUG', 'WARNING', or logging.WARNING.
108-
Pass osw.OFF to silence osw without detaching the handler.
187+
Pass osw.OFF to silence osw everywhere, its own handler and the
188+
application's alike.
109189
"""
190+
global _level_is_ours
110191
_logger.setLevel(level)
111-
112-
113-
enable_logging()
114-
115-
if os.environ.get(LOG_LEVEL_ENV_VAR) is None:
116-
# once per interpreter, since this module is only imported once. Sent
117-
# through the logger itself, so it disappears with everything else as soon
118-
# as the level is raised or the environment variable is set.
119-
_logger.info(
120-
"osw logs at %s. Use osw.set_log_level('WARNING') to see less, "
121-
"osw.disable_logging() to switch it off, or set %s=OFF before import.",
122-
logging.getLevelName(_logger.level),
123-
LOG_LEVEL_ENV_VAR,
124-
)
192+
_level_is_ours = False
193+
194+
195+
def _configure_on_import():
196+
"""Sets logging up the way an interpreter that configured none needs it"""
197+
if _application_handles_records():
198+
# logging was configured before osw was imported, so the records
199+
# already have somewhere to go and only the level is osw's to set
200+
if LOG_LEVEL_ENV_VAR in os.environ:
201+
set_log_level(_parse_level(os.environ[LOG_LEVEL_ENV_VAR]))
202+
return
203+
enable_logging()
204+
if LOG_LEVEL_ENV_VAR not in os.environ:
205+
# once per interpreter, since this module is imported once. Sent
206+
# through the logger itself, so it disappears with everything else as
207+
# soon as the level is raised or the environment variable is set.
208+
_logger.info(
209+
"osw logs at %s on the 'osw' logger. Use osw.set_log_level"
210+
"('WARNING') to see less, osw.disable_logging() to switch it off, "
211+
"or set %s=OFF before import. Configuring logging yourself, e.g. "
212+
"with logging.basicConfig(), takes the output over automatically.",
213+
logging.getLevelName(_logger.level),
214+
LOG_LEVEL_ENV_VAR,
215+
)
216+
217+
218+
_configure_on_import()

0 commit comments

Comments
 (0)