On Mon, Nov 8, 2010 at 16:10, Ron Adam <r...@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.
_______________________________________________
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
