summaryrefslogtreecommitdiffstats
path: root/Doc/using
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/using')
-rw-r--r--Doc/using/cmdline.rst75
-rw-r--r--Doc/using/unix.rst31
-rw-r--r--Doc/using/windows.rst6
3 files changed, 71 insertions, 41 deletions
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 8a5b247..0d12126 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -1,5 +1,8 @@
.. highlightlang:: none
+.. ATTENTION: You probably should update Misc/python.man, too, if you modify
+.. this file.
+
.. _using-on-general:
Command line and environment
@@ -21,7 +24,7 @@ Command line
When invoking Python, you may specify any of these options::
- python [-bBdEhiORsSuvVWx?] [-c command | -m module-name | script | - ] [args]
+ python [-bBdEhiORqsSuvVWx?] [-c command | -m module-name | script | - ] [args]
The most common use case is, of course, a simple invocation of a script::
@@ -92,8 +95,9 @@ source.
file is not available.
If this option is given, the first element of :data:`sys.argv` will be the
- full path to the module file. As with the :option:`-c` option, the current
- directory will be added to the start of :data:`sys.path`.
+ full path to the module file (while the module file is being located, the
+ first element will be set to ``"-m"``). As with the :option:`-c` option,
+ the current directory will be added to the start of :data:`sys.path`.
Many standard library modules contain code that is invoked on their execution
as a script. An example is the :mod:`timeit` module::
@@ -111,6 +115,7 @@ source.
.. versionchanged:: 3.1
Supply the package name to run a ``__main__`` submodule.
+
.. describe:: -
Read commands from standard input (:data:`sys.stdin`). If standard input is
@@ -215,6 +220,13 @@ Miscellaneous options
Discard docstrings in addition to the :option:`-O` optimizations.
+.. cmdoption:: -q
+
+ Don't display the copyright and version messages even in interactive mode.
+
+ .. versionadded:: 3.2
+
+
.. cmdoption:: -R
Turn on hash randomization, so that the :meth:`__hash__` values of str, bytes
@@ -235,12 +247,13 @@ Miscellaneous options
See also :envvar:`PYTHONHASHSEED`.
- .. versionadded:: 3.1.5
+ .. versionadded:: 3.2.3
.. cmdoption:: -s
- Don't add user site directory to sys.path
+ Don't add the :data:`user site-packages directory <site.USER_SITE>` to
+ :data:`sys.path`.
.. seealso::
@@ -257,7 +270,8 @@ Miscellaneous options
Force the binary layer of the stdin, stdout and stderr streams (which is
available as their ``buffer`` attribute) to be unbuffered. The text I/O
- layer will still be line-buffered.
+ layer will still be line-buffered if writing to the console, or
+ block-buffered if redirected to a non-interactive file.
See also :envvar:`PYTHONUNBUFFERED`.
@@ -317,7 +331,7 @@ Miscellaneous options
the remaining fields. Empty fields match all values; trailing empty fields
may be omitted. The *message* field matches the start of the warning message
printed; this match is case-insensitive. The *category* field matches the
- warning category. This must be a class name; the match test whether the
+ warning category. This must be a class name; the match tests whether the
actual warning category of the message is a subclass of the specified warning
category. The full class name must be given. The *module* field matches the
(fully-qualified) module name; this match is case-sensitive. The *line*
@@ -329,6 +343,8 @@ Miscellaneous options
:pep:`230` -- Warning framework
+ :envvar:`PYTHONWARNINGS`
+
.. cmdoption:: -x
@@ -338,6 +354,16 @@ Miscellaneous options
.. note:: The line numbers in error messages will be off by one.
+.. cmdoption:: -X
+
+ Reserved for various implementation-specific options. CPython currently
+ defines none of them, but allows to pass arbitrary values and retrieve
+ them through the :data:`sys._xoptions` dictionary.
+
+ .. versionchanged:: 3.2
+ It is now allowed to pass :option:`-X` with CPython.
+
+
Options you shouldn't use
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -347,11 +373,6 @@ Options you shouldn't use
.. _Jython: http://jython.org
-.. cmdoption:: -X
-
- Reserved for alternative implementations of Python to use for their own
- purposes.
-
.. _using-on-envvars:
@@ -451,13 +472,14 @@ These environment variables influence Python's behavior.
.. envvar:: PYTHONCASEOK
If this is set, Python ignores case in :keyword:`import` statements. This
- only works on Windows.
+ only works on Windows, OS X, and OS/2.
.. envvar:: PYTHONDONTWRITEBYTECODE
If this is set, Python won't try to write ``.pyc`` or ``.pyo`` files on the
- import of source modules.
+ import of source modules. This is equivalent to specifying the :option:`-B`
+ option.
.. envvar:: PYTHONHASHSEED
@@ -478,14 +500,15 @@ These environment variables influence Python's behavior.
the value 0 will lead to the same hash values as when hash randomization is
disabled.
- .. versionadded:: 3.1.5
+ .. versionadded:: 3.2.3
.. envvar:: PYTHONIOENCODING
- Overrides the encoding used for stdin/stdout/stderr, in the syntax
- ``encodingname:errorhandler``. The ``:errorhandler`` part is optional and
- has the same meaning as in :func:`str.encode`.
+ If this is set before running the interpreter, it overrides the encoding used
+ for stdin/stdout/stderr, in the syntax ``encodingname:errorhandler``. The
+ ``:errorhandler`` part is optional and has the same meaning as in
+ :func:`str.encode`.
For stderr, the ``:errorhandler`` part is ignored; the handler will always be
``'backslashreplace'``.
@@ -493,7 +516,8 @@ These environment variables influence Python's behavior.
.. envvar:: PYTHONNOUSERSITE
- If this is set, Python won't add the user site directory to sys.path
+ If this is set, Python won't add the :data:`user site-packages directory
+ <site.USER_SITE>` to :data:`sys.path`.
.. seealso::
@@ -502,7 +526,10 @@ These environment variables influence Python's behavior.
.. envvar:: PYTHONUSERBASE
- Sets the base directory for the user site directory
+ Defines the :data:`user base directory <site.USER_BASE>`, which is used to
+ compute the path of the :data:`user site-packages directory <site.USER_SITE>`
+ and :ref:`Distutils installation paths <inst-alt-install-user>` for ``python
+ setup.py install --user``.
.. seealso::
@@ -515,12 +542,18 @@ These environment variables influence Python's behavior.
value instead of the value got through the C runtime. Only works on
Mac OS X.
+.. envvar:: PYTHONWARNINGS
+
+ This is equivalent to the :option:`-W` option. If set to a comma
+ separated string, it is equivalent to specifying :option:`-W` multiple
+ times.
+
Debug-mode variables
~~~~~~~~~~~~~~~~~~~~
Setting these variables only has an effect in a debug build of Python, that is,
-if Python was configured with the :option:`--with-pydebug` build option.
+if Python was configured with the ``--with-pydebug`` build option.
.. envvar:: PYTHONTHREADDEBUG
diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst
index 61e707b..8bbc312 100644
--- a/Doc/using/unix.rst
+++ b/Doc/using/unix.rst
@@ -1,4 +1,4 @@
-.. highlightlang:: none
+.. highlightlang:: sh
.. _using-on-unix:
@@ -26,11 +26,11 @@ following links:
.. seealso::
- http://www.linux.com/articles/60383
+ http://www.debian.org/doc/manuals/maint-guide/first.en.html
for Debian users
http://linuxmafia.com/pub/linux/suse-linux-internals/chapter35.html
for OpenSuse users
- http://docs.fedoraproject.org/drafts/rpm-guide-en/ch-creating-rpms.html
+ http://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-creating-rpms.html
for Fedora users
http://www.slackbook.org/html/package-management-making-packages.html
for Slackware users
@@ -55,8 +55,8 @@ On FreeBSD and OpenBSD
On OpenSolaris
--------------
-To install the newest Python versions on OpenSolaris, install blastwave
-(http://www.blastwave.org/howto.html) and type "pkg_get -i python" at the
+To install the newest Python versions on OpenSolaris, install `blastwave
+<http://www.blastwave.org/howto.html>`_ and type ``pkg_get -i python`` at the
prompt.
@@ -65,22 +65,23 @@ Building Python
If you want to compile CPython yourself, first thing you should do is get the
`source <http://python.org/download/source/>`_. You can download either the
-latest release's source or just grab a fresh `checkout
-<http://www.python.org/dev/faq/#how-do-i-get-a-checkout-of-the-repository-read-only-and-read-write>`_.
+latest release's source or just grab a fresh `clone
+<http://docs.python.org/devguide/setup#getting-the-source-code>`_. (If you want
+to contribute patches, you will need a clone.)
-The build process consists the usual ::
+The build process consists in the usual ::
./configure
make
make install
invocations. Configuration options and caveats for specific Unix platforms are
-extensively documented in the :file:`README` file in the root of the Python
+extensively documented in the :source:`README` file in the root of the Python
source tree.
.. warning::
- ``make install`` can overwrite or masquerade the :file:`python` binary.
+ ``make install`` can overwrite or masquerade the :file:`python3` binary.
``make altinstall`` is therefore recommended instead of ``make install``
since it only installs :file:`{exec_prefix}/bin/python{version}`.
@@ -98,7 +99,7 @@ For example, on most Linux systems, the default for both is :file:`/usr`.
+-----------------------------------------------+------------------------------------------+
| File/directory | Meaning |
+===============================================+==========================================+
-| :file:`{exec_prefix}/bin/python` | Recommended location of the interpreter. |
+| :file:`{exec_prefix}/bin/python3` | Recommended location of the interpreter. |
+-----------------------------------------------+------------------------------------------+
| :file:`{prefix}/lib/python{version}`, | Recommended locations of the directories |
| :file:`{exec_prefix}/lib/python{version}` | containing the standard modules. |
@@ -108,10 +109,6 @@ For example, on most Linux systems, the default for both is :file:`/usr`.
| | developing Python extensions and |
| | embedding the interpreter. |
+-----------------------------------------------+------------------------------------------+
-| :file:`~/.pythonrc.py` | User-specific initialization file loaded |
-| | by the user module; not used by default |
-| | or by most applications. |
-+-----------------------------------------------+------------------------------------------+
Miscellaneous
@@ -125,11 +122,11 @@ e.g. with ::
and put an appropriate Shebang line at the top of the script. A good choice is
usually ::
- #!/usr/bin/env python
+ #!/usr/bin/env python3
which searches for the Python interpreter in the whole :envvar:`PATH`. However,
some Unices may not have the :program:`env` command, so you may need to hardcode
-``/usr/bin/python`` as the interpreter path.
+``/usr/bin/python3`` as the interpreter path.
To use shell commands in your Python scripts, look at the :mod:`subprocess` module.
diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst
index 12378b3..742a290 100644
--- a/Doc/using/windows.rst
+++ b/Doc/using/windows.rst
@@ -45,9 +45,9 @@ for detailed information about platforms with precompiled installers.
"7 Minutes to "Hello World!""
by Richard Dooling, 2006
- `Installing on Windows <http://diveintopython.org/installing_python/windows.html>`_
+ `Installing on Windows <http://diveintopython.net/installing_python/windows.html>`_
in "`Dive into Python: Python from novice to pro
- <http://diveintopython.org/index.html>`_"
+ <http://diveintopython.net/index.html>`_"
by Mark Pilgrim, 2004,
ISBN 1-59059-356-1
@@ -290,7 +290,7 @@ Compiling Python on Windows
If you want to compile CPython yourself, first thing you should do is get the
`source <http://python.org/download/source/>`_. You can download either the
latest release's source or just grab a fresh `checkout
-<http://www.python.org/dev/faq/#how-do-i-get-a-checkout-of-the-repository-read-only-and-read-write>`_.
+<http://docs.python.org/devguide/setup#checking-out-the-code>`_.
For Microsoft Visual C++, which is the compiler with which official Python
releases are built, the source tree contains solutions/project files. View the