On 17/11/2010 14:19, Nick Coghlan wrote: > On Wed, Nov 17, 2010 at 11:45 PM, Fred Drake<fdrake at acm.org> wrote: >> On Wed, Nov 17, 2010 at 8:30 AM, Nick Coghlan<ncoghlan at gmail.com> wrote: >>> The library documentation is *not* the right place for quibbling about >>> what constitutes a public API when using other means than the library >>> documentation to find APIs to call. >> Quibbling can happen on the mailing list, where it can be ignored by >> those who aren't interested. >> >> But the documentation is the right place to document what we come up >> with for the standard library. I expect what the tools do will inform >> any decisions, and the tools (those in the stdlib) will henceforth be >> maintained with that in mind. >> >> I *am* suggesting that the scope of this be restricted to what's >> appropriate for the standard library, rather than a general >> recommendation for others. Third-party projects are free to use what >> we come up with, or provide their own policies. That's theirs to >> decide, and I see no value in interfering with that. > The standard library documentation should say that the public API is > what the documentation says it is. Officially, anyone going outside > those documented APIs should not be surprised if things get removed or > changed arbitrarily without warning. That has long been the python-dev > policy and I, for one, don't think it should change. > > What we're talking about in this thread is what to do in the grey area > of APIs which are not included in the official documentation, but also > don't have names starting with an underscore so they "look public" We're *also* discussing codifying the naming conventions (or using __all__) within the standard library, so it isn't just about deprecations (which is why I think PEP 8 rather than PEP 5). This is so that in the future if a name looks public users can have more confidence that it actually is... Obviously what to do about modules that don't follow these rules currently is a big part of it (and how the discussion started). All the best, Michael > when reading the source code or exploring the API in the interactive > interpreter. It *may* be appropriate for the standard library > documentation to acknowledge that this grey area exists (I'm not yet > convinced on that point), but it definitely should *not* be > encouraging anyone to rely on it or on our policies for dealing with > it. > > The policy we're aiming to clarify here is what we should do when we > come across standard library APIs that land in the grey area, with > there being two appropriate ways to deal with them: > 1. Document them and make them officially public > 2. Deprecate the public names and make them officially private (with > the public names later removed in accordance with normal deprecation > procedures) > > The actual approach taken will vary on a case-by-case basis (and is a > little trickier in the case of module level globals, since those can't > be deprecated properly), but is always aimed at bringing the standard > library more into line with the official position (i.e. APIs are > either public-and-documented or private). > > So the official policy from a language *user* point of view would > remain unchanged (i.e. if it isn't documented, you're on your own). As > a *pragmatic* policy, however, we would explicitly acknowledge that > developers may inadvertently use an undocumented API without realising > that it isn't technically public, and hence apply the normal > deprecation process even though the official policy says we don't have > to. > > Regards, > Nick. > -- http://www.voidspace.org.uk/
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4