diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -978,30 +978,32 @@ done. This can be done using the :c:fun PyErr_Restore(err_type, err_value, err_traceback); Py_DECREF(self->my_callback); } Py_TYPE(obj)->tp_free((PyObject*)self); } .. note:: + There are limitations to what you can safely do in a deallocator function. First, if your type supports garbage collection (using :c:member:`~PyTypeObject.tp_traverse` and/or :c:member:`~PyTypeObject.tp_clear`), some of the object's members can have been cleared or finalized by the time :c:member:`~PyTypeObject.tp_dealloc` is called. Second, in :c:member:`~PyTypeObject.tp_dealloc`, your object is in an unstable state: its reference count is equal to zero. Any call to a non-trivial object or API (as in the example above) might end up calling :c:member:`~PyTypeObject.tp_dealloc` again, causing a double free and a crash. Starting with Python 3.4, it is recommended not to put any complex finalization code in :c:member:`~PyTypeObject.tp_dealloc`, and instead use the new :c:member:`~PyTypeObject.tp_finalize` type method. .. seealso:: + :pep:`442` explains the new finalization scheme. .. index:: single: string; object representation builtin: repr Object Presentation ------------------- diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -692,17 +692,19 @@ Yes. Here's a simple example that uses u Note that in general for percent-encoded POST operations, query strings must be quoted using :func:`urllib.parse.urlencode`. For example, to send ``name=Guy Steele, Jr.``:: >>> import urllib.parse >>> urllib.parse.urlencode({'name': 'Guy Steele, Jr.'}) 'name=Guy+Steele%2C+Jr.' -.. seealso:: :ref:`urllib-howto` for extensive examples. +.. seealso:: + + :ref:`urllib-howto` for extensive examples. What module should I use to help with generating HTML? ------------------------------------------------------ .. XXX add modern template languages You can find a collection of useful links on the `Web Programming wiki page diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1889,16 +1889,17 @@ the populated namespace and the list of >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='store_true') >>> parser.add_argument('bar') >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam']) (Namespace(bar='BAR', foo=True), ['--badger', 'spam']) .. warning:: + :ref:`Prefix matching ` rules apply to :meth:`parse_known_args`. The parser may consume an option even if it's just a prefix of one of its known options, instead of leaving it in the remaining arguments list. Customizing file parsing ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -192,17 +192,19 @@ Creating connections Options allowing to change how the connection is created: * *ssl*: if given and not false, a SSL/TLS transport is created (by default a plain TCP transport is created). If *ssl* is a :class:`ssl.SSLContext` object, this context is used to create the transport; if *ssl* is :const:`True`, a context with some unspecified default settings is used. - .. seealso:: :ref:`SSL/TLS security considerations ` + .. seealso:: + + :ref:`SSL/TLS security considerations ` * *server_hostname*, is only for use together with *ssl*, and sets or overrides the hostname that the target server's certificate will be matched against. By default the value of the *host* argument is used. If *host* is empty, there is no default and you must pass a value for *server_hostname*. If *server_hostname* is an empty string, hostname matching is disabled (which is a serious security risk, allowing for man-in-the-middle-attacks). diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst --- a/Doc/library/asyncio-protocol.rst +++ b/Doc/library/asyncio-protocol.rst @@ -390,24 +390,26 @@ These callbacks may be called on :class: :meth:`pause_writing` and :meth:`resume_writing` calls are paired -- :meth:`pause_writing` is called once when the buffer goes strictly over the high-water mark (even if subsequent writes increases the buffer size even more), and eventually :meth:`resume_writing` is called once when the buffer size reaches the low-water mark. .. note:: + If the buffer size equals the high-water mark, :meth:`pause_writing` is not called -- it must go strictly over. Conversely, :meth:`resume_writing` is called when the buffer size is equal or lower than the low-water mark. These end conditions are important to ensure that things go as expected when either mark is zero. .. note:: + On BSD systems (OS X, FreeBSD, etc.) flow control is not supported for :class:`DatagramProtocol`, because send failures caused by writing too many packets cannot be detected easily. The socket always appears 'ready' and excess packets are dropped; an :class:`OSError` with errno set to :const:`errno.ENOBUFS` may or may not be raised; if it is raised, it will be reported to :meth:`DatagramProtocol.error_received` but otherwise ignored. diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -264,16 +264,17 @@ Example combining a :class:`Future` and loop.close() The coroutine function is responsible for the computation (which takes 1 second) and it stores the result into the future. The :meth:`~BaseEventLoop.run_until_complete` method waits for the completion of the future. .. note:: + The :meth:`~BaseEventLoop.run_until_complete` method uses internally the :meth:`~Future.add_done_callback` method to be notified when the future is done. Example: Future with run_forever() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Doc/library/email.contentmanager.rst b/Doc/library/email.contentmanager.rst --- a/Doc/library/email.contentmanager.rst +++ b/Doc/library/email.contentmanager.rst @@ -396,17 +396,19 @@ Currently the email package provides onl If the input cannot be encoded in the specified encoding (eg: ``7bit``), raise a :exc:`ValueError`. For :class:`~email.message.Message`, per :rfc:`2046`, raise an error if a *cte* of ``quoted-printable`` or ``base64`` is requested for *subtype* ``rfc822``, and for any *cte* other than ``7bit`` for *subtype* ``external-body``. For ``message/rfc822``, use ``8bit`` if *cte* is not specified. For all other values of *subtype*, use ``7bit``. - .. note:: A *cte* of ``binary`` does not actually work correctly yet. + .. note:: + + A *cte* of ``binary`` does not actually work correctly yet. The ``Message`` object as modified by ``set_content`` is correct, but :class:`~email.generator.BytesGenerator` does not serialize it correctly. If *disposition* is set, use it as the value of the :mailheader:`Content-Disposition` header. If not specified, and *filename* is specified, add the header with the value ``attachment``. If it is not specified and *filename* is also not specified, do not add diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst --- a/Doc/library/logging.handlers.rst +++ b/Doc/library/logging.handlers.rst @@ -859,17 +859,19 @@ supports sending logging messages to a W if more specific customization of what's sent to the server is required. .. method:: emit(record) Sends the record to the Web server as an URL-encoded dictionary. The :meth:`mapLogRecord` method is used to convert the record to the dictionary to be sent. - .. note:: Since preparing a record for sending it to a Web server is not + .. note:: + + Since preparing a record for sending it to a Web server is not the same as a generic formatting operation, using :meth:`~logging.Handler.setFormatter` to specify a :class:`~logging.Formatter` for a :class:`HTTPHandler` has no effect. Instead of calling :meth:`~logging.Handler.format`, this handler calls :meth:`mapLogRecord` and then :func:`urllib.parse.urlencode` to encode the dictionary in a form suitable for sending to a Web server. diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -846,16 +846,17 @@ Miscellaneous already finished. .. function:: cpu_count() Return the number of CPUs in the system. May raise :exc:`NotImplementedError`. .. seealso:: + :func:`os.cpu_count` .. function:: current_process() Return the :class:`Process` object corresponding to the current process. An analogue of :func:`threading.current_thread`. diff --git a/Doc/library/os.rst b/Doc/library/os.rst --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -52,16 +52,17 @@ Notes on the availability of these funct .. data:: name The name of the operating system dependent module imported. The following names have currently been registered: ``'posix'``, ``'nt'``, ``'ce'``, ``'java'``. .. seealso:: + :attr:`sys.platform` has a finer granularity. :func:`os.uname` gives system-dependent version information. The :mod:`platform` module provides detailed checks for the system's identity. .. _os-filenames: diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -27,25 +27,28 @@ Pure paths are useful in some special ca #. If you want to manipulate Windows paths on a Unix machine (or vice versa). You cannot instantiate a :class:`WindowsPath` when running on Unix, but you can instantiate :class:`PureWindowsPath`. #. You want to make sure that your code only manipulates paths without actually accessing the OS. In this case, instantiating one of the pure classes may be useful since those simply don't have any OS-accessing operations. .. note:: + This module has been included in the standard library on a :term:`provisional basis `. Backwards incompatible changes (up to and including removal of the package) may occur if deemed necessary by the core developers. .. seealso:: + :pep:`428`: The pathlib module -- object-oriented filesystem paths. .. seealso:: + For low-level path manipulation on strings, you can also use the :mod:`os.path` module. Basic use --------- Importing the main class:: diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -136,16 +136,17 @@ to read the pickle produced. other Python 3 versions is required. * Protocol version 4 was added in Python 3.4. It adds support for very large objects, pickling more kinds of objects, and some data format optimizations. Refer to :pep:`3154` for information about improvements brought by protocol 4. .. note:: + Serialization is a more primitive notion than persistence; although :mod:`pickle` reads and writes file objects, it does not handle the issue of naming persistent objects, nor the (even more complicated) issue of concurrent access to persistent objects. The :mod:`pickle` module can transform a complex object into a byte stream and it can transform the byte stream into an object with the same internal structure. Perhaps the most obvious thing to do with these byte streams is to write them onto a file, but it is also conceivable to send them across a network or store them in a database. The :mod:`shelve` diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -254,24 +254,26 @@ purposes. and :data:`OP_NO_SSLv3` with high encryption cipher suites without RC4 and without unauthenticated cipher suites. Passing :data:`~Purpose.SERVER_AUTH` as *purpose* sets :data:`~SSLContext.verify_mode` to :data:`CERT_REQUIRED` and either loads CA certificates (when at least one of *cafile*, *capath* or *cadata* is given) or uses :meth:`SSLContext.load_default_certs` to load default CA certificates. .. note:: + The protocol, options, cipher and other settings may change to more restrictive values anytime without prior deprecation. The values represent a fair balance between compatibility and security. If your application needs specific settings, you should create a :class:`SSLContext` and apply the settings yourself. .. note:: + If you find that when certain older clients or servers attempt to connect with a :class:`SSLContext` created by this function that they get an error stating "Protocol or cipher suite mismatch", it may be that they only support SSL3.0 which this function excludes using the :data:`OP_NO_SSLv3`. SSL3.0 has problematic security due to a number of poor implementations and it's reliance on MD5 within the protocol. If you wish to continue to use this function but still allow SSL 3.0 connections you can re-enable them using:: @@ -927,16 +929,17 @@ to speed up repeated connections from th .. class:: SSLContext(protocol) Create a new SSL context. You must pass *protocol* which must be one of the ``PROTOCOL_*`` constants defined in this module. :data:`PROTOCOL_SSLv23` is currently recommended for maximum interoperability. .. seealso:: + :func:`create_default_context` lets the :mod:`ssl` module choose security settings for a given purpose. :class:`SSLContext` objects have the following methods and attributes: .. method:: SSLContext.cert_store_stats() diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst --- a/Doc/library/statistics.rst +++ b/Doc/library/statistics.rst @@ -130,17 +130,19 @@ However, for reading convenience, most o .. doctest:: >>> median([1, 3, 5, 7]) 4.0 This is suited for when your data is discrete, and you don't mind that the median may not be an actual data point. - .. seealso:: :func:`median_low`, :func:`median_high`, :func:`median_grouped` + .. seealso:: + + :func:`median_low`, :func:`median_high`, :func:`median_grouped` .. function:: median_low(data) Return the low median of numeric data. If *data* is empty, :exc:`StatisticsError` is raised. The low median is always a member of the data set. When the number of data diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -3867,16 +3867,17 @@ pairs within braces, for example: ``{'ja key/value pairs: ``d.update(red=1, blue=2)``. .. method:: values() Return a new view of the dictionary's values. See the :ref:`documentation of view objects `. .. seealso:: + :class:`types.MappingProxyType` can be used to create a read-only view of a :class:`dict`. .. _dict-views: Dictionary view objects ----------------------- diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -793,16 +793,17 @@ always available. the entries inserted as a result of :envvar:`PYTHONPATH`. A program is free to modify this list for its own purposes. Only strings and bytes should be added to :data:`sys.path`; all other data types are ignored during import. .. seealso:: + Module :mod:`site` This describes how to use .pth files to extend :data:`sys.path`. .. data:: path_hooks A list of callables that take a path argument to try to create a :term:`finder` for the path. If a finder can be created, it is to be diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -36,16 +36,17 @@ added to the filter by calling :func:`fi state by calling :func:`resetwarnings`. The printing of warning messages is done by calling :func:`showwarning`, which may be overridden; the default implementation of this function formats the message by calling :func:`formatwarning`, which is also available for use by custom implementations. .. seealso:: + :func:`logging.captureWarnings` allows you to handle all warnings with the standard logging infrastructure. .. _warning-categories: Warning Categories ------------------ diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -102,16 +102,17 @@ source. Many standard library modules contain code that is invoked on their execution as a script. An example is the :mod:`timeit` module:: python -mtimeit -s 'setup here' 'benchmarked code here' python -mtimeit -h # for details .. seealso:: + :func:`runpy.run_module` Equivalent functionality directly available to Python code :pep:`338` -- Executing modules as scripts .. versionchanged:: 3.1 Supply the package name to run a ``__main__`` submodule. @@ -153,17 +154,19 @@ If no interface option is given, :option an empty string (``""``) and the current directory will be added to the start of :data:`sys.path`. Also, tab-completion and history editing is automatically enabled, if available on your platform (see :ref:`rlcompleter-config`). .. versionchanged:: 3.4 Automatic enabling of tab-completion and history editing. -.. seealso:: :ref:`tut-invoking` +.. seealso:: + + :ref:`tut-invoking` Generic options ~~~~~~~~~~~~~~~ .. cmdoption:: -? -h --help @@ -357,16 +360,17 @@ Miscellaneous options warning category. This must be a class name; the match tests whether the actual warning category of the message is a subclass of the specified warning category. The full class name must be given. The *module* field matches the (fully-qualified) module name; this match is case-sensitive. The *line* field matches the line number, where zero matches all line numbers and is thus equivalent to an omitted line number. .. seealso:: + :mod:`warnings` -- the warnings module :pep:`230` -- Warning framework :envvar:`PYTHONWARNINGS` .. cmdoption:: -x