[Python-Dev] How to resolve distinguishing between documentation and implementation

[Brett Cannon]

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>