Logger formatter class initialization state clarification

Documentation

https://docs.python.org/3/library/logging.html#logging.Handler.setFormatter

When providing a logger handler with a formatter class, there is no documentation stating if that formatter class needs to be initialized before passing it as an argument. Through trial and error, I found that it needs to be initialized first. Please either clarify the documentation or have underlying code check to see if the formatter is initialized yet.

Problemed formatter configuration:

handler.setFormatter(xml_log_formatter)
logging.info('test_msg')

Error:

Fixed formatter configuration:

handler.setFormatter(xml_log_formatter())
logging.info('test_msg')

Purposed code check (from a custom logging module):

#Instantiate formatter class (if needed)
if isinstance(cls.log_formatter, type):
    cls.log_formatter = cls.log_formatter()

Linked PRs

@jlynchMicron

@jlynchMicron I would like to work on this, I wanted to ask how necessary the proposed change to the setFormatter method is. Would allowing it to accept both formatter instances and classes have a significant impact on the usability or functionality of the logging module? The current behavior works if users follow the documentation, though it could be clearer.

Is this change something that is critical to address, or would clarifying the documentation alone be sufficient?

@Uvi-12

Hi @Uvi-12, I believe clarification in the documentation would totally be sufficient. The error message generated when using an un-initialized formatter class is not very clear to a more novice programmer, especially when their formatter.format function does have a "record" positional argument.

@Uvi-12

Hi @Uvi-12, I believe clarification in the documentation would totally be sufficient. The error message generated when using an un-initialized formatter class is not very clear to a more novice programmer, especially when their formatter.format function does have a "record" positional argument.

Thank you for the clarification! I understand that the error message can be confusing, especially for novice users. Given that, I’ll go ahead and work on improving the documentation to make it clearer and help prevent misunderstandings related to un-initialized formatter classes.

Let me know if there are any additional points I should consider while working on this!

I think that should be it, thanks!

@jlynchMicron

@jlynchMicron Please check PR #127850 and let me know if it solves the issue.

@Uvi-12

@Uvi-12 looks good to me!

gh-127805: Clarify Formatter initialization in logging.rst. (GH-127850)

pythongh-127805: Clarify Formatter initialization in logging.rst. (py…

[3.12] gh-127805: Clarify Formatter initialization in logging.rst. (G…

[3.13] gh-127805: Clarify Formatter initialization in logging.rst. (G…

Navigation Menu

Repository navigation

Logger formatter class initialization state clarification #127805

Documentation

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Logger formatter class initialization state clarification #127805

Description

Documentation

Linked PRs

Activity

Uvi-12 commented on Dec 11, 2024

jlynchMicron commented on Dec 11, 2024

Uvi-12 commented on Dec 11, 2024

jlynchMicron commented on Dec 11, 2024

Uvi-12 commented on Dec 12, 2024

jlynchMicron commented on Dec 13, 2024

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions