classification
Title: contextlib doc bug
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Kwpolska, SilentGhost, YoSTEALTH, altendky, docs@python, marco.buttu, orsenthil
Priority: normal Keywords: patch

Created on 2017-01-02 16:54 by YoSTEALTH, last changed 2017-01-04 15:56 by altendky. This issue is now closed.

Files
File name Uploaded Description Edit
contextlib.patch marco.buttu, 2017-01-02 19:11
Messages (7)
msg284489 - (view) Author: (YoSTEALTH) * Date: 2017-01-02 16:54
Link: https://docs.python.org/3/library/contextlib.html#contextlib.ContextDecorator

"from contextlib import ContextDecorator

class mycontext(ContextBaseClass, ContextDecorator):"

"ContextBaseClass" is referenced but its no where to be found in source.
msg284491 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2017-01-02 17:41
ContextBaseClass is meant to represent a user-defined class that is a parent of mycontext.
msg284495 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-01-02 19:11
Going a bit OT, in the contextlib doc there are two examples that have both normal code and shell code in the same code block. In this way we loose the prompt syntax highlight, and the code block can also confuse the reader.  In the patch attached the two examples are executed entirely in the shell, and both are under doctest.
msg284496 - (view) Author: (YoSTEALTH) * Date: 2017-01-02 19:50
@SilentGhost
You are right, I see it now!

If this is the case maybe "ContextBaseClass" should be changed to "UserDefinedContextClass" (or something...) having "Base" in the class name was confusing, since module "io" has IOBase class that refer to its "base class" figured it was the same concept for contextlib as well.

Also it would be nice if example was improved a bit.


Another Idea:
 - why not have an empty context manager base class? like:

def ContextBase:

    def __enter__(self):
        return self

    def __exit__(self, *errors):
        pass

This is something anyone can use to extend their class to support context manager? I actually have a class like this i have used many times in my projects! Its simple yet useful.
msg284497 - (view) Author: (YoSTEALTH) * Date: 2017-01-02 19:52
typo:
def ContextBase:
to
class ContextBase:
msg284609 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2017-01-04 05:09
I am going to vote for "not a bug" here. From the context is it understood that the `ContextBaseClass` is to be provided by the user.

> Existing context managers that already have a base class can be extended by using ContextDecorator as a mixin class:

The idea here is the illustrate the Mixin possibility with a Base class and not to provide a full example with Base class code as well.

@Marco, also not a good ticket add more doc strings to this module.rst. If the docs of those can be improved, they can done separately, concentrating on all the possible improvements.
msg284644 - (view) Author: Kyle Altendorf (altendky) * Date: 2017-01-04 15:56
I would think that the idea of simply adding some reference to `User` such as was suggested with `UserDefinedContextClass` would be reasonable and helpful.  This doesn't involve any more code merely a more explanatory name.
History
Date User Action Args
2017-01-04 15:56:37altendkysetnosy: + altendky
messages: + msg284644
2017-01-04 05:09:06orsenthilsetstatus: open -> closed

nosy: + orsenthil
messages: + msg284609

resolution: not a bug
2017-01-03 10:40:55SilentGhostsetnosy: + docs@python
versions: + Python 3.5, Python 3.6, Python 3.7
assignee: docs@python
components: + Documentation
type: behavior
stage: patch review
2017-01-02 19:52:38YoSTEALTHsetmessages: + msg284497
2017-01-02 19:50:59YoSTEALTHsetmessages: + msg284496
2017-01-02 19:11:12marco.buttusetfiles: + contextlib.patch

nosy: + marco.buttu
messages: + msg284495

keywords: + patch
2017-01-02 17:41:32SilentGhostsetnosy: + SilentGhost
messages: + msg284491
2017-01-02 16:57:50Kwpolskasetnosy: + Kwpolska
2017-01-02 16:54:11YoSTEALTHcreate