[Python-Dev] How to resolve distinguishing between documentation and implementation (original) (raw)

Brett Cannon brett at python.org
Fri Jan 29 13:26:32 EST 2016

On Fri, 29 Jan 2016 at 10:14 Serhiy Storchaka <storchaka at gmail.com> wrote:

How to resolve distinguishing between documentation and implementation if current implementation is incorrect, but third-party code can implicitly depends on it?

For example see issue26198. Currently buffer overflow of predefined buffer for "es#" and "et#" format units causes TypeError (with misleading message, but this is other story). The correct and documented exception is ValueError. User code can depend on current behavior, because TypeError is what is raised now for this type of errors, and this is what is raised for other types of errors. Unlikely authors of such code read the documentation, otherwise this issue would be reported earlier. On other hand, looks these format units are rarely used with predefined buffer (never in the stdlib since 3.5). I think it is obvious that the code in the development branch should be changed to produce documented and more logical exception. But what about bugfix releases? Changing the documentation would be misleading, changing the code can break existing code (unlikely, but).

When the potential breakage is low, I would move to the more reasonable exception and add the appropriate note to the docs and What's New about how to port pre-existing code by either changing the exception caught or catching both exceptions until support < 3.6 can be dropped by the user. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20160129/ffc5949d/attachment.html>

More information about the Python-Dev mailing list