On Tue, Nov 16, 2010 at 8:34 AM, <exar...@twistedmatrix.com> wrote: > On 03:48 pm, gu...@python.org wrote: >> >> On Tue, Nov 16, 2010 at 7:16 AM, Alexander Belopolsky >> <alexander.belopol...@gmail.com> wrote: >>> >>> What this thread has shown is that there is no consensus on what >>> public names are and what rules should be followed when changing names >>> that can be imported from a module. I have opened an issue at >>> http://bugs.python.org/issue10434 to address this. My vote is to >>> adopt the definition spelled out in the language reference, copy it to >>> the library manual and add some discussion of the deprecation >>> policies. >> >> Hm. Apart from the specific semantics assigned by the language to >> single and double leading (and trailing) underscores, I still think >> this belongs in a style guide, not in the library manual. When reading >> the library manual, one should always assume that undocumented >> features are subject to change at any time. > > I don't think it belongs only in PEP 8 (that's "a style guide" you're > referring to, correct?). It needs to be front and center. This is > information that every single user of the stdlib needs in order to use the > stdlib correctly.
That depends on what methods you're imagining "every single user" is using to find out what the API *is*. In my experience there are many ways people do this: - by reading the source - by reading the official docs - by trial and error - inspection of objects (e.g. dir()) - using help() - by reading pydoc output collected on some website (or local disk) - by following tutorials - by reading books containing reference documentation generated by 3rd party authors Most people do several of those things. (Personally, I learned about many APIs by creating them. But I'm probably an exception. :-) > No matter how many times we discuss this policy on this list (I know it's > come up here before), the majority of python users still won't learn about > it. Agreed. And adding a disclaimer to help() or pydoc output won't make much of a difference, I expect. > PEP 8 isn't nearly visible enough, either. Whatever the rule is, it needs > to be presented with the information itself. If the rule is that things not > documented in the library manual have no compatibility guarantees, then all > of the means of getting documentation *other* than looking at the library > manual need to indicate this somehow (alternatively, the information > shouldn't be duplicated, but I doubt I'll convince anyone of that). Assuming people actually read the disclaimers. > Here's a stupid proposal. What if the top of pydoc output said (for stdlib > modules only) "The library manual is the canonical reference. Refer to it > before using APIs you find in this documentation." Still inconvenient, but > inconvenient is better than secret/impossible. Personally I think it would be sufficient if the disclaimer was at the top of the library reference itself. That's certainly enough from a legalistic "I told you so" POV and I doubt that we'll be able to move the POV of what people actually use... -- --Guido van Rossum (python.org/~guido) _______________________________________________ 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