[Python-Dev] Breaking undocumented API (original) (raw)

Brett Cannon brett at python.org
Mon Nov 8 23:01:18 CET 2010

On Mon, Nov 8, 2010 at 13:36, Ron Adam <rrr at ronadam.com> wrote:

On 11/08/2010 01:58 PM, Brett Cannon wrote:

On Mon, Nov 8, 2010 at 09:20, Alexander Belopolsky <belopolsky at users.sourceforge.net>  wrote:

Was: [issue2001] Pydoc interactive browsing enhancement On Sun, Nov 7, 2010 at 9:17 AM, Nick Coghlan<report at bugs.python.org>  wrote: ..

I'd actually started typing out the command to commit this before it finally clicked that the patch changes public APIs of the pydoc module in incompatible ways. Sure, they aren't documented, but the fact they aren't protected by an underscore means I'm not comfortable with the idea of removing them or radically change their functionality without going through a deprecation period first.

I have a similar issue with the trace module and would appreciate some guidance on this as well.  The trace module documented API includes just the Trace class, but the module defines several helper functions and classes  that do not start with a leading underscore and are not excluded from * imports by all.  (There is no trace.all.) I think we need to, as a group, decide how to handle undocumented APIs that don't have a leading underscore: they get treated just the same as the documented APIs, or are they private regardless and thus we can change them at our whim? My understanding is that anything with an actual docstring is part of the public API.  Any thing with a leading underscore is private.

That's a bad rule. Why shouldn't I be able to document something that is not meant for the public so that fellow developers know what the heck should be going on in the code?

And to a lesser extent, objects with out docstrings, but have comments instead or nothing, may change, so don't depend on them.  Thankfully most things do have docstrings.

I freely admit that I have more questions than answers, so I would like to hear from a wider audience. The main reason I have said that non-underscore names should be properly deprecated (assuming they are not contained in an underscored-named module) is that dir() and help() do not distinguish. If you are perusing a module from the interpreter prompt you have no way to know whether something is public or private if it lacks an underscore. Is it reasonable to assume that any API found through dir() or help() must be checked with the official docs before you can consider using it, even if you have no explicit need to read the official docs? I (unfortunately) say no, which is why I have argued that non-underscored names need to be properly deprecated. This obviously places a nasty burden on us, though, so I don't like taking this position. Unless we can make it clearly known through help() or something that the official docs must be checked to know what can and cannot be reliably used I don't think it is reasonable to force users to not be able to rely on help() (we should probably change help() to print a big disclaimer for anything with a leading underscore, though). +1 on the help disclaimer for objects with leading underscores. Currently help() does not see comments when they are used in place of a docstring.  I think it would be easy to have help notate things with no docstrings as "Warning: Undocumented . Use at your own risk." At first, it would probably have a nice side effect of getting any public API's documented with doc strings. (if they aren't already.) But that doesn't mean we can't go through, fix up our names, and deprecate the old public names; that's fair game in my book. I agree. It may also be useful to clarify that importing some "utility" modules is not recommended because they may be changed more often and may not follow the standard process.  Would something like the following work, but still allow for importing if the exception is caught with a try except? if name == "main":  main() else:  raise ImportWarning("This is utility module and may be changed.")

Sure it would work, but that doesn't make it pleasant to use. It already breaks how warnings are typically handled by raising it instead of calling warnings.warn(). Plus I'm now supposed to try/except certain imports? That's messy. At that point we are coding in visibility rules instead of following convention and that doesn't sit well with me.

-Brett

Cheers,  Ron

Python-Dev mailing list Python-Dev at python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/brett%40python.org

More information about the Python-Dev mailing list