Skip to content

gh-93162: Add ability to configure QueueHandler/QueueListener together and provide getHandlerByName() and getHandlerNames() APIs. #93269

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

Merged
ambv merged 8 commits into from
Jun 7, 2022
Merged

gh-93162: Add ability to configure QueueHandler/QueueListener together and provide getHandlerByName() and getHandlerNames() APIs. #93269

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3686d74
Add ability to configure QueueHandler/QueueListener together and prov…
vsajip May 25, 2022
2bca114
Improve cross-referencing from the NEWS item.
vsajip May 26, 2022
ef2d96d
Improve documentation and refine test.
vsajip May 27, 2022
debf516
Fix typos, add clarification.
vsajip May 27, 2022
16778fe
Make improvements based on feedback.
vsajip May 30, 2022
42d43b9
Make more improvements based on feedback.
vsajip May 31, 2022
9936dff
Refactor test, add failure cases.
vsajip May 31, 2022
a29ded8
Correct typos in documentation.
vsajip May 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Correct typos in documentation.
  • Loading branch information
@vsajip
vsajip committed May 31, 2022
commit a29ded8205dc31a64c897a1f8ee9204438cf6515
17 changes: 9 additions & 8 deletions Doc/library/logging.config.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -669,10 +669,11 @@ Configuring QueueHandler and QueueListener
If you want to configure a :class:`~logging.handlers.QueueHandler`, noting that this
is normally used in conjunction with a :class:`~logging.handlers.QueueListener`, you
can configure both together. After the configuration, the ``QueueListener`` instance
will be available as the :attr:`listener` attribute of the created handler, and that
in turn will be available to you using :func:`~logging.getHandlerByName` and passing
the name you have used for the ``QueueHandler`` in your configuration. The
dictionary schema for configuring the pair is shown in the example YAML snippet below.
will be available as the :attr:`~logging.handlers.QueueHandler.listener` attribute of
the created handler, and that in turn will be available to you using
:func:`~logging.getHandlerByName` and passing the name you have used for the
``QueueHandler`` in your configuration. The dictionary schema for configuring the pair
is shown in the example YAML snippet below.

.. code-block:: yaml

Expand All @@ -697,9 +698,9 @@ If the ``queue`` key is present, the corresponding value can be one of the follo
* A string that resolves to a callable which, when called with no arguments, returns
the :class:`queue.Queue` instance to use. That callable could be a
:class:`queue.Queue` subclass or a function which returns a suitable queue instance,
such as :func:`my.module.queue_factory`.
such as ``my.module.queue_factory()``.

* A dict with a ``()`` key which is constructed in the usual way as discussed in
* A dict with a ``'()'`` key which is constructed in the usual way as discussed in
:ref:`logging-config-dict-userdef`. The result of this construction should be a
:class:`queue.Queue` instance.

Expand All @@ -713,9 +714,9 @@ If the ``listener`` key is present, the corresponding value can be one of the fo
code.

* A string which resolves to a class which is a subclass of ``QueueListener``, such as
``'my,package.CustomListener'``.
``'my.package.CustomListener'``.

* A dict with a ``()`` key which is constructed in the usual way as discussed in
* A dict with a ``'()'`` key which is constructed in the usual way as discussed in
:ref:`logging-config-dict-userdef`. The result of this construction should be a
callable with the same signature as the ``QueueListener`` initializer.
Comment on lines +720 to +721
Copy link
Copy Markdown
Contributor

@spacemanspiff2007 spacemanspiff2007 Jun 3, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The result of this construction should be a callable with the same signature...

Does that mean () will be resolved, then called with the dict args and the result of that call should return a callable again?

Copy link
Copy Markdown
Member Author

@vsajip vsajip Jun 3, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. The callable will be called just as QueueListener would be.

Copy link
Copy Markdown
Contributor

@spacemanspiff2007 spacemanspiff2007 Jun 3, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But that's different than the normal behavior of '()':

In order to provide complete flexibility for user-defined object instantiation, the user needs to provide a ‘factory’ - 
a callable which is called with a configuration dictionary and which returns the instantiated object.

from docs.
Note that the return normally is not a callable but an instantiated object.

Copy link
Copy Markdown
Member Author

@vsajip vsajip Jun 4, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but in this case the value to be returned is documented explicitly. How can it be returned as an instantiated object in this case, if it has no access to the queue?

Copy link
Copy Markdown
Member Author

@vsajip vsajip Jun 4, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also note that "instantiated object" is a generic term. It does not imply any specific type of object, and a callable is also an instantiated object.

Copy link
Copy Markdown
Contributor

@spacemanspiff2007 spacemanspiff2007 Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think it would be possible to provide an example in the docs?
That'll make things more clear.

Copy link
Copy Markdown
Member Author

@vsajip vsajip Jun 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feel free to submit a documentation PR with what you think should be in there, and I'll take a look.


Expand Down