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

[Nick Coghlan]

On 16 Oct 2013 01:54, "R. David Murray" <rdmurray at bitdance.com> wrote:
>
> On Tue, 15 Oct 2013 22:57:34 +1000, Nick Coghlan <ncoghlan at gmail.com>
wrote:
> > 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. "
>
> Someone could read this and reason by analogy: "so if the *context
> manager* is named suppress, then execution will resume following the
> statement where the exception was suppressed".  They'd be wrong, of
> course, I'm just pointing out some confusion that we might still see.
>
> > 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."
>
> This should emphasize that execution resumes with the statement following
> the with block, and give that as a strong motivation for only using it
> to cover the line where the exception is to be suppressed (and there are
> likely to be very few cases where it would reasonable for it to be more
> than one line, and that is probably worth pointing out).
>
> > 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.
>
> I think 'trap' would be much clearer.  What about making the context
> manager provide the trapped exception, in a fashion similar to
> what assertRaises does?  Even if that was almost never used in practice,
> the fact that the CM provides only *one* exception no matter how
> many statements are in the with block would strongly reinforce the
> actual semantics of the construct.  It would also make it parallel to
> assertRaises, which seems like a consistency bonus.
>
> And I could see it getting used.  I think I've had code where the logic
> was: possibly trap an exception, stuff it in a variable, do some logic,
> check the variable to see if we had an exception earlier, and if so do
> something with it or otherwise branch the logic.  I won't say this is
> common, and I won't say there wouldn't often be a better way to write
> it...but I can think that it might have utility.

Yes, something along those lines is exactly what I plan to explore for 3.5.
It's a completely orthogonal question, though - suppress is specifically an
up front statement of intent for the case where you genuinely don't care if
the exception gets raised or not.

With suppress already available, the more general construct can be designed
specifically for the case where you *do* care if the exception was raised
or not.

By contrast, providing only the more general construct would mean that "I
don't care if an exception is raised or not" would be implied solely by the
absence of an "as" clause, which is a very poor way to communicate intent.

> With that change, I'd be +1.  With just suppress, I'm -0.

Please, please, please just let it drop. Even though it eventually
convinced me to change the name, this thread still epitomises everything
that sucks about soul destroying, energy draining bikeshed painting that
makes me wonder why I ever bother trying to make anything better.

Regards,
Nick.

>
> --David
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
https://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20131016/9d417126/attachment-0001.html>