Logging getLogger Documentation Incomplete

[Wikilicious]

Documentation

The latest logging.getLogger documentation is incomplete/inaccurate.

Specifically, "If no name is specified, return the root logger.".

To more accurately reflect the code...
Change it to "If name is Falsy or 'root', return the root logger."

logging.getLogger https://github.com/python/cpython/blob/3.13/Lib/logging/__init__.py#L2128

def getLogger(name=None):
    """
    Return a logger with the specified name, creating it if necessary.

    If no name is specified, return the root logger.
    """
    if not name or isinstance(name, str) and name == root.name:
        return root
    return Logger.manager.getLogger(name)

Examples that will return root logger:

logger = logging.getLogger()
logger = logging.getLogger("")
logger = logging.getLogger("root")
logger = logging.getLogger(None)
logger = logging.getLogger(False)
logger = logging.getLogger(0)  

[picnixz]

I don't think this is needed. We don't necessarily want those side effects to be documented. The root logger should not necessarily be named "root", it may change in the future and we may want to make that change invisible.

Semantically speaking, it does not make sense to pass a falsey value to the function even if it's accepted at runtime. So I don't think we will document that.

What we want to document is "the root logger can be retrieved via logging.getLogger()" and that's essentially the only way we want for the public API.

cc @vsajip

[Wikilicious]

Perhaps not needed... but, useful in guiding future examples.

e.g.
https://docs.python.org/3/howto/logging-cookbook.html#logging-to-multiple-destinations

# add the handler to the root logger
logging.getLogger('').addHandler(console)

https://docs.python.org/3/howto/logging-cookbook.html#dealing-with-handlers-that-block
root = logging.getLogger() note var=root
https://docs.python.org/3/howto/logging-cookbook.html#imparting-contextual-information-in-handlers
logger = logging.getLogger() note var=logger

[picnixz]

I think we can unify the examples then and avoid using '' as the name when possible.

[ZeroIntensity]

logging.getLogger("root") is possibly worth documenting, but the "falsy returning root" behavior is an implementation detail, and I don't think it should be documented. It's not guaranteed that passing an integer or something like that will work in the future.

[picnixz]

I'm not fond of documenting "root" because the runtime code checks for root.name which may change in the future or may be changed externally (IIRC you could technically get the root logger and directly change its name via root.name = ...).

[Wikilicious]

I like the combination of treating the falsy part as an implementation detail (@ZeroIntensity) and removing references to getLogger('') in the logging-cookbook/docs (@picnixz).

The name "root" is checked at runtime; however, the class RootLogger is hardcoded with name="root" and no exposed method to change its name.
My thought process is the docs insinuates None is the only way to get the root logger. In my mind... I'd assume all strings would propagate to the root logger... but, the name "root" is treated as a reserved name... it is the root logger. I feel that's a detail worth documenting.

[picnixz]

and no exposed method to change its name.

You're right but the attribute is still without an underscore and people could think it's public so there might be code in the wild that changes the name (even if it's incorrect). If, in the future, we were to change the name, we don't necessarily want to expose the fact that "root" is the name. So, instead, I really think the root logger should be retrieved via logger.getLogger(). But, if @vsajip thinks that "root" should be a reserved name, then I'm not against documenting it.

[vsajip]

At the moment, getLogger(), getLogger('') and getLogger('root') all return the root logger. I don't especially want to document root as a reserved name, or encourage the third of the three call styles as the way to get the root logger. I suppose it doesn't do any harm to leave the first two calls as documented ways of getting the root logger, but I agree that all the examples in the documentation should use the first form of call.