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

[Guido van Rossum]

Typically we fix this in the next feature release but not in bugfix
releases, and that's what I recommend in this case. But deciding
remains an art, not an exact science.

People who catch specific lists of exceptions based on experience are
bound to run into trouble occasionally, so I have little pity on them
when they upgrade to the next feature release (especially when the new
behavior is more logical and follows an established standard). For
bugfix releases I like to be much more conservative, since people
often don't have control over which bugfix release is installed.

On Fri, Jan 29, 2016 at 10:14 AM, Serhiy Storchaka  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).
>
> ___
> Python-Dev mailing list
> Python-Dev@python.org
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
> https://mail.python.org/mailman/options/python-dev/guido%40python.org



-- 
--Guido van Rossum (python.org/~guido)
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Serhiy Storchaka]

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).


___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

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

[Brett Cannon]

On Fri, 29 Jan 2016 at 10:14 Serhiy Storchaka  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.
___
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com