Skip to content

logging.Formatter docstring missing processName attribute. #134360

Closed
Closed
logging.Formatter docstring missing processName attribute.#134360
Labels
docsDocumentation in the Doc dir

Description

@junhaoliao
junhaoliao
opened on May 20, 2025

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

Activity

  1. junhaoliao
    added
    docsDocumentation in the Doc dir
    on May 20, 2025
  2. github-project-automation
    added this to docs issueson May 20, 2025
  3. github-project-automation
    moved this to Todo in docs issueson May 20, 2025

  4. SofieTorch commented on May 20, 2025

    @SofieTorch
    SofieTorch
    on May 20, 2025
    Contributor

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

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

  5. vsajip
    added a commit that references this issue on May 21, 2025

    gh-134360 Add processName attribute to `logging.Formatter` docstring (G…

    c740fe3
  6. miss-islington
    added 2 commits that reference this issue on May 21, 2025

    pythongh-134360 Add processName attribute to `logging.Formatter` docs…

    0ddcf8c

    pythongh-134360 Add processName attribute to `logging.Formatter` docs…

    8ab3d64
  7. vsajip
    added 2 commits that reference this issue on May 21, 2025

    [3.13] gh-134360 Add processName attribute to `logging.Formatter` doc…

    7ada439

    [3.14] gh-134360 Add processName attribute to `logging.Formatter` doc…

    64047f7
  8. vsajip
    closed this as completedon May 21, 2025

  9. tomasr8 commented on May 21, 2025

    @tomasr8
    tomasr8
    on May 21, 2025
    Member

    Thanks @SofieTorch !!

  10. junhaoliao commented on May 21, 2025

    @junhaoliao
    junhaoliao
    on May 21, 2025
    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?

  11. junhaoliao commented on May 21, 2025

    @junhaoliao
    junhaoliao
    on May 21, 2025
    Author

    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?

  12. tomasr8 commented on May 21, 2025

    @tomasr8
    tomasr8
    on May 21, 2025
    Member

    @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.

  13. lkollar
    added a commit that references this issue on May 26, 2025

    pythongh-134360 Add processName attribute to `logging.Formatter` docs…

    77908ec
  14. Pranjal095
    added a commit that references this issue on Jul 12, 2025

    pythongh-134360 Add processName attribute to `logging.Formatter` docs…

    0bdb422
  15. taegyunkim
    added a commit that references this issue on Aug 4, 2025

    pythongh-134360 Add processName attribute to `logging.Formatter` docs…

    04d2f13
  16. gostak-dd
    added a commit that references this issue on Jun 2, 2026

    pythongh-134360 Add processName attribute to `logging.Formatter` docs…

    220525c
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dir

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions