Skip to content

logging.Formatter docstring missing processName attribute. #134360

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.

Sign up for GitHub

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

Jump to bottom
Closed
junhaoliao opened this issue May 20, 2025 · 5 comments
Closed

logging.Formatter docstring missing processName attribute. #134360

junhaoliao opened this issue May 20, 2025 · 5 comments
Labels
docs Documentation in the Doc dir

Comments

@junhaoliao
Copy link

junhaoliao commented May 20, 2025 •
edited by bedevere-app bot
Loading

Documentation

The docstring for logging.Formatter class is missing the processName attribute that is available in LogRecord and documented in the official Python documentation.

Issues

The processName attribute is documented in the LogRecord attributes section of the Python documentation, but it's not listed in the Formatter class docstring that enumerates the attributes users can include in format strings.

cpython/Doc/library/logging.rst

Lines 995 to 1075 in ec39fd2

+----------------+-------------------------+-----------------------------------------------+
| Attribute name | Format | Description |
+================+=========================+===============================================+
| args | You shouldn't need to | The tuple of arguments merged into ``msg`` to |
| | format this yourself. | produce ``message``, or a dict whose values |
| | | are used for the merge (when there is only one|
| | | argument, and it is a dictionary). |
+----------------+-------------------------+-----------------------------------------------+
| asctime | ``%(asctime)s`` | Human-readable time when the |
| | | :class:`LogRecord` was created. By default |
| | | this is of the form '2003-07-08 16:49:45,896' |
| | | (the numbers after the comma are millisecond |
| | | portion of the time). |
+----------------+-------------------------+-----------------------------------------------+
| created | ``%(created)f`` | Time when the :class:`LogRecord` was created |
| | | (as returned by :func:`time.time_ns` / 1e9). |
+----------------+-------------------------+-----------------------------------------------+
| exc_info | You shouldn't need to | Exception tuple (à la ``sys.exc_info``) or, |
| | format this yourself. | if no exception has occurred, ``None``. |
+----------------+-------------------------+-----------------------------------------------+
| filename | ``%(filename)s`` | Filename portion of ``pathname``. |
+----------------+-------------------------+-----------------------------------------------+
| funcName | ``%(funcName)s`` | Name of function containing the logging call. |
+----------------+-------------------------+-----------------------------------------------+
| levelname | ``%(levelname)s`` | Text logging level for the message |
| | | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, |
| | | ``'ERROR'``, ``'CRITICAL'``). |
+----------------+-------------------------+-----------------------------------------------+
| levelno | ``%(levelno)s`` | Numeric logging level for the message |
| | | (:const:`DEBUG`, :const:`INFO`, |
| | | :const:`WARNING`, :const:`ERROR`, |
| | | :const:`CRITICAL`). |
+----------------+-------------------------+-----------------------------------------------+
| lineno | ``%(lineno)d`` | Source line number where the logging call was |
| | | issued (if available). |
+----------------+-------------------------+-----------------------------------------------+
| message | ``%(message)s`` | The logged message, computed as ``msg % |
| | | args``. This is set when |
| | | :meth:`Formatter.format` is invoked. |
+----------------+-------------------------+-----------------------------------------------+
| module | ``%(module)s`` | Module (name portion of ``filename``). |
+----------------+-------------------------+-----------------------------------------------+
| msecs | ``%(msecs)d`` | Millisecond portion of the time when the |
| | | :class:`LogRecord` was created. |
+----------------+-------------------------+-----------------------------------------------+
| msg | You shouldn't need to | The format string passed in the original |
| | format this yourself. | logging call. Merged with ``args`` to |
| | | produce ``message``, or an arbitrary object |
| | | (see :ref:`arbitrary-object-messages`). |
+----------------+-------------------------+-----------------------------------------------+
| name | ``%(name)s`` | Name of the logger used to log the call. |
+----------------+-------------------------+-----------------------------------------------+
| pathname | ``%(pathname)s`` | Full pathname of the source file where the |
| | | logging call was issued (if available). |
+----------------+-------------------------+-----------------------------------------------+
| process | ``%(process)d`` | Process ID (if available). |
+----------------+-------------------------+-----------------------------------------------+
| processName | ``%(processName)s`` | Process name (if available). |
+----------------+-------------------------+-----------------------------------------------+
| relativeCreated| ``%(relativeCreated)d`` | Time in milliseconds when the LogRecord was |
| | | created, relative to the time the logging |
| | | module was loaded. |
+----------------+-------------------------+-----------------------------------------------+
| stack_info | You shouldn't need to | Stack frame information (where available) |
| | format this yourself. | from the bottom of the stack in the current |
| | | thread, up to and including the stack frame |
| | | of the logging call which resulted in the |
| | | creation of this record. |
+----------------+-------------------------+-----------------------------------------------+
| thread | ``%(thread)d`` | Thread ID (if available). |
+----------------+-------------------------+-----------------------------------------------+
| threadName | ``%(threadName)s`` | Thread name (if available). |
+----------------+-------------------------+-----------------------------------------------+
| taskName | ``%(taskName)s`` | :class:`asyncio.Task` name (if available). |
+----------------+-------------------------+-----------------------------------------------+
.. versionchanged:: 3.1
*processName* was added.
.. versionchanged:: 3.12
*taskName* was added.

Missing attribute:

  • processName - Process name (if available), added in Python 3.1

Suggested Fix

Add the processName attribute to the docstring with its description:

%(processName)s Process name (if available)

Linked PRs
@junhaoliao junhaoliao added the docs Documentation in the Doc dir label May 20, 2025
@SofieTorch SofieTorch mentioned this issue May 20, 2025
Merged
@SofieTorch
Copy link
Contributor

SofieTorch commented May 20, 2025 •
edited
Loading

I'm working on this! As part of the PyCon US 25 sprints :)

Already opened a PR: #134371, waiting for review.

vsajip pushed a commit that referenced this issue May 21, 2025
@SofieTorch
gh-134360 Add processName attribute to logging.Formatter docstring (G…
c740fe3 
…H-134371)
miss-islington pushed a commit to miss-islington/cpython that referenced this issue May 21, 2025
@SofieTorch @miss-islington
pythongh-134360 Add processName attribute to logging.Formatter docs…
0ddcf8c 
…tring (pythonGH-134371)

(cherry picked from commit c740fe3)

Co-authored-by: Sofia Toro <sofie.torch@outlook.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue May 21, 2025
@SofieTorch @miss-islington
pythongh-134360 Add processName attribute to logging.Formatter docs…
8ab3d64 
…tring (pythonGH-134371)

(cherry picked from commit c740fe3)

Co-authored-by: Sofia Toro <sofie.torch@outlook.com>
This was referenced May 21, 2025
Merged
Merged
vsajip pushed a commit that referenced this issue May 21, 2025
@miss-islington @SofieTorch
[3.13] gh-134360 Add processName attribute to logging.Formatter doc…
7ada439 
…string (GH-134371) (GH-134404)

Co-authored-by: Sofia Toro <sofie.torch@outlook.com>
vsajip pushed a commit that referenced this issue May 21, 2025
@miss-islington @SofieTorch
[3.14] gh-134360 Add processName attribute to logging.Formatter doc…
64047f7 
…string (GH-134371) (GH-134405)

Co-authored-by: Sofia Toro <sofie.torch@outlook.com>
@vsajip vsajip closed this as completed May 21, 2025
@tomasr8
Copy link
Member

tomasr8 commented May 21, 2025

Thanks @SofieTorch !!

@junhaoliao
Copy link
Author

Thanks @SofieTorch @vsajip @tomasr8 . I actually had the change before submitting this detailed issue, went for lunch and saw a PR was already put up. And now the PR has been merged. All was done in less than a day which is really amazing.

Is PyCon US 25 a competition of some sort? I was going to set an assignee as me on the issue but wasn't able to due to lack of access. I guess this one-line change is minor, but is there a way to avoid duplicate work by contributors?

@junhaoliao
Copy link
Author

junhaoliao commented May 21, 2025 •
edited
Loading

These are some other items I wanted to address in the PR draft:

  • Do we need to add the versionchanged footnotes to the Formatter docstring?
  • Also, there's a missing ending parenthesis as shown in L2085 in junhaoliao@ded89bf .

Shall we file a separate issues / PRs for the fixes?

@tomasr8
Copy link
Member

tomasr8 commented May 21, 2025

@junhaoliao Sorry about that! I didn't realize you were already working on it :/

When you open an issue that you are planning to work on, you can mention it in the description so that others know not to pick up the issue 🙂

The PyConUS sprints are currently taking place so there are lots of new contributors around :)

Do we need to add the versionchanged footnotes to the Formatter docstring?

Not sure, some other docstrings in the module do have those notes. What do you think @vsajip ?

Also, there's a missing ending parenthesis as shown in L2085

We normally don't encourage purely stylistic changes/typo fixes but it ultimately depends on the module maintainer if they want to make that change. A separate issue would not be needed for this though, a PR is fine.

lkollar pushed a commit to lkollar/cpython that referenced this issue May 26, 2025
@SofieTorch @lkollar
pythongh-134360 Add processName attribute to logging.Formatter docs…
77908ec 
…tring (pythonGH-134371)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Documentation in the Doc dir
Projects
docs issues
Status: Todo
Milestone
No milestone
Development

No branches or pull requests
4 participants
@vsajip @tomasr8 @junhaoliao @SofieTorch