[Python-Dev] Breaking undocumented API (original) (raw)

Michael Foord fuzzyman at voidspace.org.uk
Thu Nov 11 14:57:53 CET 2010

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.rxblank. If not, how can we deprecate trace.rxblank 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.

More information about the Python-Dev mailing list