diff options
Diffstat (limited to 'Doc/using')
-rw-r--r-- | Doc/using/cmdline.rst | 75 | ||||
-rw-r--r-- | Doc/using/unix.rst | 31 | ||||
-rw-r--r-- | Doc/using/windows.rst | 6 |
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 |