Nick Coghlan <ncogh...@gmail.com> added the comment: A note regarding applicability if we did make a change to our approach:
* asyncio & pathlib are already non-provisional, so wouldn't be affected. * typing is still provisional, but introducing a new FutureWarning after two releases without one would be problematic, so we should probably leave it alone and only apply a policy change (if we make one) to *new* provisional APIs * the main open proposal we have for a new provisional API in 3.7 is for the interpreters module in PEP 554 (as we don't expect either execution contexts or data classes to need to be provisional). Defaulting to emitting a FutureWarning for that would be appropriate, since we already expect there to be changes over time in the way it interacts with the threading module. Accordingly, I've added Eric Snow to the nosy list here, since it's his PEP that would be most directly affected (it would need to define a new "__main__.use_provisional_interpreters" feature flag, and emit a FutureWarning on import if that wasn't set). The specific cases of our current approach to handling provisional APIs causing problems for others that came up in the original discussion were: * third party libraries (e.g. Twisted, Django) being pressured by their users to add asyncio support while asyncio was still provisional. This pushed the burden of explaining what CPython's provisional API status actually means on to the developers of those libraries, including the implication that the community support period for any particular version of the provisional API may end up being measured in months rather than the years typically implied by inclusion in the CPython standard library. * developers & users of the cattrs package getting caught by surprise when backwards incompatible changes were made to the typing module So this RFE is about ensuring that we have *adequately informed* consent when people opt-in to the more demanding requirements of using provisional APIs (i.e. you need to be able to reliably track the latest version, and if you and your users aren't in a position to commit to that, it's desirable to either not support them at all, or else treat support for them as an optional add-on until they're declared stable). It's also about helping to ensure that when folks do have questions about what it means for a Python API to be provisional, they come to *us* (the CPython core developers that are actually working on those provisional APIs) with their questions, rather than hassling third party library developers that are just trying to keep up with the related changes. For syntactic changes, we already have __future__ imports as a way for people to declare informed consent and adopt features early. We don't currently have a comparable mechanism for provisional APIs - we're just assuming that everyone advocating for early adoption of the API will also be including the appropriate caveats around the fact that it's provisional, and that this may place additional burdens on both end users attempting to use it, and third party libraries attempting to support it. We've had 5 years of experience with the provisional API R&D model now, and while some of the uses haven't caused any ecosystem level problems that we're aware of (e.g. pathlib), two of the more high profile uses (asyncio & typing) *have* caused problems, and at least some of those problems can be attributed to the fact that it's easy for people to learn of and start using a provisional API without ever looking at the standard library module documentation for it: - they may be following something they saw in a talk - they may be following an answer from Stack Overflow - they may be following a blog post or 3rd party guide rather than the standard library documentation - they may be following the documentation for a 3rd party libary or framework As a result, merely importing a provisional API doesn't really qualify as giving appropriately informed consent, while silencing a FutureWarning that's emitted by default *does*: the act of silencing the warning means that either they've read the warning themselves and decided to silence it, or else they've silenced it based on someone else's advice. This differs from DeprecationWarnings, since we know from experience (most recently with the initially proposed warnings in the locale coercion PEP) that any kind of new output on stderr can sometimes break working code. Making those opt-in thus meant that we could continue adding them as needed, but developers would be in control of when and where they actually appear (e.g. only in their test systems, instead of on end user's machines). With FutureWarnings for provisional APIs, we'd be aiming to encourage a couple of key behaviours: - for direct use in scripts and application code, set the feature flag when first adding an import of the provisional API, and have this guidance be a standard part of all third party introductions to using the provisional API - for third party libraries, either only import provisional APIs when their own users explicitly opt-in to using related experimental features, or else inform their users that they should set the feature flag appropriately when depending on the library ---------- nosy: +eric.snow _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue31742> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
