On 17/11/2010 21:57, Steven D'Aprano wrote:
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.
Along with the others +1
I think how we handle the deprecations (legacy modules with unclear or
clearly wrong naming policies) is the least interesting part of this
discussion. For deprecating existing names we have *no choice* but to
proceed on a case-by-case basis evaluating how likely the deprecation is
to break other code, whether or not the name was originally intended to
be public or not. (At least that is how we *should* proceed and part of
our standard deprecation policy - it is why we aren't removing
unittest.TestCase.assertEquals and assert_ even though they are
deprecated. They are just too widely used.)
What is more important is that we have a clearly stated policy for new
modules and adding names to existing modules so that we don't have to
repeat this debate in five years time.
My suggestion, which fits in with the use of __all__ by the language and
also the convention widely in use by the community already boils down to:
* If __all__ exists it is definitive
* Imported names are never part of the public API of a module unless in
__all__ or documented to be part of the API
* Names with leading underscores are private unless in __all__ (and if
you want to export leading underscore names as part of a public API you
should define __all__ or "import *" won't export them)
* Leading underscore convention extends to packages and class members;
no members of a package or class whose name begins with a leading
underscore are public
It is still good practise that public APIs *should* be documented (and
*should* have docstrings). There is however no corollary that private
APIs should not be documented (and they may have docstrings).
All the best,
Michael Foord
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.
--
http://www.voidspace.org.uk/
READ CAREFULLY. By accepting and reading this email you agree,
on behalf of your employer, to release me from all obligations
and waivers arising from any and all NON-NEGOTIATED agreements,
licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap,
confidentiality, non-disclosure, non-compete and acceptable use
policies (”BOGUS AGREEMENTS”) that I have entered into with your
employer, its partners, licensors, agents and assigns, in
perpetuity, without prejudice to my ongoing rights and privileges.
You further represent that you have the authority to release me
from any BOGUS AGREEMENTS on behalf of your employer.
_______________________________________________
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
