On Wed, Nov 17, 2010 at 9:19 AM, Nick Coghlan <ncogh...@gmail.com> wrote: .. > 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. > +1
That's another reason why it is appropriate to document this in both Library Reference and the Developers Guide (whatever it is). In the Library Reference we can say point-blank: "This is the authoritative documentation of what Python Library provides. Anything not mentioned here is subject to change between releases without notice." In the Developers Guide, guide, however we can take a more nuanced approach that would start with a general policy that changing existing APIs public or not is costly and should not be done without significant offsetting benefit. More on this below. > 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" > 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. > Users will venture into grey area regardless of whether its existence is acknowledged or not. Developers Guide should take this into consideration, but there is no need to encourage this practice in the Library Reference. In the Developers Guide, we can list a set of factors that need to be considered when changing or removing an undocumented API. For example: 1. Does it start with an underscore? 2. Is __all__ defined for the module? Id so, is the name in __all__? 3. Is API name well chosen for what it does? 4. How old is the module? Was is written before modern policies have been adopted? 5. Is API used in the standard library outside of the module? 6. Is API broken? Can it be fixed? (If it was broken in several releases and nobody complained - it is ok to remove.) 7. Is API used? General google search or google code search can give an insight. The decision to remove an API should be always done on a case by case basis. Purely style compliance changes such as let's add __all__ and rename all names not in all by prepending an underscore should always add old names back as deprecated aliases. (Breaking from xyz import * by adding __all__ to xyz is probably ok because code using from xyz import * may be broken by any addition to xyz and users have been warned.) .. > 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. +1 _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com