Skip to content

C
cpython
Commit 3732ed24 authored by Larry Hastings's avatar Larry Hastings
Browse files
Options

Merge in all documentation changes since branching 3.4.0rc1.

parent b6b6a6d5
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 2029 additions and 567 deletions
Doc/c-api/arg.rst
View file @ 3732ed24
......@@ -45,6 +45,7 @@ in any early abort case).
Unless otherwise stated, buffers are not NUL-terminated.
.. note::
For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of
the length argument (int or :c:type:`Py_ssize_t`) is controlled by
defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
......
Doc/c-api/exceptions.rst
View file @ 3732ed24
......@@ -525,11 +525,11 @@ Exception Objects
reference, as accessible from Python through :attr:`__cause__`.
.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *ctx)
.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause)
Set the cause associated with the exception to *ctx*. Use *NULL* to clear
it. There is no type check to make sure that *ctx* is either an exception
instance or :const:`None`. This steals a reference to *ctx*.
Set the cause associated with the exception to *cause*. Use *NULL* to clear
it. There is no type check to make sure that *cause* is either an exception
instance or :const:`None`. This steals a reference to *cause*.
:attr:`__suppress_context__` is implicitly set to ``True`` by this function.
......
Doc/c-api/init.rst
View file @ 3732ed24
......@@ -582,6 +582,7 @@ code, or when embedding the Python interpreter:
.. index:: module: _thread
.. note::
When only the main thread exists, no GIL operations are needed. This is a
common situation (most Python programs do not use threads), and the lock
operations slow the interpreter down a bit. Therefore, the lock is not
......
Doc/c-api/module.rst
View file @ 3732ed24
......@@ -120,7 +120,7 @@ There are only a few functions special to module objects.
Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
created, or *NULL* if the module wasn't created with
:c:func:`PyModule_Create`.i
:c:func:`PyModule_Create`.
.. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
......
Doc/c-api/object.rst
View file @ 3732ed24
......@@ -357,9 +357,9 @@ attribute is considered sufficient for this determination.
.. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)
Return an estimated length for the object *o*. First trying to return its
actual length, then an estimate using ``__length_hint__``, and finally
returning the default value. On error ``-1`` is returned. This is the
Return an estimated length for the object *o*. First try to return its
actual length, then an estimate using :meth:`~object.__length_hint__`, and
finally return the default value. On error return ``-1``. This is the
equivalent to the Python expression ``operator.length_hint(o, default)``.
.. versionadded:: 3.4
......
Doc/c-api/tuple.rst
View file @ 3732ed24
......@@ -129,6 +129,14 @@ type.
Initializes a struct sequence type *type* from *desc* in place.
.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on
failure.
.. versionadded:: 3.4
.. c:type:: PyStructSequence_Desc
Contains the meta information of a struct sequence type to create.
......
Doc/c-api/typeobj.rst
View file @ 3732ed24
......@@ -205,9 +205,8 @@ type objects) *must* have the :attr:`ob_size` field.
bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW`
flag bit is set, the instance should be printed the same way as :c:member:`~PyTypeObject.tp_str`
would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance
should be printed the same was as :c:member:`~PyTypeObject.tp_repr` would format it. It should
return ``-1`` and set an exception condition when an error occurred during the
comparison.
should be printed the same way as :c:member:`~PyTypeObject.tp_repr` would format it. It should
return ``-1`` and set an exception condition when an error occurs.
It is possible that the :c:member:`~PyTypeObject.tp_print` field will be deprecated. In any case,
it is recommended not to define :c:member:`~PyTypeObject.tp_print`, but instead to rely on
......
Doc/conf.py
View file @ 3732ed24
......@@ -61,6 +61,8 @@ add_module_names = True
# By default, highlight as Python 3.
highlight_language = 'python3'
needs_sphinx = '1.1'
# Options for HTML output
# -----------------------
......@@ -118,11 +120,11 @@ _stdauthor = r'Guido van Rossum\\Fred L. Drake, Jr., editor'
latex_documents = [
('c-api/index', 'c-api.tex',
'The Python/C API', _stdauthor, 'manual'),
('distutils/index', 'distutils.tex',
('distributing/index', 'distributing.tex',
'Distributing Python Modules', _stdauthor, 'manual'),
('extending/index', 'extending.tex',
'Extending and Embedding Python', _stdauthor, 'manual'),
('install/index', 'install.tex',
('installing/index', 'installing.tex',
'Installing Python Modules', _stdauthor, 'manual'),
('library/index', 'library.tex',
'The Python Library Reference', _stdauthor, 'manual'),
......
Doc/contents.rst
View file @ 3732ed24
......@@ -11,8 +11,8 @@
library/index.rst
extending/index.rst
c-api/index.rst
distutils/index.rst
install/index.rst
distributing/index.rst
installing/index.rst
howto/index.rst
faq/index.rst
glossary.rst
......@@ -21,3 +21,11 @@
bugs.rst
copyright.rst
license.rst
.. include legacy packaging docs in build
.. toctree::
:hidden:
distutils/index.rst
install/index.rst
Doc/distributing/index.rst 0 → 100644
View file @ 3732ed24
.. _distributing-index:
###############################
Distributing Python Modules
###############################
:Email: distutils-sig@python.org
As a popular open source development project, Python has an active
supporting community of contributors and users that also make their software
available for other Python developers to use under open source license terms.
This allows Python users to share and collaborate effectively, benefiting
from the solutions others have already created to common (and sometimes
even rare!) problems, as well as potentially contributing their own
solutions to the common pool.
This guide covers the distribution part of the process. For a guide to
installing other Python projects, refer to the
:ref:`installation guide <installing-index>`.
.. note::
For corporate and other institutional users, be aware that many
organisations have their own policies around using and contributing to
open source software. Please take such policies into account when making
use of the distribution and installation tools provided with Python.
Key terms
=========
* the `Python Package Index <https://pypi.python.org/pypi>`__ is a public
repository of open source licensed packages made available for use by
other Python users
* the `Python Packaging Authority
<http://packaging.python.org/en/latest/future.html>`__ are the group of
developers and documentation authors responsible for the maintenance and
evolution of the standard packaging tools and the associated metadata and
file format standards. They maintain a variety of tools, documentation
and issue trackers on both `GitHub <https://github.com/pypa>`__ and
`BitBucket <https://bitbucket.org/pypa/>`__.
* ``distutils`` is the original build and distribution system first added to
the Python standard library in 1998. While direct use of ``distutils`` is
being phased out, it still laid the foundation for the current packaging
and distribution infrastructure, and it not only remains part of the
standard library, but its name lives on in other ways (such as the name
of the mailing list used to coordinate Python packaging standards
development).
Open source licensing and collaboration
=======================================
In most parts of the world, software is automatically covered by copyright.
This means that other developers require explicit permission to copy, use,
modify and redistribute the software.
Open source licensing is a way of explicitly granting such permission in a
relatively consistent way, allowing developers to share and collaborate
efficiently by making common solutions to various problems freely available.
This leaves many developers free to spend more time focusing on the problems
that are relatively unique to their specific situation.
The distribution tools provided with Python are designed to make it
reasonably straightforward for developers to make their own contributions
back to that common pool of software if they choose to do so.
The same distribution tools can also be used to distribute software within
an organisation, regardless of whether that software is published as open
source software or not.
Installing the tools
====================
The standard library does not include build tools that support modern
Python packaging standards, as the core development team has found that it
is important to have standard tools that work consistently, even on older
versions of Python.
The currently recommended build and distribution tools can be installed
using ``pip``::
pip install setuptools wheel twine
Reading the guide
=================
The Python Packaging User Guide covers the various key steps and elements
involved in creating a project
* `Project structure`_
* `Building and packaging the project`_
* `Uploading the project to the Python Package Index`_
.. _Project structure: \
http://packaging.python.org/en/latest/tutorial.html#creating-your-own-project
.. _Building and packaging the project: \
http://packaging.python.org/en/latest/tutorial.html#building-packaging-your-project
.. _Uploading the project to the Python Package Index: \
http://packaging.python.org/en/latest/tutorial.html#uploading-your-project-to-pypi
How do I...?
============
These are quick answers or links for some common tasks.
... choose a name for my project?
---------------------------------
This isn't an easy topic, but here are a few tips:
* check the Python Package Index to see if the name is already in use
* check popular hosting sites like GitHub, BitBucket, etc to see if there
is already a project with that name
* check what comes up in a web search for the name you're considering
* avoid particularly common words, especially ones with multiple meanings,
as they can make it difficult for users to find your software when
searching for it
... create and distribute binary extensions?
--------------------------------------------
This is actually quite a complex topic, with a variety of alternatives
available depending on exactly what you're aiming to achieve. See the
Python Packaging User Guide for more information and recommendations.
.. seealso::
`Python Packaging User Guide: Binary Extensions
<http://packaging.python.org/en/latest/extensions.html>`__
.. other topics:
Once the Development & Deployment part of PPUG is fleshed out, some of
those sections should be linked from new questions here (most notably,
we should have a question about avoiding depending on PyPI that links to
http://packaging.python.org/en/latest/deployment.html#pypi-mirrors-and-caches)
Doc/distutils/apiref.rst
View file @ 3732ed24
......@@ -853,17 +853,6 @@ Windows. It also contains the Mingw32CCompiler class which handles the mingw32
port of GCC (same as cygwin in no-cygwin mode).
:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler
===================================================
.. module:: distutils.emxccompiler
:synopsis: OS/2 EMX Compiler support
This module provides the EMXCCompiler class, a subclass of
:class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2.
:mod:`distutils.archive_util` --- Archiving utilities
======================================================
......@@ -1171,15 +1160,6 @@ other utility module.
underscore. No { } or ( ) style quoting is available.
.. function:: grok_environment_error(exc[, prefix='error: '])
Generate a useful error message from an :exc:`OSError` exception object.
Handles Python 1.5.1 and later styles, and does what it can to deal with
exception objects that don't have a filename (which happens when the error
is due to a two-file operation, such as :func:`~os.rename` or :func:`~os.link`).
Returns the error message as a string prefixed with *prefix*.
.. function:: split_quoted(s)
Split a string up according to Unix shell-like rules for quotes and backslashes.
......@@ -1943,8 +1923,12 @@ Subclasses of :class:`Command` must define the following methods.
.. module:: distutils.command.clean
:synopsis: Clean a package build area
This command removes the temporary files created by :command:`build`
and its subcommands, like intermediary compiled object files. With
the ``--all`` option, the complete build directory will be removed.
.. % todo
Extension modules built :ref:`in place <distutils-build-ext-inplace>`
will not be cleaned, as they are not in the build directory.
:mod:`distutils.command.config` --- Perform package configuration
......
Doc/distutils/configfile.rst
View file @ 3732ed24
......@@ -69,6 +69,8 @@ universal :option:`--help` option, e.g. ::
Note that an option spelled :option:`--foo-bar` on the command-line is spelled
:option:`foo_bar` in configuration files.
.. _distutils-build-ext-inplace:
For example, say you want your extensions to be built "in-place"---that is, you
have an extension :mod:`pkg.ext`, and you want the compiled extension file
(:file:`ext.so` on Unix, say) to be put in the same source directory as your
......
Doc/distutils/index.rst
View file @ 3732ed24
.. _distutils-index:
###############################
Distributing Python Modules
###############################
##############################################
Distributing Python Modules (Legacy version)
##############################################
:Authors: Greg Ward, Anthony Baxter
:Email: distutils-sig@python.org
......
Doc/distutils/setupscript.rst
View file @ 3732ed24
......@@ -685,6 +685,8 @@ include the following code fragment in your :file:`setup.py` before the
DistributionMetadata.download_url = None
.. _debug-setup-script:
Debugging the setup script
==========================
......@@ -700,7 +702,8 @@ installation is broken because they don't read all the way down to the bottom
and see that it's a permission problem.
On the other hand, this doesn't help the developer to find the cause of the
failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set
failure. For this purpose, the :envvar:`DISTUTILS_DEBUG` environment variable can be set
to anything except an empty string, and distutils will now print detailed
information what it is doing, and prints the full traceback in case an exception
occurs.
information about what it is doing, dump the full traceback when an exception
occurs, and print the whole command line when an external program (like a C
compiler) fails.
Doc/extending/index.rst
View file @ 3732ed24
......@@ -21,14 +21,31 @@ Python) that give the language its wide application range.
For a detailed description of the whole Python/C API, see the separate
:ref:`c-api-index`.
.. note::
This guide only covers the basic tools for creating extensions provided
as part of this version of CPython. Third party tools may offer simpler
alternatives. Refer to the `binary extensions section
<https://python-packaging-user-guide.readthedocs.org/en/latest/extensions.html>`__
in the Python Packaging User Guide for more information.
Recommended third party tools
=============================
This guide only covers the basic tools for creating extensions provided
as part of this version of CPython. Third party tools like Cython,
``cffi``, SWIG and Numba offer both simpler and more sophisticated
approaches to creating C and C++ extensions for Python.
.. seealso::
`Python Packaging User Guide: Binary Extensions <https://packaging.python.org/en/latest/extensions.html>`_
The Python Packaging User Guide not only covers several available
tools that simplify the creation of binary extensions, but also
discusses the various reasons why creating an extension module may be
desirable in the first place.
Creating extensions without third party tools
=============================================
This section of the guide covers creating C and C++ extensions without
assistance from third party tools. It is intended primarily for creators
of those tools, rather than being a recommended way to create your own
C extensions.
.. toctree::
:maxdepth: 2
......@@ -38,4 +55,17 @@ For a detailed description of the whole Python/C API, see the separate
newtypes.rst
building.rst
windows.rst
Embedding the CPython runtime in a larger application
=====================================================
Sometimes, rather than creating an extension that runs inside the Python
interpreter as the main application, it is desirable to instead embed
the CPython runtime inside a larger application. This section covers
some of the details involved in doing that successfully.
.. toctree::
:maxdepth: 2
:numbered:
embedding.rst
Doc/faq/general.rst
View file @ 3732ed24
......@@ -471,7 +471,8 @@ that is written in Python using Tkinter. PythonWin is a Windows-specific IDE.
Emacs users will be happy to know that there is a very good Python mode for
Emacs. All of these programming environments provide syntax highlighting,
auto-indenting, and access to the interactive interpreter while coding. Consult
http://www.python.org/editors/ for a full list of Python editing environments.
`the Python wiki <https://wiki.python.org/moin/PythonEditors>`_ for a full list
of Python editing environments.
If you want to discuss Python's use in education, you may be interested in
joining `the edu-sig mailing list
......
Doc/faq/library.rst
View file @ 3732ed24
......@@ -513,6 +513,7 @@ For data that is more regular (e.g. a homogeneous list of ints or floats),
you can also use the :mod:`array` module.
.. note::
To read and write binary data, it is mandatory to open the file in
binary mode (here, passing ``"rb"`` to :func:`open`). If you use
``"r"`` instead (the default), the file will be open in text mode
......
Doc/faq/programming.rst
View file @ 3732ed24
......@@ -1103,6 +1103,7 @@ Use a list comprehension::
result = [obj.method() for obj in mylist]
.. _faq-augmented-assignment-tuple-error:
Why does a_tuple[i] += ['item'] raise an exception when the addition works?
---------------------------------------------------------------------------
......
Doc/glossary.rst
View file @ 3732ed24
......@@ -783,6 +783,14 @@ Glossary
mapping rather than a sequence because the lookups use arbitrary
:term:`immutable` keys rather than integers.
The :class:`collections.abc.Sequence` abstract base class
defines a much richer interface that goes beyond just
:meth:`__getitem__` and :meth:`__len__`, adding :meth:`count`,
:meth:`index`, :meth:`__contains__`, and
:meth:`__reversed__`. Types that implement this expanded
interface can be registered explicitly using
:func:`~abc.register`.
single dispatch
A form of :term:`generic function` dispatch where the implementation is
chosen based on the type of a single argument.
......
Doc/howto/pyporting.rst
View file @ 3732ed24
......@@ -26,6 +26,32 @@ Porting Python 2 Code to Python 3
For help with porting, you can email the python-porting_ mailing list with
questions.
The Short Version
=================
* Decide what's the oldest version of Python 2 you want to support (if at all)
* Make sure you have a thorough test suite and use continuous integration
testing to make sure you stay compatible with the versions of Python you care
about
* If you have dependencies, check their Python 3 status using caniusepython3
(`command-line tool <https://pypi.python.org/pypi/caniusepython3>`__,
`web app <https://caniusepython3.com/>`__)
With that done, your options are:
* If you are dropping Python 2 support, use 2to3_ to port to Python 3
* If you are keeping Python 2 support, then start writing Python 2/3-compatible
code starting **TODAY**
+ If you have dependencies that have not been ported, reach out to them to port
their project while working to make your code compatible with Python 3 so
you're ready when your dependencies are all ported
+ If all your dependencies have been ported (or you have none), go ahead and
port to Python 3
* If you are creating a new project that wants to have 2/3 compatibility,
code in Python 3 and then backport to Python 2
Before You Begin
================
......@@ -85,7 +111,7 @@ between Python 2 and 3 easier.
Projects to Consider
--------------------
The lowest level library for suppoting Python 2 & 3 simultaneously is six_.
The lowest level library for supporting Python 2 & 3 simultaneously is six_.
Reading through its documentation will give you an idea of where exactly the
Python language changed between versions 2 & 3 and thus what you will want the
library to help you continue to support.
......@@ -548,7 +574,10 @@ Backporting Python 3 code to Python 2
If you have Python 3 code and have little interest in supporting Python 2 you
can use 3to2_ to translate from Python 3 code to Python 2 code. This is only
recommended if you don't plan to heavily support Python 2 users.
recommended if you don't plan to heavily support Python 2 users. Otherwise
write your code for Python 3 and then backport as far back as you want. This
is typically easier than going from Python 2 to 3 as you will have worked out
any difficulties with e.g. bytes/strings, etc.
Other Resources
......
Doc/includes/email-alternative-new-api.py
View file @ 3732ed24
......@@ -19,7 +19,7 @@ Cela ressemble à un excellent recipie[1] déjeuner.
[1] http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718
--Éric
--Pepé
""")
# Add the html version. This converts the message into a multipart/alternative
......
Doc/install/index.rst
View file @ 3732ed24
......@@ -2,9 +2,9 @@
.. _install-index:
*****************************
Installing Python Modules
*****************************
********************************************
Installing Python Modules (Legacy version)
********************************************
:Author: Greg Ward
......@@ -58,7 +58,8 @@ new goodies to their toolbox. You don't need to know Python to read this
document; there will be some brief forays into using Python's interactive mode
to explore your installation, but that's it. If you're looking for information
on how to distribute your own Python modules so that others may use them, see
the :ref:`distutils-index` manual.
the :ref:`distutils-index` manual. :ref:`debug-setup-script` may also be of
interest.
.. _inst-trivial-install:
......
Doc/installing/index.rst 0 → 100644
View file @ 3732ed24
.. highlightlang:: none
.. _installing-index:
*****************************
Installing Python Modules
*****************************
:Email: distutils-sig@python.org
As a popular open source development project, Python has an active
supporting community of contributors and users that also make their software
available for other Python developers to use under open source license terms.
This allows Python users to share and collaborate effectively, benefiting
from the solutions others have already created to common (and sometimes
even rare!) problems, as well as potentially contributing their own
solutions to the common pool.
This guide covers the installation part of the process. For a guide to
creating and sharing your own Python projects, refer to the
:ref:`distribution guide <distributing-index>`.
.. note::
For corporate and other institutional users, be aware that many
organisations have their own policies around using and contributing to
open source software. Please take such policies into account when making
use of the distribution and installation tools provided with Python.
Key terms
=========
* ``pip`` is the preferred installer program. Starting with Python 3.4, it
is included by default with the Python binary installers.
* a virtual environment is a semi-isolated Python environment that allows
packages to be installed for use by a particular application, rather than
being installed system wide
* ``pyvenv`` is the standard tool for creating virtual environments, and has
been part of Python since Python 3.3. Starting with Python 3.4, it
defaults to installing ``pip`` into all created virtual environments
* the `Python Package Index <https://pypi.python.org/pypi>`__ is a public
repository of open source licensed packages made available for use by
other Python users
* the `Python Packaging Authority
<http://packaging.python.org/en/latest/future.html>`__ are the group of
developers and documentation authors responsible for the maintenance and
evolution of the standard packaging tools and the associated metadata and
file format standards. They maintain a variety of tools, documentation
and issue trackers on both `GitHub <https://github.com/pypa>`__ and
`BitBucket <https://bitbucket.org/pypa/>`__.
* ``distutils`` is the original build and distribution system first added to
the Python standard library in 1998. While direct use of ``distutils`` is
being phased out, it still laid the foundation for the current packaging
and distribution infrastructure, and it not only remains part of the
standard library, but its name lives on in other ways (such as the name
of the mailing list used to coordinate Python packaging standards
development).
Basic usage
===========
The standard packaging tools are all designed to be used from the command
line. For Windows users, the examples below assume that the option to
adjust the system PATH environment variable was selected when installing
Python. For Linux users, the command to install into the system version of
Python 3 is likely to be ``pip3`` rather than ``pip``.
The following command will install the latest version of a module and its
dependencies from the Python Package Index::
pip install SomePackage
It's also possible to specify an exact or minimum version directly on the
command line::
pip install SomePackage==1.0.4 # specific version
pip install 'SomePackage>=1.0.4' # minimum version
Normally, if a suitable module is already installed, attempting to install
it again will have no effect. Upgrading existing modules must be requested
explicitly::
pip install --upgrade SomePackage
More information and resources regarding ``pip`` and its capabilities can be
found in the `Python Packaging User Guide <http://packaging.python.org>`__.
``pyvenv`` has its own documentation at :ref:`scripts-pyvenv`. Installing
into an active virtual environment uses the commands shown above.
.. seealso::
`Python Packaging User Guide: Installing Python packages
<http://packaging.python.org/en/latest/tutorial.html#installing-python-packages>`__
How do I ...?
=============
These are quick answers or links for some common tasks.
... install ``pip`` in versions of Python prior to Python 3.4?
--------------------------------------------------------------
Python only started bundling ``pip`` with Python 3.4. For earlier versions,
``pip`` needs to be "bootstrapped" as described in the Python Packaging
User Guide.
.. seealso::
`Python Packaging User Guide: Installing the Tools
<http://packaging.python.org/en/latest/tutorial.html#installing-the-tools>`__
.. installing-per-user-installation:
... install packages just for the current user?
-----------------------------------------------
Passing the ``--user`` option to ``pip install`` will install a package
just for the current user, rather than for all users of the system.
... install scientific Python packages?
---------------------------------------
A number of scientific Python packages have complex binary dependencies, and
aren't currently easy to install using ``pip`` directly. At this point in
time, it will often be easier for users to install these packages by
`other means
<http://packaging.python.org/en/latest/platforms.html#installing-scientific-packages>`__
rather than attempting to install them with ``pip``.
.. seealso::
`Python Packaging User Guide: Installing Scientific Packages
<http://packaging.python.org/en/latest/platforms.html#installing-scientific-packages>`__
... work with multiple versions of Python installed in parallel?
----------------------------------------------------------------
On Linux, Mac OS X and other POSIX systems, use the versioned Python commands
in combination with the ``-m`` switch to run the appropriate copy of
``pip``::
python2 -m pip install SomePackage # default Python 2
python2.7 -m pip install SomePackage # specifically Python 2.7
python3 -m pip install SomePackage # default Python 3
python3.4 -m pip install SomePackage # specifically Python 3.4
(appropriately versioned ``pip`` commands may also be available)
On Windows, use the ``py`` Python launcher in combination with the ``-m``
switch::
py -2 -m pip install SomePackage # default Python 2
py -2.7 -m pip install SomePackage # specifically Python 2.7
py -3 -m pip install SomePackage # default Python 3
py -3.4 -m pip install SomePackage # specifically Python 3.4
.. other questions:
Once the Development & Deployment part of PPUG is fleshed out, some of
those sections should be linked from new questions here (most notably,
we should have a question about avoiding depending on PyPI that links to
http://packaging.python.org/en/latest/deployment.html#pypi-mirrors-and-caches)
Common installation issues
==========================
Installing into the system Python on Linux
------------------------------------------
On Linux systems, a Python installation will typically be included as part
of the distribution. Installing into this Python installation requires
root access to the system, and may interfere with the operation of the
system package manager and other components of the system if a component
is unexpectedly upgraded using ``pip``.
On such systems, it is often better to use a virtual environment or a
per-user installation when installing packages with ``pip``.
Installing binary extensions
----------------------------
Python has typically relied heavily on source based distribution, with end
users being expected to compile extension modules from source as part of
the installation process.
With the introduction of support for the binary ``wheel`` format, and the
ability to publish wheels for at least Windows and Mac OS X through the
Python Package Index, this problem is expected to diminish over time,
as users are more regularly able to install pre-built extensions rather
than needing to build them themselves.
Some of the solutions for installing `scientific software
<http://packaging.python.org/en/latest/platforms.html#installing-scientific-packages>`__
that is not yet available as pre-built ``wheel`` files may also help with
obtaining other binary extensions without needing to build them locally.
.. seealso::
`Python Packaging User Guide: Binary Extensions
<http://packaging.python.org/en/latest/extensions.html>`__
Doc/library/aifc.rst
View file @ 3732ed24
......@@ -226,7 +226,7 @@ number of frames must be filled in.
file parameters have been set.
.. versionchanged:: 3.4
Any :term:`bytes-like object`\ s are now accepted.
Any :term:`bytes-like object` is now accepted.
.. method:: aifc.writeframesraw(data)
......@@ -235,7 +235,7 @@ number of frames must be filled in.
updated.
.. versionchanged:: 3.4
Any :term:`bytes-like object`\ s are now accepted.
Any :term:`bytes-like object` is now accepted.
.. method:: aifc.close()
......
Doc/library/asyncio-eventloop.rst
View file @ 3732ed24
......@@ -488,7 +488,7 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
* *stdout*: Either a file-like object representing the pipe to be connected
to the subprocess's standard output stream using
:meth:`~BaseEventLoop.connect_write_pipe`, or the constant
:meth:`~BaseEventLoop.connect_read_pipe`, or the constant
:const:`subprocess.PIPE` (the default). By default a new pipe will be
created and connected.
......@@ -589,8 +589,8 @@ pool of processes). By default, an event loop uses a thread pool executor
Arrange for a callback to be called in the specified executor.
*executor* is a :class:`~concurrent.futures.Executor` instance,
the default executor is used if *executor* is ``None``.
The *executor* argument should be an :class:`~concurrent.futures.Executor`
instance. The default executor is used if *executor* is ``None``.
This method is a :ref:`coroutine <coroutine>`.
......
Doc/library/asyncio-protocol.rst
View file @ 3732ed24
......@@ -376,8 +376,8 @@ The following callbacks are called on :class:`DatagramProtocol` instances.
Flow control callbacks
----------------------
These callbacks may be called on :class:`Protocol` and
:class:`SubprocessProtocol` instances:
These callbacks may be called on :class:`Protocol`,
:class:`DatagramProtocol` and :class:`SubprocessProtocol` instances:
.. method:: BaseProtocol.pause_writing()
......@@ -402,6 +402,15 @@ buffer size reaches the low-water mark.
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.
Coroutines and protocols
------------------------
......@@ -488,6 +497,6 @@ TCP echo server example, send back received data and close the connection::
:meth:`Transport.close` can be called immediately after
:meth:`WriteTransport.write` even if data are not sent yet on the socket: both
methods are asynchronous. ``yield from`` is not needed because these transport
methods don't return coroutines.
methods are not coroutines.
Doc/library/asyncio-subprocess.rst
View file @ 3732ed24
......@@ -8,16 +8,16 @@ Create a subprocess
.. function:: create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
Run the shell command *cmd* given as a string. Return a :class:`Process`
Run the shell command *cmd* given as a string. Return a :class:`~asyncio.subprocess.Process`
instance.
This function returns a :ref:`coroutine object <coroutine>`.
This function is a :ref:`coroutine <coroutine>`.
.. function:: create_subprocess_exec(\*args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
Create a subprocess. Return a :class:`Process` instance.
Create a subprocess. Return a :class:`~asyncio.subprocess.Process` instance.
This function returns a :ref:`coroutine object <coroutine>`.
This function is a :ref:`coroutine <coroutine>`.
Use the :meth:`BaseEventLoop.connect_read_pipe` and
:meth:`BaseEventLoop.connect_write_pipe` methods to connect pipes.
......
Doc/library/asyncio-sync.rst
View file @ 3732ed24
......@@ -64,7 +64,7 @@ Lock
.. method:: locked()
Return ``True`` if lock is acquired.
Return ``True`` if the lock is acquired.
.. method:: acquire()
......@@ -73,7 +73,7 @@ Lock
This method blocks until the lock is unlocked, then sets it to locked and
returns ``True``.
This method returns a :ref:`coroutine object <coroutine>`.
This method is a :ref:`coroutine <coroutine>`.
.. method:: release()
......@@ -141,6 +141,15 @@ Condition
A new :class:`Lock` object is created and used as the underlying lock.
.. method:: acquire()
Acquire the underlying lock.
This method blocks until the lock is unlocked, then sets it to locked and
returns ``True``.
This method is a :ref:`coroutine <coroutine>`.
.. method:: notify(n=1)
By default, wake up one coroutine waiting on this condition, if any.
......@@ -156,6 +165,10 @@ Condition
call until it can reacquire the lock. Since :meth:`notify` does not
release the lock, its caller should.
.. method:: locked()
Return ``True`` if the underlying lock is acquired.
.. method:: notify_all()
Wake up all threads waiting on this condition. This method acts like
......@@ -163,6 +176,18 @@ Condition
calling thread has not acquired the lock when this method is called, a
:exc:`RuntimeError` is raised.
.. method:: release()
Release the underlying lock.
When the lock is locked, reset it to unlocked, and return. If any other
coroutines are blocked waiting for the lock to become unlocked, allow
exactly one of them to proceed.
When invoked on an unlocked lock, a :exc:`RuntimeError` is raised.
There is no return value.
.. method:: wait()
Wait until notified.
......
Doc/library/audioop.rst
View file @ 3732ed24
......@@ -12,10 +12,8 @@ integers, unless specified otherwise.
.. versionchanged:: 3.4
Support for 24-bit samples was added.
.. versionchanged:: 3.4
Any :term:`bytes-like object`\ s are now accepted by all functions in this
module. Strings no more supported.
All functions now accept any :term:`bytes-like object`.
String input now results in an immediate error.
.. index::
single: Intel/DVI ADPCM
......@@ -82,7 +80,7 @@ The module defines the following variables and functions:
"Byteswap" all samples in a fragment and returns the modified fragment.
Converts big-endian samples to little-endian and vice versa.
.. versionadded: 3.4
.. versionadded:: 3.4
.. function:: cross(fragment, width)
......
Doc/library/base64.rst
View file @ 3732ed24
:mod:`base64` --- RFC 3548: Base16, Base32, Base64 Data Encodings
=================================================================
:mod:`base64` --- Base16, Base32, Base64, Base85 Data Encodings
===============================================================
.. module:: base64
:synopsis: RFC 3548: Base16, Base32, Base64 Data Encodings
:synopsis: RFC 3548: Base16, Base32, Base64 Data Encodings;
Base85 and Ascii85
.. index::
pair: base64; encoding
single: MIME; base64 encoding
This module provides data encoding and decoding as specified in :rfc:`3548`.
This standard defines the Base16, Base32, and Base64 algorithms for encoding
and decoding arbitrary binary strings into ASCII-only byte strings that can be
This module provides functions for encoding binary data to printable
ASCII characters and decoding such encodings back to binary data.
It provides encoding and decoding functions for the encodings specified in
in :rfc:`3548`, which defines the Base16, Base32, and Base64 algorithms,
and for the de-facto standard Ascii85 and Base85 encodings.
The :rfc:`3548` encodings are suitable for encoding binary data so that it can
safely sent by email, used as parts of URLs, or included as part of an HTTP
POST request. The encoding algorithm is not the same as the
:program:`uuencode` program.
There are two interfaces provided by this module. The modern interface
supports encoding and decoding ASCII byte string objects using all three
alphabets. Additionally, the decoding functions of the modern interface also
accept Unicode strings containing only ASCII characters. The legacy interface
provides for encoding and decoding to and from file-like objects as well as
byte strings, but only using the Base64 standard alphabet.
There are two :rfc:`3548` interfaces provided by this module. The modern
interface supports encoding and decoding ASCII byte string objects using all
three :rfc:`3548` defined alphabets (normal, URL-safe, and filesystem-safe).
Additionally, the decoding functions of the modern interface also accept
Unicode strings containing only ASCII characters. The legacy interface provides
for encoding and decoding to and from file-like objects as well as byte
strings, but only using the Base64 standard alphabet.
.. versionchanged:: 3.3
ASCII-only Unicode strings are now accepted by the decoding functions of
......@@ -29,7 +35,7 @@ byte strings, but only using the Base64 standard alphabet.
.. versionchanged:: 3.4
Any :term:`bytes-like object`\ s are now accepted by all
encoding and decoding functions in this module.
encoding and decoding functions in this module. Ascii85/Base85 support added.
The modern interface provides:
......
Doc/library/csv.rst
View file @ 3732ed24
......@@ -142,36 +142,43 @@ The :mod:`csv` module defines the following functions:
The :mod:`csv` module defines the following classes:
.. class:: DictReader(csvfile, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)
Create an object which operates like a regular reader but maps the information
read into a dict whose keys are given by the optional *fieldnames* parameter.
If the *fieldnames* parameter is omitted, the values in the first row of the
*csvfile* will be used as the fieldnames. If the row read has more fields
than the fieldnames sequence, the remaining data is added as a sequence
keyed by the value of *restkey*. If the row read has fewer fields than the
fieldnames sequence, the remaining keys take the value of the optional
*restval* parameter. Any other optional or keyword arguments are passed to
the underlying :class:`reader` instance.
.. class:: DictWriter(csvfile, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)
Create an object which operates like a regular writer but maps dictionaries onto
output rows. The *fieldnames* parameter identifies the order in which values in
the dictionary passed to the :meth:`writerow` method are written to the
*csvfile*. The optional *restval* parameter specifies the value to be written
if the dictionary is missing a key in *fieldnames*. If the dictionary passed to
the :meth:`writerow` method contains a key not found in *fieldnames*, the
optional *extrasaction* parameter indicates what action to take. If it is set
to ``'raise'`` a :exc:`ValueError` is raised. If it is set to ``'ignore'``,
extra values in the dictionary are ignored. Any other optional or keyword
arguments are passed to the underlying :class:`writer` instance.
Note that unlike the :class:`DictReader` class, the *fieldnames* parameter of
the :class:`DictWriter` is not optional. Since Python's :class:`dict` objects
are not ordered, there is not enough information available to deduce the order
in which the row should be written to the *csvfile*.
.. class:: DictReader(csvfile, fieldnames=None, restkey=None, restval=None, \
dialect='excel', *args, **kwds)
Create an object which operates like a regular reader but maps the
information read into a dict whose keys are given by the optional
*fieldnames* parameter. The *fieldnames* parameter is a :mod:`sequence
<collections.abc>` whose elements are associated with the fields of the
input data in order. These elements become the keys of the resulting
dictionary. If the *fieldnames* parameter is omitted, the values in the
first row of the *csvfile* will be used as the fieldnames. If the row read
has more fields than the fieldnames sequence, the remaining data is added as
a sequence keyed by the value of *restkey*. If the row read has fewer
fields than the fieldnames sequence, the remaining keys take the value of
the optional *restval* parameter. Any other optional or keyword arguments
are passed to the underlying :class:`reader` instance.
.. class:: DictWriter(csvfile, fieldnames, restval='', extrasaction='raise', \
dialect='excel', *args, **kwds)
Create an object which operates like a regular writer but maps dictionaries
onto output rows. The *fieldnames* parameter is a :mod:`sequence
<collections.abc>` of keys that identify the order in which values in the
dictionary passed to the :meth:`writerow` method are written to the
*csvfile*. The optional *restval* parameter specifies the value to be
written if the dictionary is missing a key in *fieldnames*. If the
dictionary passed to the :meth:`writerow` method contains a key not found in
*fieldnames*, the optional *extrasaction* parameter indicates what action to
take. If it is set to ``'raise'`` a :exc:`ValueError` is raised. If it is
set to ``'ignore'``, extra values in the dictionary are ignored. Any other
optional or keyword arguments are passed to the underlying :class:`writer`
instance.
Note that unlike the :class:`DictReader` class, the *fieldnames* parameter
of the :class:`DictWriter` is not optional. Since Python's :class:`dict`
objects are not ordered, there is not enough information available to deduce
the order in which the row should be written to the *csvfile*.
.. class:: Dialect
......
Doc/library/curses.rst
View file @ 3732ed24
......@@ -12,7 +12,7 @@ The :mod:`curses` module provides an interface to the curses library, the
de-facto standard for portable advanced terminal handling.
While curses is most widely used in the Unix environment, versions are available
for DOS, OS/2, and possibly other systems as well. This extension module is
for Windows, DOS, and possibly other systems as well. This extension module is
designed to match the API of ncurses, an open-source curses library hosted on
Linux and the BSD variants of Unix.
......
Doc/library/distutils.rst
View file @ 3732ed24
......@@ -12,14 +12,15 @@ additional modules into a Python installation. The new modules may be either
100%-pure Python, or may be extension modules written in C, or may be
collections of Python packages which include modules coded in both Python and C.
Most Python users will *not* want to use this module directly, but instead
use the cross-version tools maintained by the Python Packaging Authority.
Refer to the `Python Packaging User Guide <http://packaging.python.org>`_
for more information.
User documentation and API reference are provided in another document:
For the benefits of packaging tool authors and users seeking a deeper
understanding of the details of the current packaging and distribution
system, the legacy :mod:`distutils` based user documentation and API
reference remain available:
.. seealso::
:ref:`distutils-index`
The manual for developers and packagers of Python modules. This describes
how to prepare :mod:`distutils`\ -based packages so that they may be
easily installed into an existing Python installation. It also contains
instructions for end-users wanting to install a distutils-based package,
:ref:`install-index`.
* :ref:`install-index`
* :ref:`distutils-index`
Doc/library/email-examples.rst
View file @ 3732ed24
......@@ -40,8 +40,10 @@ text version: [2]_
.. literalinclude:: ../includes/email-alternative.py
Examples using the Provision API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _email-contentmanager-api-examples:
Examples using the Provisional API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here is a reworking of the last example using the provisional API. To make
things a bit more interesting, we include a related image in the html part, and
we save a copy of what we are going to send to disk, as well as sending it.
......
Doc/library/email.contentmanager.rst
View file @ 3732ed24
......@@ -54,6 +54,7 @@ this module.
documented in this module because of the provisional nature of the code, the
implementation lives in the :mod:`email.message` module.
.. currentmodule:: email.message
.. class:: EmailMessage(policy=default)
......@@ -235,6 +236,16 @@ this module.
all other headers intact and in their original order.
.. class:: MIMEPart(policy=default)
This class represents a subpart of a MIME message. It is identical to
:class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are
added when :meth:`~EmailMessage.set_content` is called, since sub-parts do
not need their own :mailheader:`MIME-Version` headers.
.. currentmodule:: email.contentmanager
.. class:: ContentManager()
Base class for content managers. Provides the standard registry mechanisms
......@@ -305,14 +316,6 @@ this module.
values of *typekey*, see :meth:`set_content`.
.. class:: MIMEPart(policy=default)
This class represents a subpart of a MIME message. It is identical to
:class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are
added when :meth:`~EmailMessage.set_content` is called, since sub-parts do
not need their own :mailheader:`MIME-Version` headers.
Content Manager Instances
~~~~~~~~~~~~~~~~~~~~~~~~~
......
Doc/library/email.message.rst
View file @ 3732ed24
......@@ -466,7 +466,7 @@ Here are the methods of the :class:`Message` class:
to ``False``.
.. method:: set_param(param, value, header='Content-Type', requote=True,
.. method:: set_param(param, value, header='Content-Type', requote=True, \
charset=None, language='', replace=False)
Set a parameter in the :mailheader:`Content-Type` header. If the
......@@ -488,7 +488,7 @@ Here are the methods of the :class:`Message` class:
end of the list of headers. If *replace* is ``True``, the header
will be updated in place.
.. versionchanged: 3.4 ``replace`` keyword was added.
.. versionchanged:: 3.4 ``replace`` keyword was added.
.. method:: del_param(param, header='content-type', requote=True)
......
Doc/library/email.policy.rst
View file @ 3732ed24
......@@ -419,7 +419,7 @@ added matters. To illustrate::
additional arguments. By default ``content_manager`` is set to
:data:`~email.contentmanager.raw_data_manager`.
.. versionadded 3.4
.. versionadded:: 3.4
The class provides the following concrete implementations of the abstract
......
Doc/library/ensurepip.rst
View file @ 3732ed24
......@@ -28,7 +28,7 @@ when creating a virtual environment) or after explicitly uninstalling
.. seealso::
:ref:`install-index`
:ref:`installing-index`
The end user guide for installing Python packages
:pep:`453`: Explicit bootstrapping of pip in Python installations
......
Doc/library/enum.rst
View file @ 3732ed24
......@@ -139,7 +139,7 @@ If you want to access enum members by *name*, use item access::
>>> Color['green']
<Color.green: 2>
If have an enum member and need its :attr:`name` or :attr:`value`::
If you have an enum member and need its :attr:`name` or :attr:`value`::
>>> member = Color.red
>>> member.name
......
Doc/library/exceptions.rst
View file @ 3732ed24
......@@ -265,7 +265,6 @@ The following exceptions are the exceptions that are usually raised.
:exc:`mmap.error` have been merged into :exc:`OSError`.
.. versionchanged:: 3.4
The :attr:`filename` attribute is now the original file name passed to
the function, instead of the name encoded to or decoded from the
filesystem encoding. Also, the :attr:`filename2` attribute was added.
......
Doc/library/fractions.rst
View file @ 3732ed24
......@@ -99,7 +99,9 @@ another rational number, or from a string.
value of *flt*, which must be a :class:`float`. Beware that
``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``
.. note:: From Python 3.2 onwards, you can also construct a
.. note::
From Python 3.2 onwards, you can also construct a
:class:`Fraction` instance directly from a :class:`float`.
......@@ -108,7 +110,9 @@ another rational number, or from a string.
This class method constructs a :class:`Fraction` representing the exact
value of *dec*, which must be a :class:`decimal.Decimal` instance.
.. note:: From Python 3.2 onwards, you can also construct a
.. note::
From Python 3.2 onwards, you can also construct a
:class:`Fraction` instance directly from a :class:`decimal.Decimal`
instance.
......
Doc/library/functions.rst
View file @ 3732ed24
......@@ -540,12 +540,13 @@ are always available. They are listed here in alphabetical order.
A call to ``format(value, format_spec)`` is translated to
``type(value).__format__(format_spec)`` which bypasses the instance
dictionary when searching for the value's :meth:`__format__` method. A
:exc:`TypeError` exception is raised if the method is not found or if either
the *format_spec* or the return value are not strings.
:exc:`TypeError` exception is raised if the method search reaches
:mod:`object` and the *format_spec* is non-empty, or if either the
*format_spec* or the return value are not strings.
.. versionadded:: 3.4
.. versionchanged:: 3.4
``object().__format__(format_spec)`` raises :exc:`TypeError`
if *format_spec* is not empty string.
if *format_spec* is not an empty string.
.. _func-frozenset:
......@@ -609,12 +610,26 @@ are always available. They are listed here in alphabetical order.
This function is added to the built-in namespace by the :mod:`site` module.
.. versionchanged:: 3.4
Changes to :mod:`pydoc` and :mod:`inspect` mean that the reported
signatures for callables are now more comprehensive and consistent.
.. function:: hex(x)
Convert an integer number to a hexadecimal string. The result is a valid Python
expression. If *x* is not a Python :class:`int` object, it has to define an
:meth:`__index__` method that returns an integer.
Convert an integer number to a lowercase hexadecimal string
prefixed with "0x", for example:
>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'
If x is not a Python :class:`int` object, it has to define an __index__()
method that returns an integer.
See also :func:`int` for converting a hexadecimal string to an
integer using a base of 16.
.. note::
......@@ -780,6 +795,9 @@ are always available. They are listed here in alphabetical order.
such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and
``heapq.nlargest(1, iterable, key=keyfunc)``.
.. versionadded:: 3.4
The *default* keyword-only argument.
.. _func-memoryview:
.. function:: memoryview(obj)
......@@ -811,6 +829,9 @@ are always available. They are listed here in alphabetical order.
such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1,
iterable, key=keyfunc)``.
.. versionadded:: 3.4
The *default* keyword-only argument.
.. function:: next(iterator[, default])
Retrieve the next item from the *iterator* by calling its
......
Doc/library/getopt.rst
View file @ 3732ed24
......@@ -10,6 +10,7 @@
--------------
.. note::
The :mod:`getopt` module is a parser for command line options whose API is
designed to be familiar to users of the C :c:func:`getopt` function. Users who
are unfamiliar with the C :c:func:`getopt` function or who would like to write
......
Doc/library/hashlib.rst
View file @ 3732ed24
......@@ -101,18 +101,18 @@ Hashlib provides the following constant attributes:
.. data:: algorithms_guaranteed
Contains the names of the hash algorithms guaranteed to be supported
A set containing the names of the hash algorithms guaranteed to be supported
by this module on all platforms.
.. versionadded:: 3.2
.. data:: algorithms_available
Contains the names of the hash algorithms that are available
in the running Python interpreter. These names will be recognized
when passed to :func:`new`. :attr:`algorithms_guaranteed`
will always be a subset. Duplicate algorithms with different
name formats may appear in this set (thanks to OpenSSL).
A set containing the names of the hash algorithms that are available in the
running Python interpreter. These names will be recognized when passed to
:func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The
same algorithm may appear multiple times in this set under different names
(thanks to OpenSSL).
.. versionadded:: 3.2
......
Doc/library/hmac.rst
View file @ 3732ed24
......@@ -23,9 +23,8 @@ This module implements the HMAC algorithm as described by :rfc:`2104`.
defaults to the :data:`hashlib.md5` constructor.
.. versionchanged:: 3.4
Parameter *key* can be a bytes or bytearray object. Parameter *msg* can
be of any type supported by :mod:`hashlib`.
Parameter *key* can be a bytes or bytearray object.
Parameter *msg* can be of any type supported by :mod:`hashlib`.
Paramter *digestmod* can be the name of a hash algorithm.
.. deprecated:: 3.4
......
Doc/library/http.server.rst
View file @ 3732ed24
......@@ -351,7 +351,7 @@ of which this module provides three different variants:
The :class:`SimpleHTTPRequestHandler` class can be used in the following
manner in order to create a very basic webserver serving files relative to
the current directory. ::
the current directory::
import http.server
import socketserver
......@@ -365,15 +365,17 @@ the current directory. ::
print("serving at port", PORT)
httpd.serve_forever()
.. _http-server-cli:
:mod:`http.server` can also be invoked directly using the :option:`-m`
switch of the interpreter with a ``port number`` argument. Similar to
the previous example, this serves files relative to the current directory. ::
the previous example, this serves files relative to the current directory::
python -m http.server 8000
By default, server binds itself to all interfaces. To restrict it to bind to a
particular interface only, ``--bind ADDRESS`` argument can be used. For e.g, to
restrict the server to bind only to localhost. ::
By default, server binds itself to all interfaces. The option ``-b/--bind``
specifies a specific address to which it should bind. For example, the
following command causes the server to bind to localhost only::
python -m http.server 8000 --bind 127.0.0.1
......@@ -422,7 +424,7 @@ restrict the server to bind only to localhost. ::
reasons. Problems with the CGI script will be translated to error 403.
:class:`CGIHTTPRequestHandler` can be enabled in the command line by passing
the ``--cgi`` option.::
the ``--cgi`` option::
python -m http.server --cgi 8000
Doc/library/importlib.rst
View file @ 3732ed24
......@@ -134,7 +134,7 @@ Functions
When :func:`reload` is executed:
* Python modules' code is recompiled and the module-level code re-executed,
* Python module's code is recompiled and the module-level code re-executed,
defining a new set of objects which are bound to names in the module's
dictionary by reusing the :term:`loader` which originally loaded the
module. The ``init`` function of extension modules is not called a second
......
Doc/library/inspect.rst
View file @ 3732ed24
......@@ -729,6 +729,11 @@ Classes and functions
Consider using the new :ref:`Signature Object <inspect-signature-object>`
interface, which provides a better way of introspecting functions.
.. versionchanged:: 3.4
This function is now based on :func:`signature`, but still ignores
``__wrapped__`` attributes and includes the already bound first
parameter in the signature output for bound methods.
.. function:: getargvalues(frame)
......
Doc/library/io.rst
View file @ 3732ed24
......@@ -686,6 +686,7 @@ than raw I/O does.
:exc:`UnsupportedOperation`.
.. warning::
:class:`BufferedRWPair` does not attempt to synchronize accesses to
its underlying raw streams. You should not pass it the same object
as reader and writer; use :class:`BufferedRandom` instead.
......
Doc/library/ipaddress.rst
View file @ 3732ed24
......@@ -154,20 +154,20 @@ write code that handles both IP versions correctly.
.. attribute:: is_private
``True`` if the address is allocated for private networks. See
iana-ipv4-special-registry (for IPv4) or iana-ipv6-special-registry
iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
(for IPv6).
.. attribute:: is_global
``True`` if the address is allocated for public networks. See
iana-ipv4-special-registry (for IPv4) or iana-ipv6-special-registry
iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
(for IPv6).
.. versionadded:: 3.4
.. versionadded:: 3.4
.. attribute:: is_unspecified
``True`` if the address is unspecified. See :RFC:`5375` (for IPv4)
``True`` if the address is unspecified. See :RFC:`5735` (for IPv4)
or :RFC:`2373` (for IPv6).
.. attribute:: is_reserved
......@@ -184,6 +184,9 @@ write code that handles both IP versions correctly.
``True`` if the address is reserved for link-local usage. See
:RFC:`3927`.
.. _iana-ipv4-special-registry: http://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
.. _iana-ipv6-special-registry: http://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
.. class:: IPv6Address(address)
......@@ -218,18 +221,23 @@ write code that handles both IP versions correctly.
The long form of the address representation, with all leading zeroes and
groups consisting entirely of zeroes included.
For the following attributes, see the corresponding documention of the
:class:`IPv4Address` class:
.. attribute:: packed
.. attribute:: version
.. attribute:: max_prefixlen
.. attribute:: is_multicast
.. attribute:: is_private
.. attribute:: is_global
.. attribute:: is_unspecified
.. attribute:: is_reserved
.. attribute:: is_loopback
.. attribute:: is_link_local
Refer to the corresponding attribute documentation in
:class:`IPv4Address`
.. versionadded:: 3.4
is_global
.. attribute:: is_site_local
......
Doc/library/logging.config.rst
View file @ 3732ed24
......@@ -148,7 +148,9 @@ in :mod:`logging` itself) and defining handlers which are declared either in
send it to the socket as a string of bytes preceded by a four-byte length
string packed in binary using ``struct.pack('>L', n)``.
.. note:: Because portions of the configuration are passed through
.. note::
Because portions of the configuration are passed through
:func:`eval`, use of this function may open its users to a security risk.
While the function only binds to a socket on ``localhost``, and so does
not accept connections from remote machines, there are scenarios where
......@@ -752,7 +754,9 @@ The ``class`` entry is optional. It indicates the name of the formatter's class
:class:`~logging.Formatter` can present exception tracebacks in an expanded or
condensed format.
.. note:: Due to the use of :func:`eval` as described above, there are
.. note::
Due to the use of :func:`eval` as described above, there are
potential security risks which result from using the :func:`listen` to send
and receive configurations via sockets. The risks are limited to where
multiple users with no mutual trust run code on the same machine; see the
......
Doc/library/math.rst
View file @ 3732ed24
......@@ -36,9 +36,9 @@ Number-theoretic and representation functions
.. function:: copysign(x, y)
Return *x* with the sign of *y*. On a platform that supports
signed zeros, ``copysign(1.0, -0.0)`` returns *-1.0*.
Return a float with the magnitude (absolute value) of *x* but the sign of
*y*. On platforms that support signed zeros, ``copysign(1.0, -0.0)``
returns *-1.0*.
.. function:: fabs(x)
......
Doc/library/multiprocessing.rst
View file @ 3732ed24
......@@ -136,9 +136,11 @@ to start a process. These *start methods* are
Available on Unix platforms which support passing file descriptors
over Unix pipes.
Before Python 3.4 *fork* was the only option available on Unix. Also,
prior to Python 3.4, child processes would inherit all the parents
inheritable handles on Windows.
.. versionchanged:: 3.4
*spawn* added on all unix platforms, and *forkserver* added for
some unix platforms.
Child processes no longer inherit all of the parents inheritable
handles on Windows.
On Unix using the *spawn* or *forkserver* start methods will also
start a *semaphore tracker* process which tracks the unlinked named
......@@ -1474,7 +1476,7 @@ their parent process exits. The manager classes are defined in the
*exposed* is used to specify a sequence of method names which proxies for
this typeid should be allowed to access using
:meth:`BaseProxy._callMethod`. (If *exposed* is ``None`` then
:meth:`BaseProxy._callmethod`. (If *exposed* is ``None`` then
:attr:`proxytype._exposed_` is used instead if it exists.) In the case
where no exposed list is specified, all "public methods" of the shared
object will be accessible. (Here a "public method" means any attribute
......@@ -1853,25 +1855,30 @@ with the :class:`Pool` class.
callbacks and has a parallel map implementation.
*processes* is the number of worker processes to use. If *processes* is
``None`` then the number returned by :func:`os.cpu_count` is used. If
*initializer* is not ``None`` then each worker process will call
``None`` then the number returned by :func:`os.cpu_count` is used.
If *initializer* is not ``None`` then each worker process will call
``initializer(*initargs)`` when it starts.
*maxtasksperchild* is the number of tasks a worker process can complete
before it will exit and be replaced with a fresh worker process, to enable
unused resources to be freed. The default *maxtasksperchild* is None, which
means worker processes will live as long as the pool.
*context* can be used to specify the context used for starting
the worker processes. Usually a pool is created using the
function :func:`multiprocessing.Pool` or the :meth:`Pool` method
of a context object. In both cases *context* is set
appropriately.
Note that the methods of the pool object should only be called by
the process which created the pool.
.. versionadded:: 3.2
*maxtasksperchild* is the number of tasks a worker process can complete
before it will exit and be replaced with a fresh worker process, to enable
unused resources to be freed. The default *maxtasksperchild* is None, which
means worker processes will live as long as the pool.
*maxtasksperchild*
.. versionadded:: 3.4
*context* can be used to specify the context used for starting
the worker processes. Usually a pool is created using the
function :func:`multiprocessing.Pool` or the :meth:`Pool` method
of a context object. In both cases *context* is set
appropriately.
*context*
.. note::
......
Doc/library/operator.rst
View file @ 3732ed24
......@@ -240,9 +240,9 @@ their character equivalents.
.. function:: length_hint(obj, default=0)
Return an estimated length for the object *o*. First trying to return its
Return an estimated length for the object *o*. First try to return its
actual length, then an estimate using :meth:`object.__length_hint__`, and
finally returning the default value.
finally return the default value.
.. versionadded:: 3.4
......
Doc/library/os.path.rst
View file @ 3732ed24
......@@ -193,11 +193,17 @@ the :mod:`glob` module.)
.. function:: ismount(path)
Return ``True`` if pathname *path* is a :dfn:`mount point`: a point in a file
system where a different file system has been mounted. The function checks
whether *path*'s parent, :file:`path/..`, is on a different device than *path*,
or whether :file:`path/..` and *path* point to the same i-node on the same
device --- this should detect mount points for all Unix and POSIX variants.
Return ``True`` if pathname *path* is a :dfn:`mount point`: a point in a
file system where a different file system has been mounted. On POSIX, the
function checks whether *path*'s parent, :file:`path/..`, is on a different
device than *path*, or whether :file:`path/..` and *path* point to the same
i-node on the same device --- this should detect mount points for all Unix
and POSIX variants. On Windows, a drive letter root and a share UNC are
always mount points, and for any other path ``GetVolumePathName`` is called
to see if it is different from the input path.
.. versionadded:: 3.4
Support for detecting non-root mount points on Windows.
.. function:: join(path1[, path2[, ...]])
......@@ -251,7 +257,7 @@ the :mod:`glob` module.)
.. function:: samefile(path1, path2)
Return ``True`` if both pathname arguments refer to the same file or directory.
On Unix, this is determined by the device number and i-node number and raises an
This is determined by the device number and i-node number and raises an
exception if a :func:`os.stat` call on either pathname fails.
Availability: Unix, Windows.
......
Doc/library/os.rst
View file @ 3732ed24
......@@ -260,7 +260,9 @@ process and user.
Availability: Unix.
.. note:: On Mac OS X, :func:`getgroups` behavior differs somewhat from
.. note::
On Mac OS X, :func:`getgroups` behavior differs somewhat from
other Unix platforms. If the Python interpreter was built with a
deployment target of :const:`10.5` or earlier, :func:`getgroups` returns
the list of effective group ids associated with the current user process;
......@@ -940,8 +942,9 @@ or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Window
the C library.
.. versionchanged:: 3.4
Add :data:`O_TMPFILE` constant. It's only available on Linux Kernel 3.11
or newer.
Add :data:`O_PATH` on systems that support it.
Add :data:`O_TMPFILE`, only available on Linux Kernel 3.11
or newer.
.. function:: openpty()
......@@ -2653,7 +2656,7 @@ written in Python, such as a mail server's external command delivery program.
Fork a child process. Return ``0`` in the child and the child's process id in the
parent. If an error occurs :exc:`OSError` is raised.
Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX have
Note that some platforms including FreeBSD <= 6.3 and Cygwin have
known issues when using fork() from a thread.
.. warning::
......@@ -2899,7 +2902,6 @@ written in Python, such as a mail server's external command delivery program.
:manpage:`times(2)` or the corresponding Windows Platform API documentation.
On Windows, only :attr:`user` and :attr:`system` are known; the other
attributes are zero.
On OS/2, only :attr:`elapsed` is known; the other attributes are zero.
Availability: Unix, Windows.
......
Doc/library/pathlib.rst
View file @ 3732ed24
......@@ -522,6 +522,36 @@ Pure paths provide the following methods and properties:
ValueError: '/etc/passwd' does not start with '/usr'
.. method:: PurePath.with_name(name)
Return a new path with the :attr:`name` changed. If the original path
doesn't have a name, ValueError is raised::
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_name('setup.py')
PureWindowsPath('c:/Downloads/setup.py')
>>> p = PureWindowsPath('c:/')
>>> p.with_name('setup.py')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name
raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name
.. method:: PurePath.with_suffix(suffix)
Return a new path with the :attr:`suffix` changed. If the original path
doesn't have a suffix, the new *suffix* is appended instead::
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_suffix('.bz2')
PureWindowsPath('c:/Downloads/pathlib.tar.bz2')
>>> p = PureWindowsPath('README')
>>> p.with_suffix('.txt')
PureWindowsPath('README.txt')
.. _concrete-paths:
......
Doc/library/pkgutil.rst
View file @ 3732ed24
......@@ -147,6 +147,7 @@ support.
*prefix* is a string to output on the front of every module name on output.
.. note::
Only works for a :term:`finder` which defines an ``iter_modules()``
method. This interface is non-standard, so the module also provides
implementations for :class:`importlib.machinery.FileFinder` and
......@@ -185,6 +186,7 @@ support.
walk_packages(ctypes.__path__, ctypes.__name__ + '.')
.. note::
Only works for a :term:`finder` which defines an ``iter_modules()``
method. This interface is non-standard, so the module also provides
implementations for :class:`importlib.machinery.FileFinder` and
......
Doc/library/plistlib.rst
View file @ 3732ed24
......@@ -32,6 +32,9 @@ Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
(but only with string keys), :class:`Data`, :class:`bytes`, :class:`bytesarray`
or :class:`datetime.datetime` objects.
.. versionchanged:: 3.4
New API, old API deprecated. Support for binary format plists added.
.. seealso::
`PList manual page <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_
......@@ -107,7 +110,7 @@ This module defines the following functions:
An :exc:`OverflowError` will be raised for integer values that cannot
be represented in (binary) plist files.
.. versionadded: 3.4
.. versionadded:: 3.4
.. function:: dumps(value, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
......@@ -116,7 +119,7 @@ This module defines the following functions:
the documentation for :func:`dump` for an explanation of the keyword
arguments of this function.
.. versionadded: 3.4
.. versionadded:: 3.4
The following functions are deprecated:
......@@ -135,7 +138,7 @@ The following functions are deprecated:
to ``__getitem_``. This means that you can use attribute access to
access items of these dictionaries.
.. deprecated: 3.4 Use :func:`load` instead.
.. deprecated:: 3.4 Use :func:`load` instead.
.. function:: writePlist(rootObject, pathOrFile)
......@@ -143,7 +146,7 @@ The following functions are deprecated:
Write *rootObject* to an XML plist file. *pathOrFile* may be either a file name
or a (writable and binary) file object
.. deprecated: 3.4 Use :func:`dump` instead.
.. deprecated:: 3.4 Use :func:`dump` instead.
.. function:: readPlistFromBytes(data)
......@@ -194,7 +197,7 @@ The following classes are available:
.. deprecated:: 3.4 Use a :class:`bytes` object instead
The following constants are avaiable:
The following constants are available:
.. data:: FMT_XML
......
Doc/library/pydoc.rst
View file @ 3732ed24
......@@ -84,3 +84,8 @@ Reference Manual pages.
.. versionchanged:: 3.2
Added the ``-b`` option, deprecated the ``-g`` option.
.. versionchanged:: 3.4
:mod:`pydoc` now uses :func:`inspect.signature` rather than
:func:`inspect.getfullargspec` to extract signature information from
callables.
Doc/library/site.rst
View file @ 3732ed24
......@@ -123,9 +123,13 @@ On systems that support :mod:`readline`, this module will also import and
configure the :mod:`rlcompleter` module, if Python is started in
:ref:`interactive mode <tut-interactive>` and without the :option:`-S` option.
The default behavior is enable tab-completion and to use
:file:`~/.python_history` as the history save file. To disable it, override
the :data:`sys.__interactivehook__` attribute in your :mod:`sitecustomize`
or :mod:`usercustomize` module or your :envvar:`PYTHONSTARTUP` file.
:file:`~/.python_history` as the history save file. To disable it, delete (or
override) the :data:`sys.__interactivehook__` attribute in your
:mod:`sitecustomize` or :mod:`usercustomize` module or your
:envvar:`PYTHONSTARTUP` file.
.. versionchanged:: 3.4
Activation of rlcompleter and history was made automatic.
Module contents
......
Doc/library/smtplib.rst
View file @ 3732ed24
......@@ -117,6 +117,9 @@ A nice selection of exceptions is defined as well:
Subclass of :exc:`OSError` that is the base exception class for all
the other exceptions provided by this module.
.. versionchanged:: 3.4
SMTPException became subclass of :exc:`OSError`
.. exception:: SMTPServerDisconnected
......
Doc/library/socket.rst
View file @ 3732ed24
......@@ -6,8 +6,7 @@
This module provides access to the BSD *socket* interface. It is available on
all modern Unix systems, Windows, MacOS, OS/2, and probably additional
platforms.
all modern Unix systems, Windows, MacOS, and probably additional platforms.
.. note::
......@@ -468,7 +467,7 @@ The :mod:`socket` module also offers various network-related services:
(10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))]
.. versionchanged:: 3.2
parameters can now be passed as single keyword arguments.
parameters can now be passed using keyword arguments.
.. function:: getfqdn([name])
......@@ -634,6 +633,9 @@ The :mod:`socket` module also offers various network-related services:
Availability: Unix (maybe not all platforms), Windows.
.. versionchanged:: 3.4
Windows support added
.. function:: inet_ntop(address_family, packed_ip)
......@@ -650,6 +652,9 @@ The :mod:`socket` module also offers various network-related services:
Availability: Unix (maybe not all platforms), Windows.
.. versionchanged:: 3.4
Windows support added
..
XXX: Are sendmsg(), recvmsg() and CMSG_*() available on any
......@@ -794,6 +799,7 @@ to sockets.
:keyword:`with` statement around them.
.. note::
:meth:`close()` releases the resource associated with a connection but
does not necessarily close the connection immediately. If you want
to close the connection in a timely fashion, call :meth:`shutdown()`
......@@ -1512,4 +1518,3 @@ the :data:`SO_REUSEADDR` flag tells the kernel to reuse a local socket in
details of socket semantics. For Unix, refer to the manual pages; for Windows,
see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may
want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6.
Doc/library/ssl.rst
View file @ 3732ed24
......@@ -818,6 +818,7 @@ SSL sockets also have the following additional methods and attributes:
'version': 3}
.. note::
To validate a certificate for a particular service, you can use the
:func:`match_hostname` function.
......@@ -841,10 +842,8 @@ SSL sockets also have the following additional methods and attributes:
.. versionchanged:: 3.4
:exc:`ValueError` is raised when the handshake isn't done.
.. versionchanged:: 3.4
The returned dictionary includes additional X509v3 extension items
such as ``crlDistributionPoints``, ``caIssuers`` and ``OCSP`` URIs.
such as ``crlDistributionPoints``, ``caIssuers`` and ``OCSP`` URIs.
.. method:: SSLSocket.cipher()
......
Doc/library/stringprep.rst
View file @ 3732ed24
......@@ -3,7 +3,6 @@
.. module:: stringprep
:synopsis: String preparation, as per RFC 3453
:deprecated:
.. moduleauthor:: Martin v. Löwis <martin@v.loewis.de>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
......
Doc/library/subprocess.rst
View file @ 3732ed24
......@@ -629,6 +629,12 @@ Instances of the :class:`Popen` class have the following methods:
:exc:`TimeoutExpired` exception. It is safe to catch this exception and
retry the wait.
.. note::
The function is implemented using a busy loop (non-blocking call and
short sleeps). Use the :mod:`asyncio` module for an asynchronous wait:
see :class:`asyncio.create_subprocess_exec`.
.. warning::
This will deadlock when using ``stdout=PIPE`` and/or
......@@ -639,6 +645,11 @@ Instances of the :class:`Popen` class have the following methods:
.. versionchanged:: 3.3
*timeout* was added.
.. deprecated:: 3.4
Do not use the undocumented *endtime* parameter. It is was
unintentionally exposed in 3.3 but was intended to be private
for internal use. Use *timeout* instead.
.. method:: Popen.communicate(input=None, timeout=None)
......@@ -1080,8 +1091,10 @@ handling consistency are valid for these functions.
>>> subprocess.getstatusoutput('/bin/junk')
(256, 'sh: /bin/junk: not found')
.. versionchanged:: 3.3
Availability: Unix & Windows
Availability: Unix & Windows
.. versionchanged:: 3.3.4
Windows support added
.. function:: getoutput(cmd)
......@@ -1094,8 +1107,10 @@ handling consistency are valid for these functions.
>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'
.. versionchanged:: 3.3
Availability: Unix & Windows
Availability: Unix & Windows
.. versionchanged:: 3.3.4
Windows support added
Notes
......
Doc/library/sunau.rst
View file @ 3732ed24
......@@ -251,7 +251,7 @@ AU_write objects, as returned by :func:`.open` above, have the following methods
Write audio frames, without correcting *nframes*.
.. versionchanged:: 3.4
Any :term:`bytes-like object`\ s are now accepted.
Any :term:`bytes-like object` is now accepted.
.. method:: AU_write.writeframes(data)
......@@ -259,7 +259,7 @@ AU_write objects, as returned by :func:`.open` above, have the following methods
Write audio frames and make sure *nframes* is correct.
.. versionchanged:: 3.4
Any :term:`bytes-like object`\ s are now accepted.
Any :term:`bytes-like object` is now accepted.
.. method:: AU_write.close()
......
Doc/library/sys.rst
View file @ 3732ed24
......@@ -227,7 +227,9 @@ always available.
installed in :file:`{exec_prefix}/lib/python{X.Y}/lib-dynload`, where *X.Y*
is the version number of Python, for example ``3.2``.
.. note:: If a :ref:`virtual environment <venv-def>` is in effect, this
.. note::
If a :ref:`virtual environment <venv-def>` is in effect, this
value will be changed in ``site.py`` to point to the virtual environment.
The value for the Python installation will still be available, via
:data:`base_exec_prefix`.
......@@ -692,10 +694,11 @@ always available.
.. data:: __interactivehook__
When present, this function is automatically called (with no arguments)
when the interpreter is launched in :ref:`interactive mode <tut-interactive>`.
This is done after the :envvar:`PYTHONSTARTUP` file is read, so that you
can set this hook there.
When this attribute exists, its value is automatically called (with no
arguments) when the interpreter is launched in :ref:`interactive mode
<tut-interactive>`. This is done after the :envvar:`PYTHONSTARTUP` file is
read, so that you can set this hook there. The :mod:`site` module
:ref:`sets this <rlcompleter-config>`.
.. versionadded:: 3.4
......
Doc/library/test.rst
View file @ 3732ed24
......@@ -199,6 +199,7 @@ The :mod:`test.support` module provides support for Python's regression
test suite.
.. note::
:mod:`test.support` is not a public module. It is documented here to help
Python developers write tests. The API of this module is subject to change
without backwards compatibility concerns between releases.
......
Doc/library/textwrap.rst
View file @ 3732ed24
......@@ -40,13 +40,14 @@ functions should be good enough; otherwise, you should use an instance of
:func:`wrap`.
.. function:: shorten(text, width=70, *, placeholder=" [...]")
.. function:: shorten(text, width, **kwargs)
Collapse and truncate the given text to fit in the given width.
Collapse and truncate the given *text* to fit in the given *width*.
The text first has its whitespace collapsed. If it then fits in
the *width*, it is returned unchanged. Otherwise, as many words
as possible are joined and then the *placeholder* is appended::
First the whitespace in *text* is collapsed (all whitespace is replaced by
single spaces). If the result fits in the *width*, it is returned.
Otherwise, enough words are dropped from the end so that the remaining words
plus the :attr:`placeholder` fit within :attr:`width`::
>>> textwrap.shorten("Hello world!", width=12)
'Hello world!'
......@@ -55,6 +56,12 @@ functions should be good enough; otherwise, you should use an instance of
>>> textwrap.shorten("Hello world", width=10, placeholder="...")
'Hello...'
Optional keyword arguments correspond to the instance attributes of
:class:`TextWrapper`, documented below. Note that the whitespace is
collapsed before the text is passed to the :class:`TextWrapper` :meth:`fill`
function, so changing the value of :attr:`.tabsize`, :attr:`.expand_tabs`,
:attr:`.drop_whitespace`, and :attr:`.replace_whitespace` will have no effect.
.. versionadded:: 3.4
......@@ -110,8 +117,8 @@ functions should be good enough; otherwise, you should use an instance of
:func:`wrap`, :func:`fill` and :func:`shorten` work by creating a
:class:`TextWrapper` instance and calling a single method on it. That
instance is not reused, so for applications that process many text
strings, it may be more efficient to create your own
:class:`TextWrapper` object.
strings using :func:`wrap` and/or :func:`fill`, it may be more efficient to
create your own :class:`TextWrapper` object.
Text is preferably wrapped on whitespaces and right after the hyphens in
hyphenated words; only then will long words be broken if necessary, unless
......@@ -252,16 +259,16 @@ hyphenated words; only then will long words be broken if necessary, unless
.. attribute:: max_lines
(default: ``None``) If not ``None``, then the text be will truncated to
*max_lines* lines.
(default: ``None``) If not ``None``, then the output will contain at most
*max_lines* lines, with *placeholder* appearing at the end of the output.
.. versionadded:: 3.4
.. attribute:: placeholder
(default: ``' [...]'``) String that will be appended to the last line of
text if it will be truncated.
(default: ``' [...]'``) String that will appear at the end of the output
text if it has been truncated.
.. versionadded:: 3.4
......
Doc/library/tracemalloc.rst
View file @ 3732ed24
......@@ -184,6 +184,7 @@ Pretty top
Code to display the 10 lines allocating the most memory with a pretty output,
ignoring ``<frozen importlib._bootstrap>`` and ``<unknown>`` files::
import linecache
import os
import tracemalloc
......@@ -201,6 +202,9 @@ ignoring ``<frozen importlib._bootstrap>`` and ``<unknown>`` files::
filename = os.sep.join(frame.filename.split(os.sep)[-2:])
print("#%s: %s:%s: %.1f KiB"
% (index, filename, frame.lineno, stat.size / 1024))
line = linecache.getline(frame.filename, frame.lineno).strip()
if line:
print(' %s' % line)
other = top_stats[limit:]
if other:
......@@ -218,19 +222,28 @@ ignoring ``<frozen importlib._bootstrap>`` and ``<unknown>`` files::
Example of output of the Python test suite::
2013-11-08 14:16:58.149320: Top 10 lines
#1: collections/__init__.py:368: 291.9 KiB
#2: Lib/doctest.py:1291: 200.2 KiB
#3: unittest/case.py:571: 160.3 KiB
#4: Lib/abc.py:133: 99.8 KiB
#5: urllib/parse.py:476: 71.8 KiB
#6: <string>:5: 62.7 KiB
#7: Lib/base64.py:140: 59.8 KiB
#8: Lib/_weakrefset.py:37: 51.8 KiB
#9: collections/__init__.py:362: 50.6 KiB
#10: test/test_site.py:56: 48.0 KiB
7496 other: 4161.9 KiB
Total allocated size: 5258.8 KiB
Top 10 lines
#1: Lib/base64.py:414: 419.8 KiB
_b85chars2 = [(a + b) for a in _b85chars for b in _b85chars]
#2: Lib/base64.py:306: 419.8 KiB
_a85chars2 = [(a + b) for a in _a85chars for b in _a85chars]
#3: collections/__init__.py:368: 293.6 KiB
exec(class_definition, namespace)
#4: Lib/abc.py:133: 115.2 KiB
cls = super().__new__(mcls, name, bases, namespace)
#5: unittest/case.py:574: 103.1 KiB
testMethod()
#6: Lib/linecache.py:127: 95.4 KiB
lines = fp.readlines()
#7: urllib/parse.py:476: 71.8 KiB
for a in _hexdig for b in _hexdig}
#8: <string>:5: 62.0 KiB
#9: Lib/_weakrefset.py:37: 60.0 KiB
self.data = set()
#10: Lib/base64.py:142: 59.8 KiB
_b32tab2 = [a + b for a in _b32tab for b in _b32tab]
6220 other: 3602.8 KiB
Total allocated size: 5303.1 KiB
See :meth:`Snapshot.statistics` for more options.
......
Doc/library/types.rst
View file @ 3732ed24
......@@ -15,6 +15,9 @@ It also defines names for some object types that are used by the standard
Python interpreter, but not exposed as builtins like :class:`int` or
:class:`str` are.
Finally, it provides some additional type-related utility classes and functions
that are not fundamental enough to be builtins.
Dynamic Type Creation
---------------------
......@@ -220,6 +223,9 @@ Standard names are defined for the following types:
Return a new view of the underlying mapping's values.
Additional Utility Classes and Functions
----------------------------------------
.. class:: SimpleNamespace
A simple :class:`object` subclass that provides attribute access to its
......@@ -246,3 +252,18 @@ Standard names are defined for the following types:
instead.
.. versionadded:: 3.3
.. function:: DynamicClassAttribute(fget=None, fset=None, fdel=None, doc=None)
Route attribute access on a class to __getattr__.
This is a descriptor, used to define attributes that act differently when
accessed through an instance and through a class. Instance access remains
normal, but access to an attribute through a class will be routed to the
class's __getattr__ method; this is done by raising AttributeError.
This allows one to have properties active on an instance, and have virtual
attributes on the class with the same name (see Enum for an example).
.. versionadded:: 3.4
Doc/library/undoc.rst
View file @ 3732ed24
......@@ -20,7 +20,7 @@ These modules are used to implement the :mod:`os.path` module, and are not
documented beyond this mention. There's little need to document these.
:mod:`ntpath`
--- Implementation of :mod:`os.path` on Win32, Win64, WinCE, and OS/2 platforms.
--- Implementation of :mod:`os.path` on Win32, Win64, and WinCE platforms.
:mod:`posixpath`
--- Implementation of :mod:`os.path` on POSIX.
Doc/library/unittest.mock-examples.rst
View file @ 3732ed24
......@@ -426,7 +426,7 @@ mock using the "as" form of the with statement:
As an alternative `patch`, `patch.object` and `patch.dict` can be used as
class decorators. When used in this way it is the same as applying the
decorator indvidually to every method whose name starts with "test".
decorator individually to every method whose name starts with "test".
.. _further-examples:
......
Doc/library/unittest.mock.rst
View file @ 3732ed24
......@@ -958,7 +958,7 @@ method:
.. [#] The only exceptions are magic methods and attributes (those that have
leading and trailing double underscores). Mock doesn't create these but
instead of raises an ``AttributeError``. This is because the interpreter
instead raises an ``AttributeError``. This is because the interpreter
will often implicitly request these methods, and gets *very* confused to
get a new Mock object when it expects a magic method. If you need magic
method support see :ref:`magic methods <magic-methods>`.
......@@ -1509,7 +1509,7 @@ Patching Descriptors and Proxy Objects
Both patch_ and patch.object_ correctly patch and restore descriptors: class
methods, static methods and properties. You should patch these on the *class*
rather than an instance. They also work with *some* objects
that proxy attribute access, like the `django setttings object
that proxy attribute access, like the `django settings object
<http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198>`_.
......
Doc/library/unittest.rst
View file @ 3732ed24
......@@ -239,9 +239,10 @@ Test Discovery
Unittest supports simple test discovery. In order to be compatible with test
discovery, all of the test files must be :ref:`modules <tut-modules>` or
:ref:`packages <tut-packages>` importable from the top-level directory of
the project (this means that their filenames must be valid
:ref:`identifiers <identifiers>`).
:ref:`packages <tut-packages>` (including :term:`namespace packages
<namespace package>`) importable from the top-level directory of
the project (this means that their filenames must be valid :ref:`identifiers
<identifiers>`).
Test discovery is implemented in :meth:`TestLoader.discover`, but can also be
used from the command line. The basic command-line usage is::
......@@ -306,6 +307,9 @@ as the start directory.
Test modules and packages can customize test loading and discovery by through
the `load_tests protocol`_.
.. versionchanged:: 3.4
Test discovery supports :term:`namespace packages <namespace package>`.
.. _organizing-tests:
......@@ -1620,11 +1624,11 @@ Loading and running tests
.. method:: discover(start_dir, pattern='test*.py', top_level_dir=None)
Find and return all test modules from the specified start directory,
recursing into subdirectories to find them. Only test files that match
*pattern* will be loaded. (Using shell style pattern matching.) Only
module names that are importable (i.e. are valid Python identifiers) will
be loaded.
Find all the test modules by recursing into subdirectories from the
specified start directory, and return a TestSuite object containing them.
Only test files that match *pattern* will be loaded. (Using shell style
pattern matching.) Only module names that are importable (i.e. are valid
Python identifiers) will be loaded.
All test modules must be importable from the top level of the project. If
the start directory is not the top level directory then the top level
......@@ -1654,12 +1658,11 @@ Loading and running tests
.. versionchanged:: 3.4
Modules that raise :exc:`SkipTest` on import are recorded as skips,
not errors.
.. versionchanged:: 3.4
Paths are sorted before being imported to ensure execution order for a
given test suite is the same even if the underlying file system's ordering
is not dependent on file name like in ext3/4.
not errors.
Discovery works for :term:`namespace packages <namespace package>`.
Paths are sorted before being imported so that execution order is
the same even if the underlying file system's ordering is not
dependent on file name.
The following attributes of a :class:`TestLoader` can be configured either by
......
Doc/library/urllib.error.rst
View file @ 3732ed24
......@@ -48,7 +48,7 @@ The following exceptions are raised by :mod:`urllib.error` as appropriate:
.. attribute:: headers
The HTTP response headers for the HTTP request that cause the
The HTTP response headers for the HTTP request that caused the
:exc:`HTTPError`.
.. versionadded:: 3.4
......
Doc/library/urllib.request.rst
View file @ 3732ed24
......@@ -218,7 +218,7 @@ The following classes are provided:
fetching of the image, this should be true.
*method* should be a string that indicates the HTTP request method that
will be used (e.g. ``'HEAD'``). Its value is stored in the
will be used (e.g. ``'HEAD'``). If provided, its value is stored in the
:attr:`~Request.method` attribute and is used by :meth:`get_method()`.
Subclasses may indicate a default method by setting the
:attr:`~Request.method` attribute in the class itself.
......@@ -440,13 +440,20 @@ request.
.. attribute:: Request.method
The HTTP request method to use. This value is used by
:meth:`~Request.get_method` to override the computed HTTP request
method that would otherwise be returned. This attribute is initialized with
the value of the *method* argument passed to the constructor.
The HTTP request method to use. By default its value is :const:`None`,
which means that :meth:`~Request.get_method` will do its normal computation
of the method to be used. Its value can be set (thus overriding the default
computation in :meth:`~Request.get_method`) either by providing a default
value by setting it at the class level in a :class:`Request` subclass, or by
passing a value in to the :class:`Request` constructor via the *method*
argument.
.. versionadded:: 3.3
.. versionchanged:: 3.4
A default value can now be set in subclasses; previously it could only
be set via the constructor argument.
.. method:: Request.get_method()
......
Doc/library/venv.rst
View file @ 3732ed24
......@@ -76,6 +76,8 @@ Creating virtual environments
without there needing to be any reference to its venv in ``PATH``.
.. _venv-api:
API
---
......
Doc/library/wave.rst
View file @ 3732ed24
......@@ -150,14 +150,30 @@ them, and is otherwise implementation dependent.
Wave_write Objects
------------------
For seekable output streams, the ``wave`` header will automatically be updated
to reflect the number of frames actually written. For unseekable streams, the
*nframes* value must be accurate when the first frame data is written. An
accurate *nframes* value can be achieved either by calling
:meth:`~Wave_write.setnframes` or :meth:`~Wave_write.setparams` with the number
of frames that will be written before :meth:`~Wave_write.close` is called and
then using :meth:`~Wave_write.writeframesraw` to write the frame data, or by
calling :meth:`~Wave_write.writeframes` with all of the frame data to be
written. In the latter case :meth:`~Wave_write.writeframes` will calculate
the number of frames in the data and set *nframes* accordingly before writing
the frame data.
Wave_write objects, as returned by :func:`.open`, have the following methods:
.. versionchanged:: 3.4
Added support for unseekable files.
.. method:: Wave_write.close()
Make sure *nframes* is correct, and close the file if it was opened by
:mod:`wave`. This method is called upon object collection. Can raise an
exception if *nframes* is not correct and a file is not seekable.
:mod:`wave`. This method is called upon object collection. It will raise
an exception if the output stream is not seekable and *nframes* does not
match the number of frames actually written.
.. method:: Wave_write.setnchannels(n)
......@@ -181,8 +197,9 @@ Wave_write objects, as returned by :func:`.open`, have the following methods:
.. method:: Wave_write.setnframes(n)
Set the number of frames to *n*. This will be changed later if more frames are
written.
Set the number of frames to *n*. This will be changed later if the number
of frames actually written is different (this update attempt will
raise an error if the output stream is not seekable).
.. method:: Wave_write.setcomptype(type, name)
......@@ -209,16 +226,18 @@ Wave_write objects, as returned by :func:`.open`, have the following methods:
Write audio frames, without correcting *nframes*.
.. versionchanged:: 3.4
Any :term:`bytes-like object`\ s are now accepted.
Any :term:`bytes-like object` is now accepted.
.. method:: Wave_write.writeframes(data)
Write audio frames and make sure *nframes* is correct. Can raise an
exception if a file is not seekable.
Write audio frames and make sure *nframes* is correct. It will raise an
error if the output stream is not seekable and the total number of frames
that have been written after *data* has been written does not match the
previously set value for *nframes*.
.. versionchanged:: 3.4
Any :term:`bytes-like object`\ s are now accepted.
Any :term:`bytes-like object` is now accepted.
Note that it is invalid to set any parameters after calling :meth:`writeframes`
......
Doc/library/xml.etree.elementtree.rst
View file @ 3732ed24
......@@ -952,7 +952,8 @@ XMLParser Objects
specified in the XML file.
.. deprecated:: 3.4
The *html* argument.
The *html* argument. The remaining arguments should be passed via
keywword to prepare for the removal of the *html* argument.
.. method:: close()
......
Doc/library/xml.rst
View file @ 3732ed24
......@@ -14,9 +14,9 @@ Python's interfaces for processing XML are grouped in the ``xml`` package.
.. warning::
The XML modules are not secure against erroneous or maliciously
constructed data. If you need to parse untrusted or unauthenticated data see
:ref:`xml-vulnerabilities`.
constructed data. If you need to parse untrusted or
unauthenticated data see the :ref:`xml-vulnerabilities` and
:ref:`defused-packages` sections.
It is important to note that modules in the :mod:`xml` package require that
there be at least one SAX-compliant XML parser available. The Expat parser is
......@@ -46,16 +46,15 @@ The XML handling submodules are:
.. _xml-vulnerabilities:
XML vulnerabilities
===================
-------------------
The XML processing modules are not secure against maliciously constructed data.
An attacker can abuse vulnerabilities for e.g. denial of service attacks, to
access local files, to generate network connections to other machines, or
to or circumvent firewalls. The attacks on XML abuse unfamiliar features
like inline `DTD`_ (document type definition) with entities.
An attacker can abuse XML features to carry out denial of service attacks,
access local files, generate network connections to other machines, or
circumvent firewalls.
The following table gives an overview of the known attacks and if the various
modules are vulnerable to them.
The following table gives an overview of the known attacks and whether
the various modules are vulnerable to them.
========================= ======== ========= ========= ======== =========
kind sax etree minidom pulldom xmlrpc
......@@ -68,7 +67,7 @@ decompression bomb No No No No **Yes**
========================= ======== ========= ========= ======== =========
1. :mod:`xml.etree.ElementTree` doesn't expand external entities and raises a
ParserError when an entity occurs.
:exc:`ParserError` when an entity occurs.
2. :mod:`xml.dom.minidom` doesn't expand external entities and simply returns
the unexpanded entity verbatim.
3. :mod:`xmlrpclib` doesn't expand external entities and omits them.
......@@ -77,23 +76,21 @@ decompression bomb No No No No **Yes**
billion laughs / exponential entity expansion
The `Billion Laughs`_ attack -- also known as exponential entity expansion --
uses multiple levels of nested entities. Each entity refers to another entity
several times, the final entity definition contains a small string. Eventually
the small string is expanded to several gigabytes. The exponential expansion
consumes lots of CPU time, too.
several times, and the final entity definition contains a small string.
The exponential expansion results in several gigabytes of text and
consumes lots of memory and CPU time.
quadratic blowup entity expansion
A quadratic blowup attack is similar to a `Billion Laughs`_ attack; it abuses
entity expansion, too. Instead of nested entities it repeats one large entity
with a couple of thousand chars over and over again. The attack isn't as
efficient as the exponential case but it avoids triggering countermeasures of
parsers against heavily nested entities.
efficient as the exponential case but it avoids triggering parser countermeasures
that forbid deeply-nested entities.
external entity expansion
Entity declarations can contain more than just text for replacement. They can
also point to external resources by public identifiers or system identifiers.
System identifiers are standard URIs or can refer to local files. The XML
parser retrieves the resource with e.g. HTTP or FTP requests and embeds the
content into the XML document.
also point to external resources or local files. The XML
parser accesses the resource and embeds the content into the XML document.
DTD retrieval
Some XML libraries like Python's :mod:`xml.dom.pulldom` retrieve document type
......@@ -101,31 +98,32 @@ DTD retrieval
implications as the external entity expansion issue.
decompression bomb
The issue of decompression bombs (aka `ZIP bomb`_) apply to all XML libraries
that can parse compressed XML stream like gzipped HTTP streams or LZMA-ed
Decompression bombs (aka `ZIP bomb`_) apply to all XML libraries
that can parse compressed XML streams such as gzipped HTTP streams or
LZMA-compressed
files. For an attacker it can reduce the amount of transmitted data by three
magnitudes or more.
The documentation of `defusedxml`_ on PyPI has further information about
The documentation for `defusedxml`_ on PyPI has further information about
all known attack vectors with examples and references.
defused packages
----------------
.. _defused-packages:
`defusedxml`_ is a pure Python package with modified subclasses of all stdlib
XML parsers that prevent any potentially malicious operation. The courses of
action are recommended for any server code that parses untrusted XML data. The
package also ships with example exploits and an extended documentation on more
XML exploits like xpath injection.
The :mod:`defusedxml` and :mod:`defusedexpat` Packages
------------------------------------------------------
`defusedexpat`_ provides a modified libexpat and patched replacment
:mod:`pyexpat` extension module with countermeasures against entity expansion
DoS attacks. Defusedexpat still allows a sane and configurable amount of entity
expansions. The modifications will be merged into future releases of Python.
`defusedxml`_ is a pure Python package with modified subclasses of all stdlib
XML parsers that prevent any potentially malicious operation. Use of this
package is recommended for any server code that parses untrusted XML data. The
package also ships with example exploits and extended documentation on more
XML exploits such as XPath injection.
The workarounds and modifications are not included in patch releases as they
break backward compatibility. After all inline DTD and entity expansion are
well-definied XML features.
`defusedexpat`_ provides a modified libexpat and a patched
:mod:`pyexpat` module that have countermeasures against entity expansion
DoS attacks. The :mod:`defusedexpat` module still allows a sane and configurable amount of entity
expansions. The modifications may be included in some future release of Python,
but will not be included in any bugfix releases of
Python because they break backward compatibility.
.. _defusedxml: https://pypi.python.org/pypi/defusedxml/
......@@ -133,4 +131,3 @@ well-definied XML features.
.. _Billion Laughs: http://en.wikipedia.org/wiki/Billion_laughs
.. _ZIP bomb: http://en.wikipedia.org/wiki/Zip_bomb
.. _DTD: http://en.wikipedia.org/wiki/Document_Type_Definition
Doc/library/zipfile.rst
View file @ 3732ed24
......@@ -401,18 +401,32 @@ The :class:`PyZipFile` constructor takes the same parameters as the
``2``, only files with that optimization level (see :func:`compile`) are
added to the archive, compiling if necessary.
If the pathname is a file, the filename must end with :file:`.py`, and
If *pathname* is a file, the filename must end with :file:`.py`, and
just the (corresponding :file:`\*.py[co]`) file is added at the top level
(no path information). If the pathname is a file that does not end with
(no path information). If *pathname* is a file that does not end with
:file:`.py`, a :exc:`RuntimeError` will be raised. If it is a directory,
and the directory is not a package directory, then all the files
:file:`\*.py[co]` are added at the top level. If the directory is a
package directory, then all :file:`\*.py[co]` are added under the package
name as a file path, and if any subdirectories are package directories,
all of these are added recursively. *basename* is intended for internal
use only. When *filterfunc(pathname)* is given, it will be called for every
invocation. When it returns a false value, that path and its subpaths will
be ignored.
all of these are added recursively.
*basename* is intended for internal use only.
*filterfunc*, if given, must be a function taking a single string
argument. It will be passed each path (including each individual full
file path) before it is added to the archive. If *filterfunc* returns a
false value, the path will not be added, and if it is a directory its
contents will be ignored. For example, if our test files are all either
in ``test`` directories or start with the string ``test_``, we can use a
*filterfunc* to exclude them::
>>> zf = PyZipFile('myprog.zip')
>>> def notests(s):
... fn = os.path.basename(s)
... return (not (fn == 'test' or fn.startswith('test_')))
>>> zf.writepy('myprog', filterfunc=notests)
The :meth:`writepy` method makes archives with file names like
this::
......
Doc/reference/datamodel.rst
View file @ 3732ed24
......@@ -1226,6 +1226,10 @@ Basic customization
The return value must be a string object.
.. versionchanged:: 3.4
The __format__ method of ``object`` itself raises a :exc:`TypeError`
if passed any non-empty string.
.. _richcmpfuncs:
.. method:: object.__lt__(self, other)
......@@ -1643,6 +1647,8 @@ of these candidate metaclasses. If none of the candidate metaclasses meets
that criterion, then the class definition will fail with ``TypeError``.
.. _prepare:
Preparing the class namespace
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......@@ -2044,11 +2050,13 @@ left undefined.
``&=``, ``^=``, ``|=``). These methods should attempt to do the operation
in-place (modifying *self*) and return the result (which could be, but does
not have to be, *self*). If a specific method is not defined, the augmented
assignment falls back to the normal methods. For instance, to execute the
statement ``x += y``, where *x* is an instance of a class that has an
:meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance
of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)``
and ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``.
assignment falls back to the normal methods. For instance, if *x* is an
instance of a class with an :meth:`__iadd__` method, ``x += y`` is equivalent
to ``x = x.__iadd__(y)`` . Otherwise, ``x.__add__(y)`` and ``y.__radd__(x)``
are considered, as with the evaluation of ``x + y``. In certain situations,
augmented assignment can result in unexpected errors (see
:ref:`faq-augmented-assignment-tuple-error`), but this behavior is in
fact part of the data model.
.. method:: object.__neg__(self)
......
Doc/tools/sphinxext/indexcontent.html
View file @ 3732ed24
......@@ -16,14 +16,14 @@
<p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">Python HOWTOs</a><br/>
<span class="linkdescr">in-depth documents on specific topics</span></p>
</td><td width="50%">
<p class="biglink"><a class="biglink" href="{{ pathto("installing/index") }}">Installing Python Modules</a><br/>
<span class="linkdescr">installing from the Python Package Index &amp; other sources</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("distributing/index") }}">Distributing Python Modules</a><br/>
<span class="linkdescr">publishing modules for installation by others</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">Extending and Embedding</a><br/>
<span class="linkdescr">tutorial for C/C++ programmers</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">Python/C API</a><br/>
<span class="linkdescr">reference for C/C++ programmers</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("install/index") }}">Installing Python Modules</a><br/>
<span class="linkdescr">information for installers &amp; sys-admins</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("distutils/index") }}">Distributing Python Modules</a><br/>
<span class="linkdescr">sharing modules with others</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">FAQs</a><br/>
<span class="linkdescr">frequently asked questions (with answers!)</span></p>
</td></tr>
......
Doc/tools/sphinxext/susp-ignored.csv
View file @ 3732ed24
......@@ -282,3 +282,4 @@ whatsnew/changelog,,:PythonCmd,"With Tk < 8.5 _tkinter.c:PythonCmd() raised Unic
whatsnew/changelog,,::,": Fix FTP tests for IPv6, bind to ""::1"" instead of ""localhost""."
whatsnew/changelog,,::,": Use ""127.0.0.1"" or ""::1"" instead of ""localhost"" as much as"
whatsnew/changelog,,:password,user:password
whatsnew/changelog,,:gz,w:gz
Doc/tutorial/introduction.rst
View file @ 3732ed24
......@@ -371,9 +371,9 @@ values. The most versatile is the *list*, which can be written as a list of
comma-separated values (items) between square brackets. Lists might contain
items of different types, but usually the items all have the same type. ::
>>> squares = [1, 2, 4, 9, 16, 25]
>>> squares = [1, 4, 9, 16, 25]
>>> squares
[1, 2, 4, 9, 16, 25]
[1, 4, 9, 16, 25]
Like strings (and all other built-in :term:`sequence` type), lists can be
indexed and sliced::
......@@ -389,12 +389,12 @@ All slice operations return a new list containing the requested elements. This
means that the following slice returns a new (shallow) copy of the list::
>>> squares[:]
[1, 2, 4, 9, 16, 25]
[1, 4, 9, 16, 25]
Lists also supports operations like concatenation::
>>> squares + [36, 49, 64, 81, 100]
[1, 2, 4, 9, 16, 25, 36, 49, 64, 81, 100]
[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
Unlike strings, which are :term:`immutable`, lists are a :term:`mutable`
type, i.e. it is possible to change their content::
......
Doc/tutorial/whatnow.rst
View file @ 3732ed24
......@@ -21,8 +21,8 @@ the set are:
and many other tasks. Skimming through the Library Reference will give you an
idea of what's available.
* :ref:`install-index` explains how to install external modules written by other
Python users.
* :ref:`installing-index` explains how to install additional modules written
by other Python users.
* :ref:`reference-index`: A detailed explanation of Python's syntax and
semantics. It's heavy reading, but is useful as a complete guide to the
......
Doc/using/unix.rst
View file @ 3732ed24
......@@ -60,6 +60,8 @@ To install the newest Python versions on OpenSolaris, install `blastwave
prompt.
.. _building-python-on-unix:
Building Python
===============
......
Doc/using/venv-create.inc
View file @ 3732ed24
......@@ -11,6 +11,11 @@ containing a copy of the ``python`` binary (or binaries, in the case of
Windows). It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
subdirectory (on Windows, this is ``Lib\site-packages``).
.. seealso::
`Python Packaging User Guide: Creating and using virtual environments
<http://packaging.python.org/en/latest/tutorial.html#creating-and-using-virtual-environments>`__
.. highlight:: none
On Windows, you may have to invoke the ``pyvenv`` script as follows, if you
......@@ -38,6 +43,8 @@ The command, if run with ``-h``, will show the available options::
virtual environment.
--symlinks Try to use symlinks rather than copies, when symlinks
are not the default for the platform.
--copies Try to use copies rather than symlinks, even when
symlinks are the default for the platform.
--clear Delete the environment directory if it already exists.
If not specified and the directory exists, an error is
raised.
......@@ -47,7 +54,8 @@ The command, if run with ``-h``, will show the available options::
environment (pip is bootstrapped by default)
.. versionchanged:: 3.4
Installs pip by default, added the ``--without-pip`` option
Installs pip by default, added the ``--without-pip`` and ``--copies``
options
If the target directory already exists an error will be raised, unless
the ``--clear`` or ``--upgrade`` option was provided.
......
Doc/using/windows.rst
View file @ 3732ed24
......@@ -11,6 +11,10 @@
This document aims to give an overview of Windows-specific behaviour you should
know about when using Python on Microsoft Windows.
.. XXX (ncoghlan)
This looks rather stale to me...
Installing Python
=================
......
Doc/whatsnew/3.4.rst
View file @ 3732ed24
This diff is collapsed.
Misc/NEWS
View file @ 3732ed24
......@@ -7,15 +7,17 @@ What's New in Python 3.4.0?
Release date: 2014-03-16
Core and Builtins
-----------------
Library
-------
- Issue #20939: Fix test_geturl failure in test_urllibnet due to
new redirect of http://www.python.org/ to https://www.python.org.
Documentation
-------------
- Merge in all documentation changes since branching 3.4.0rc1.
What's New in Python 3.4.0 release candidate 3?
===============================================
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7