warnings: adding new filter resets prior existing "once" filters

[clark165]

Bug report

Bug description:

If a filter is defined with action="once", the occurrence tracking is reset each time a new filter is defined. This can override the ability to effectively use action="once" if the filter manipulation occurs in a library which the user cannot control (e.g. matplotlib).

For example, the following code will only output a warning once (i.e. works as intended):

import warnings

warnings.filterwarnings("once", "test warning", UserWarning)
warnings.warn("test warning", UserWarning)
warnings.warn("test warning", UserWarning)

However, simply inserting an unrelated filter prior to the second warning will cause both to be output:

warnings.filterwarnings("once", "test warning", UserWarning)
warnings.warn("test warning", UserWarning)

warnings.filterwarnings("ignore", "something unrelated")
warnings.warn("test warning", UserWarning)

CPython versions tested on:

3.14

Operating systems tested on:

Linux

[Lohitha0-0]

I'd like to work on this. After tracing the code, the reset happens
because warn_explicit() clears __warningregistry__ whenever
_filters_version changes — which happens on every filterwarnings()
call regardless of relevance.

Before implementing a fix, could a core dev confirm the preferred approach:

1. Selective registry invalidation (only clear entries matching the new filter)
2. Move "once" tracking to the global _onceregistry which isn't
   version-gated, keeping it persistent across filter changes

Also confirming: any fix needs to mirror both Lib/warnings.py and
Python/_warnings.c. Is that correct?

Happy to proceed once direction is confirmed.

[picnixz]

This can override the ability to effectively use action="once" if the filter manipulation occurs in a library which the user cannot control (e.g. matplotlib).

Not entirely, in this case you should use warnings.catch_warnings() I think though it may sometimes be not what you actually want, that I agree.

---

Does the issue occur only with the C extension module or with the pure Python implementation? AFAICT, the pure python implementation (_py_warnings) wouldn't have this issue.

[clark165]

Could you elaborate on how catch_warnings would be used to get similar behavior as warnings.filterwarnings(action="once", ...)? For example, in a loop where an underlying library call is manipulating the filter registry on each iteration. I've noticed matplotlib doing this, which is maybe worthy of its own bug report.

On the Python vs C - I was just noticing that as well. The pure python implementation doesn't seem to have this same issue:

from test.support import import_helper
warnings = import_helper.import_fresh_module('warnings', blocked=['_warnings'])

warnings.filterwarnings("once", test warning", UserWarning)
warnings.warn("test warning", UserWarning)

warnings.filterwarnings("ignore", "something unrelated")
warnings.warn("test warning", UserWarning)  # does not get displayed

So the fact that the python and C implementations don't agree seems to be the main issue which needs resolving. I would think the C implementation should be updated to align with Python?

The documentation could also be clearer on the expected behavior. Based on the Python implementation, it appears that clearing the registry upon filter version rolls is the intended behavior for action = "module" or "default", but is not for action="once".

[picnixz]

I would think the C implementation should be updated to align with Python?

Yeah, I think the C implementation has a bug here but I'm not sure it's actually possible to make it aligned with the Python one (and in this case, the Python side must be ameneded). At least, by reading the docs, there is nothing about the fact that adding a filter in between may actually reset the registry. However, we need to be careful here to understand why it's been done that way at the C level.

Could you elaborate on how catch_warnings would be used to get similar behavior as warnings.filterwarnings(action="once", ...)

Actually, suggesting catch_warnings() was a way to address "if the filter manipulation occurs in a library which the user cannot control" where "filter manipulation" is understood generically. I wanted to highlight that you still had a way to "control" a bit the warnings. In your "once" case, though, I don't have any solution (I just wanted to mention it in case you were looking for something else).

For example, in a loop where an underlying library call is manipulating the filter registry on each iteration

In this case, I think the problem is in the library. You usually register warning filters at a single place, likely called when you initialize the framework, but not in the middle of your program I think. At least, I don't know about such patterns.