New submission from Nick Coghlan <[email protected]>:
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 <[email protected]>
<https://bugs.python.org/issue31742>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
