[New-bugs-announce] [issue31742] Default to emitting FutureWarning for provisional APIs

[Nick Coghlan]

New submission from Nick Coghlan <ncoghlan at gmail.com>:

Chatting to Donald Stufft and Amber Brown about the way we currently handle provisional APIs, I think they have a legitimate concern that we may not be gathering adequately informed consent from users when they depend on APIs that we've reserved the right to change in the future.

So what I'm now wondering is whether or not it may be worth amending PEP 411 to say that all provisional modules should include an import-time snippet like the following:

    import __main__
    if not getattr(__main__, f"use_provisional_{__name__}"):
        import warnings
        warnings.warn(FutureWarning, f"The {__name__} module is currently a provisional API. New features might be added and API may change even between minor releases if deemed necessary.")

The exact wording of the warning would match the caveat used in that module's API documentation (the variant above comes from the "typing" module)

The idea here would be that *application* developers would get a FutureWarning whenever a provisional module was imported, unless they set "use_provisional_<module>" in __main__.

Storing the marker attribute in __main__ would be intended to serve two purposes:

- it's always going to be imported anyway, so the runtime cost of the new snippet in the provisional modules will be low
- it sends a clear indication to library authors that they *shouldn't* be setting the flag implicitly as a side-effect of import (framework authors, by contrast, may decide to set it, since they're more in control of the overall application behaviour than library authors)

----------
messages: 304006
nosy: dstufft, gvanrossum, ncoghlan
priority: normal
severity: normal
stage: needs patch
status: open
title: Default to emitting FutureWarning for provisional APIs
type: enhancement
versions: Python 3.6, Python 3.7

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue31742>
_______________________________________