[Python-Dev] Breaking undocumented API (original) (raw)

Ben Finney ben+python at benfinney.id.au
Thu Nov 18 02:08:08 CET 2010

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

More information about the Python-Dev mailing list