[Python-Dev] Breaking undocumented API

[Michael Foord]

On 11/11/2010 13:39, Tres Seaver wrote:
> -----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".

I don't think this is generally sufficient given the not-infrequent 
occurrence of undocumented-but-used APIs in the standard library.

Another example is re.Scanner.

http://bugs.python.org/issue5337

Making the rules explicit and following a deprecation process seems like 
a sensible way forward to me. That still leaves Alexander's question 
open; how to handle module level constants that can't easily be formally 
deprecated. One possibility is using something similar to the twisted 
technique for deprecating module constants. That would mean adding code 
to the standard library to do this.

I would say that if it seems unlikely that the constants are used in the 
wild, and google code search confirms this, then it is fine to skip the 
deprecation process. If there are known uses we should at least document 
the deprecation (and alias) for a release before removing.

All the best,

Michael


>
> 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-----
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk


-- 

http://www.voidspace.org.uk/

READ CAREFULLY. By accepting and reading this email you agree,
on behalf of your employer, to release me from all obligations
and waivers arising from any and all NON-NEGOTIATED agreements,
licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap,
confidentiality, non-disclosure, non-compete and acceptable use
policies (”BOGUS AGREEMENTS”) that I have entered into with your
employer, its partners, licensors, agents and assigns, in
perpetuity, without prejudice to my ongoing rights and privileges.
You further represent that you have the authority to release me
from any BOGUS AGREEMENTS on behalf of your employer.