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
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
