[Python-Dev] Breaking undocumented API

Ron Adam rrr at ronadam.com
Mon Nov 8 22:36:25 CET 2010



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.

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 <object>. 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.")

Cheers,
   Ron


More information about the Python-Dev mailing list