[Python-Dev] cpython: Rename contextlib.ignored() to contextlib.ignore().

[Nick Coghlan]

On 15 October 2013 22:27, Antoine Pitrou <solipsis at pitrou.net> wrote:
> Le Tue, 15 Oct 2013 22:05:41 +1000,
> Nick Coghlan <ncoghlan at gmail.com> a écrit :
>
>> On 15 October 2013 13:12, Glenn Linderman <v+python at g.nevcal.com>
>> wrote:
>> > Of course, if the name were changed to be accurate, or the feature
>> > made less prone to misuse, then maybe it would terminate.
>>
>> I've come to the conclusion it makes sense to rename it from ignore to
>> suppress, since that's the term already used for this operation in the
>> rest of the context management docs: http://bugs.python.org/issue19266
>
> "suppress" and/or "trap" (which I believe is a common name for such
> operation).

I chose the new name based on the terminology used in the existing
docs (I'll grant that a lot of these docs were written by me at
various points in time, but taken together they still create a solid
precedent that "suppress" refers to discarding the exception, while
"trap" just refers to catching it and then potentially doing something
with it, including reraising it).

>From http://docs.python.org/dev/library/stdtypes.html#contextmanager.__exit__:

"Exit the runtime context and return a Boolean flag indicating if any
exception that occurred should be suppressed."

"Returning a true value from this method will cause the with statement
to suppress the exception and continue execution with the statement
immediately following the with statement. "

>From http://docs.python.org/dev/reference/datamodel.html#object.__exit__

"If an exception is supplied, and the method wishes to suppress the
exception (i.e., prevent it from being propagated), it should return a
true value."

>From http://docs.python.org/dev/library/contextlib#contextlib.contextmanager

"If an exception is trapped merely in order to log it or to perform
some action (rather than to suppress it entirely), the generator must
reraise that exception."

>From http://docs.python.org/dev/library/contextlib#contextlib.ignore (!)

"As with any other mechanism that completely suppresses exceptions, it
should only be used to cover very specific errors where silently
ignoring the exception is known to be the right thing to do."

>From http://docs.python.org/dev/library/contextlib#contextlib.ExitStack

"...if an inner callback suppresses or replaces an exception, then
outer callbacks will be passed arguments based on that updated state."

>From http://docs.python.org/dev/library/contextlib#contextlib.ExitStack.enter_context

"These context managers may suppress exceptions just as they normally
would if used directly as part of a with statement."

>From http://docs.python.org/dev/library/contextlib#contextlib.ExitStack.push

"By returning true values, these callbacks can suppress exceptions the
same way context manager __exit__() methods can."

>From http://docs.python.org/dev/library/contextlib#contextlib.ExitStack.callback

"Unlike the other methods, callbacks added this way cannot suppress
exceptions (as they are never passed the exception details)."

So, having been convinced that "ignore" was the wrong choice of name,
reviewing the docs made it clear to me what the name *should* be.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia