[Python-Dev] Breaking undocumented API

[Ron Adam]

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?
     #
     ...


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

Cheers,
   Ron