diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/install/index.rst | 7 | ||||
| -rw-r--r-- | Doc/library/ctypes.rst | 52 | ||||
| -rw-r--r-- | Doc/library/functools.rst | 10 | ||||
| -rw-r--r-- | Doc/library/imputil.rst | 234 | ||||
| -rw-r--r-- | Doc/library/ipc.rst | 1 | ||||
| -rw-r--r-- | Doc/library/modules.rst | 1 | ||||
| -rw-r--r-- | Doc/library/rfc822.rst | 6 | ||||
| -rw-r--r-- | Doc/library/runpy.rst | 8 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 81 | ||||
| -rw-r--r-- | Doc/library/ssl.rst | 319 | ||||
| -rw-r--r-- | Doc/library/test.rst | 33 | ||||
| -rw-r--r-- | Doc/library/urllib2.rst | 2 |
12 files changed, 631 insertions, 123 deletions
diff --git a/Doc/install/index.rst b/Doc/install/index.rst index 01f17f8..c607eb9 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -604,8 +604,6 @@ value of ``sys.path``. :: The null string in ``sys.path`` represents the current working directory. -.. % $ <-- bow to font-lock - The expected convention for locally installed packages is to put them in the :file:`{...}/site-packages/` directory, but you may want to install Python modules into some arbitrary directory. For example, your site may have a @@ -624,9 +622,8 @@ installing fixed versions of standard modules.) Paths can be absolute or relative, in which case they're relative to the directory containing the :file:`.pth` file. Any directories added to the search -path will be scanned in turn for :file:`.pth` files. See `site module -documentation <http://www.python.org/dev/doc/devel/lib/module-site.html>`_ for -more information. +path will be scanned in turn for :file:`.pth` files. See the documentation of +the :mod:`site` module for more information. A slightly less convenient way is to edit the :file:`site.py` file in Python's standard library, and modify ``sys.path``. :file:`site.py` is automatically diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index dc37565..1a52a75 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -109,7 +109,7 @@ UNICODE is defined or not:: *windll* does not try to select one of them by magic, you must access the version you need by specifying ``GetModuleHandleA`` or ``GetModuleHandleW`` -explicitely, and then call it with normal strings or unicode strings +explicitly, and then call it with normal strings or unicode strings respectively. Sometimes, dlls export functions with names which aren't valid Python @@ -383,7 +383,7 @@ course, it must be one of integer, string, or unicode:: If you don't want to store the instance's data in the :attr:`_as_parameter_` instance variable, you could define a ``property`` which makes the data -avaiblable. +available. .. _ctypes-specifying-required-argument-types: @@ -600,7 +600,7 @@ Structure/union alignment and byte order ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By default, Structure and Union fields are aligned in the same way the C -compiler does it. It is possible to override this behaviour be specifying a +compiler does it. It is possible to override this behavior be specifying a :attr:`_pack_` class attribute in the subclass definition. This must be set to a positive integer and specifies the maximum alignment for the fields. This is what ``#pragma pack(n)`` also does in MSVC. @@ -643,7 +643,7 @@ positive integer:: TenPointsArrayType = POINT * 10 -Here is an example of an somewhat artifical data type, a structure containing 4 +Here is an example of an somewhat artificial data type, a structure containing 4 POINTs among other stuff:: >>> from ctypes import * @@ -1134,7 +1134,7 @@ hit the NULL entry:: >>> The fact that standard Python has a frozen module and a frozen package -(indicated by the negative size member) is not wellknown, it is only used for +(indicated by the negative size member) is not well known, it is only used for testing. Try it out with ``import __hello__`` for example. @@ -1167,7 +1167,7 @@ Consider the following example:: >>> Hm. We certainly expected the last statement to print ``3 4 1 2``. What -happended? Here are the steps of the ``rc.a, rc.b = rc.b, rc.a`` line above:: +happened? Here are the steps of the ``rc.a, rc.b = rc.b, rc.a`` line above:: >>> temp0, temp1 = rc.b, rc.a >>> rc.a = temp0 @@ -1180,8 +1180,8 @@ contents of ``temp0`` into ``rc`` 's buffer. This, in turn, changes the contents of ``temp1``. So, the last assignment ``rc.b = temp1``, doesn't have the expected effect. -Keep in mind that retrieving subobjects from Structure, Unions, and Arrays -doesn't *copy* the subobject, instead it retrieves a wrapper object accessing +Keep in mind that retrieving sub-objects from Structure, Unions, and Arrays +doesn't *copy* the sub-object, instead it retrieves a wrapper object accessing the root-object's underlying buffer. Another example that may behave different from what one would expect is this:: @@ -1292,11 +1292,11 @@ library to load. is the form used for the posix linker option :option:`-l`). If no library can be found, returns ``None``. -The exact functionality is system dependend. +The exact functionality is system dependent. On Linux, ``find_library`` tries to run external programs (/sbin/ldconfig, gcc, and objdump) to find the library file. It returns the filename of the library -file. Here are sone examples:: +file. Here are some examples:: >>> from ctypes.util import find_library >>> find_library("m") @@ -1308,7 +1308,7 @@ file. Here are sone examples:: >>> On OS X, ``find_library`` tries several predefined naming schemes and paths to -locate the library, and returns a full pathname if successfull:: +locate the library, and returns a full pathname if successful:: >>> from ctypes.util import find_library >>> find_library("c") @@ -1367,7 +1367,7 @@ way is to instantiate one of the following classes: platform. The Python GIL is released before calling any function exported by these -libraries, and reaquired afterwards. +libraries, and reacquired afterwards. .. class:: PyDLL(name, mode=DEFAULT_MODE, handle=None) @@ -1411,7 +1411,7 @@ details, consult the ``dlopen(3)`` manpage, on Windows, *mode* is ignored. *RTLD_GLOBAL*, otherwise it is the same as *RTLD_LOCAL*. Instances of these classes have no public methods, however :meth:`__getattr__` -and :meth:`__getitem__` have special behaviour: functions exported by the shared +and :meth:`__getitem__` have special behavior: functions exported by the shared library can be accessed as attributes of by index. Please note that both :meth:`__getattr__` and :meth:`__getitem__` cache their result, so calling them repeatedly returns the same object each time. @@ -1427,7 +1427,7 @@ underscore to not clash with exported function names: .. attribute:: PyDLL._name - The name of the library passed in the contructor. + The name of the library passed in the constructor. Shared libraries can also be loaded by using one of the prefabricated objects, which are instances of the :class:`LibraryLoader` class, either by calling the @@ -1440,7 +1440,7 @@ loader instance. Class which loads shared libraries. ``dlltype`` should be one of the :class:`CDLL`, :class:`PyDLL`, :class:`WinDLL`, or :class:`OleDLL` types. - :meth:`__getattr__` has special behaviour: It allows to load a shared library by + :meth:`__getattr__` has special behavior: It allows to load a shared library by accessing it as attribute of a library loader instance. The result is cached, so repeated attribute accesses return the same library each time. @@ -1508,7 +1508,7 @@ They are instances of a private class: Instances of foreign functions are also C compatible data types; they represent C function pointers. -This behaviour can be customized by assigning to special attributes of the +This behavior can be customized by assigning to special attributes of the foreign function object. @@ -1520,7 +1520,7 @@ foreign function object. It is possible to assign a callable Python object that is not a ctypes type, in this case the function is assumed to return a C ``int``, and the callable will be called with this integer, allowing to do further processing or error - checking. Using this is deprecated, for more flexible postprocessing or error + checking. Using this is deprecated, for more flexible post processing or error checking use a ctypes data type as :attr:`restype` and assign a callable to the :attr:`errcheck` attribute. @@ -1558,10 +1558,10 @@ foreign function object. :attr:`restype` attribute. ``func`` is the foreign function object itself, this allows to reuse the same - callable object to check or postprocess the results of several functions. + callable object to check or post process the results of several functions. ``arguments`` is a tuple containing the parameters originally passed to the - function call, this allows to specialize the behaviour on the arguments used. + function call, this allows to specialize the behavior on the arguments used. The object that this function returns will be returned from the foreign function call, but it can also check the result value and raise an exception if the @@ -1634,7 +1634,7 @@ different ways, depending on the type and number of the parameters in the call. :noindex: Returns a foreign function that will call a COM method. ``vtbl_index`` is the - index into the virtual function table, a small nonnegative integer. *name* is + index into the virtual function table, a small non-negative integer. *name* is name of the COM method. *iid* is an optional pointer to the interface identifier which is used in extended error reporting. @@ -1827,14 +1827,14 @@ Utility functions .. function:: DllCanUnloadNow() - Windows only: This function is a hook which allows to implement inprocess COM + Windows only: This function is a hook which allows to implement in-process COM servers with ctypes. It is called from the DllCanUnloadNow function that the _ctypes extension dll exports. .. function:: DllGetClassObject() - Windows only: This function is a hook which allows to implement inprocess COM + Windows only: This function is a hook which allows to implement in-process COM servers with ctypes. It is called from the DllGetClassObject function that the ``_ctypes`` extension dll exports. @@ -1920,7 +1920,7 @@ Utility functions Windows only: this function is probably the worst-named thing in ctypes. It creates an instance of WindowsError. If *code* is not specified, ``GetLastError`` is called to determine the error code. If ``descr`` is not - spcified, :func:`FormatError` is called to get a textual description of the + specified, :func:`FormatError` is called to get a textual description of the error. @@ -1982,13 +1982,13 @@ Common instance variables of ctypes data types: Sometimes ctypes data instances do not own the memory block they contain, instead they share part of the memory block of a base object. The - :attr:`_b_base_` readonly member is the root ctypes object that owns the memory + :attr:`_b_base_` read-only member is the root ctypes object that owns the memory block. .. attribute:: _CData._b_needsfree_ - This readonly variable is true when the ctypes data instance has allocated the + This read-only variable is true when the ctypes data instance has allocated the memory block itself, false otherwise. @@ -2033,7 +2033,7 @@ converted to native Python types. In other words, if a foreign function has a :attr:`restype` of :class:`c_char_p`, you will always receive a Python string, *not* a :class:`c_char_p` instance. -Subclasses of fundamental data types do *not* inherit this behaviour. So, if a +Subclasses of fundamental data types do *not* inherit this behavior. So, if a foreign functions :attr:`restype` is a subclass of :class:`c_void_p`, you will receive an instance of this subclass from the function call. Of course, you can get the value of the pointer by accessing the ``value`` attribute. diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 4874b55..01e1fcb 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -15,7 +15,15 @@ The :mod:`functools` module is for higher-order functions: functions that act on or return other functions. In general, any callable object can be treated as a function for the purposes of this module. -The :mod:`functools` module defines the following function: +The :mod:`functools` module defines the following functions: + + +.. function:: reduce(function, iterable[, initializer]) + + This is the same function as :func:`reduce`. It is made available in this module + to allow writing code more forward-compatible with Python 3. + + .. versionadded:: 2.6 .. function:: partial(func[,*args][, **keywords]) diff --git a/Doc/library/imputil.rst b/Doc/library/imputil.rst new file mode 100644 index 0000000..34117fa --- /dev/null +++ b/Doc/library/imputil.rst @@ -0,0 +1,234 @@ + +:mod:`imputil` --- Import utilities +===================================================== + +.. module:: imputil + :synopsis: Manage and augment the import process. + + +.. index:: statement: import + +This module provides a very handy and useful mechanism for custom +:keyword:`import` hooks. Compared to the older :mod:`ihooks` module, +:mod:`imputil` takes a dramatically simpler and more straight-forward +approach to custom :keyword:`import` functions. + + +.. class:: ImportManager([fs_imp]) + + Manage the import process. + + .. method:: ImportManager.install([namespace]) + + Install this ImportManager into the specified namespace. + + .. method:: ImportManager.uninstall() + + Restore the previous import mechanism. + + .. method:: ImportManager.add_suffix(suffix, importFunc) + + Undocumented. + + +.. class:: Importer() + + Base class for replacing standard import functions. + + .. method:: Importer.import_top(name) + + Import a top-level module. + + .. method:: Importer.get_code(parent, modname, fqname) + + Find and retrieve the code for the given module. + + *parent* specifies a parent module to define a context for importing. + It may be ``None``, indicating no particular context for the search. + + *modname* specifies a single module (not dotted) within the parent. + + *fqname* specifies the fully-qualified module name. This is a + (potentially) dotted name from the "root" of the module namespace + down to the modname. + + If there is no parent, then modname==fqname. + + This method should return ``None``, or a 3-tuple. + + * If the module was not found, then ``None`` should be returned. + + * The first item of the 2- or 3-tuple should be the integer 0 or 1, + specifying whether the module that was found is a package or not. + + * The second item is the code object for the module (it will be + executed within the new module's namespace). This item can also + be a fully-loaded module object (e.g. loaded from a shared lib). + + * The third item is a dictionary of name/value pairs that will be + inserted into new module before the code object is executed. This + is provided in case the module's code expects certain values (such + as where the module was found). When the second item is a module + object, then these names/values will be inserted *after* the module + has been loaded/initialized. + + +.. class:: BuiltinImporter() + + Emulate the import mechanism for builtin and frozen modules. This is a + sub-class of the :class:`Importer` class. + + .. method:: BuiltinImporter.get_code(parent, modname, fqname) + + Undocumented. + +.. function:: py_suffix_importer(filename, finfo, fqname) + + Undocumented. + +.. class:: DynLoadSuffixImporter([desc]) + + Undocumented. + + .. method:: DynLoadSuffixImporter.import_file(filename, finfo, fqname) + + Undocumented. + +.. _examples-imputil: + +Examples +-------- + +This is a re-implementation of hierarchical module import. + +This code is intended to be read, not executed. However, it does work +-- all you need to do to enable it is "import knee". + +(The name is a pun on the klunkier predecessor of this module, "ni".) + +:: + + import sys, imp, __builtin__ + + # Replacement for __import__() + def import_hook(name, globals=None, locals=None, fromlist=None): + parent = determine_parent(globals) + q, tail = find_head_package(parent, name) + m = load_tail(q, tail) + if not fromlist: + return q + if hasattr(m, "__path__"): + ensure_fromlist(m, fromlist) + return m + + def determine_parent(globals): + if not globals or not globals.has_key("__name__"): + return None + pname = globals['__name__'] + if globals.has_key("__path__"): + parent = sys.modules[pname] + assert globals is parent.__dict__ + return parent + if '.' in pname: + i = pname.rfind('.') + pname = pname[:i] + parent = sys.modules[pname] + assert parent.__name__ == pname + return parent + return None + + def find_head_package(parent, name): + if '.' in name: + i = name.find('.') + head = name[:i] + tail = name[i+1:] + else: + head = name + tail = "" + if parent: + qname = "%s.%s" % (parent.__name__, head) + else: + qname = head + q = import_module(head, qname, parent) + if q: return q, tail + if parent: + qname = head + parent = None + q = import_module(head, qname, parent) + if q: return q, tail + raise ImportError, "No module named " + qname + + def load_tail(q, tail): + m = q + while tail: + i = tail.find('.') + if i < 0: i = len(tail) + head, tail = tail[:i], tail[i+1:] + mname = "%s.%s" % (m.__name__, head) + m = import_module(head, mname, m) + if not m: + raise ImportError, "No module named " + mname + return m + + def ensure_fromlist(m, fromlist, recursive=0): + for sub in fromlist: + if sub == "*": + if not recursive: + try: + all = m.__all__ + except AttributeError: + pass + else: + ensure_fromlist(m, all, 1) + continue + if sub != "*" and not hasattr(m, sub): + subname = "%s.%s" % (m.__name__, sub) + submod = import_module(sub, subname, m) + if not submod: + raise ImportError, "No module named " + subname + + def import_module(partname, fqname, parent): + try: + return sys.modules[fqname] + except KeyError: + pass + try: + fp, pathname, stuff = imp.find_module(partname, + parent and parent.__path__) + except ImportError: + return None + try: + m = imp.load_module(fqname, fp, pathname, stuff) + finally: + if fp: fp.close() + if parent: + setattr(parent, partname, m) + return m + + + # Replacement for reload() + def reload_hook(module): + name = module.__name__ + if '.' not in name: + return import_module(name, name, None) + i = name.rfind('.') + pname = name[:i] + parent = sys.modules[pname] + return import_module(name[i+1:], name, parent) + + + # Save the original hooks + original_import = __builtin__.__import__ + original_reload = __builtin__.reload + + # Now install our hooks + __builtin__.__import__ = import_hook + __builtin__.reload = reload_hook + +.. index:: + module: knee + +Also see the :mod:`importers` module (which can be found +in :file:`Demo/imputil/` in the Python source distribution) for additional +examples. + diff --git a/Doc/library/ipc.rst b/Doc/library/ipc.rst index fd425ed..86a66f1 100644 --- a/Doc/library/ipc.rst +++ b/Doc/library/ipc.rst @@ -19,6 +19,7 @@ The list of modules described in this chapter is: subprocess.rst socket.rst + ssl.rst signal.rst asyncore.rst asynchat.rst diff --git a/Doc/library/modules.rst b/Doc/library/modules.rst index 2590a3a..ec6f7cd 100644 --- a/Doc/library/modules.rst +++ b/Doc/library/modules.rst @@ -14,6 +14,7 @@ The full list of modules described in this chapter is: .. toctree:: imp.rst + imputil.rst zipimport.rst pkgutil.rst modulefinder.rst diff --git a/Doc/library/rfc822.rst b/Doc/library/rfc822.rst index 52df013..da9f536 100644 --- a/Doc/library/rfc822.rst +++ b/Doc/library/rfc822.rst @@ -198,10 +198,12 @@ A :class:`Message` instance has the following methods: .. method:: Message.getheader(name[, default]) - Like ``getrawheader(name)``, but strip leading and trailing whitespace. + Return a single string consisting of the last header matching *name*, + but strip leading and trailing whitespace. Internal whitespace is not stripped. The optional *default* argument can be used to specify a different default to be returned when there is no header - matching *name*. + matching *name*; it defaults to ``None``. + This is the preferred way to get parsed headers. .. method:: Message.get(name[, default]) diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst index 8846973..cfaab94 100644 --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -52,11 +52,9 @@ The :mod:`runpy` module provides a single function: If the argument *alter_sys* is supplied and evaluates to ``True``, then ``sys.argv[0]`` is updated with the value of ``__file__`` and - ``sys.modules[__name__]`` is updated with a new module object for the module - being executed. Note that neither ``sys.argv[0]`` nor ``sys.modules[__name__]`` - are restored to their original values before the function returns -- if client - code needs these values preserved, it must either save them explicitly or - else avoid enabling the automatic alterations to :mod:`sys`. + ``sys.modules[__name__]`` is updated with a temporary module object for the + module being executed. Both ``sys.argv[0]`` and ``sys.modules[__name__]`` + are restored to their original values before the function returns. Note that this manipulation of :mod:`sys` is not thread-safe. Other threads may see the partially initialised module, as well as the altered list of arguments. diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 46774a3..65842d0 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -300,17 +300,6 @@ The module :mod:`socket` exports the following constants and functions: omitted in that case. -.. function:: ssl(sock[, keyfile, certfile]) - - Initiate a SSL connection over the socket *sock*. *keyfile* is the name of a PEM - formatted file that contains your private key. *certfile* is a PEM formatted - certificate chain file. On success, a new :class:`SSLObject` is returned. - - .. warning:: - - This does not do any certificate verification! - - .. function:: socketpair([family[, type[, proto]]]) Build a pair of connected socket objects using the given address family, socket @@ -752,40 +741,6 @@ values given to the :class:`socket` constructor. .. versionadded:: 2.5 -.. _ssl-objects: - -SSL Objects ------------ - -SSL objects have the following methods. - - -.. method:: SSL.write(s) - - Writes the string *s* to the on the object's SSL connection. The return value is - the number of bytes written. - - -.. method:: SSL.read([n]) - - If *n* is provided, read *n* bytes from the SSL connection, otherwise read until - EOF. The return value is a string of the bytes read. - - -.. method:: SSL.server() - - Returns a string describing the server's certificate. Useful for debugging - purposes; do not parse the content of this string because its format can't be - parsed unambiguously. - - -.. method:: SSL.issuer() - - Returns a string describing the issuer of the server's certificate. Useful for - debugging purposes; do not parse the content of this string because its format - can't be parsed unambiguously. - - .. _socket-example: Example @@ -903,39 +858,3 @@ sends traffic to the first one connected successfully. :: s.close() print 'Received', repr(data) -This example connects to an SSL server, prints the server and issuer's -distinguished names, sends some bytes, and reads part of the response:: - - import socket - - s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) - s.connect(('www.verisign.com', 443)) - - ssl_sock = socket.ssl(s) - - print repr(ssl_sock.server()) - print repr(ssl_sock.issuer()) - - # Set a simple HTTP request -- use httplib in actual code. - ssl_sock.write("""GET / HTTP/1.0\r - Host: www.verisign.com\r\n\r\n""") - - # Read a chunk of data. Will not necessarily - # read all the data returned by the server. - data = ssl_sock.read() - - # Note that you need to close the underlying socket, not the SSL object. - del ssl_sock - s.close() - -At this writing, this SSL example prints the following output (line breaks -inserted for readability):: - - '/C=US/ST=California/L=Mountain View/ - O=VeriSign, Inc./OU=Production Services/ - OU=Terms of use at www.verisign.com/rpa (c)00/ - CN=www.verisign.com' - '/O=VeriSign Trust Network/OU=VeriSign, Inc./ - OU=VeriSign International Server CA - Class 3/ - OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign' - diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst new file mode 100644 index 0000000..8ac7e26 --- /dev/null +++ b/Doc/library/ssl.rst @@ -0,0 +1,319 @@ + +:mod:`ssl` --- SSL wrapper for socket objects, and utility functions +==================================================================== + +.. module:: ssl + :synopsis: SSL wrapper for socket objects, and utility functions + +.. versionadded:: 2.6 + + +This module provides access to Transport Layer Security (often known +as "Secure Sockets Layer") encryption and peer authentication +facilities for network sockets, both client-side and server-side. +This module uses the OpenSSL library. It is available on all modern +Unix systems, Windows, Mac OS X, and probably additional +platforms, as long as OpenSSL is installed on that platform. + +.. note:: + + Some behavior may be platform dependent, since calls are made to the operating + system socket APIs. + +This section documents the objects and functions in the `ssl` module; +for more general information about TLS, SSL, and certificates, the +reader is referred to the paper, *Introducing SSL and Certificates using OpenSSL*, by Frederick J. Hirsch, at +http://old.pseudonym.org/ssl/wwwj-index.html. + +This module defines a class, :class:`ssl.sslsocket`, which is +derived from the :class:`socket.socket` type, and supports additional +:meth:`read` and :meth:`write` methods, along with a method, :meth:`getpeercert`, +to retrieve the certificate of the other side of the connection. + +This module defines the following functions, exceptions, and constants: + +.. function:: cert_time_to_seconds(timestring) + + Returns a floating-point value containing a normal seconds-after-the-epoch time + value, given the time-string representing the "notBefore" or "notAfter" date + from a certificate. + + Here's an example:: + + >>> import ssl + >>> ssl.cert_time_to_seconds("May 9 00:00:00 2007 GMT") + 1178694000.0 + >>> import time + >>> time.ctime(ssl.cert_time_to_seconds("May 9 00:00:00 2007 GMT")) + 'Wed May 9 00:00:00 2007' + >>> + +.. exception:: sslerror + + Raised to signal an error from the underlying SSL implementation. This + signifies some problem in the higher-level + encryption and authentication layer that's superimposed on the underlying + network connection. + +.. data:: CERT_NONE + + Value to pass to the `cert_reqs` parameter to :func:`sslobject` + when no certificates will be required or validated from the other + side of the socket connection. + +.. data:: CERT_OPTIONAL + + Value to pass to the `cert_reqs` parameter to :func:`sslobject` + when no certificates will be required from the other side of the + socket connection, but if they are provided, will be validated. + Note that use of this setting requires a valid certificate + validation file also be passed as a value of the `ca_certs` + parameter. + +.. data:: CERT_REQUIRED + + Value to pass to the `cert_reqs` parameter to :func:`sslobject` + when certificates will be required from the other side of the + socket connection. Note that use of this setting requires a valid certificate + validation file also be passed as a value of the `ca_certs` + parameter. + +.. data:: PROTOCOL_SSLv2 + + Selects SSL version 2 as the channel encryption protocol. + +.. data:: PROTOCOL_SSLv23 + + Selects SSL version 2 or 3 as the channel encryption protocol. This is a setting to use for maximum compatibility + with the other end of an SSL connection, but it may cause the specific ciphers chosen for the encryption to be + of fairly low quality. + +.. data:: PROTOCOL_SSLv3 + + Selects SSL version 3 as the channel encryption protocol. + +.. data:: PROTOCOL_TLSv1 + + Selects SSL version 2 as the channel encryption protocol. This is + the most modern version, and probably the best choice for maximum + protection, if both sides can speak it. + + +Certificates +------------ + +Certificates in general are part of a public-key / private-key system. In this system, each `principal`, +(which may be a machine, or a person, or an organization) is assigned a unique two-part encryption key. +One part of the key is public, and is called the *public key*; the other part is kept secret, and is called +the *private key*. The two parts are related, in that if you encrypt a message with one of the parts, you can +decrypt it with the other part, and **only** with the other part. + +A certificate contains information about two principals. It contains +the name of a *subject*, and the subject's public key. It also +contains a statement by a second principal, the *issuer*, that the +subject is who he claims to be, and that this is indeed the subject's +public key. The issuer's statement is signed with the issuer's +private key, which only the issuer knows. However, anyone can verify +the issuer's statement by finding the issuer's public key, decrypting +the statement with it, and comparing it to the other information in +the certificate. The certificate also contains information about the +time period over which it is valid. This is expressed as two fields, +called "notBefore" and "notAfter". + +The underlying system which is used in the Python SSL support is +called "OpenSSL". It contains facilities for constructing and +validating certificates. In the Python use of certificates, the other +side of a network connection can be required to produce a certificate, +and that certificate can be validated against a file filled with +self-signed *root* certificates (so-called because the issuer is the +same as the subject), and and "CA" (certification authority) +certificates assured by those root certificates (and by other CA +certificates). Either side of a connection, client or server, can +request certificates and validation, and the connection can be optionally +set up to fail if a valid certificate is not presented by the other side. + + +sslsocket Objects +----------------- + +.. class:: sslsocket(sock [, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version=PROTOCOL_SSLv23, ca_certs=None]) + + Takes an instance *sock* of :class:`socket.socket`, and returns an instance of a subtype + of :class:`socket.socket` which wraps the underlying socket in an SSL context. + For client-side sockets, the context construction is lazy; if the underlying socket isn't + connected yet, the context construction will be performed after :meth:`connect` is called + on the socket. + + The `keyfile` and `certfile` parameters specify optional files which contain a certificate + to be used to identify the local side of the connection. Often the private key is stored + in the same file as the certificate; in this case, only the `certfile` parameter need be + passed. If the private key is stored in a separate file, both parameters must be used. + + The parameter `server_side` is a boolean which identifies whether server-side or client-side + behavior is desired from this socket. + + The parameter `cert_reqs` specifies whether a certificate is + required from the other side of the connection, and whether it will + be validated if provided. It must be one of the three values + :const:`CERT_NONE` (certificates ignored), :const:`CERT_OPTIONAL` (not required, + but validated if provided), or :const:`CERT_REQUIRED` (required and + validated). If the value of this parameter is not :const:`CERT_NONE`, then + the `ca_certs` parameter must point to a file of CA certificates. + + The parameter `ssl_version` specifies which version of the SSL protocol to use. Typically, + the server specifies this, and a client connecting to it must use the same protocol. An + SSL server using :const:`PROTOCOL_SSLv23` can understand a client connecting via SSL2, SSL3, or TLS1, + but a client using :const:`PROTOCOL_SSLv23` can only connect to an SSL2 server. + + The `ca_certs` file contains a set of concatenated "certification authority" certificates, + which are used to validate certificates passed from the other end of the connection. + This file + contains the certificates in PEM format (IETF RFC 1422) where each certificate is + encoded in base64 encoding and surrounded with a header and footer:: + + -----BEGIN CERTIFICATE----- + ... (CA certificate in base64 encoding) ... + -----END CERTIFICATE----- + + The various certificates in the file are just concatenated together:: + + -----BEGIN CERTIFICATE----- + ... (CA certificate in base64 encoding) ... + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + ... (a second CA certificate in base64 encoding) ... + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + ... (a root certificate in base64 encoding) ... + -----END CERTIFICATE----- + + Some "standard" root certificates are available at + http://www.thawte.com/roots/ (for Thawte roots) and + http://www.verisign.com/support/roots.html (for Verisign roots). + +.. method:: sslsocket.read([nbytes]) + + Reads up to `nbytes` bytes from the SSL-encrypted channel and returns them. + +.. method:: sslsocket.write(data) + + Writes the `data` to the other side of the connection, using the SSL channel to encrypt. Returns the number + of bytes written. + +.. method:: sslsocket.getpeercert() + + If there is no certificate for the peer on the other end of the connection, returns `None`. + If a certificate was received from the peer, but not validated, returns an empty `dict` instance. + If a certificate was received and validated, returns a `dict` instance with the fields + `subject` (the principal for which the certificate was issued), `issuer` (the signer of + the certificate), `notBefore` (the time before which the certificate should not be trusted), + and `notAfter` (the time after which the certificate should not be trusted) filled in. + + The "subject" and "issuer" fields are themselves dictionaries containing the fields given + in the certificate's data structure for each principal:: + + {'issuer': {'commonName': u'somemachine.python.org', + 'countryName': u'US', + 'localityName': u'Wilmington', + 'organizationName': u'Python Software Foundation', + 'organizationalUnitName': u'SSL', + 'stateOrProvinceName': u'Delaware'}, + 'subject': {'commonName': u'somemachine.python.org', + 'countryName': u'US', + 'localityName': u'Wilmington', + 'organizationName': u'Python Software Foundation', + 'organizationalUnitName': u'SSL', + 'stateOrProvinceName': u'Delaware'}, + 'notAfter': 'Sep 4 21:54:26 2007 GMT', + 'notBefore': 'Aug 25 21:54:26 2007 GMT', + 'version': 2} + + This certificate is said to be *self-signed*, because the subject + and issuer are the same entity. The *version* field refers the the X509 version + that's used for the certificate. + +Examples +-------- + +This example connects to an SSL server, prints the server's address and certificate, +sends some bytes, and reads part of the response:: + + import socket, ssl, pprint + + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + ssl_sock = ssl.sslsocket(s, ca_certs="/etc/ca_certs_file", cert_reqs=ssl.CERT_REQUIRED) + + ssl_sock.connect(('www.verisign.com', 443)) + + print repr(ssl_sock.getpeername()) + print pprint.pformat(ssl_sock.getpeercert()) + + # Set a simple HTTP request -- use httplib in actual code. + ssl_sock.write("""GET / HTTP/1.0\r + Host: www.verisign.com\r\n\r\n""") + + # Read a chunk of data. Will not necessarily + # read all the data returned by the server. + data = ssl_sock.read() + + # note that closing the sslsocket will also close the underlying socket + ssl_sock.close() + +As of August 25, 2007, the certificate printed by this program +looked like this:: + + {'issuer': {'commonName': u'VeriSign Class 3 Extended Validation SSL SGC CA', + 'countryName': u'US', + 'organizationName': u'VeriSign, Inc.', + 'organizationalUnitName': u'Terms of use at https://www.verisign.com/rpa (c)06'}, + 'subject': {'1.3.6.1.4.1.311.60.2.1.2': u'Delaware', + '1.3.6.1.4.1.311.60.2.1.3': u'US', + 'commonName': u'www.verisign.com', + 'countryName': u'US', + 'localityName': u'Mountain View', + 'organizationName': u'VeriSign, Inc.', + 'organizationalUnitName': u'Terms of use at www.verisign.com/rpa (c)06', + 'postalCode': u'94043', + 'serialNumber': u'2497886', + 'stateOrProvinceName': u'California', + 'streetAddress': u'487 East Middlefield Road'}, + 'notAfter': 'May 8 23:59:59 2009 GMT', + 'notBefore': 'May 9 00:00:00 2007 GMT', + 'version': 2} + +For server operation, typically you'd need to have a server certificate, and private key, each in a file. +You'd open a socket, bind it to a port, call :meth:`listen` on it, then start waiting for clients +to connect:: + + import socket, ssl + + bindsocket = socket.socket() + bindsocket.bind(('myaddr.mydomain.com', 10023)) + bindsocket.listen(5) + +When one did, you'd call :meth:`accept` on the socket to get the new socket from the other +end, and use :func:`sslsocket` to create a server-side SSL context for it:: + + while True: + newsocket, fromaddr = bindsocket.accept() + connstream = ssl.sslsocket(newsocket, server_side=True, certfile="mycertfile", + keyfile="mykeyfile", ssl_protocol=ssl.PROTOCOL_TLSv1) + deal_with_client(connstream) + +Then you'd read data from the `connstream` and do something with it till you are finished with the client (or the client is finished with you):: + + def deal_with_client(connstream): + + data = connstream.read() + # null data means the client is finished with us + while data: + if not do_something(connstream, data): + # we'll assume do_something returns False when we're finished with client + break + data = connstream.read() + # finished with client + connstream.close() + +And go back to listening for new client connections. + + diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 8972091..90b4db3 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -284,8 +284,38 @@ The :mod:`test.test_support` module defines the following functions: This will run all tests defined in the named module. -The :mod:`test.test_support` module defines the following classes: +.. function:: catch_warning() + + This is a context manager that guards the warnings filter from being + permanently changed and records the data of the last warning that has been + issued. + + Use like this:: + + with catch_warning() as w: + warnings.warn("foo") + assert str(w.message) == "foo" + + .. versionadded:: 2.6 + + +.. function:: captured_stdout() + + This is a context manager than runs the :keyword:`with` statement body using + a :class:`StringIO.StringIO` object as sys.stdout. That object can be + retrieved using the ``as`` clause of the with statement. + + Example use:: + + with captured_stdout() as s: + print "hello" + assert s.getvalue() == "hello" + + .. versionadded:: 2.6 + + +The :mod:`test.test_support` module defines the following classes: .. class:: TransientResource(exc[, **kwargs]) @@ -314,4 +344,3 @@ The :mod:`test.test_support` module defines the following classes: .. method:: EnvironmentVarGuard.unset(envvar) Temporarily unset the environment variable ``envvar``. - diff --git a/Doc/library/urllib2.rst b/Doc/library/urllib2.rst index 41bb033..ea43ebf 100644 --- a/Doc/library/urllib2.rst +++ b/Doc/library/urllib2.rst @@ -69,7 +69,7 @@ The :mod:`urllib2` module defines the following functions: :class:`HTTPRedirectHandler`, :class:`FTPHandler`, :class:`FileHandler`, :class:`HTTPErrorProcessor`. - If the Python installation has SSL support (:func:`socket.ssl` exists), + If the Python installation has SSL support (i.e., if the :mod:`ssl` module can be imported), :class:`HTTPSHandler` will also be added. Beginning in Python 2.3, a :class:`BaseHandler` subclass may also change its |