[Python-checkins] python/nondist/peps pep-0333.txt,1.5,1.6

[pje at users.sourceforge.net]

Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv17715

Modified Files:
	pep-0333.txt 
Log Message:
Move 'fileno()' support to a separate section, where it should be
easier to see it's an optional and platform-specific extension, not
an excuse to return "file-like" objects instead of iterables.

Index: pep-0333.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0333.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- pep-0333.txt	1 Sep 2004 04:59:21 -0000	1.5
+++ pep-0333.txt	1 Sep 2004 13:44:07 -0000	1.6
@@ -281,24 +281,6 @@
 returned by the application provides a working ``__len__()`` 
 method, it **must** return an accurate result.
 
-If the returned iterable has a ``fileno`` attribute, the server **may**
-assume that this is a ``fileno()`` method returning an operating
-system file descriptor, and that it is allowed to read directly from
-that descriptor up to the end of the file, and/or use any appropriate
-operating system facilities (e.g. the ``sendfile()`` system call) to
-transmit the file's contents.  If the server does this, it must begin
-transmission with the file's current position, and end at the end of
-the file.
-
-Note that an application **must not** return an iterable with a 
-``fileno`` attribute if it is anything other than a method returning 
-an **operating system file descriptor**.  "File-like" objects
-that do not possess a true operating system file descriptor number
-are expressly forbidden.  Servers running on platforms where file
-descriptors do not exist, or where there is no meaningful API for
-accelerating transmission from a file descriptor should ignore the
-``fileno`` attribute.
-
 If the iterable returned by the application has a ``close()`` method,
 the server or gateway **must** call that method upon completion of the
 current request, whether the request was completed normally, or 
@@ -865,6 +847,41 @@
 being bypassed by applications using those extensions!
 
 
+Optional Platform-Specific File Handling
+----------------------------------------
+
+If the application-returned iterable has a ``fileno`` attribute,
+the server or gateway **may** assume that this is a ``fileno()`` 
+method returning an operating system file descriptor, and that it is
+allowed to read directly from that descriptor up to the end of the
+file, and/or use any appropriate operating system facilities (e.g.
+the ``sendfile()`` system call) to transmit the file's contents.  If
+the server does this, it must begin transmission with the file's
+current position, and end at the end of the file.
+
+Note that an application **must not** return an iterable with a
+``fileno`` attribute if it is anything other than a method returning
+an **operating system file descriptor**.  "File-like" objects
+that do not possess a true operating system file descriptor number
+are expressly.  Servers running on platforms where file
+descriptors do not exist, or where there is no meaningful API for
+accelerating transmission from a file descriptor should ignore the
+``fileno`` attribute.
+
+On platforms that possess some analagous mechanism for fast
+transmission of static files or pipes, a server or gateway **may**
+offer a similar extension using a different method name, returning
+an object of the appropriate type for that platform.  Such servers
+**should** document the method name to be used and the type of
+object that it should return.
+
+Please note that this optional extension does not excuse the
+application from returning an iterable object.  Returning an object
+that is not iterable -- even if it implements ``fileno()`` or is
+"file-like" -- is not acceptable, and will be rejected by servers
+and gateways that do not support this optional extension.
+
+
 HTTP 1.1 Expect/Continue
 ------------------------