[Python-Dev] Breaking undocumented API
tseaver at palladion.com
Thu Nov 11 14:39:54 CET 2010
-----BEGIN PGP SIGNED MESSAGE-----
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
> 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
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
-----END PGP SIGNATURE-----
More information about the Python-Dev