This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author ncoghlan
Recipients dstufft, gvanrossum, hawkowl, ncoghlan
Date 2017-10-10.07:03:55
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1507619035.75.0.213398074469.issue31742@psf.upfronthosting.co.za>
In-reply-to
Content
I think if someone is going to be put off by a FutureWarning, then that indicates they're not yet familiar with just what the provisional API status means, and those are exactly the folks we *want* to scare away from provisional APIs (or features in third party libraries and frameworks that depend on them).

After all, if "Set 'use_provisional_<module> = True' in __main__" is more of an inconvenience than someone is prepared to tolerate to enable warning-free access to a still evolving feature, imagine how upset they'd be if we actually *did* make a breaking change to that API.

I did realise my draft warning was missing a bit though, which was to explain how to turn it off:

    import __main__
    _feature_flag = f"use_provisional_{__name__}"
    if not getattr(__main__, _feature_flag):
        import warnings
        _provisional_msg = f"The {__name__} module is currently a provisional API - see documentation for details. Set '__main__.{_feature_flag} = True' to disable this warning."
        warnings.warn(FutureWarning, _provisional_msg)

I also revised the draft message to account for Guido's observation about even "provisional" APIs being mostly stable by directing folks to the module documentation for details. That way the maintainers of the provisional API don't need to duplicate their explanation of how provisional the module actually is (e.g. the typing docs make it clear that feature additions and API changes are currently in scope for maintenance releases, but outright removal isn't listed as a possible outcome).

Folks that want to always opt-in to various features in their REPL sessions can then set them via PYTHONSTARTUP.

I'll also note here why I'm proposing this as a per-process flag rather than a per-module one:

- checking a feature flag in __main__ is easy, checking a flag in the "importing module" is hard
- module caching means only the first import would actually run the code to emit the warning any way
- we know from experience that having to set per-module __future__ flags to access backwards incompatible syntax changes genuinely *is* annoying (to the point where we'll implement clever tricks like those Yury came up with for native coroutines to avoid needing them)
History
Date User Action Args
2017-10-10 07:03:55ncoghlansetrecipients: + ncoghlan, gvanrossum, dstufft, hawkowl
2017-10-10 07:03:55ncoghlansetmessageid: <1507619035.75.0.213398074469.issue31742@psf.upfronthosting.co.za>
2017-10-10 07:03:55ncoghlanlinkissue31742 messages
2017-10-10 07:03:55ncoghlancreate