[Python-Dev] Breaking undocumented API

[Brett Cannon]

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

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
>