Nick Coghlan wrote:
The policy we're aiming to clarify here is what we should do when we
come across standard library APIs that land in the grey area, with
there being two appropriate ways to deal with them:
1. Document them and make them officially public
2. Deprecate the public names and make them officially private (with
the public names later removed in accordance with normal deprecation
procedures)
You missed at least two other options:
3. Treat "documented" and "public" as orthogonal, not synonymous:
undocumented public API is not an oxymoron, and neither is documented
private API.
4. Do nothing. Inertia wins. Is this problem we're trying to solve so
serious that we need to solve it now except on a case-by-case basis?
The approach that gives us the most flexibility is #3. Clearly one would
not need to document private APIs for the use of the general public, but
adding docstrings to private functions and classes for in-house use is a
sensible thing to do. This applies equally to the standard library as to
any other major project.
Likewise, one might introduce a public function into some module, but
for whatever reason, choose not to document it. (Perhaps it's a lack of
hours in the day, perhaps it is a deliberate decision.) In this case,
the mere lack of documentation shouldn't relieve us of the
responsibility of treating the function as public.
For emphasis: I strongly believe that public/private and
documented/undocumented are orthogonal qualities, and should not be
treated as, or forced to be, identical.
The use of imported modules is possibly an exception. If a user is
writing something like (say) getopt.os.getcwd() instead of importing os
directly, then they're on shaky ground. We shouldn't expect module
authors to write "import os as _os" just to avoid making os a part of
their public API.
I'd be prepared to make an exception to the rule "no leading underscore
means public": imported modules are implementation details unless
explicitly documented otherwise. E.g. the os module explicitly makes
path part of its public API, but os.sys is an implementation detail.
--
Steven
_______________________________________________
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
