[Python-Dev] Breaking undocumented API

[Guido van Rossum]

On Wed, Nov 17, 2010 at 5:08 PM, Ben Finney <ben+python at benfinney.id.au> wrote:
> 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.

Agreed on both counts.

-- 
--Guido van Rossum (python.org/~guido)