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
2831def _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+
52120def 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
86157def 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
101177def 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