[Python-Dev] Breaking undocumented API

[Brett Cannon]

On Mon, Nov 8, 2010 at 16:10, Ron Adam <rrr at ronadam.com> wrote:
>
>
> On 11/08/2010 04:01 PM, Brett Cannon wrote:
>
>>> 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?
>
> You can use comments instead of a docstring.
>
> Here are the possible cases concerned with the subject.  I'm using functions
> here for these examples, but this also applies to other objects.
>
>
> def public_api():
>    """ Should always have a nice docstring. """
>    ...
>
>
> def _private_api():
>    #
>    # Isn't it a good practice to use comments here?
>    #
>    ...

That is ugly. I already hate doing that for unittest, I'm not about to
champion that for anything else.

It would also lead to essentially requiring a docstrings for
everything that is public whether someone wants to bother to writing a
docstring or not. I don't think we should be suggesting that a
docstring be required either.

>
>
> def _publicly_documented_private_api():
>    """  Not sure why you would want to do this
>         instead of using comments.
>    """
>    ...
>
>
> def undocumented_public_api():
>    ...
>
>
> def _undocumented_private_api():
>    ...
>
>
> Out of these, the two that are problematic are the
> _publicly_documented_private_api() and the undocumented_public_api().
>
> The _publicly_documented_private_api() is a problem because people *will*
> use it even though it has a leading underscore.  Especially those who are
> new to python.
>
> The undocumented_public_api() wouldn't be a problem if all private api's
> used leading  underscore, but for older modules, it isn't always clear what
> the intention was.  Was it undocumented because the programmer simply
> forgot, or was it intended to be a private api?
>
>
>
>>> 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.
>
> No, you're not suppose to try/except imports.  That's the point.
>
> You can do that, only if you really want to abuse the intended purpose of a
> module that isn't meant to be imported in the first place.  If someone wants
> to do that, it isn't a problem.  They are well aware of the risks if they do
> it.  (This is just one option and probably one that isn't thought out very
> well.)
>
> Brett, I'm sure you can up with a better alternative.   ;-)

But I don't want to have to do that in the stdlib by remembering what
modules I should or should not import. This is just as much about
developer burden on core devs as it is making sure we don't yank the
rug out from underneath users.