[Python-Dev] Breaking undocumented API

[Ben Finney]

Steven D'Aprano <steve at pearwood.info> writes:

> 3. Treat "documented" and "public" as orthogonal, not synonymous:
> undocumented public API is not an oxymoron, and neither is documented
> private API.

+1

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

After reading the discussion for many days, I'm leaning to this position
also.

-- 
 \         “I may disagree with what you say, but I will defend to the |
  `\        death your right to mis-attribute this quote to Voltaire.” |
_o__)                   —Avram Grumer, rec.arts.sf.written, 2000-05-30 |
Ben Finney