Why does a Python library attach logging.NullHandler to its logger and configure nothing else?

### Who owns the destination Python's logging module splits responsibility deliberately. Naming a logger and emitting records is the job of the code that has something to say; deciding where those records go, in what format, at what verbosity, is the job of the process that is running. A library lives in someone else's process. If it calls `logging.basicConfig`, adds its own `logging.StreamHandler`, or sets a level on the root logger at import time, it silently takes over an application-wide decision — and does so at whatever point in the import order it happens to be reached. So the rule for library code is short: call `logging.getLogger(__name__)`, log, and configure nothing. Records propagate up the dotted hierarchy to the application's handlers all by themselves, so the library needs no destination of its own to be useful. ### The one exception, and why it exists There is exactly one handler a library should attach, and it writes nothing. When a record finishes the walk up its ancestors without meeting a single handler, the logging module falls back to `logging.lastResort`, a handler that writes warnings and above to standard error with no formatting. That fallback is a kindness for scripts, but from a library's point of view it means an application that never configured logging at all can suddenly see raw warning text from a dependency it did not know was talking. Attaching `logging.NullHandler()` to the library's top-level logger — the package name, so every module beneath it is covered — prevents that. The null handler's emit does nothing, but it is a handler, and the fallback fires only when no handler was found. Note the ordering inside the walk: a handler is counted as found *before* its level is checked, so even a handler that rejects everything suppresses the fallback. That is precisely the property the null handler relies on. It costs nothing else. When the application does configure a handler on the root logger, the library's records still propagate past the null handler and reach it, formatted like everything else. The null handler neither swallows records nor stops propagation; those are different mechanisms. ### The lost-message symptoms this explains Two complaints come out of the same model. "The library prints warnings I never asked for" is the missing null handler: nothing was configured, so the fallback wrote to standard error. "The library logs nothing at all" is usually the mirror — the application configured a handler somewhere that this logger's chain does not reach, or set the level so nothing is created, or the library's own logger has propagation switched off by some well-meaning helper. Checking, in order, whether the record is created, whether it propagates, and whether any handler on the chain accepts it turns both complaints into a two-minute diagnosis. A third variant is worth naming: a library that attaches a real handler rather than a null one produces duplicated output in every application that has also configured the root, and the application author cannot easily remove it without reaching into the library's logger. The null handler is the version of that gesture that is safe to ship. ### What a library should offer instead Give the application handles rather than decisions. Use dotted names that make prefixes meaningful, so an application can raise verbosity for one part of the library without the rest. Document the top-level logger name — it is part of your public surface, as much as a function signature. Keep the emitting code free of any assumption about formatting, since the formatter belongs to whatever handler the application installed. If your library is also an entry point — a command-line tool shipped from the same package — put the configuration in the command-line code path, not at import time. Being imported and being run are different situations, and only the second one has the right to decide where logs go. ### The application side of the same contract The mirror obligation belongs to the application: configure once, early, in the entry point, and configure the root logger rather than reaching into each dependency's logger by name. Because every library's records propagate upward, one handler on the root is enough to capture all of them, and per-library tuning is then a matter of raising or lowering a dotted prefix rather than installing more destinations. An application that instead attaches a handler to each dependency it cares about is signing up for the duplication and ordering problems the null-handler convention exists to avoid.