Mailman 3 May 2005 - Python-checkins

python/nondist/peps pep-0343.txt,1.5,1.6
by gvanrossum＠users.sourceforge.net May 14, 2005

May 14, 2005

Update of /cvsroot/python/python/nondist/peps In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18203 Modified Files: pep-0343.txt Log Message: Explain the __exit__() signature. Index: pep-0343.txt =================================================================== RCS file: /cvsroot/python/python/nondist/peps/pep-0343.txt,v retrieving revision 1.5 retrieving revision 1.6 diff -u -d -r1.5 -r1.6 --- pep-0343.txt 14 May 2005 05:08:23 -0000 1.5 +++ pep-0343.txt 14 May 2005 05:18:36 -0000 1.6 @@ -185,6 +185,23 @@ with three arguments representing the exception type, value, and traceback. + The motivation for this API to __exit__(), as opposed to the + argument-less __exit__() from PEP 310, was given by the + transactional() use case, example 3 below. The template in that + example must commit or roll back the transaction depending on + whether an exception occurred or not. Rather than just having a + boolean flag indicating whether an exception occurred, we pass the + complete exception information, for the benefor of an + exception-logging facility for example. Relying on sys.exc_info() + to get att the exception information was rejected; sys.exc_info() + has very complex semantics and it is perfectly possible that it + returns the exception information for an exception that was caught + ages ago. It was also proposed to add an additional boolean to + distinguish between reaching the end of BLOCK and a non-local + goto. This was rejected as too complex and unnecessary; a + non-local goto should be considered unexceptional for the purposes + of a database transaction roll-back decision. + Optional Generator Decorator It is possible to write a decorator that makes it possible to use @@ -300,7 +317,7 @@ def __init__(self, db): self.db = db def __enter__(self): - pass + self.db.begin() def __exit__(self, *args): if args and args[0] is not None: self.db.rollback()

1 0

python/nondist/peps pep-0343.txt,1.4,1.5
by gvanrossum＠users.sourceforge.net May 14, 2005

May 14, 2005

Update of /cvsroot/python/python/nondist/peps In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv17313 Modified Files: pep-0343.txt Log Message: Slight elaboration for readers who don't recall PEP 310. Index: pep-0343.txt =================================================================== RCS file: /cvsroot/python/python/nondist/peps/pep-0343.txt,v retrieving revision 1.4 retrieving revision 1.5 diff -u -d -r1.4 -r1.5 --- pep-0343.txt 14 May 2005 05:02:28 -0000 1.4 +++ pep-0343.txt 14 May 2005 05:08:23 -0000 1.5 @@ -37,18 +37,34 @@ However, the with-statement of PEP 310 does *not* hide control flow, in my view: while a finally-suite temporarily suspends the control flow, in the end, the control flow resumes as if the - finally-suite wasn't there at all. Consider this: + finally-suite wasn't there at all. + + Remember, PEP 310 proposes rougly this syntax (the "VAR =" part is + optional): with VAR = EXPR: + BLOCK + + which roughly translates into + + VAR = EXPR + VAR.__enter__() + try: + BLOCK + finally: + VAR.__exit__() + + Now consider this example: + + with f = opening("/etc/passwd"): BLOCK1 BLOCK2 Here, just as if the first line was "if True" instead, we know that if BLOCK1 completes without an exception, BLOCK2 will be - reached; and if BLOCK1 raises an exception or executes a - non-local goto (a break, continue or return), BLOCK2 is *not* - reached. The magic added by the with-statement at the end doesn't - affect this. + reached; and if BLOCK1 raises an exception or executes a non-local + goto (a break, continue or return), BLOCK2 is *not* reached. The + magic added by the with-statement at the end doesn't affect this. (You may ask, what if a bug in the __exit__ method causes an exception? Then all is lost -- but this is no worse than with

1 0

python/nondist/peps pep-0343.txt,1.3,1.4
by gvanrossum＠users.sourceforge.net May 14, 2005

May 14, 2005

Update of /cvsroot/python/python/nondist/peps In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv16548 Modified Files: pep-0343.txt Log Message: Add a motivational section, remove tabs, add colons, and some very minor edits. Index: pep-0343.txt =================================================================== RCS file: /cvsroot/python/python/nondist/peps/pep-0343.txt,v retrieving revision 1.3 retrieving revision 1.4 diff -u -d -r1.3 -r1.4 --- pep-0343.txt 14 May 2005 04:02:10 -0000 1.3 +++ pep-0343.txt 14 May 2005 05:02:28 -0000 1.4 @@ -17,7 +17,103 @@ Motivation and Summary - TBD. + PEP 340, Anonymous Block Statements, combined many powerful ideas: + using generators as block templates, adding exception handling and + finalization to generators, and more. Besides praise it received + a lot of opposition from people who didn't like the fact that it + was, under the covers, a (optential) looping construct. This + meant that break and continue in a block-statement would break or + continue the block-statement, even if it was used as a non-looping + resource management tool. + + But the final blow came when I read Raymond Chen's rant about + flow-control macros[1]. Raymond argues convincingly that hiding + flow control in macros makes your code inscrutable, and I find + that his argument applies to Python as well as to C. I realized + that PEP 340 templates can hide all sorts of control flow; for + example, its example 4 (auto_retry()) catches exceptions and + repeats the block up to three times. + + However, the with-statement of PEP 310 does *not* hide control + flow, in my view: while a finally-suite temporarily suspends the + control flow, in the end, the control flow resumes as if the + finally-suite wasn't there at all. Consider this: + + with VAR = EXPR: + BLOCK1 + BLOCK2 + + Here, just as if the first line was "if True" instead, we know + that if BLOCK1 completes without an exception, BLOCK2 will be + reached; and if BLOCK1 raises an exception or executes a + non-local goto (a break, continue or return), BLOCK2 is *not* + reached. The magic added by the with-statement at the end doesn't + affect this. + + (You may ask, what if a bug in the __exit__ method causes an + exception? Then all is lost -- but this is no worse than with + other exceptions; the nature of exceptions is that they can happen + *anywhere*, and you just have to live with that. Even if you + write bug-free code, a KeyboardInterrupt exception can still cause + it to exit between any two virtual machine opcodes.) + + This argument almost led me to endorse PEP 310, but I had one idea + left from the PEP 340 euphoria that I wasn't ready to drop: using + generators as "templates" for abstractions like acquiring and + releasing a lock or opening and closing a file is a powerful idea, + as can be seen by looking at the examples in that PEP. + + Inspired by a counter-proposal to PEP 340 by Phillip Eby I tried + to create a decorator that would turn a suitable generator into an + object with the necessary __entry__ and __exit__ methods. Here I + ran into a snag: while it wasn't too hard for the locking example, + it was impossible to do this for the opening example. The idea + was to define the template like this: + + @with_template + def opening(filename): + f = open(filename) + yield f + f.close() + + and used it like this: + + with f = opening(filename): + ...read data from f... + + The problem is that in PEP 310, the result of calling EXPR is + assigned directly to VAR, and then VAR's __exit__ method is called + upon exit from BLOCK1. But here, VAR clearly needs to receive the + opened file, and that would mean that __exit__ would have to be a + method on the file. + + While this can be solved using a proxy class, this is awkward and + made me realize that a slightly different translation would make + writing the desired decorator a piece of cake: let VAR receive the + result from calling the __enter__ method, and save the value of + EXPR to call its __exit__ method later. Then the decorator can + return an instance of a wrapper class whose __enter__ method calls + the generator's next() method and returns whatever next() returns; + the wrapper instance's __exit__ method calls next() again but + expects it to raise StopIteration. (Details below in the section + Optional Generator Decorator.) + + So now the final hurdle was that the PEP 310 syntax: + + with VAR = EXPR: + BLOCK1 + + would be deceptive, since VAR does *not* receive the value of + EXPR. Given PEP 340, it was an easy step to: + + with EXPR as VAR: + BLOCK1 + + or, using an alternate keyword that has been proposed a number of + times: + + do EXPR as VAR: + BLOCK1 Use Cases @@ -25,7 +121,7 @@ Specification - A new statement is proposed with the syntax + A new statement is proposed with the syntax: do EXPR as VAR: BLOCK @@ -53,7 +149,7 @@ BLOCK except: exc = sys.exc_info() - raise + raise finally: abc.__exit__(exc) @@ -66,7 +162,7 @@ The calling convention for abc.__exit__() is: as follows. If the finally-suite was reached through normal completion of BLOCK or - through a "non-local goto" (a break, continue or return statement + through a non-local goto (a break, continue or return statement in BLOCK), abc.__exit__() is called without arguments (or perhaps with three None arguments?). If the finally-suite was reached through an exception raised in BLOCK, abc.__exit__() is called @@ -122,18 +218,18 @@ It would be possible to endow certain objects, like files, sockets, and locks, with __enter__ and __exit__ methods so that - instead of writing + instead of writing: do locking(myLock): BLOCK - one could write simply + one could write simply: do myLock: BLOCK I think we should be careful with this; it could lead to mistakes - like + like: f = open(filename) do f: @@ -264,6 +360,10 @@ as an exercise for the reader. (Mail it to me if you'd like to see it here.) +References + + [1] http://blogs.msdn.com/oldnewthing/archive/2005/01/06/347666.aspx + Copyright This document has been placed in the public domain.

1 0

python/nondist/peps pep-0343.txt,1.2,1.3
by gvanrossum＠users.sourceforge.net May 14, 2005

May 14, 2005

Update of /cvsroot/python/python/nondist/peps In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv9821 Modified Files: pep-0343.txt Log Message: Various clarifications. Mention Decimal context example. Clarify that I don't like having files etc. implement __enter__ and __exit__ directly. Index: pep-0343.txt =================================================================== RCS file: /cvsroot/python/python/nondist/peps/pep-0343.txt,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- pep-0343.txt 14 May 2005 02:02:40 -0000 1.2 +++ pep-0343.txt 14 May 2005 04:02:10 -0000 1.3 @@ -57,6 +57,10 @@ finally: abc.__exit__(exc) + Here, the variables 'abc' and 'exc' are internal variables and not + accessible to the user; they will most likely be implemented as + special registers or stack positions. + If the "as VAR" part of the syntax is omitted, the "VAR =" part of the translation is omitted (but abc.__enter__() is still called). @@ -114,6 +118,32 @@ A robust implementation of such a decorator should be made part of the standard library. +Other Optional Extensions + + It would be possible to endow certain objects, like files, + sockets, and locks, with __enter__ and __exit__ methods so that + instead of writing + + do locking(myLock): + BLOCK + + one could write simply + + do myLock: + BLOCK + + I think we should be careful with this; it could lead to mistakes + like + + f = open(filename) + do f: + BLOCK1 + do f: + BLOCK2 + + which does not do what one might think (f is closed when BLOCK2 is + entered). + Examples Several of these examples contain "yield None". If PEP 342 is @@ -194,6 +224,10 @@ do redirecting_stdout(f): print "Hello world" + This isn't thread-safe, of course, but neither is doing this + same dance manually. In a single-threaded program (e.g., a + script) it is a totally fine way of doing things. + 6. A variant on opening() that also returns an error condition: @do_template @@ -226,6 +260,10 @@ by default all signals are blocked. The implementation is left as an exercise to the reader. + 8. Another use for this feature is the Decimal context. It's left + as an exercise for the reader. (Mail it to me if you'd like to + see it here.) + Copyright This document has been placed in the public domain.

1 0

python/nondist/peps pep-0343.txt,1.1,1.2
by gvanrossum＠users.sourceforge.net May 14, 2005

May 14, 2005

Update of /cvsroot/python/python/nondist/peps In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv25715 Modified Files: pep-0343.txt Log Message: Don't be wishy-washy about the call to __exit__(). Fix the redirecting_stdout() example (remove the try/finally). Index: pep-0343.txt =================================================================== RCS file: /cvsroot/python/python/nondist/peps/pep-0343.txt,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- pep-0343.txt 14 May 2005 00:08:20 -0000 1.1 +++ pep-0343.txt 14 May 2005 02:02:40 -0000 1.2 @@ -46,23 +46,28 @@ The translation of the above statement is: abc = EXPR + exc = () # Or (None, None, None) ? try: - VAR = abc.__enter__() - BLOCK + try: + VAR = abc.__enter__() + BLOCK + except: + exc = sys.exc_info() + raise finally: - abc.__exit__(*sys.exc_info()) # XXX See below + abc.__exit__(exc) If the "as VAR" part of the syntax is omitted, the "VAR =" part of the translation is omitted (but abc.__enter__() is still called). - The call to abc.__exit__() is only approximated as written. The - actual calling convention is: If the finally-suite was reached - through normal completion of BLOCK or through a "non-local goto" - (a break, continue or return statement in BLOCK), abc.__exit__() - is called without arguments (or perhaps with three None - arguments). If the finally-suite was reached through an exception - raised in BLOCK, abc.__exit__() is called with three arguments - representing the exception type, value, and traceback. + The calling convention for abc.__exit__() is: as follows. If the + finally-suite was reached through normal completion of BLOCK or + through a "non-local goto" (a break, continue or return statement + in BLOCK), abc.__exit__() is called without arguments (or perhaps + with three None arguments?). If the finally-suite was reached + through an exception raised in BLOCK, abc.__exit__() is called + with three arguments representing the exception type, value, and + traceback. Optional Generator Decorator @@ -70,41 +75,41 @@ a generator that yields exactly once to control a do-statement. Here's a sketch of such a decorator: - class Wrapper(object): - def __init__(self, gen): - self.gen = gen - self.state = "initial" - def __enter__(self): - assert self.state == "initial" - self.state = "entered" - try: - return self.gen.next() - except StopIteration: - self.state = "error" - raise RuntimeError("template generator didn't yield") - def __exit__(self, *args): - assert self.state == "entered" - self.state = "exited" - try: - self.gen.next() - except StopIteration: - return - else: - self.state = "error" - raise RuntimeError("template generator didn't stop") + class Wrapper(object): + def __init__(self, gen): + self.gen = gen + self.state = "initial" + def __enter__(self): + assert self.state == "initial" + self.state = "entered" + try: + return self.gen.next() + except StopIteration: + self.state = "error" + raise RuntimeError("template generator didn't yield") + def __exit__(self, *args): + assert self.state == "entered" + self.state = "exited" + try: + self.gen.next() + except StopIteration: + return + else: + self.state = "error" + raise RuntimeError("template generator didn't stop") - def do_template(func): - def helper(*args, **kwds): - return Wrapper(func(*args, **kwds)) - return helper + def do_template(func): + def helper(*args, **kwds): + return Wrapper(func(*args, **kwds)) + return helper This decorator could be used as follows: - @do_template - def opening(filename): - f = open(filename) # IOError here is untouched by Wrapper - yield f - f.close() # Ditto for errors here (however unlikely) + @do_template + def opening(filename): + f = open(filename) # IOError here is untouched by Wrapper + yield f + f.close() # Ditto for errors here (however unlikely) A robust implementation of such a decorator should be made part of the standard library. @@ -151,14 +156,14 @@ class transactional: def __init__(self, db): - self.db = db + self.db = db def __enter__(self): pass - def __exit__(self, *args): - if args and args[0] is not None: - self.db.rollback() - else: - self.db.commit() + def __exit__(self, *args): + if args and args[0] is not None: + self.db.rollback() + else: + self.db.commit() 4. Example 1 rewritten without a generator: @@ -166,9 +171,9 @@ def __init__(self, lock): self.lock = lock def __enter__(self): - self.lock.acquire() + self.lock.acquire() def __exit__(self, *args): - self.lock.release() + self.lock.release() (This example is easily modified to implement the other examples; it shows how much simpler generators are for the same @@ -179,11 +184,9 @@ @do_template def redirecting_stdout(new_stdout): save_stdout = sys.stdout - try: - sys.stdout = new_stdout - yield None - finally: - sys.stdout = save_stdout + sys.stdout = new_stdout + yield None + sys.stdout = save_stdout Used as follows: @@ -200,7 +203,7 @@ except IOError, err: yield None, err else: - yield f, None + yield f, None f.close() Used as follows:

1 0

python/nondist/peps pep-0343.txt, NONE, 1.1 pep-0000.txt, 1.305, 1.306
by gvanrossum＠users.sourceforge.net May 14, 2005

May 14, 2005

Update of /cvsroot/python/python/nondist/peps In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv7951 Modified Files: pep-0000.txt Added Files: pep-0343.txt Log Message: Add PEP 343: Anonymous Block Redux --- NEW FILE: pep-0343.txt --- PEP: 343 Title: Anonymous Block Redux Version: $Revision: 1.1 $ Last-Modified: $Date: 2005/05/14 00:08:20 $ Author: Guido van Rossum Status: Draft Type: Standards Track Content-Type: text/plain Created: 13-May-2005 Post-History: Introduction After a lot of discussion about PEP 340 and alternatives, I've decided to withdraw PEP 340 and propose a slight variant on PEP 310. Motivation and Summary TBD. Use Cases See the Examples section near the end. Specification A new statement is proposed with the syntax do EXPR as VAR: BLOCK Here, 'do' and 'as' are new keywords; EXPR is an arbitrary expression (but not an expression-list) and VAR is an arbitrary assignment target (which may be a comma-separated list). The "as VAR" part is optional. The choice of the 'do' keyword is provisional; an alternative under consideration is 'with'. A yield-statement is illegal inside BLOCK. This is because the do-statement is translated into a try/finally statement, and yield is illegal in a try/finally statement. The translation of the above statement is: abc = EXPR try: VAR = abc.__enter__() BLOCK finally: abc.__exit__(*sys.exc_info()) # XXX See below If the "as VAR" part of the syntax is omitted, the "VAR =" part of the translation is omitted (but abc.__enter__() is still called). The call to abc.__exit__() is only approximated as written. The actual calling convention is: If the finally-suite was reached through normal completion of BLOCK or through a "non-local goto" (a break, continue or return statement in BLOCK), abc.__exit__() is called without arguments (or perhaps with three None arguments). If the finally-suite was reached through an exception raised in BLOCK, abc.__exit__() is called with three arguments representing the exception type, value, and traceback. Optional Generator Decorator It is possible to write a decorator that makes it possible to use a generator that yields exactly once to control a do-statement. Here's a sketch of such a decorator: class Wrapper(object): def __init__(self, gen): self.gen = gen self.state = "initial" def __enter__(self): assert self.state == "initial" self.state = "entered" try: return self.gen.next() except StopIteration: self.state = "error" raise RuntimeError("template generator didn't yield") def __exit__(self, *args): assert self.state == "entered" self.state = "exited" try: self.gen.next() except StopIteration: return else: self.state = "error" raise RuntimeError("template generator didn't stop") def do_template(func): def helper(*args, **kwds): return Wrapper(func(*args, **kwds)) return helper This decorator could be used as follows: @do_template def opening(filename): f = open(filename) # IOError here is untouched by Wrapper yield f f.close() # Ditto for errors here (however unlikely) A robust implementation of such a decorator should be made part of the standard library. Examples Several of these examples contain "yield None". If PEP 342 is accepted, these can be changed to just "yield". 1. A template for ensuring that a lock, acquired at the start of a block, is released when the block is left: @do_template def locking(lock): lock.acquire() yield None lock.release() Used as follows: do locking(myLock): # Code here executes with myLock held. The lock is # guaranteed to be released when the block is left (even # if via return or by an uncaught exception). 2. A template for opening a file that ensures the file is closed when the block is left: @do_template def opening(filename, mode="r"): f = open(filename, mode) yield f f.close() Used as follows: do opening("/etc/passwd") as f: for line in f: print line.rstrip() 3. A template for committing or rolling back a database transaction; this is written as a class rather than as a decorator since it requires access to the exception information: class transactional: def __init__(self, db): self.db = db def __enter__(self): pass def __exit__(self, *args): if args and args[0] is not None: self.db.rollback() else: self.db.commit() 4. Example 1 rewritten without a generator: class locking: def __init__(self, lock): self.lock = lock def __enter__(self): self.lock.acquire() def __exit__(self, *args): self.lock.release() (This example is easily modified to implement the other examples; it shows how much simpler generators are for the same purpose.) 5. Redirect stdout temporarily: @do_template def redirecting_stdout(new_stdout): save_stdout = sys.stdout try: sys.stdout = new_stdout yield None finally: sys.stdout = save_stdout Used as follows: do opening(filename, "w") as f: do redirecting_stdout(f): print "Hello world" 6. A variant on opening() that also returns an error condition: @do_template def opening_w_error(filename, mode="r"): try: f = open(filename, mode) except IOError, err: yield None, err else: yield f, None f.close() Used as follows: do opening_w_error("/etc/passwd", "a") as f, err: if err: print "IOError:", err else: f.write("guido::0:0::/:/bin/sh\n") 7. Another useful example would be an operation that blocks signals. The use could be like this: import signal do signal.blocking(): # code executed without worrying about signals An optional argument might be a list of signals to be blocked; by default all signals are blocked. The implementation is left as an exercise to the reader. Copyright This document has been placed in the public domain. Index: pep-0000.txt =================================================================== RCS file: /cvsroot/python/python/nondist/peps/pep-0000.txt,v retrieving revision 1.305 retrieving revision 1.306 diff -u -d -r1.305 -r1.306 --- pep-0000.txt 11 May 2005 21:58:13 -0000 1.305 +++ pep-0000.txt 14 May 2005 00:08:19 -0000 1.306 @@ -120,6 +120,7 @@ S 340 Anonymous Block Statements GvR S 341 Unifying try-except and try-finally Birkenfeld S 342 Enhanced Iterators GvR + S 343 Anonymous Block Redux GvR S 754 IEEE 754 Floating Point Special Values Warnes Finished PEPs (done, implemented in CVS) @@ -380,6 +381,7 @@ S 340 Anonymous Block Statements GvR S 341 Unifying try-except and try-finally Birkenfeld S 342 Enhanced Iterators GvR + S 343 Anonymous Block Redux GvR SR 666 Reject Foolish Indentation Creighton S 754 IEEE 754 Floating Point Special Values Warnes I 3000 Python 3.0 Plans Kuchling, Cannon

1 0

python/dist/src/Misc ACKS,1.289.2.1,1.289.2.2
by montanaro＠users.sourceforge.net May 12, 2005

May 12, 2005

Update of /cvsroot/python/python/dist/src/Misc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv2030 Modified Files: Tag: release24-maint ACKS Log Message: backport Index: ACKS =================================================================== RCS file: /cvsroot/python/python/dist/src/Misc/ACKS,v retrieving revision 1.289.2.1 retrieving revision 1.289.2.2 diff -u -d -r1.289.2.1 -r1.289.2.2 --- ACKS 10 Feb 2005 22:47:13 -0000 1.289.2.1 +++ ACKS 12 May 2005 13:45:11 -0000 1.289.2.2 @@ -503,6 +503,7 @@ Saskia van Rossum Donald Wallace Rouse II Liam Routt +Paul Rubin Audun S. Runde Jeff Rush Sam Rushing

1 0

python/dist/src/Misc ACKS,1.294,1.295
by montanaro＠users.sourceforge.net May 12, 2005

May 12, 2005

Update of /cvsroot/python/python/dist/src/Misc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv1779 Modified Files: ACKS Log Message: credit source of idea for recent doc changes Index: ACKS =================================================================== RCS file: /cvsroot/python/python/dist/src/Misc/ACKS,v retrieving revision 1.294 retrieving revision 1.295 diff -u -d -r1.294 -r1.295 --- ACKS 10 Feb 2005 20:48:03 -0000 1.294 +++ ACKS 12 May 2005 13:44:23 -0000 1.295 @@ -506,6 +506,7 @@ Saskia van Rossum Donald Wallace Rouse II Liam Routt +Paul Rubin Audun S. Runde Jeff Rush Sam Rushing

1 0

python/dist/src/Doc/lib libsocksvr.tex, 1.18, 1.18.4.1
by montanaro＠users.sourceforge.net May 12, 2005

May 12, 2005

Update of /cvsroot/python/python/dist/src/Doc/lib In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv1594 Modified Files: Tag: release24-maint libsocksvr.tex Log Message: backport from head Index: libsocksvr.tex =================================================================== RCS file: /cvsroot/python/python/dist/src/Doc/lib/libsocksvr.tex,v retrieving revision 1.18 retrieving revision 1.18.4.1 diff -u -d -r1.18 -r1.18.4.1 --- libsocksvr.tex 21 Jul 2004 02:47:10 -0000 1.18 +++ libsocksvr.tex 12 May 2005 13:43:40 -0000 1.18.4.1 @@ -52,10 +52,87 @@ \setindexsubitem{(SocketServer protocol)} +\subsection{Server Creation Notes} + +There are five classes in an inheritance diagram, four of which represent +synchronous servers of four types: + +\begin{verbatim} + +------------+ + | BaseServer | + +------------+ + | + v + +-----------+ +------------------+ + | TCPServer |------->| UnixStreamServer | + +-----------+ +------------------+ + | + v + +-----------+ +--------------------+ + | UDPServer |------->| UnixDatagramServer | + +-----------+ +--------------------+ +\end{verbatim} + +Note that \class{UnixDatagramServer} derives from \class{UDPServer}, not +from \class{UnixStreamServer} -- the only difference between an IP and a +Unix stream server is the address family, which is simply repeated in both +unix server classes. + +Forking and threading versions of each type of server can be created using +the \class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes. For +instance, a threading UDP server class is created as follows: + +\begin{verbatim} + class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass +\end{verbatim} + +The mix-in class must come first, since it overrides a method defined in +\class{UDPServer}. Setting the various member variables also changes the +behavior of the underlying server mechanism. + +To implement a service, you must derive a class from +\class{BaseRequestHandler} and redefine its \method{handle()} method. You +can then run various versions of the service by combining one of the server +classes with your request handler class. The request handler class must be +different for datagram or stream services. This can be hidden by using the +mix-in request handler classes \class{StreamRequestHandler} or +\class{DatagramRequestHandler}. + +Of course, you still have to use your head! For instance, it makes no sense +to use a forking server if the service contains state in memory that can be +modified by different requests, since the modifications in the child process +would never reach the initial state kept in the parent process and passed to +each child. In this case, you can use a threading server, but you will +probably have to use locks to protect the integrity of the shared data. + +On the other hand, if you are building an HTTP server where all data is +stored externally (for instance, in the file system), a synchronous class +will essentially render the service "deaf" while one request is being +handled -- which may be for a very long time if a client is slow to receive +all the data it has requested. Here a threading or forking server is +appropriate. + +In some cases, it may be appropriate to process part of a request +synchronously, but to finish processing in a forked child depending on the +request data. This can be implemented by using a synchronous server and +doing an explicit fork in the request handler class \method{handle()} +method. + +Another approach to handling multiple simultaneous requests in an +environment that supports neither threads nor \function{fork()} (or where +these are too expensive or inappropriate for the service) is to maintain an +explicit table of partially finished requests and to use \function{select()} +to decide which request to work on next (or whether to handle a new incoming +request). This is particularly important for stream services where each +client can potentially be connected for a long time (if threads or +subprocesses cannot be used). + %XXX should data and methods be intermingled, or separate? % how should the distinction between class and instance variables be % drawn? +\subsection{Server Objects} + \begin{funcdesc}{fileno}{} Return an integer file descriptor for the socket on which the server is listening. This function is most commonly passed to @@ -160,7 +237,8 @@ % instance variables, adding new network families? \begin{funcdesc}{server_activate}{} -Called by the server's constructor to activate the server. +Called by the server's constructor to activate the server. The default +behavior just \method{listen}s to the server's socket. May be overridden. \end{funcdesc} @@ -176,6 +254,8 @@ The default implementation always returns \constant{True}. \end{funcdesc} +\subsection{RequestHandler Objects} + The request handler class must define a new \method{handle()} method, and can override any of the following methods. A new instance is created for each request. @@ -189,6 +269,7 @@ \begin{funcdesc}{handle}{} This function must do all the work required to service a request. +The default implementation does nothing. Several instance attributes are available to it; the request is available as \member{self.request}; the client address as \member{self.client_address}; and the server instance as

1 0

python/dist/src/Doc/lib libsocksvr.tex, 1.18, 1.19
by montanaro＠users.sourceforge.net May 12, 2005

May 12, 2005

Update of /cvsroot/python/python/dist/src/Doc/lib In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv1244 Modified Files: libsocksvr.tex Log Message: Incorporate a lightly edited version of the SocketServer module's docstring into the docs and segregate the method descriptions for the various classes into separate sections. Base on suggestion by Paul Rubin in c.l.py. Index: libsocksvr.tex =================================================================== RCS file: /cvsroot/python/python/dist/src/Doc/lib/libsocksvr.tex,v retrieving revision 1.18 retrieving revision 1.19 diff -u -d -r1.18 -r1.19 --- libsocksvr.tex 21 Jul 2004 02:47:10 -0000 1.18 +++ libsocksvr.tex 12 May 2005 13:42:42 -0000 1.19 @@ -52,10 +52,87 @@ \setindexsubitem{(SocketServer protocol)} +\subsection{Server Creation Notes} + +There are five classes in an inheritance diagram, four of which represent +synchronous servers of four types: + +\begin{verbatim} + +------------+ + | BaseServer | + +------------+ + | + v + +-----------+ +------------------+ + | TCPServer |------->| UnixStreamServer | + +-----------+ +------------------+ + | + v + +-----------+ +--------------------+ + | UDPServer |------->| UnixDatagramServer | + +-----------+ +--------------------+ +\end{verbatim} + +Note that \class{UnixDatagramServer} derives from \class{UDPServer}, not +from \class{UnixStreamServer} -- the only difference between an IP and a +Unix stream server is the address family, which is simply repeated in both +unix server classes. + +Forking and threading versions of each type of server can be created using +the \class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes. For +instance, a threading UDP server class is created as follows: + +\begin{verbatim} + class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass +\end{verbatim} + +The mix-in class must come first, since it overrides a method defined in +\class{UDPServer}. Setting the various member variables also changes the +behavior of the underlying server mechanism. + +To implement a service, you must derive a class from +\class{BaseRequestHandler} and redefine its \method{handle()} method. You +can then run various versions of the service by combining one of the server +classes with your request handler class. The request handler class must be +different for datagram or stream services. This can be hidden by using the +mix-in request handler classes \class{StreamRequestHandler} or +\class{DatagramRequestHandler}. + +Of course, you still have to use your head! For instance, it makes no sense +to use a forking server if the service contains state in memory that can be +modified by different requests, since the modifications in the child process +would never reach the initial state kept in the parent process and passed to +each child. In this case, you can use a threading server, but you will +probably have to use locks to protect the integrity of the shared data. + +On the other hand, if you are building an HTTP server where all data is +stored externally (for instance, in the file system), a synchronous class +will essentially render the service "deaf" while one request is being +handled -- which may be for a very long time if a client is slow to receive +all the data it has requested. Here a threading or forking server is +appropriate. + +In some cases, it may be appropriate to process part of a request +synchronously, but to finish processing in a forked child depending on the +request data. This can be implemented by using a synchronous server and +doing an explicit fork in the request handler class \method{handle()} +method. + +Another approach to handling multiple simultaneous requests in an +environment that supports neither threads nor \function{fork()} (or where +these are too expensive or inappropriate for the service) is to maintain an +explicit table of partially finished requests and to use \function{select()} +to decide which request to work on next (or whether to handle a new incoming +request). This is particularly important for stream services where each +client can potentially be connected for a long time (if threads or +subprocesses cannot be used). + %XXX should data and methods be intermingled, or separate? % how should the distinction between class and instance variables be % drawn? +\subsection{Server Objects} + \begin{funcdesc}{fileno}{} Return an integer file descriptor for the socket on which the server is listening. This function is most commonly passed to @@ -160,7 +237,8 @@ % instance variables, adding new network families? \begin{funcdesc}{server_activate}{} -Called by the server's constructor to activate the server. +Called by the server's constructor to activate the server. The default +behavior just \method{listen}s to the server's socket. May be overridden. \end{funcdesc} @@ -176,6 +254,8 @@ The default implementation always returns \constant{True}. \end{funcdesc} +\subsection{RequestHandler Objects} + The request handler class must define a new \method{handle()} method, and can override any of the following methods. A new instance is created for each request. @@ -189,6 +269,7 @@ \begin{funcdesc}{handle}{} This function must do all the work required to service a request. +The default implementation does nothing. Several instance attributes are available to it; the request is available as \member{self.request}; the client address as \member{self.client_address}; and the server instance as

1 0