diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/arg.rst | 10 | ||||
| -rw-r--r-- | Doc/c-api/exceptions.rst | 9 | ||||
| -rw-r--r-- | Doc/distutils/apiref.rst | 29 | ||||
| -rw-r--r-- | Doc/howto/unicode.rst | 2 | ||||
| -rw-r--r-- | Doc/library/email.mime.rst | 15 | ||||
| -rw-r--r-- | Doc/library/json.rst | 4 | ||||
| -rw-r--r-- | Doc/library/logging.rst | 12 | ||||
| -rw-r--r-- | Doc/library/multiprocessing.rst | 6 | ||||
| -rw-r--r-- | Doc/library/new.rst | 4 | ||||
| -rw-r--r-- | Doc/library/pydoc.rst | 7 | ||||
| -rw-r--r-- | Doc/library/socketserver.rst | 2 | ||||
| -rw-r--r-- | Doc/library/urllib2.rst | 61 | ||||
| -rw-r--r-- | Doc/library/webbrowser.rst | 2 | ||||
| -rw-r--r-- | Doc/library/winsound.rst | 9 | ||||
| -rw-r--r-- | Doc/library/xml.etree.elementtree.rst | 10 |
15 files changed, 131 insertions, 51 deletions
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 5dc28af062..144a36545d 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -136,8 +136,9 @@ variable(s) whose address should be passed. them. Instead, the implementation assumes that the string object uses the encoding passed in as parameter. -``b`` (integer) [char] - Convert a Python integer to a tiny int, stored in a C :ctype:`char`. +``b`` (integer) [unsigned char] + Convert a nonnegative Python integer to an unsigned tiny int, stored in a C + :ctype:`unsigned char`. ``B`` (integer) [unsigned char] Convert a Python integer to a tiny int without overflow checking, stored in a C @@ -533,3 +534,8 @@ and the following format units are left untouched. If there is an error in the format string, the :exc:`SystemError` exception is set and *NULL* returned. + +.. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs) + + Identical to :cfunc:`Py_BuildValue`, except that it accepts a va_list + rather than a variable number of arguments. diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 29985218e4..536b123af7 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -73,11 +73,10 @@ is a separate error indicator for each thread. .. cfunction:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc) - Return true if the *given* exception matches the exception in *exc*. If *exc* - is a class object, this also returns true when *given* is an instance of a - subclass. If *exc* is a tuple, all exceptions in the tuple (and recursively in - subtuples) are searched for a match. If *given* is *NULL*, a memory access - violation will occur. + Return true if the *given* exception matches the exception in *exc*. If + *exc* is a class object, this also returns true when *given* is an instance + of a subclass. If *exc* is a tuple, all exceptions in the tuple (and + recursively in subtuples) are searched for a match. .. cfunction:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb) diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index a8f74616ab..4a0d354547 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -88,9 +88,9 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *options* | default options for the setup | a string | | | script | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *license* | The license for the package | | + | *license* | The license for the package | a string | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *keywords* | Descriptive meta-data. See | | + | *keywords* | Descriptive meta-data, see | | | | :pep:`314` | | +--------------------+--------------------------------+-------------------------------------------------------------+ | *platforms* | | | @@ -98,6 +98,13 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *cmdclass* | A mapping of command names to | a dictionary | | | :class:`Command` subclasses | | +--------------------+--------------------------------+-------------------------------------------------------------+ + | *data_files* | A list of data files to | a list | + | | install | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *package_dir* | A mapping of package to | a dictionary | + | | directory names | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + .. function:: run_setup(script_name[, script_args=None, stop_after='run']) @@ -1100,6 +1107,24 @@ other utility module. For non-POSIX platforms, currently just returns ``sys.platform``. + For MacOS X systems the OS version reflects the minimal version on which + binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` + during the build of Python), not the OS version of the current system. + + For universal binary builds on MacOS X the architecture value reflects + the univeral binary status instead of the architecture of the current + processor. For 32-bit universal binaries the architecture is ``fat``, + for 64-bit universal binaries the architecture is ``fat64``, and + for 4-way universal binaries the architecture is ``universal``. + + Examples of returned values on MacOS X: + + * ``macosx-10.3-ppc`` + + * ``macosx-10.3-fat`` + + * ``macosx-10.5-universal`` + .. % XXX isn't this also provided by some other non-distutils module? diff --git a/Doc/howto/unicode.rst b/Doc/howto/unicode.rst index 561ce29f52..d5dec63baa 100644 --- a/Doc/howto/unicode.rst +++ b/Doc/howto/unicode.rst @@ -30,7 +30,7 @@ For a while people just wrote programs that didn't display accents. I remember looking at Apple ][ BASIC programs, published in French-language publications in the mid-1980s, that had lines like these:: - PRINT "FICHER EST COMPLETE." + PRINT "FICHIER EST COMPLETE." PRINT "CARACTERE NON ACCEPTE." Those messages should contain accents, and they just look wrong to someone who diff --git a/Doc/library/email.mime.rst b/Doc/library/email.mime.rst index 6f1b0aea98..415a6825f9 100644 --- a/Doc/library/email.mime.rst +++ b/Doc/library/email.mime.rst @@ -19,6 +19,7 @@ things easier. Here are the classes: +.. currentmodule:: email.mime.base .. class:: MIMEBase(_maintype, _subtype, **_params) @@ -39,6 +40,8 @@ Here are the classes: :mailheader:`MIME-Version` header (always set to ``1.0``). +.. currentmodule:: email.mime.nonmultipart + .. class:: MIMENonMultipart() Module: :mod:`email.mime.nonmultipart` @@ -52,6 +55,8 @@ Here are the classes: .. versionadded:: 2.2.2 +.. currentmodule:: email.mime.multipart + .. class:: MIMEMultipart([subtype[, boundary[, _subparts[, _params]]]]) Module: :mod:`email.mime.multipart` @@ -77,6 +82,8 @@ Here are the classes: .. versionadded:: 2.2.2 +.. currentmodule:: email.mime.application + .. class:: MIMEApplication(_data[, _subtype[, _encoder[, **_params]]]) Module: :mod:`email.mime.application` @@ -99,6 +106,8 @@ Here are the classes: .. versionadded:: 2.5 +.. currentmodule:: email.mime.audio + .. class:: MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]]) Module: :mod:`email.mime.audio` @@ -122,6 +131,8 @@ Here are the classes: *_params* are passed straight through to the base class constructor. +.. currentmodule:: email.mime.image + .. class:: MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]]) Module: :mod:`email.mime.image` @@ -145,6 +156,8 @@ Here are the classes: *_params* are passed straight through to the :class:`MIMEBase` constructor. +.. currentmodule:: email.mime.message + .. class:: MIMEMessage(_msg[, _subtype]) Module: :mod:`email.mime.message` @@ -158,6 +171,8 @@ Here are the classes: :mimetype:`rfc822`. +.. currentmodule:: email.mime.text + .. class:: MIMEText(_text[, _subtype[, _charset]]) Module: :mod:`email.mime.text` diff --git a/Doc/library/json.rst b/Doc/library/json.rst index bff779be57..cf6138ed3f 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -166,7 +166,7 @@ Basic Usage :func:`dump`. -.. function load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) +.. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON document) to a Python object. @@ -202,7 +202,7 @@ Basic Usage class. -.. function loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) +.. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON document) to a Python object. diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index dac6aeb173..3e54422abe 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -553,10 +553,10 @@ provided: #. :class:`HTTPHandler` instances send error messages to an HTTP server using either ``GET`` or ``POST`` semantics. -The :class:`StreamHandler` and :class:`FileHandler` classes are defined in the -core logging package. The other handlers are defined in a sub- module, -:mod:`logging.handlers`. (There is also another sub-module, -:mod:`logging.config`, for configuration functionality.) +The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler` +classes are defined in the core logging package. The other handlers are +defined in a sub- module, :mod:`logging.handlers`. (There is also another +sub-module, :mod:`logging.config`, for configuration functionality.) Logged messages are formatted for presentation through instances of the :class:`Formatter` class. They are initialized with a format string suitable for @@ -1544,6 +1544,8 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call StreamHandler ^^^^^^^^^^^^^ +.. module:: logging.handlers + The :class:`StreamHandler` class, located in the core :mod:`logging` package, sends logging output to streams such as *sys.stdout*, *sys.stderr* or any file-like object (or, more precisely, any object which supports :meth:`write` @@ -2050,6 +2052,8 @@ supports sending logging messages to a Web server, using either ``GET`` or Formatter Objects ----------------- +.. currentmodule:: logging + :class:`Formatter`\ s have the following attributes and methods. They are responsible for converting a :class:`LogRecord` to (usually) a string which can be interpreted by either a human or an external system. The base diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 8297e9fcd5..6f4a3f1bf1 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -358,7 +358,7 @@ The :mod:`multiprocessing` package mostly replicates the API of the .. attribute:: daemon - The process's daemon flag, a Boolean value. This must be called before + The process's daemon flag, a Boolean value. This must be set before :meth:`start` is called. The initial value is inherited from the creating process. @@ -1810,9 +1810,9 @@ Address Formats filesystem. * An ``'AF_PIPE'`` address is a string of the form - ``r'\\\\.\\pipe\\PipeName'``. To use :func:`Client` to connect to a named + :samp:`r'\\\\.\\pipe\\{PipeName}'`. To use :func:`Client` to connect to a named pipe on a remote computer called ServerName* one should use an address of the - form ``r'\\\\ServerName\\pipe\\PipeName'`` instead. + form :samp:`r'\\\\{ServerName}\\pipe\\{PipeName}'`` instead. Note that any string beginning with two backslashes is assumed by default to be an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address. diff --git a/Doc/library/new.rst b/Doc/library/new.rst index d8e455c945..670d3d7922 100644 --- a/Doc/library/new.rst +++ b/Doc/library/new.rst @@ -1,4 +1,3 @@ - :mod:`new` --- Creation of runtime internal objects =================================================== @@ -7,7 +6,8 @@ :deprecated: .. deprecated:: 2.6 - The :mod:`new` module has been removed in Python 3.0. + The :mod:`new` module has been removed in Python 3.0. Use the :mod:`types` + module's classes instead. .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst index 6d4986e81c..3784515477 100644 --- a/Doc/library/pydoc.rst +++ b/Doc/library/pydoc.rst @@ -36,6 +36,13 @@ it contains the path separator for your operating system, such as a slash in Unix), and refers to an existing Python source file, then documentation is produced for that file. +.. note:: + + In order to find objects and their documentation, :mod:`pydoc` imports the + module(s) to be documented. Therefore, any code on module level will be + executed on that occasion. Use an ``if __name__ == '__main__':`` guard to + only execute code when a file is invoked as a script and not just imported. + Specifying a :option:`-w` flag before the argument will cause HTML documentation to be written out to a file in the current directory, instead of displaying text on the console. diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst index 7f4daad341..786632edc2 100644 --- a/Doc/library/socketserver.rst +++ b/Doc/library/socketserver.rst @@ -448,7 +448,7 @@ This is the server side:: if __name__ == "__main__": HOST, PORT = "localhost", 9999 - server = SocketServer.UDPServer((HOST, PORT), BaseUDPRequestHandler) + server = SocketServer.UDPServer((HOST, PORT), MyUDPHandler) server.serve_forever() This is the client side:: diff --git a/Doc/library/urllib2.rst b/Doc/library/urllib2.rst index 18f5af7378..4c7c582908 100644 --- a/Doc/library/urllib2.rst +++ b/Doc/library/urllib2.rst @@ -391,23 +391,23 @@ OpenerDirector Objects .. method:: OpenerDirector.add_handler(handler) - *handler* should be an instance of :class:`BaseHandler`. The following methods - are searched, and added to the possible chains (note that HTTP errors are a - special case). + *handler* should be an instance of :class:`BaseHandler`. The following + methods are searched, and added to the possible chains (note that HTTP errors + are a special case). - * :meth:`protocol_open` --- signal that the handler knows how to open *protocol* - URLs. + * :samp:`{protocol}_open` --- signal that the handler knows how to open + *protocol* URLs. - * :meth:`http_error_type` --- signal that the handler knows how to handle HTTP - errors with HTTP error code *type*. + * :samp:`http_error_{type}` --- signal that the handler knows how to handle + HTTP errors with HTTP error code *type*. - * :meth:`protocol_error` --- signal that the handler knows how to handle errors - from (non-\ ``http``) *protocol*. + * :samp:`{protocol}_error` --- signal that the handler knows how to handle + errors from (non-\ ``http``) *protocol*. - * :meth:`protocol_request` --- signal that the handler knows how to pre-process - *protocol* requests. + * :samp:`{protocol}_request` --- signal that the handler knows how to + pre-process *protocol* requests. - * :meth:`protocol_response` --- signal that the handler knows how to + * :samp:`{protocol}_response` --- signal that the handler knows how to post-process *protocol* responses. @@ -441,24 +441,24 @@ OpenerDirector objects open URLs in three stages: The order in which these methods are called within each stage is determined by sorting the handler instances. -#. Every handler with a method named like :meth:`protocol_request` has that +#. Every handler with a method named like :samp:`{protocol}_request` has that method called to pre-process the request. -#. Handlers with a method named like :meth:`protocol_open` are called to handle +#. Handlers with a method named like :samp:`{protocol}_open` are called to handle the request. This stage ends when a handler either returns a non-\ :const:`None` value (ie. a response), or raises an exception (usually :exc:`URLError`). Exceptions are allowed to propagate. In fact, the above algorithm is first tried for methods named - :meth:`default_open`. If all such methods return :const:`None`, the algorithm - is repeated for methods named like :meth:`protocol_open`. If all such methods - return :const:`None`, the algorithm is repeated for methods named - :meth:`unknown_open`. + :meth:`default_open`. If all such methods return :const:`None`, the + algorithm is repeated for methods named like :samp:`{protocol}_open`. If all + such methods return :const:`None`, the algorithm is repeated for methods + named :meth:`unknown_open`. Note that the implementation of these methods may involve calls of the parent :class:`OpenerDirector` instance's :meth:`.open` and :meth:`.error` methods. -#. Every handler with a method named like :meth:`protocol_response` has that +#. Every handler with a method named like :samp:`{protocol}_response` has that method called to post-process the response. @@ -514,8 +514,10 @@ The following members and methods should only be used by classes derived from .. method:: BaseHandler.protocol_open(req) :noindex: + ("protocol" is to be replaced by the protocol name.) + This method is *not* defined in :class:`BaseHandler`, but subclasses should - define it if they want to handle URLs with the given protocol. + define it if they want to handle URLs with the given *protocol*. This method, if defined, will be called by the parent :class:`OpenerDirector`. Return values should be the same as for :meth:`default_open`. @@ -563,8 +565,10 @@ The following members and methods should only be used by classes derived from .. method:: BaseHandler.protocol_request(req) :noindex: + ("protocol" is to be replaced by the protocol name.) + This method is *not* defined in :class:`BaseHandler`, but subclasses should - define it if they want to pre-process requests of the given protocol. + define it if they want to pre-process requests of the given *protocol*. This method, if defined, will be called by the parent :class:`OpenerDirector`. *req* will be a :class:`Request` object. The return value should be a @@ -574,8 +578,10 @@ The following members and methods should only be used by classes derived from .. method:: BaseHandler.protocol_response(req, response) :noindex: + ("protocol" is to be replaced by the protocol name.) + This method is *not* defined in :class:`BaseHandler`, but subclasses should - define it if they want to post-process responses of the given protocol. + define it if they want to post-process responses of the given *protocol*. This method, if defined, will be called by the parent :class:`OpenerDirector`. *req* will be a :class:`Request` object. *response* will be an object @@ -660,7 +666,9 @@ ProxyHandler Objects .. method:: ProxyHandler.protocol_open(request) :noindex: - The :class:`ProxyHandler` will have a method :meth:`protocol_open` for every + ("protocol" is to be replaced by the protocol name.) + + The :class:`ProxyHandler` will have a method :samp:`{protocol}_open` for every *protocol* which has a proxy in the *proxies* dictionary given in the constructor. The method will modify requests to go through the proxy, by calling ``request.set_proxy()``, and call the next handler in the chain to @@ -865,9 +873,10 @@ HTTPErrorProcessor Objects For 200 error codes, the response object is returned immediately. For non-200 error codes, this simply passes the job on to the - :meth:`protocol_error_code` handler methods, via :meth:`OpenerDirector.error`. - Eventually, :class:`urllib2.HTTPDefaultErrorHandler` will raise an - :exc:`HTTPError` if no other handler handles the error. + :samp:`{protocol}_error_code` handler methods, via + :meth:`OpenerDirector.error`. Eventually, + :class:`urllib2.HTTPDefaultErrorHandler` will raise an :exc:`HTTPError` if no + other handler handles the error. .. _urllib2-examples: diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst index 13cd8c7c2f..d340b8a528 100644 --- a/Doc/library/webbrowser.rst +++ b/Doc/library/webbrowser.rst @@ -172,7 +172,7 @@ Here are some simple examples:: Browser Controller Objects -------------------------- -Browser controllers provide two methods which parallel two of the module-level +Browser controllers provide these methods which parallel two of the module-level convenience functions: diff --git a/Doc/library/winsound.rst b/Doc/library/winsound.rst index f9709feab8..b4a3391d1a 100644 --- a/Doc/library/winsound.rst +++ b/Doc/library/winsound.rst @@ -30,8 +30,9 @@ provided by Windows platforms. It includes functions and several constants. Call the underlying :cfunc:`PlaySound` function from the Platform API. The *sound* parameter may be a filename, audio data as a string, or ``None``. Its interpretation depends on the value of *flags*, which can be a bitwise ORed - combination of the constants described below. If the system indicates an error, - :exc:`RuntimeError` is raised. + combination of the constants described below. If the *sound* parameter is + ``None``, any currently playing waveform sound is stopped. If the system + indicates an error, :exc:`RuntimeError` is raised. .. function:: MessageBeep([type=MB_OK]) @@ -108,6 +109,10 @@ provided by Windows platforms. It includes functions and several constants. Stop playing all instances of the specified sound. + .. note:: + + This flag is not supported on modern Windows platforms. + .. data:: SND_ASYNC diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index cdc774ec07..b17d5103aa 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -94,6 +94,16 @@ Functions *events* is a list of events to report back. If omitted, only "end" events are reported. Returns an :term:`iterator` providing ``(event, elem)`` pairs. + .. note:: + + :func:`iterparse` only guarantees that it has seen the ">" + character of a starting tag when it emits a "start" event, so the + attributes are defined, but the contents of the text and tail attributes + are undefined at that point. The same applies to the element children; + they may or may not be present. + + If you need a fully populated element, look for "end" events instead. + .. function:: parse(source[, parser]) |