With 343 accepted, we can now add __enter__() and __exit__() methods to objects.
What term should describe those objects in the documentation?
For instance, if the new magic methods are added to decimal.Context(), do we then describe Context objects as "withable" ;-)
The PEP itself doesn't provide much of a clue. The terms "template", "wrapper", and "block" are over-broad and do not provide a metaphor for setup/teardown, r entry/exit, or initialization/finalization.
Whatever term is selected, it should be well thought-out and added to the glossary. The choice of words will likely have a great effect on learnability and on how people think about the new tool.
Raymond
"Raymond Hettinger" raymond.hettinger@verizon.net writes:
With 343 accepted, we can now add __enter__() and __exit__() methods to objects.
What term should describe those objects in the documentation?
Hmm, don't know.
I talked about an object 'that conformed to the with protocol' at EuroPython, which seems about right -- but is hardly an adjective!
Guard? Monitor? Don't really like either of these.
Cheers, mwh
"Michael Hudson" mwh@python.net wrote in message news:2macl7xxpa.fsf@starship.python.net...
Guard? Monitor? Don't really like either of these.
I know I am late, but since guard means something else, 'sentinel' (in the line of __enter__ and __exit__ interpretation) could be an alternative. Tongue in cheek.
"Resource managed"?
On 6/30/05, Raymond Hettinger raymond.hettinger@verizon.net wrote:
With 343 accepted, we can now add __enter__() and __exit__() methods to objects.
What term should describe those objects in the documentation?
For instance, if the new magic methods are added to decimal.Context(), do we then describe Context objects as "withable" ;-)
The PEP itself doesn't provide much of a clue. The terms "template", "wrapper", and "block" are over-broad and do not provide a metaphor for setup/teardown, r entry/exit, or initialization/finalization.
Whatever term is selected, it should be well thought-out and added to the glossary. The choice of words will likely have a great effect on learnability and on how people think about the new tool.
Raymond
Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/brett%40python.org
Raymond Hettinger wrote:
Whatever term is selected, it should be well thought-out and added to the glossary. The choice of words will likely have a great effect on learnability and on how people think about the new tool.
When writing PEP 346, I ended up choosing "user defined statement" as a generic term for the sundry ways that the 'with' statement could be used. Signal blocking, exception logging, transactions, resource management, etc. . .
For me, the key point was that to understand what a 'with' statement is really doing, you needed to understand the behaviour of the supplied object. This is far less the case with other compound Python statements.
For 'if' statements and 'while' loops, the supplied object will always be interpreted as a boolean. In 'for' loops, the supplied object is guaranteed to return a series of other objects. An 'except' clause always expects an exception type of some description.
For 'with' statements, all we really know is that the object may do something before the suite it is entered, and something else as the suite is exited. Other than that, it could be (or do) anything. Hence, 'user defined statement'.
With that piece of terminology in place, the natural outcome was to call objects that supplied __enter__ and __exit__ methods "statement templates".
I also used this term to come up with PEP 346's name for the generator to statement template conversion decorator: "stmt_template"
(Like others, the fact that 'with' is a verb makes it very hard for me to interpret "with_template" correctly when I see it as a decorator - I always want to ask "with which template?")
Cheers, Nick.
Nick Coghlan wrote:
Raymond Hettinger wrote:
Whatever term is selected, it should be well thought-out and added to the glossary. The choice of words will likely have a great effect on learnability and on how people think about the new tool.
I tried to bring this up on python-list, but I didn't get much of a response. I suggested "witherator" as a too cute alternative, but was hoping to get some alternatives to that.
http://mail.python.org/pipermail/python-list/2005-June/286684.html
For 'with' statements, all we really know is that the object may do something before the suite it is entered, and something else as the suite is exited. Other than that, it could be (or do) anything. Hence, 'user defined statement'.
I would say the key attribute is the "and something else as the suite is exited" part. With out that, the "with" statement isn't needed and a regular function or generator would work.
A term which stresses finalizing may be appropriate.
With that piece of terminology in place, the natural outcome was to call objects that supplied __enter__ and __exit__ methods "statement templates".
Will objects be created that can be used with and without "with" statements? I think that this could be a source of confusion.
It seems to me that "with" statements require a "with" object, and that those objects probably shouldn't be used without the "with" statement. Having a clear separation might be a good idea.
Should there be a "with" (different name most likely) type?
Would there be any advantages of a "with" base object that can have constructor methods that can accept either a try-finally generator or two functions to insert into the __enter__ and __exit__ methods as arguments?
For example, call a with object a "manage" object then:
with manage.generator(open_file_gen) as f: BLOCK
with manage.enter_exit(lock_func, unlock_func) as lock: BLOCK
I also used this term to come up with PEP 346's name for the generator to statement template conversion decorator: "stmt_template"
(Like others, the fact that 'with' is a verb makes it very hard for me to interpret "with_template" correctly when I see it as a decorator - I always want to ask "with which template?")
I agree, the decorator adds a layer of complexity to it. I think the with-generator behavior needs to be described without the decorator version first, then the decorator becomes syntactic sugar to make it easier to do the same thing.
Ron
[Raymond]
Whatever term is selected, it should be well thought-out and added
to
the glossary. The choice of words will likely have a great effect
on
learnability and on how people think about the new tool.
[Ron Adam]
I tried to bring this up on python-list, but I didn't get much of a response. I suggested "witherator" as a too cute alternative, but was hoping to get some alternatives to that.
That wins in the cuteness and trademarkability categories ;-)
Here is a more plain and direct alternative proposal:
"Decimal objects support the enter/exit protocol"
On a separate note, I also propose that __exit__() be renamed to __leave__(). The enter/leave word pairing are a better fit in standard English:
Entering the Austin city limits ... Leaving the Austin city limits. You may enter ... You may leave. Enter the Dragon ... Elvis has left the building.
FWIW, there is precedent in x86 assembly language:
enter: sets up nested procedure definition leave: reverses the effect of enter
Likewise, GUI programmers use Enter and Leave for mouse events.
Google has no shortage of hits for the pairing:
http://www.google.com/search?q=%22enter+or+leave"
Raymond
Raymond Hettinger wrote:
On a separate note, I also propose that __exit__() be renamed to __leave__(). The enter/leave word pairing are a better fit in standard English:
I tend to associate leave with leaving, and leaving with arriving.
I didn't even think the __enter__ / __exit__ names were an issue. <shrug>
Then again there's alway __premanage__ and __postmanage__. That fits Nicks requirement for visual pairing as they both start with 'p'. And then calling it a manager object fits very nicely too.
Hmmm, wonder if you could implement programs based on gant charts using nested manager objects? Would the nested managers be mid-level managers?
This might have some marketing appeal to large corporations. ;-)
Ron
On Thu, 2005-06-30 at 22:41, Raymond Hettinger wrote:
With 343 accepted, we can now add __enter__() and __exit__() methods to objects.
What term should describe those objects in the documentation?
Their raison d'etre is to bracket user code with setup and teardown methods, so how about the term "bracketing object"?
Mark Russell
On 7/1/05, Fred L. Drake, Jr. fdrake@acm.org wrote:
On Friday 01 July 2005 11:44, Phillip J. Eby wrote:
Resource managers.
Yeah, I was thinking that, but was somewhat ambivalent. But I definately like it better than anything else proposed so far.
I say we steal from the C++ and the RAII paradigm and go with RMUW (Resource Management Using 'with'). No need to get cutesy and we already have acronym overload anyway, so one more won't kill us.
-Brett
On Friday 01 July 2005 10:45 am, Fred L. Drake, Jr. wrote:
On Friday 01 July 2005 11:44, Phillip J. Eby wrote:
Resource managers.
Yeah, I was thinking that, but was somewhat ambivalent. But I definately like it better than anything else proposed so far.
I like that as well. My hat in the ring would be "brackets" or "bracketed statements", implying there is something before, after and in the middle. Also not an acronym, and short.
And while we're on naming issues...
Regarding __enter__/__exit__ versus __enter__/__leave__, I like the latter not only because of ASM history but that the two are the same length, making documentation cleaner in some cases.
ENTER: blah blah LEAVE: blah blah
A minor item, but then I'm big on visual symmetry. ;-)
-Jeff
"Phillip J. Eby" pje@telecommunity.com writes:
At 05:41 PM 6/30/2005 -0400, Raymond Hettinger wrote:
With 343 accepted, we can now add __enter__() and __exit__() methods to objects.
What term should describe those objects in the documentation?
Resource managers.
Thing is, there may be no resource; in my talk at EuroPython:
http://starship.python.net/crew/mwh/recexc.pdf
I used a with statement to establish and dis-establish an error handler -- would you call that a resource?
Cheers, mwh
Just because not all cars are used as vehicles, does that mean that cars are not vehicles?
There may be cases where the object being managed is not a resource per-se, but that doesn't mean that the mechanism is misnamed as a 'resource manager'; it's just the most common use case that any of us have managed to think of (as of yet).
- Josiah
Michael Hudson mwh@python.net wrote:
"Phillip J. Eby" pje@telecommunity.com writes:
At 05:41 PM 6/30/2005 -0400, Raymond Hettinger wrote:
With 343 accepted, we can now add __enter__() and __exit__() methods to objects.
What term should describe those objects in the documentation?
Resource managers.
Thing is, there may be no resource; in my talk at EuroPython:
http://starship.python.net/crew/mwh/recexc.pdfI used a with statement to establish and dis-establish an error handler -- would you call that a resource?
On 3 Jul 2005, at 18:25, Josiah Carlson wrote:
Just because not all cars are used as vehicles, does that mean that cars are not vehicles?
No, but it means calling all vehicles "cars" is dumb.
There may be cases where the object being managed is not a resource per-se, but that doesn't mean that the mechanism is misnamed as a 'resource manager'; it's just the most common use case that any of us have managed to think of (as of yet).
This is possible. I just wanted to expand everyone's minds :)
Cheers, mwh
There may be cases where the object being managed is not a resource per-se, but that doesn't mean that the mechanism is misnamed as a 'resource manager'; it's just the most common use case that any of
us
have managed to think of (as of yet).
[Michael Hudson]
This is possible. I just wanted to expand everyone's minds :)
Stick by your guns. The mechanism is more general than resource management. Like decorators, the encapsulation of a try/finally wrapper is completely generic and not married to the resource management context.
Raymond
At 03:41 PM 7/3/2005 -0400, Raymond Hettinger wrote:
There may be cases where the object being managed is not a resource per-se, but that doesn't mean that the mechanism is misnamed as a 'resource manager'; it's just the most common use case that any of
us
have managed to think of (as of yet).
[Michael Hudson]
This is possible. I just wanted to expand everyone's minds :)
Stick by your guns. The mechanism is more general than resource management. Like decorators, the encapsulation of a try/finally wrapper is completely generic and not married to the resource management context.
Expand your mind. :) "Resource" can include whatever objects you want it to -- or no objects at all. A resource can be conceptual - like for example the user's attention, or the contents of a status bar or log message, or the timing/profiling of an activity. I think maybe you're projecting one particular concept of "resource management" (acquisition/release) and therefore say it's too narrow. But that's like I'm saying "vehicle", and you think that means "car".
Should we give mind-expanding examples of "resource"? Yes, sure. But it's easier to say and teach "resource management" first, and then expand the concept, than to start with some more nebulous concept and then say, "but mostly you're going to use it to manage resources of various kinds." :)
If you did want to start with something vague, you could always call it "context management", and call the objects "context listeners", saying that the "with" statement defines a context in which its body occurs, and the context listener is notified of the context's entry and exit. But I don't think that this really works as the primary explanation; I think it's better as a mind-expanding "Another way to think of this is..." add-on to the simple resource management explanation.
The mechanism is more general than resource management. Like decorators, the encapsulation of a try/finally
wrapper
is completely generic and not married to the resource management context.
[Phillip]
Expand your mind. :) "Resource" can include whatever objects you want
it
to -- or no objects at all.
There is no value in expanding a concept to the point of being meaningless (i.e. meaning whatever you want it to or nothing at all). Instead, we need a phrase that expresses the essence of the following:
abc = EXPR exc = (None, None, None) VAR = abc.__enter__() try: try: BLOCK except: exc = sys.exc_info() raise finally: abc.__exit__(*exc)
There is nothing in that that says resource managed. The pre/post steps could do almost anything from logging, to changing environments, to translating, launching/joining unrelated threads, to communicating with other processes, etc.
Ideally, the phrase needs to fit in a list of all of the other properties of the abc object (i.e. abc objects are callable, iterable, support the buffer interface, and are withable or somesuch).
Another trouble with "resource managed" is that it makes little sense even when describing something that is clearly a resource (for instance, "locking objects are resource managed", what the heck could that mean, there is no hint about the presence of __enter__ and __exit__ or the ability to work with the "with" keyword). The phrase does nothing but suggest a particular application that historically has been implemented without the new mechanism.
Of course, what makes this exercise hard is that our two new keywords are prepositions and the process that they apply to is somewhat abstract.
Raymond
P.S. I would still like to encourage the adoption of __leave__ instead of __exit__. The first suggests part of an enter/leave pair. The latter could too easily be taken as a standalone. If everyone doesn't see the subtle reasons why __leave__ is better, then at least consider __beginwith__ and __endwith__ which say exactly what they mean and are obviously paired with each other and with the new keyword. Remember, these methods are going to show up in objects such as Context which are not primarily about 343. All of the other methods names will have nothing to do with 343, so our choice of magic names needs to be really good (as there will likely be NO contextual hints).
"Raymond Hettinger" python@rcn.com writes:
Another trouble with "resource managed" is that it makes little sense even when describing something that is clearly a resource (for instance, "locking objects are resource managed", what the heck could that mean, there is no hint about the presence of __enter__ and __exit__ or the ability to work with the "with" keyword).
At this point, I'm almost liking 'witherator'. At least it's something you can look up in the index.
(I think Raymond has identified the problem I have with resource manager more clearly then I did; I certainly don't think I'd realise what "decimal.Context() is a resource manager" meant at first reading).
Cheers, mwh
Michael Hudson wrote:
(I think Raymond has identified the problem I have with resource manager more clearly then I did; I certainly don't think I'd realise what "decimal.Context() is a resource manager" meant at first reading).
I'm also worried that "resource manager" is too narrow a term, and would only fit by considerable stretching in many cases.
I'm thinking about something like "context manager", or at least something with "context" in it.
Greg
Fred L. Drake, Jr. wrote:
Oh, I like this one. "Context manager" / "context protocol" work well for me.
And it means we get to say "decimal.context supports the context protocol", which sounds perfectly sensible, even obvious. :-)
Raymond Hettinger wrote:
There is no value in expanding a concept to the point of being meaningless (i.e. meaning whatever you want it to or nothing at all). Instead, we need a phrase that expresses the essence of the following:
abc = EXPR exc = (None, None, None) VAR = abc.__enter__() try: try: BLOCK except: exc = sys.exc_info() raise finally: abc.__exit__(*exc)There is nothing in that that says resource managed. The pre/post steps could do almost anything from logging, to changing environments, to translating, launching/joining unrelated threads, to communicating with other processes, etc.
The name 'abc' is the manager object, so find a better term to replace 'abc'.
Cheers, Ron
At 11:48 PM 7/3/2005 -0400, Raymond Hettinger wrote:
Remember, these methods are going to show up in objects such as Context which are not primarily about 343. All of the other methods names will have nothing to do with 343, so our choice of magic names needs to be really good (as there will likely be NO contextual hints).
with context_expression as variable: # perform actions within a context
The "with" statement establishes a context in which some operations are to be performed. Often, this is a resource management context, wherein some resource is allocated when the context is entered, and when it is exited. Or it may be a locking context, where a lock is acquired and released around the statements. Or it may be a computational context, such as a Decimal context that controls the precision of decimal calculations. In fact, it may be any context that can be defined in terms of behavior to be performed when the context is entered and exited.
The object produced by 'context_expression' must have __enter_context__ and __exit_context__ methods, which will be invoked by the "with" statement when the context is entered, and when it is exited for any reason (such as by an exception, "return" statement, or other control flow statements).
...etc.
[Phillip J. Eby]
with context_expression as variable: # perform actions within a context
The "with" statement establishes a context in which some operations
are to
be performed. Often, this is a resource management context, wherein
some
resource is allocated when the context is entered, and when it is exited. Or it may be a locking context, where a lock is acquired and released around the statements. Or it may be a computational context, such as a Decimal context that controls the precision of decimal calculations. In fact, it may be any context that can be defined in
terms
of behavior to be performed when the context is entered and exited.
The object produced by 'context_expression' must have
__enter_context__
and __exit_context__ methods, which will be invoked by the "with"
statement
when the context is entered, and when it is exited for any reason
(such as
by an exception, "return" statement, or other control flow
statements).
This is much improved. I think we're getting close. So far, I like Nick's most recent version the best, but this is in the ballpark.
The new methods names are a step in the right direction but they are butt-ugly and unfriendly. It is much cleaner looking and equally communicative to write __beginwith__ and __endwith__. Those names are clearly bookends and associated with with-suites. They are shorter, more pithy, and don't abuse underscore conventions (the current worst offenders are test___all__.py and the set module's __as_temporarily_immutable__ attribute which gives me COBOL flashbacks).
[Nick Coghlan]
Based on the various discussions, the following suggests the term "suite managers". That focuses on the fact that we're doing something before and after the contained suite.
The fact that they bracket a single suite seems to be the only thing the assorted uses really have in common, and emphasising that seems to work well. It's certainly the first case where I've been able to easily explain what decimal.Context does (or will do) when used in a 'with' statement.
I think you're onto something. Stick with it. Your whole write-up is clear. It is the first one that doesn't look like it had to twist its metaphor into a knot.
Raymond
Raymond Hettinger wrote:
This is much improved. I think we're getting close. So far, I like Nick's most recent version the best, but this is in the ballpark.
I like some of Phillip's suggestions, particularly the 'context' term. I'll put some thought into combining the two over the next couple of days. I spent too much time today thinking about the differences between exit and leave ;)
Cheers, Nick.
Phillip J. Eby wrote:
At 11:48 PM 7/3/2005 -0400, Raymond Hettinger wrote:
with context_expression as variable: # perform actions within a context
The "with" statement establishes a context in which some operations are to be performed.
I like this.
The object produced by 'context_expression' must have __enter_context__ and __exit_context__ methods, which will be invoked by the "with" statement when the context is entered...
And we could call this the "context protocol".
Greg
On Monday 04 Jul 2005 03:10, Phillip J. Eby wrote:
At 03:41 PM 7/3/2005 -0400, Raymond Hettinger wrote:
[Michael Hudson]
This is possible. I just wanted to expand everyone's minds :)
The mechanism is more general than resourcemanagement.
Expand your mind. :) "Resource" can include whatever objects you want it to -- or no objects at all.
Is printing HTML and guaranteeing ending tags a resource ? I've been reading this thread, and been thinking that Holger Kregel's XPython hack could be implemented using the new with statement.
with some_encoding: with html: with body: with h1: print "Some heading" with p: print "This is paragraph 1" with p: print "This is paragraph 2" with h2: print "Another heading"
The enter/exit for html would be to print <html> </html> respectively and so on. (Though "p" would be special cased, etc)
Personally it seems to me that "with" is more a form of *guarantee* - something that has a guard to enter the block, and something that does something after the block.
From that perspective you could even imagine:
with enforce_conditions(pre,post): do some work. ... ...
enforce_conditions - enforces the "pre" before entering the block, and may choose to throw an exception if the precondition is false. - checks that "post" holds after the block, and may throw an exception if the postcondition is false.
Again, I don't really see that as a resource type scenario. It *may* involve a resource scenario, but it may not. (eg did a condition finish within a certain time?)
Perhaps calling it a guarantor? (or similar) * You can guarantee that you have the lock on a resource if you enter the block ? * You can guarantee that you will have properly form (X|HT)ML if using an appropriate approach ? * You can guarantee checking of post conditions in a uniform manner ?
(Assumption: That the word guarantee in this case matches that of the intent)
If you just call the with statement a "resource manager" I suspect that people will more /naturally/ think just along the idea of resources, rather than also along the lines of things that need guarantees.
Is that really a resource type scenario?
Best Regards,
Michael.
Michael Sparks wrote:
On Monday 04 Jul 2005 03:10, Phillip J. Eby wrote:
At 03:41 PM 7/3/2005 -0400, Raymond Hettinger wrote:
[Michael Hudson]
This is possible. I just wanted to expand everyone's minds :)
The mechanism is more general than resourcemanagement.
Expand your mind. :) "Resource" can include whatever objects you want it to -- or no objects at all.
Is printing HTML and guaranteeing ending tags a resource ? I've been reading this thread, and been thinking that Holger Kregel's XPython hack could be implemented using the new with statement.
with some_encoding: with html: with body: with h1: print "Some heading" with p: print "This is paragraph 1" with p: print "This is paragraph 2" with h2: print "Another heading"
The enter/exit for html would be to print <html> </html> respectively and so on. (Though "p" would be special cased, etc)
Phillip's 'context' terminology, on the other hand, applies beautifully:
- encoding context - HTML context - HTML body context - HTML heading 1 context - HTML paragraph context
I think we have a winner. . .
Cheers, Nick.
"Michael Hudson" mwh@python.net wrote in message news:2my88ovvcr.fsf@starship.python.net...
Thing is, there may be no resource; in my talk at EuroPython:
http://starship.python.net/crew/mwh/recexc.pdf
I used a with statement to establish and dis-establish an error handler -- would you call that a resource?
Yes -- now that you suggested it, given what you had on your slides ;-)
An emergency backup resource is different from a normal production resource (opened file for instance), but I can still see it as a resource.
Terry J. Reedy
At 03:04 PM 7/3/2005 +0100, Michael Hudson wrote:
"Phillip J. Eby" pje@telecommunity.com writes:
At 05:41 PM 6/30/2005 -0400, Raymond Hettinger wrote:
With 343 accepted, we can now add __enter__() and __exit__() methods to objects.
What term should describe those objects in the documentation?
Resource managers.
Thing is, there may be no resource; in my talk at EuroPython:
http://starship.python.net/crew/mwh/recexc.pdfI used a with statement to establish and dis-establish an error handler -- would you call that a resource?
Yes; an error handling resource is no different than say, a decimal context resource in this respect. A "with" statement defines the scope of use or applicability of some resource; the resource manager is the object that is notified as to when the scope is entered and exited, so that it can appropriately manage the resource.
Some resources may be their own default resource manager, but it's always possible to create a different resource management policy by creating a new resource manager.
I think this is a clear and straightforward explanation of what "with" does and what you can do with it.
participants (16)
-
Brett Cannon -
Christos Georgiou -
Eric Nieuwland -
Fred L. Drake, Jr. -
Greg Ewing -
Jeff Rush -
Josiah Carlson -
Mark Russell -
Michael Hudson -
Michael Sparks -
Nick Coghlan -
Phillip J. Eby -
Raymond Hettinger -
Raymond Hettinger -
Ron Adam -
Terry Reedy