[Python-Dev] Breaking undocumented API

Tres Seaver tseaver at palladion.com
Thu Nov 11 14:39:54 CET 2010

Hash: SHA1

On 11/11/2010 08:23 AM, Alexander Belopolsky wrote:
> On Thu, Nov 11, 2010 at 7:01 AM, Michael Foord
> <fuzzyman at voidspace.org.uk> wrote:
> ..
>>> Is it OK to add __all__ to such modules that does not include all
>>> names not starting with an underscore?  Is it OK to then remove names
>>> that clearly were not intended to be public?
>> Given the rules I suggested, which are basically the same as the one *you*
>> are saying are already in place, if "import *" exports these names then you
>> shouldn't change that behaviour without going through the deprecation
>> process.
> I don't dispute that these are *the* rules, but my question was
> whether it is ok to break them in specific cases such as
> trace.rx_blank.  If not, how can we deprecate trace.rx_blank which is
> a regex constant?
> Another specific case is token.main.  See <http://bugs.python.org/issue10386>.

I would argue that the narrative documentation for the module is
normative for defining "public API", trumping even a pre-existing
'__all__'.  Given that all non-private stdlib modules have such docs,
nobody should be relying on '__all__' as anything other than a convenience.

Therefore, in the absence of an '__all__', adding one which conforms to
the docs should not require deprecations, as the set of applications /
modules which both use the undocumented names *and* do so via 'import *'
can be safely deemed "too small to worry about".

- -- 
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/


More information about the Python-Dev mailing list