diff --git a/pep-0333.txt b/pep-0333.txt index d0b6fe94f..68507c36c 100644 --- a/pep-0333.txt +++ b/pep-0333.txt @@ -179,7 +179,7 @@ other is a class:: returns an instance of 'AppClass', which is then the iterable return value of the "application callable" as required by the spec. - + If we wanted to use *instances* of 'AppClass' as application objects instead, we would have to implement a '__call__' method, which would be invoked to execute the application, @@ -204,9 +204,9 @@ The Server/Gateway Side The server or gateway invokes the application callable once for each request it receives from an HTTP client, that is directed at the application. To illustrate, here is a simple CGI gateway, implemented -as a function taking an application object. Note that this simple -example has limited error handling, because by default an uncaught -exception will be dumped to ``sys.stderr`` and logged by the web +as a function taking an application object. Note that this simple +example has limited error handling, because by default an uncaught +exception will be dumped to ``sys.stderr`` and logged by the web server. :: @@ -256,7 +256,7 @@ server. exc_info = None # avoid dangling circular ref elif headers_set: raise AssertionError("Headers already set!") - + headers_set[:] = [status,response_headers] return write @@ -294,13 +294,13 @@ such functions as: The presence of middleware in general is transparent to both the "server/gateway" and the "application/framework" sides of the interface, and should require no special support. A user who -desires to incorporate middleware into an application simply -provides the middleware component to the server, as if it were +desires to incorporate middleware into an application simply +provides the middleware component to the server, as if it were an application, and configures the middleware component to invoke the application, as if the middleware component were a server. Of course, the "application" that the middleware wraps may in fact be another middleware component wrapping another -application, and so on, creating what is referred to as a +application, and so on, creating what is referred to as a "middleware stack". For the most part, middleware must conform to the restrictions @@ -311,7 +311,7 @@ and these points will be noted in the specification. Here is a (tongue-in-cheek) example of a middleware component that converts ``text/plain`` responses to pig latin, using Joe Strout's -``piglatin.py``. (Note: a "real" middleware component would +``piglatin.py``. (Note: a "real" middleware component would probably use a more robust way of checking the content type, and should also check for a content encoding. Also, this simple example ignores the possibility that a word might be split across @@ -320,11 +320,11 @@ a block boundary.) :: from piglatin import piglatin - + class LatinIter: """Transform iterated output to piglatin, if it's okay to do so - + Note that the "okayness" can change until the application yields its first non-empty string, so 'transform_ok' has to be a mutable truth value.""" @@ -347,30 +347,30 @@ a block boundary.) class Latinator: # by default, don't transform output - transform = False + transform = False def __init__(self, application): self.application = application def __call__(self, environ, start_response): - + transform_ok = [] - + def start_latin(status,response_headers,exc_info=None): # Reset ok flag, in case this is a repeat call - transform_ok[:]=[] + transform_ok[:]=[] for name,value in response_headers: if name.lower()=='content-type' and value=='text/plain': transform_ok.append(True) # Strip content-length if present, else it'll be wrong - response_headers = [(name,value) - for name,value in response_headers + response_headers = [(name,value) + for name,value in response_headers if name.lower()<>'content-length' ] break - + write = start_response(status,response_headers,exc_info) if transform_ok: @@ -417,7 +417,7 @@ have these names, and the application **must** invoke the ``start_response(status,response_headers)``). The ``status`` parameter is a status string of the form -``"999 Message here"``, and ``response_headers`` is a list of +``"999 Message here"``, and ``response_headers`` is a list of ``(header_name,header_value)`` tuples describing the HTTP response header. The optional ``exc_info`` parameter is described below in the sections on `The start_response() Callable`_ and `Error Handling`_. @@ -425,14 +425,14 @@ It is used only when the application has trapped an error and is attempting to display an error message to the browser. The ``start_response`` callable must return a ``write(body_data)`` -callable that takes one positional parameter: a string to be written +callable that takes one positional parameter: a string to be written as part of the HTTP response body. (Note: the ``write()`` callable is provided only to support certain existing frameworks' imperative output APIs; it should not be used by new applications or frameworks if it can be avoided. See the `Buffering and Streaming`_ section for more details.) -When called by the server, the application object must return an +When called by the server, the application object must return an iterable yielding zero or more strings. This can be accomplished in a variety of ways, such as by returning a list of strings, or by the application being a generator function that yields strings, or @@ -440,10 +440,10 @@ by the application being a class whose instances are iterable. Regardless of how it is accomplished, the application object must always return an iterable yielding zero or more strings. -The server or gateway must transmit the yielded strings to the client -in an unbuffered fashion, completing the transmission of each string +The server or gateway must transmit the yielded strings to the client +in an unbuffered fashion, completing the transmission of each string before requesting another one. (In other words, applications -**should** perform their own buffering. See the `Buffering and +**should** perform their own buffering. See the `Buffering and Streaming`_ section below for more on how application output must be handled.) @@ -456,21 +456,21 @@ other transformations for the purpose of implementing HTTP features such as byte-range transmission. See `Other HTTP Features`_, below, for more details.) -If a call to ``len(iterable)`` succeeds, the server must be able -to rely on the result being accurate. That is, if the iterable -returned by the application provides a working ``__len__()`` +If a call to ``len(iterable)`` succeeds, the server must be able +to rely on the result being accurate. That is, if the iterable +returned by the application provides a working ``__len__()`` method, it **must** return an accurate result. (See the `Handling the Content-Length Header`_ section for information on how this would normally be used.) 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 +current request, whether the request was completed normally, or terminated early due to an error. (This is to support resource release by the application. This protocol is intended to complement PEP 325's generator support, and other common iterables with ``close()`` methods. -(Note: the application **must** invoke the ``start_response()`` +(Note: the application **must** invoke the ``start_response()`` callable before the iterable yields its first body string, so that the server can send the headers before any body content. However, this invocation **may** be performed by the iterable's first iteration, so @@ -480,8 +480,8 @@ before they begin iterating over the iterable.) Finally, servers and gateways **must not** directly use any other attributes of the iterable returned by the application, unless it is an instance of a type specific to that server or gateway, such as a "file -wrapper" returned by ``wsgi.file_wrapper`` (see `Optional -Platform-Specific File Handling`_). In the general case, only +wrapper" returned by ``wsgi.file_wrapper`` (see `Optional +Platform-Specific File Handling`_). In the general case, only attributes specified here, or accessed via e.g. the PEP 234 iteration APIs are acceptable. @@ -496,19 +496,19 @@ unless their value would be an empty string, in which case they **may** be omitted, except as otherwise noted below. ``REQUEST_METHOD`` - The HTTP request method, such as ``"GET"`` or ``"POST"``. This + The HTTP request method, such as ``"GET"`` or ``"POST"``. This cannot ever be an empty string, and so is always required. -``SCRIPT_NAME`` +``SCRIPT_NAME`` The initial portion of the request URL's "path" that corresponds to - the application object, so that the application knows its virtual + the application object, so that the application knows its virtual "location". This **may** be an empty string, if the application - corresponds to the "root" of the server. + corresponds to the "root" of the server. ``PATH_INFO`` - The remainder of the request URL's "path", designating the virtual + The remainder of the request URL's "path", designating the virtual "location" of the request's target within the application. This - **may** be an empty string, if the request URL targets the + **may** be an empty string, if the request URL targets the application root and does not have a trailing slash. ``QUERY_STRING`` @@ -547,7 +547,7 @@ unless their value would be an empty string, in which case they absence of these variables should correspond with the presence or absence of the appropriate HTTP header in the request. -A server or gateway **should** attempt to provide as many other CGI +A server or gateway **should** attempt to provide as many other CGI variables as are applicable. In addition, if SSL is in use, the server or gateway **should** also provide as many of the Apache SSL environment variables [5]_ as are applicable, such as ``HTTPS=on`` and @@ -559,7 +559,7 @@ provide a meaningful ``DOCUMENT_ROOT`` or ``PATH_TRANSLATED``.) A WSGI-compliant server or gateway **should** document what variables it provides, along with their definitions as appropriate. Applications -**should** check for the presence of any variables they require, and +**should** check for the presence of any variables they require, and have a fallback plan in the event such a variable is absent. Note: missing variables (such as ``REMOTE_USER`` when no @@ -579,20 +579,20 @@ Variable Value version 1.0. ``wsgi.url_scheme`` A string representing the "scheme" portion of - the URL at which the application is being + the URL at which the application is being invoked. Normally, this will have the value ``"http"`` or ``"https"``, as appropriate. ``wsgi.input`` An input stream (file-like object) from which the HTTP request body can be read. (The server - or gateway may perform reads on-demand as + or gateway may perform reads on-demand as requested by the application, or it may pre- read the client's request body and buffer it in-memory or on disk, or use any other technique for providing such an input stream, according to its preference.) -``wsgi.errors`` An output stream (file-like object) to which +``wsgi.errors`` An output stream (file-like object) to which error output can be written, for the purpose of recording program or other errors in a standardized and possibly centralized location. @@ -610,13 +610,13 @@ Variable Value or gateway may supply different error streams to different applications, if this is desired. -``wsgi.multithread`` This value should evaluate true if the +``wsgi.multithread`` This value should evaluate true if the application object may be simultaneously invoked by another thread in the same process, and should evaluate false otherwise. -``wsgi.multiprocess`` This value should evaluate true if an - equivalent application object may be +``wsgi.multiprocess`` This value should evaluate true if an + equivalent application object may be simultaneously invoked by another process, and should evaluate false otherwise. @@ -696,12 +696,12 @@ of the form ``start_response(status,response_headers,exc_info=None)``. (As with all WSGI callables, the arguments must be supplied positionally, not by keyword.) The ``start_response`` callable is used to begin the HTTP response, and it must return a -``write(body_data)`` callable (see the `Buffering and Streaming`_ +``write(body_data)`` callable (see the `Buffering and Streaming`_ section, below). The ``status`` argument is an HTTP "status" string like ``"200 OK"`` -or ``"404 Not Found"``. That is, it is a string consisting of a -Status-Code and a Reason-Phrase, in that order and separated by a +or ``"404 Not Found"``. That is, it is a string consisting of a +Status-Code and a Reason-Phrase, in that order and separated by a single space, with no surrounding whitespace or other characters. (See RFC 2616, Section 6.1.1 for more information.) The string **must not** contain control characters, and must not be terminated @@ -733,11 +733,11 @@ examining application-supplied headers!) Applications and middleware are forbidden from using HTTP/1.1 "hop-by-hop" features or headers, any equivalent features in HTTP/1.0, -or any headers that would affect the persistence of the client's +or any headers that would affect the persistence of the client's connection to the web server. These features are the exclusive province of the actual web server, and a server or gateway **should** consider it a fatal error for an application to attempt -sending them, and raise an error if they are supplied to +sending them, and raise an error if they are supplied to ``start_response()``. (For more specifics on "hop-by-hop" features and headers, please see the `Other HTTP Features`_ section below.) @@ -748,7 +748,7 @@ application return value that yields a non-empty string, or upon the application's first invocation of the ``write()`` callable. In other words, response headers must not be sent until there is actual body data available, or until the application's returned iterable is -exhausted. (The only possible exception to this rule is if the +exhausted. (The only possible exception to this rule is if the response headers explicitly include a ``Content-Length`` of zero.) This delaying of response header transmission is to ensure that buffered @@ -772,12 +772,12 @@ been sent, ``start_response`` **must** raise an error, and **should** raise the ``exc_info`` tuple. That is:: raise exc_info[0],exc_info[1],exc_info[2] - + This will re-raise the exception trapped by the application, and in -principle should abort the application. (It is not safe for the +principle should abort the application. (It is not safe for the application to attempt error output to the browser once the HTTP headers have already been sent.) The application **must not** trap -any exceptions raised by ``start_response``, if it called +any exceptions raised by ``start_response``, if it called ``start_response`` with ``exc_info``. Instead, it should allow such exceptions to propagate back to the server or gateway. See `Error Handling`_ below, for more details. @@ -790,7 +790,7 @@ current invocation of the application. (See the example CGI gateway above for an illustration of the correct logic.) Note: servers, gateways, or middleware implementing ``start_response`` -**should** ensure that no reference is held to the ``exc_info`` +**should** ensure that no reference is held to the ``exc_info`` parameter beyond the duration of the function's execution, to avoid creating a circular reference through the traceback and frames involved. The simplest way to do this is something like:: @@ -833,7 +833,7 @@ dealing with the absence of ``Content-Length``. (Note: applications and middleware **must not** apply any kind of ``Transfer-Encoding`` to their output, such as chunking or gzipping; -as "hop-by-hop" operations, these encodings are the province of the +as "hop-by-hop" operations, these encodings are the province of the actual web server/gateway. See `Other HTTP Features`_ below, for more details.) @@ -842,7 +842,7 @@ Buffering and Streaming ----------------------- Generally speaking, applications will achieve the best throughput -by buffering their (modestly-sized) output and sending it all at +by buffering their (modestly-sized) output and sending it all at once. This is a common approach in existing frameworks such as Zope: the output is buffered in a StringIO or similar object, then transmitted all at once, along with the response headers. @@ -850,37 +850,37 @@ transmitted all at once, along with the response headers. The corresponding approach in WSGI is for the application to simply return a single-element iterable (such as a list) containing the response body as a single string. This is the recommended approach -for the vast majority of application functions, that render +for the vast majority of application functions, that render HTML pages whose text easily fits in memory. For large files, however, or for specialized uses of HTTP streaming (such as multipart "server push"), an application may need to provide -output in smaller blocks (e.g. to avoid loading a large file into +output in smaller blocks (e.g. to avoid loading a large file into memory). It's also sometimes the case that part of a response may be time-consuming to produce, but it would be useful to send ahead the portion of the response that precedes it. In these cases, applications will usually return an iterator (often a generator-iterator) that produces the output in a block-by-block -fashion. These blocks may be broken to coincide with mulitpart -boundaries (for "server push"), or just before time-consuming +fashion. These blocks may be broken to coincide with mulitpart +boundaries (for "server push"), or just before time-consuming tasks (such as reading another block of an on-disk file). -WSGI servers, gateways, and middleware **must not** delay the +WSGI servers, gateways, and middleware **must not** delay the transmission of any block; they **must** either fully transmit the block to the client, or guarantee that they will continue transmission even while the application is producing its next block. A server/gateway or middleware may provide this guarantee in one of three ways: -1. Send the entire block to the operating system (and request +1. Send the entire block to the operating system (and request that any O/S buffers be flushed) before returning control to the application, OR - + 2. Use a different thread to ensure that the block continues to be transmitted while the application produces the next block. - + 3. (Middleware only) send the entire block to its parent gateway/server @@ -901,7 +901,7 @@ needs to accumulate more data from the application before it can produce any output, it **must** yield an empty string. To put this requirement another way, a middleware component **must -yield at least one value** each time its underlying application +yield at least one value** each time its underlying application yields a value. If the middleware cannot yield any other value, it must yield an empty string. @@ -914,7 +914,7 @@ return an iterable as soon as its underlying application returns an iterable. It is also forbidden for middleware to use the ``write()`` callable to transmit data that is yielded by an underlying application. Middleware may only use their parent -server's ``write()`` callable to transmit data that the +server's ``write()`` callable to transmit data that the underlying application sent using a middleware-provided ``write()`` callable. @@ -936,7 +936,7 @@ Therefore, to allow these frameworks to continue using an imperative API, WSGI includes a special ``write()`` callable, returned by the ``start_response`` callable. -New WSGI applications and frameworks **should not** use the +New WSGI applications and frameworks **should not** use the ``write()`` callable if it is possible to avoid doing so. The ``write()`` callable is strictly a hack to support imperative streaming APIs. In general, applications should produce their @@ -956,7 +956,7 @@ proceeds onward. An application **must** return an iterable object, even if it uses ``write()`` to produce all or part of its response body. The returned iterable **may** be empty (i.e. yield no non-empty -strings), but if it *does* yield non-empty strings, that output +strings), but if it *does* yield non-empty strings, that output must be treated normally by the server or gateway (i.e., it must be sent or queued immediately). Applications **must not** invoke ``write()`` from within their return iterable, and therefore any @@ -970,7 +970,7 @@ Unicode Issues HTTP does not directly support Unicode, and neither does this interface. All encoding/decoding must be handled by the application; all strings passed to or from the server must be standard Python byte -strings, not Unicode objects. The result of using a Unicode object +strings, not Unicode objects. The result of using a Unicode object where a string object is required, is undefined. Note also that strings passed to ``start_response()`` as a status or @@ -980,9 +980,9 @@ MIME encoding. On Python platforms where the ``str`` or ``StringType`` type is in fact Unicode-based (e.g. Jython, IronPython, Python 3000, etc.), all -"strings" referred to in this specification must contain only +"strings" referred to in this specification must contain only code points representable in ISO-8859-1 encoding (``\u0000`` through -``\u00FF``, inclusive). It is a fatal error for an application to +``\u00FF``, inclusive). It is a fatal error for an application to supply strings containing any other Unicode character or code point. Similarly, servers and gateways **must not** supply strings to an application containing any other Unicode characters. @@ -1014,7 +1014,7 @@ of its use:: status = "200 Froody" response_headers = [("content-type","text/plain")] start_response(status, response_headers) - return ["normal body goes here"] + return ["normal body goes here"] except: # XXX should trap runtime issues like MemoryError, KeyboardInterrupt # in a separate handler before this bare 'except:'... @@ -1024,21 +1024,21 @@ of its use:: return ["error body goes here"] If no output has been written when an exception occurs, the call to -``start_response`` will return normally, and the application will +``start_response`` will return normally, and the application will return an error body to be sent to the browser. However, if any output -has already been sent to the browser, ``start_response`` will reraise -the provided exception. This exception **should not** be trapped by +has already been sent to the browser, ``start_response`` will reraise +the provided exception. This exception **should not** be trapped by the application, and so the application will abort. The server or gateway can then trap this (fatal) exception and abort the response. -Servers **should** trap and log any exception that aborts an -application or the iteration of its return value. If a partial +Servers **should** trap and log any exception that aborts an +application or the iteration of its return value. If a partial response has already been written to the browser when an application error occurs, the server or gateway **may** attempt to add an error message to the output, if the already-sent headers indicate a ``text/*`` content type that the server knows how to modify cleanly. -Some middleware may wish to provide additional exception handling +Some middleware may wish to provide additional exception handling services, or intercept and replace application error messages. In such cases, middleware may choose to **not** re-raise the ``exc_info`` supplied to ``start_response``, but instead raise a middleware-specific @@ -1057,7 +1057,7 @@ long as application authors: HTTP 1.1 Expect/Continue ------------------------ -Servers and gateways that implement HTTP 1.1 **must** provide +Servers and gateways that implement HTTP 1.1 **must** provide transparent support for HTTP 1.1's "expect/continue" mechanism. This may be done in any of several ways: @@ -1069,7 +1069,7 @@ may be done in any of several ways: response if/when the application first attempts to read from the input stream. The read request must then remain blocked until the client responds. - + 3. Wait until the client decides that the server does not support expect/continue, and sends the request body on its own. (This is suboptimal, and is not recommended.) @@ -1093,7 +1093,7 @@ a server should consider itself to be like an HTTP "gateway server", with the application being an HTTP "origin server". (See RFC 2616, section 1.3, for the definition of these terms.) -However, because WSGI servers and applications do not communicate via +However, because WSGI servers and applications do not communicate via HTTP, what RFC 2616 calls "hop-by-hop" headers do not apply to WSGI internal communications. WSGI applications **must not** generate any "hop-by-hop" headers [4]_, attempt to use HTTP features that would @@ -1103,7 +1103,7 @@ WSGI servers **must** handle any supported inbound "hop-by-hop" headers on their own, such as by decoding any inbound ``Transfer-Encoding``, including chunked encoding if applicable. -Applying these principles to a variety of HTTP features, it should be +Applying these principles to a variety of HTTP features, it should be clear that a server **may** handle cache validation via the ``If-None-Match`` and ``If-Modified-Since`` request headers and the ``Last-Modified`` and ``ETag`` response headers. However, it is @@ -1113,9 +1113,9 @@ the server/gateway is not required to do such validation. Similarly, a server **may** re-encode or transport-encode an application's response, but the application **should** use a -suitable content encoding on its own, and **must not** apply a +suitable content encoding on its own, and **must not** apply a transport encoding. A server **may** transmit byte ranges of the -application's response if requested by the client, and the +application's response if requested by the client, and the application doesn't natively support byte ranges. Again, however, the application **should** perform this function on its own if desired. @@ -1124,7 +1124,7 @@ that every application must reimplement every HTTP feature; many HTTP features can be partially or fully implemented by middleware components, thus freeing both server and application authors from implementing the same features over and over again. - + Thread Support -------------- @@ -1227,14 +1227,14 @@ principle can configure these externally to the server, or in the CGI case they may be able to be set via the server's configuration files. -Applications **should** try to keep such required variables to a -minimum, since not all servers will support easy configuration of -them. Of course, even in the worst case, persons deploying an +Applications **should** try to keep such required variables to a +minimum, since not all servers will support easy configuration of +them. Of course, even in the worst case, persons deploying an application can create a script to supply the necessary configuration values:: from the_app import application - + def new_app(environ,start_response): environ['the_app.configval1'] = 'something' return application(environ,start_response) @@ -1317,7 +1317,7 @@ more complex: also implement this protocol.) Finally, middleware that wishes to support pre-2.2 versions of Python, -and iterates over application return values or itself returns an +and iterates over application return values or itself returns an iterable (or both), must follow the appropriate recommendations above. (Note: It should go without saying that to support pre-2.2 versions @@ -1342,7 +1342,7 @@ into an iterable that it then returns, e.g.:: return iter(lambda: filelike.read(block_size), '') If the server or gateway supplies ``wsgi.file_wrapper``, it must be -a callable that accepts one required positional parameter, and one +a callable that accepts one required positional parameter, and one optional positional parameter. The first parameter is the file-like object to be sent, and the second parameter is an optional block size "suggestion" (which the server/gateway need not use). The @@ -1367,7 +1367,7 @@ must occur **after** the application returns, and the server or gateway checks to see if a wrapper object was returned. (Again, because of the presence of middleware, error handlers, and the like, it is not guaranteed that any wrapper created will actually be used.) - + Apart from the handling of ``close()``, the semantics of returning a file wrapper from the application should be the same as if the application had returned ``iter(filelike.read, '')``. In other words, @@ -1378,7 +1378,7 @@ reached. Of course, platform-specific file transmission APIs don't usually accept arbitrary "file-like" objects. Therefore, a ``wsgi.file_wrapper`` has to introspect the supplied object for -things such as a ``fileno()`` (Unix-like OSes) or a +things such as a ``fileno()`` (Unix-like OSes) or a ``java.nio.FileChannel`` (under Jython) in order to determine if the file-like object is suitable for use with the platform-specific API it supports. @@ -1396,7 +1396,7 @@ file wrapper class, suitable for old (pre 2.2) and new Pythons alike:: self.blksize = blksize if hasattr(filelike,'close'): self.close = filelike.close - + def __getitem__(self,key): data = self.filelike.read(self.blksize) if data: @@ -1408,7 +1408,7 @@ access to a platform-specific API:: environ['wsgi.file_wrapper'] = FileWrapper result = application(environ, start_response) - + try: if isinstance(result,FileWrapper): # check if result.filelike is usable w/platform-specific @@ -1418,10 +1418,10 @@ access to a platform-specific API:: for data in result: # etc. - + finally: if hasattr(result,'close'): - result.close() + result.close() Questions and Answers @@ -1578,15 +1578,15 @@ or are on the PEP author's "to-do" list: * Should ``wsgi.input`` be an iterator instead of a file? This would help for asynchronous applications and chunked-encoding input streams. - + * Optional extensions are being discussed for pausing iteration of an application's ouptut until input is available or until a callback occurs. - + * Add a section about synchronous vs. asynchronous apps and servers, the relevant threading models, and issues/design goals in these areas. - + Acknowledgements ================ @@ -1608,7 +1608,7 @@ thoughtful feedback made this revised draft possible. Especially: function. His input also guided the design of the exception handling facilities, especially in the area of allowing for middleware that overrides application error messages. - + * Alan Kennedy, whose courageous attempts to implement WSGI-on-Jython (well before the spec was finalized) helped to shape the "supporting older versions of Python" section, as well as the optional @@ -1617,7 +1617,7 @@ thoughtful feedback made this revised draft possible. Especially: * Mark Nottingham, who reviewed the spec extensively for issues with HTTP RFC compliance, especially with regard to HTTP/1.1 features that I didn't even know existed until he pointed them out. - + References ========== @@ -1631,7 +1631,7 @@ References .. [3] "Chunked Transfer Coding" -- HTTP/1.1, section 3.6.1 (http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6.1) -.. [4] "End-to-end and Hop-by-hop Headers" -- HTTP/1.1, Section 13.5.1 +.. [4] "End-to-end and Hop-by-hop Headers" -- HTTP/1.1, Section 13.5.1 (http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.5.1) .. [5] mod_ssl Reference, "Environment Variables" diff --git a/pep-0376.txt b/pep-0376.txt index aa4e99722..cc752dd83 100644 --- a/pep-0376.txt +++ b/pep-0376.txt @@ -172,28 +172,28 @@ XXX See if we want to add Python version in the PKG-INFO New functions in pkgutil ======================== -To use the `.egg-info` directory content, we need to add in the standard library a set of -APIs. The best place to put these APIs seems to be `pkgutil`. +To use the `.egg-info` directory content, we need to add in the standard +library a set of APIs. The best place to put these APIs seems to be `pkgutil`. + The new functions added in the package are : -- get_egg_info(pkg_name) -> path or None +- get_egg_info(project_name) -> path or None - Scans all site-packages directories and looks for all `pkg_name.egg-info` + Scans all site-packages directories and looks for all `project_name.egg-info` directories. Returns the directory path that contains a PKG-INFO that matches - `pkg_name` for the `name` metadata. Notice that there should be at most - one result. If more than one path matches the pkg_name, a DistutilsError - is raised. + `project_name` for the `name` metadata. Notice that there should be at most + one result. The first result founded will be returned. If the directory is not found, returns None. -- get_metadata(pkg_name) -> DistributionMetadata or None +- get_metadata(project_name) -> DistributionMetadata or None Uses `get_egg_info` to get the `PKG-INFO` file, and returns a `DistributionMetadata` instance that contains the metadata. This will require a small change in `DistributionMetadata` (see #4908). -- get_egg_info_file(pkg_name, filename) -> file object or None +- get_egg_info_file(project_name, filename) -> file object or None Uses `get_egg_info` and gets any file inside the directory, pointed by filename.