Initial changes for reStructuredText. Mostly, this is about turning
some of the text into ``literals``
This commit is contained in:
Greg Stein
parent
3d754f3e07
commit
8bff1bdaa0
89
pep-0268.txt
89
pep-0268.txt
|
|
@ -8,22 +8,25 @@ Type: Standards Track
|
|||
Created: 20-Aug-2001
|
||||
Python-Version: 2.x
|
||||
Post-History: 21-Aug-2001
|
||||
Content-Type: text/x-rst
|
||||
|
||||
|
||||
Abstract
|
||||
========
|
||||
|
||||
This PEP discusses new modules and extended functionality for
|
||||
Python's HTTP support. Notably, the addition of authenticated
|
||||
requests, proxy support, authenticated proxy usage, and WebDAV [1]
|
||||
requests, proxy support, authenticated proxy usage, and WebDAV_
|
||||
capabilities.
|
||||
|
||||
|
||||
Rationale
|
||||
=========
|
||||
|
||||
Python has been quite popular as a result of its "batteries
|
||||
included" positioning. One of the most heavily used protocols,
|
||||
HTTP (see RFC 2616), has been included with Python for years
|
||||
(httplib). However, this support has not kept up with the full
|
||||
(``httplib``). However, this support has not kept up with the full
|
||||
needs and requirements of many HTTP-based applications and
|
||||
systems. In addition, new protocols based on HTTP, such as WebDAV
|
||||
and XML-RPC, are becoming useful and are seeing increasing
|
||||
|
|
@ -33,8 +36,8 @@ Rationale
|
|||
|
||||
While authentication and proxy support are two very notable
|
||||
features missing from Python's core HTTP processing, they are
|
||||
minimally handled as part of Python's URL handling (urllib and
|
||||
urllib2). However, applications that need fine-grained or
|
||||
minimally handled as part of Python's URL handling (``urllib`` and
|
||||
``urllib2``). However, applications that need fine-grained or
|
||||
sophisticated HTTP handling cannot make use of the features while
|
||||
they reside in urllib. Refactoring these features into a location
|
||||
where they can be directly associated with an HTTP connection will
|
||||
|
|
@ -49,20 +52,22 @@ Rationale
|
|||
|
||||
|
||||
Specification
|
||||
=============
|
||||
|
||||
Two modules will be added to the standard library: 'httpx' (HTTP
|
||||
extended functionality), and 'davlib' (WebDAV library).
|
||||
Two modules will be added to the standard library: ``httpx`` (HTTP
|
||||
extended functionality), and ``davlib`` (WebDAV library).
|
||||
|
||||
[ suggestions for module names are welcome; davlib has some
|
||||
precedence, but something like 'webdav' might be desirable ]
|
||||
[ suggestions for module names are welcome; ``davlib`` has some
|
||||
precedence, but something like ``webdav`` might be desirable ]
|
||||
|
||||
|
||||
HTTP Authentication
|
||||
-------------------
|
||||
|
||||
The httpx module will provide a mixin for performing HTTP
|
||||
The ``httpx`` module will provide a mixin for performing HTTP
|
||||
authentication (for both proxy and origin server
|
||||
authentication). This mixin (httpx.HandleAuthentication) can be
|
||||
combined with the HTTPConnection and the HTTPSConnection classes
|
||||
authentication). This mixin (``httpx.HandleAuthentication``) can be
|
||||
combined with the ``HTTPConnection`` and the ``HTTPSConnection`` classes
|
||||
(the mixin may possibly work with the HTTP and HTTPS compatibility
|
||||
classes, but that is not a requirement).
|
||||
|
||||
|
|
@ -74,13 +79,13 @@ HTTP Authentication
|
|||
will be provided. User-supplied authenticator subclasses can be
|
||||
registered and used by the connections.
|
||||
|
||||
A "credentials" object (httpx.Credentials) is also associated with
|
||||
A "credentials" object (``httpx.Credentials``) is also associated with
|
||||
the mixin, and stores the credentials (e.g. username and password)
|
||||
needed by the authenticators. Subclasses of Credentials can be
|
||||
created to hold additional information (e.g. NT domain).
|
||||
|
||||
The mixin overrides the getresponse() method to detect 401
|
||||
(Unauthorized) and 407 (Proxy Authentication Required)
|
||||
The mixin overrides the ``getresponse()`` method to detect ``401
|
||||
(Unauthorized)`` and ``407 (Proxy Authentication Required)``
|
||||
responses. When this is found, the response object, the
|
||||
connection, and the credentials are passed to the authenticator
|
||||
corresponding with the authentication scheme specified in the
|
||||
|
|
@ -104,7 +109,7 @@ HTTP Authentication
|
|||
can resend the request with the appropriate authentication
|
||||
information.
|
||||
|
||||
If the body is too large to be stored, then the getresponse()
|
||||
If the body is too large to be stored, then the ``getresponse()``
|
||||
simply returns the response object, indicating the 401 or 407
|
||||
error. Since the authentication information has been computed and
|
||||
cached (into the Credentials object; see below), the caller can
|
||||
|
|
@ -118,21 +123,21 @@ HTTP Authentication
|
|||
authentication fails). However, we do have the path from the URL,
|
||||
and that can be useful in determining the credentials to send to
|
||||
the server. The Basic authentication scheme is typically set up
|
||||
hierarchically: the credentials for /path can be tried for
|
||||
/path/subpath. The Digest authentication scheme has explicit
|
||||
support for the hierarchical setup. The httpx.Credentials object
|
||||
hierarchically: the credentials for ``/path`` can be tried for
|
||||
``/path/subpath``. The Digest authentication scheme has explicit
|
||||
support for the hierarchical setup. The ``httpx.Credentials`` object
|
||||
will store credentials for multiple protection spaces, and can be
|
||||
looked up in two differents ways:
|
||||
|
||||
1) looked up using (host, port, path) -- this lookup scheme is
|
||||
1) looked up using ``(host, port, path)`` -- this lookup scheme is
|
||||
used when generating a request for a path where we don't know the
|
||||
authentication realm.
|
||||
|
||||
2) looked up using (host, port, realm) -- this mechanism is used
|
||||
2) looked up using ``(host, port, realm)`` -- this mechanism is used
|
||||
during the authentication process when the server has specified
|
||||
that the Request-URI resides within a specific realm.
|
||||
|
||||
The HandleAuthentication mixin will override putrequest() to
|
||||
The ``HandleAuthentication`` mixin will override ``putrequest()`` to
|
||||
automatically insert credentials, if available. The URL from the
|
||||
putrequest is used to determine the appropriate authentication
|
||||
information to use.
|
||||
|
|
@ -145,36 +150,38 @@ HTTP Authentication
|
|||
|
||||
|
||||
Proxy Handling
|
||||
--------------
|
||||
|
||||
The httpx module will provide a mixin for using a proxy to perform
|
||||
HTTP(S) operations. This mixin (httpx.UseProxy) can be combined
|
||||
with the HTTPConnection and the HTTPSConnection classes (the mixin
|
||||
The ``httpx`` module will provide a mixin for using a proxy to perform
|
||||
HTTP(S) operations. This mixin (``httpx.UseProxy``) can be combined
|
||||
with the ``HTTPConnection`` and the ``HTTPSConnection`` classes (the mixin
|
||||
may possibly work with the HTTP and HTTPS compatibility classes,
|
||||
but that is not a requirement).
|
||||
|
||||
The mixin will record the (host, port) of the proxy to use. XXX
|
||||
The mixin will record the ``(host, port)`` of the proxy to use. XXX
|
||||
will be overridden to use this host/port combination for
|
||||
connections and to rewrite request URLs into the absoluteURIs
|
||||
referring to the origin server (these URIs are passed to the proxy
|
||||
server).
|
||||
|
||||
Proxy authentication is handled by the httpx.HandleAuthentication
|
||||
class since a user may directly use HTTP(S)Connection to speak
|
||||
Proxy authentication is handled by the ``httpx.HandleAuthentication``
|
||||
class since a user may directly use ``HTTP(S)Connection`` to speak
|
||||
with proxies.
|
||||
|
||||
|
||||
WebDAV Features
|
||||
---------------
|
||||
|
||||
The davlib module will provide a mixin for sending WebDAV requests
|
||||
to a WebDAV-enabled server. This mixin (davlib.DAVClient) can be
|
||||
combined with the HTTPConnection and the HTTPSConnection classes
|
||||
The ``davlib`` module will provide a mixin for sending WebDAV requests
|
||||
to a WebDAV-enabled server. This mixin (``davlib.DAVClient``) can be
|
||||
combined with the ``HTTPConnection`` and the ``HTTPSConnection`` classes
|
||||
(the mixin may possibly work with the HTTP and HTTPS compatibility
|
||||
classes, but that is not a requirement).
|
||||
|
||||
The mixin provides methods to perform the various HTTP methods
|
||||
defined by HTTP in RFC 2616, and by WebDAV in RFC 2518.
|
||||
|
||||
A custom response object is used to decode 207 (Multi-Status)
|
||||
A custom response object is used to decode ``207 (Multi-Status)``
|
||||
responses. The response object will use the standard library's xml
|
||||
package to parse the multistatus XML information, producing a
|
||||
simple structure of objects to hold the multistatus data. Multiple
|
||||
|
|
@ -182,24 +189,30 @@ WebDAV Features
|
|||
|
||||
|
||||
Reference Implementation
|
||||
========================
|
||||
|
||||
The actual (future/final) implementation is being developed in the
|
||||
/nondist/sandbox/Lib directory, until it is accepted and moved
|
||||
``/nondist/sandbox/Lib`` directory, until it is accepted and moved
|
||||
into the main Lib directory.
|
||||
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
[1] http://www.webdav.org/
|
||||
.. _WebDAV: http://www.webdav.org/
|
||||
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
||||
This document has been placed in the public domain.
|
||||
This document has been placed in the public domain.
|
||||
|
||||
|
||||
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
End:
|
||||
..
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
fill-column: 70
|
||||
sentence-end-double-space: t
|
||||
End:
|
||||
|
|
|
|||
Loading…
Reference in New Issue