[Python-Dev] Breaking undocumented API

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
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.
- -- 
===================================================================
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/

iEYEARECAAYFAkzb8ioACgkQ+gerLs4ltQ4WBwCgux91ooO8lega+HRlYClSDj/B
SdwAoIq3ZjMwEL1V7vX8sq9k/xSRhIjA
=v9Zc
-----END PGP SIGNATURE-----