Simplify hiding developer warnings in user facing applications

[ncoghlan]

BPO	32229
Nosy	@ncoghlan, @bitdancer

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2017-12-06.04:33:06.128>
labels = ['type-feature', '3.7']
title = 'Simplify hiding developer warnings in user facing applications'
updated_at = <Date 2017-12-06.14:32:30.911>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2017-12-06.14:32:30.911>
actor = 'r.david.murray'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = []
creation = <Date 2017-12-06.04:33:06.128>
creator = 'ncoghlan'
dependencies = []
files = []
hgrepos = []
issue_num = 32229
keywords = []
message_count = 5.0
messages = ['307701', '307734', '307736', '307737', '307740']
nosy_count = 2.0
nosy_names = ['ncoghlan', 'r.david.murray']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue32229'
versions = ['Python 3.7']

[ncoghlan]

One of the observations coming out of the PEP-565 discussions is that it's surprisingly tricky to opt-in to getting all warnings from a particular package and its subpackages, while opting out of warnings in general.

The simplest approximation is to do the following:

    if not sys.warnoptions:
        warnings.simplefilter("ignore")
        warnings.filterwarnings("default", module="app_pkg.*")

That shows warnings for any module or package starting with app_pkg. A stricter filter that avoided warnings from top-level packages that merely shared the prefix would look like:

    if not sys.warnoptions:
        warnings.simplefilter("ignore")
        warnings.filterwarnings("default", module="^app_pkg(\..*)?$")

It could be helpful to encapsulate that logic in a more declarative utility API, such that applications could do the following:

    import warnings.
    warnings.hide_warnings()

Or:

    import warnings.
    warnings.hide_warnings(override_warnoptions=True)

Or:

    import warnings.
    warnings.hide_warnings(show=["app_pkg"])

Proposed API:

    def hide_warnings(*, show=(), override_warnoptions=False):
        if override_warnoptions or not sys.warnoptions:
            simplefilter("ignore")
            for pkg_name in show:
                pkg_filter =  _make_regex_for_pkg(pkg_name)
                filterwarnings("default", module=pkg_filter)

[bitdancer]

I haven't been following that discussion, and isolated from that that discussion the title of this issue and this proposal make no sense to me. Warnings are off by default, so you don't need to hide them. In what context does this get used? If this is going to be used to implement turning warnings on for the main application, why isn't it named "show_warnings"?

[ncoghlan]

Warnings aren't off by default in general - we just add implicit "ignore" filters for a few specific types.

So the primary functionality is to opt in to hiding *all* warnings, but to do it in a way that can be overridden by PYTHONWARNINGS, the interpreter's "-W" switch and the new "-X dev" mode.

For that, the usage looks like:

    import warnings
    warnings.hide_warnings()

Essentially, it flips the default behaviour over to "ignore everything", but reverts to the regular default if there are any config settings supplied.

The odd structure of my opening message arises from the fact that *given* such a modified default, it's then surprisingly tricky to say "hide warnings, except for those from modules I'm responsible for". That latter complication then becomes the rationale for the design of the proposed "show" parameter to carve out exceptions to the overall "hide everything" filter.

[ncoghlan]

Note: for consistency with the underlying action names, the API should probably be called "warnings.ignore_warnings". I'd still keep the proposed parameter name as "show" though (and we may want to consider introducing that as a more semantically meaningful alias for "default").

[bitdancer]

Ah, OK, that makes more sense. I don't run into warnings other than DeprecationWarnings in practice, so I tend to forget about them :)

I think specifying warnings filters is pretty inscrutable, in general.