Skip to content

Add structured, explicit parameter list to logging.Formatter constructor #94700

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
CAM-Gerlach opened this issue Jul 9, 2022 · 0 comments · Fixed by #94701
Closed

Add structured, explicit parameter list to logging.Formatter constructor #94700

CAM-Gerlach opened this issue Jul 9, 2022 · 0 comments · Fixed by #94701
Assignees
Labels
docs Documentation in the Doc dir

Comments

@CAM-Gerlach
Copy link
Member

As discussed at length on the recent Discourse thread, logging.Formatter is a great example of a function that would particularly benefit from an explicit list of parameter names, defaults and types, like most if not nearly all third-party Python library API docs use. This will help the reader quickly, easily and accurate find the specific information they are looking for (and ensure it is present in the first place), per the primary goal of reference documentation.

The proposed revision was well-received there, so I'm going ahead with a PR here. This, in combination will followup PRs, will also reduce the substantial inconsistency between how nearby functions/methods of comparable complexity are presented, and help serve as an additional empirical testing of the proposed explicit, structured approach to be incrementally adopted on a wider scale, particularly for more complex functions like this one. Also, it revises the text to reduce or eliminate duplication and redundancy while retaining all the same information, making it much more concise and easier to read, and phrase it more clearly and directly.

Preview before and after:

image

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant