mirror of https://github.com/python/cpython
* Add new toplevel chapter, "Using Python." (how to install,
configure and setup python on different platforms -- at least in theory.) * Move the Python on Mac docs in that chapter. * Add a new chapter about the command line invocation, by stargaming.
This commit is contained in:
Georg Brandl
parent
a147bf9a08
commit
59d121af67
|
|
@ -6,6 +6,7 @@
|
|||
|
||||
whatsnew/2.6.rst
|
||||
tutorial/index.rst
|
||||
using/index.rst
|
||||
reference/index.rst
|
||||
library/index.rst
|
||||
extending/index.rst
|
||||
|
|
|
|||
|
|
@ -14,7 +14,6 @@ Currently, the HOWTOs are:
|
|||
:maxdepth: 1
|
||||
|
||||
advocacy.rst
|
||||
pythonmac.rst
|
||||
curses.rst
|
||||
doanddont.rst
|
||||
functional.rst
|
||||
|
|
|
|||
|
|
@ -0,0 +1,427 @@
|
|||
.. highlightlang:: none
|
||||
|
||||
Invoking the Python executable
|
||||
==============================
|
||||
|
||||
The CPython interpreter scans the command line and the environment for various
|
||||
settings.
|
||||
|
||||
.. note::
|
||||
|
||||
Other implementation's command line schemes may differ. See
|
||||
:ref:`implementations` for further resources.
|
||||
|
||||
|
||||
Command line
|
||||
------------
|
||||
|
||||
When invoking Python, you may specify any of these options::
|
||||
|
||||
python [-dEiOQStuUvxX3?] [-c command | -m module-name | script | - ] [args]
|
||||
|
||||
The most common use case is, of course, a simple invocation of a script::
|
||||
|
||||
python myscript.py
|
||||
|
||||
|
||||
Interface options
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
The interpreter interface resembles that of the UNIX shell:
|
||||
|
||||
* When called with standard input connected to a tty device, it prompts for
|
||||
commands and executes them until an EOF (an end-of-file character, you can
|
||||
produce that with *Ctrl-D* on UNIX or *Ctrl-Z, Enter* on Windows) is read.
|
||||
* When called with a file name argument or with a file as standard input, it
|
||||
reads and executes a script from that file.
|
||||
* When called with ``-c command``, it executes the Python statement(s) given as
|
||||
*command*. Here *command* may contain multiple statements separated by
|
||||
newlines. Leading whitespace is significant in Python statements!
|
||||
* When called with ``-m module-name``, the given module is searched on the
|
||||
Python module path and executed as a script.
|
||||
|
||||
In non-interactive mode, the entire input is parsed before it is executed.
|
||||
|
||||
An interface option terminates the list of options consumed by the interpreter,
|
||||
all consecutive arguments will end up in :data:`sys.argv` -- note that the first
|
||||
element, subscript zero (``sys.argv[0]``), is a string reflecting the program's
|
||||
source.
|
||||
|
||||
.. cmdoption:: -c <command>
|
||||
|
||||
Execute the Python code in *command*. *command* can be one ore more
|
||||
statements separated by newlines, with significant leading whitespace as in
|
||||
normal module code.
|
||||
|
||||
If this option is given, the first element of :data:`sys.argv` will be
|
||||
``"-c"``.
|
||||
|
||||
|
||||
.. cmdoption:: -m <module-name>
|
||||
|
||||
Search :data:`sys.path` for the named module and run the corresponding module
|
||||
file as if it were executed with ``python modulefile.py`` as a script.
|
||||
|
||||
Since the argument is a *module* name, you must not give a file extension
|
||||
(``.py``). However, the ``module-name`` does not have to be a valid Python
|
||||
identifer (e.g. you can use a file name including a hyphen).
|
||||
|
||||
.. note::
|
||||
|
||||
This option cannot be used with builtin modules and extension modules
|
||||
written in C, since they do not have Python module files.
|
||||
|
||||
If this option is given, the first element of :data:`sys.argv` will be the
|
||||
full path to the module file.
|
||||
|
||||
Many standard library modules contain code that is invoked on their execution
|
||||
as a script. An example is the :mod:`timeit` module::
|
||||
|
||||
python -mtimeit -s 'setup here' 'benchmarked code here'
|
||||
python -mtimeit -h # for details
|
||||
|
||||
.. seealso::
|
||||
:func:`runpy.run_module`
|
||||
The actual implementation of this feature.
|
||||
|
||||
:pep:`338` -- Executing modules as scripts
|
||||
|
||||
.. versionchanged:: 2.5
|
||||
The module name can now include packages.
|
||||
|
||||
|
||||
.. describe:: <script>
|
||||
|
||||
Execute the Python code contained in *script*, which must be an (absolute or
|
||||
relative) file name.
|
||||
|
||||
If this option is given, the first element of :data:`sys.argv` will be the
|
||||
script file name as given on the command line.
|
||||
|
||||
|
||||
.. describe:: -
|
||||
|
||||
Read commands from standard input (:data:`sys.stdin`). If standard input is
|
||||
a terminal, :option:`-i` is implied.
|
||||
|
||||
If this option is given, the first element of :data:`sys.argv` will be
|
||||
``"-"``.
|
||||
|
||||
.. seealso::
|
||||
:ref:`tut-invoking`
|
||||
|
||||
|
||||
If no script name is given, ``sys.argv[0]`` is an empty string (``""``).
|
||||
|
||||
|
||||
Generic options
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. cmdoption:: -?
|
||||
-h
|
||||
--help
|
||||
|
||||
Print a short description of all command line options.
|
||||
|
||||
.. versionadded:: 2.5
|
||||
The ``--help`` variant.
|
||||
|
||||
|
||||
.. cmdoption:: -V
|
||||
--version
|
||||
|
||||
Print the Python version number and exit. Example output could be::
|
||||
|
||||
Python 2.5.1
|
||||
|
||||
.. versionadded:: 2.5
|
||||
The ``--version`` variant.
|
||||
|
||||
|
||||
Miscellaneous options
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. cmdoption:: -d
|
||||
|
||||
Turn on parser debugging output (for wizards only, depending on compilation
|
||||
options). See also :envvar:`PYTHONDEBUG`.
|
||||
|
||||
|
||||
.. cmdoption:: -E
|
||||
|
||||
Ignore environment variables like :envvar:`PYTHONPATH` and
|
||||
:envvar:`PYTHONHOME` that modify the behaviour of the interpreter.
|
||||
|
||||
.. XXX: full list?
|
||||
|
||||
|
||||
.. cmdoption:: -i
|
||||
|
||||
When a script is passed as first argument or the :option:`-c` option is used,
|
||||
enter interactive mode after executing the script or the command, even when
|
||||
:data:`sys.stdin` does not appear to be a terminal. The
|
||||
:envvar:`PYTHONSTARTUP` file is not read.
|
||||
|
||||
This can be useful to inspect global variables or a stack trace when a script
|
||||
raises an exception. See also :envvar:`PYTHONINSPECT`.
|
||||
|
||||
|
||||
.. cmdoption:: -O
|
||||
|
||||
Turn on basic optimizations. This changes the filename extension for
|
||||
compiled (:term:`byte code`) files from ``.pyc`` to ``.pyo``. See also
|
||||
:envvar:`PYTHONOPTIMIZE`.
|
||||
|
||||
|
||||
.. cmdoption:: -OO
|
||||
|
||||
Discard docstrings in addition to the :option:`-O` optimizations.
|
||||
|
||||
|
||||
.. cmdoption:: -Q <arg>
|
||||
|
||||
Division control. The argument must be one of the following:
|
||||
|
||||
``old``
|
||||
division of int/int and long/long return an int or long (*default*)
|
||||
``new``
|
||||
new division semantics, i.e. division of int/int and long/long returns a
|
||||
float
|
||||
``warn``
|
||||
old division semantics with a warning for int/int and long/long
|
||||
``warnall``
|
||||
old division semantics with a warning for all uses of the division operator
|
||||
|
||||
.. seealso::
|
||||
:file:`Tools/scripts/fixdiv.py`
|
||||
for a use of ``warnall``
|
||||
|
||||
:pep:`238` -- Changing the division operator
|
||||
|
||||
|
||||
.. cmdoption:: -S
|
||||
|
||||
Disable the import of the module :mod:`site` and the site-dependent
|
||||
manipulations of :data:`sys.path` that it entails.
|
||||
|
||||
|
||||
.. cmdoption:: -t
|
||||
|
||||
Issue a warning when a source file mixes tabs and spaces for indentation in a
|
||||
way that makes it depend on the worth of a tab expressed in spaces. Issue an
|
||||
error when the option is given twice (:option:`-tt`).
|
||||
|
||||
|
||||
.. cmdoption:: -u
|
||||
|
||||
Force stdin, stdout and stderr to be totally unbuffered. On systems where it
|
||||
matters, also put stdin, stdout and stderr in binary mode.
|
||||
|
||||
Note that there is internal buffering in :func:`file.readlines` and
|
||||
:ref:`bltin-file-objects` (``for line in sys.stdin``) which is not influenced
|
||||
by this option. To work around this, you will want to use
|
||||
:func:`file.readline` inside a ``while 1:`` loop.
|
||||
|
||||
See also :envvar:`PYTHONUNBUFFERED`.
|
||||
|
||||
|
||||
.. XXX should the -U option be documented?
|
||||
|
||||
.. cmdoption:: -v
|
||||
|
||||
Print a message each time a module is initialized, showing the place
|
||||
(filename or built-in module) from which it is loaded. When given twice
|
||||
(:option:`-vv`), print a message for each file that is checked for when
|
||||
searching for a module. Also provides information on module cleanup at exit.
|
||||
See also :envvar:`PYTHONVERBOSE`.
|
||||
|
||||
|
||||
.. cmdoption:: -W arg
|
||||
|
||||
Warning control. Python's warning machinery by default prints warning
|
||||
messages to :data:`sys.stderr`. A typical warning message has the following
|
||||
form::
|
||||
|
||||
file:line: category: message
|
||||
|
||||
By default, each warning is printed once for each source line where it
|
||||
occurs. This option controls how often warnings are printed.
|
||||
|
||||
Multiple :option:`-W` options may be given; when a warning matches more than
|
||||
one option, the action for the last matching option is performed. Invalid
|
||||
:option:`-W` options are ignored (though, a warning message is printed about
|
||||
invalid options when the first warning is issued).
|
||||
|
||||
Warnings can also be controlled from within a Python program using the
|
||||
:mod:`warnings` module.
|
||||
|
||||
The simplest form of argument is one of the following action strings (or a
|
||||
unique abbreviation):
|
||||
|
||||
``ignore``
|
||||
Ignore all warnings.
|
||||
``default``
|
||||
Explicitly request the default behavior (printing each warning once per
|
||||
source line).
|
||||
``all``
|
||||
Print a warning each time it occurs (this may generate many messages if a
|
||||
warning is triggered repeatedly for the same source line, such as inside a
|
||||
loop).
|
||||
``module``
|
||||
Print each warning only only the first time it occurs in each module.
|
||||
``once``
|
||||
Print each warning only the first time it occurs in the program.
|
||||
``error``
|
||||
Raise an exception instead of printing a warning message.
|
||||
|
||||
The full form of argument is::
|
||||
|
||||
action:message:category:module:line
|
||||
|
||||
Here, *action* is as explained above but only applies to messages that match
|
||||
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
|
||||
actual warning category of the message is a subclass of the specified warning
|
||||
category. The full class name must be given. The *module* field matches the
|
||||
(fully-qualified) module name; this match is case-sensitive. The *line*
|
||||
field matches the line number, where zero matches all line numbers and is
|
||||
thus equivalent to an omitted line number.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:pep:`230` -- Warning framework
|
||||
|
||||
|
||||
.. cmdoption:: -x
|
||||
|
||||
Skip the first line of the source, allowing use of non-Unix forms of
|
||||
``#!cmd``. This is intended for a DOS specific hack only.
|
||||
|
||||
.. warning:: The line numbers in error messages will be off by one!
|
||||
|
||||
|
||||
.. cmdoption:: -3
|
||||
|
||||
Warn about Python 3.x incompatibilities.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
|
||||
Related files -- UNIX
|
||||
---------------------
|
||||
|
||||
These are subject to difference depending on local installation conventions;
|
||||
:envvar:`prefix` (``${prefix}``) and :envvar:`exec_prefix` (``${exec_prefix}``)
|
||||
are installation-dependent and should be interpreted as for GNU software; they
|
||||
may be the same.
|
||||
|
||||
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:`{prefix}/lib/python{version}`, | Recommended locations of the directories |
|
||||
| :file:`{exec_prefix}/lib/python{version}` | containing the standard modules. |
|
||||
+-----------------------------------------------+------------------------------------------+
|
||||
| :file:`{prefix}/include/python{version}`, | Recommended locations of the directories |
|
||||
| :file:`{exec_prefix}/include/python{version}` | containing the include files needed for |
|
||||
| | 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. |
|
||||
+-----------------------------------------------+------------------------------------------+
|
||||
|
||||
|
||||
Environment variables
|
||||
---------------------
|
||||
|
||||
.. envvar:: PYTHONHOME
|
||||
|
||||
Change the location of the standard Python libraries. By default, the
|
||||
libraries are searched in :file:`{prefix}/lib/python<version>` and
|
||||
:file:`{exec_prefix}/lib/python<version>`, where :file:`{prefix}` and
|
||||
:file:`{exec_prefix}` are installation-dependent directories, both defaulting
|
||||
to :file:`/usr/local`.
|
||||
|
||||
When :envvar:`PYTHONHOME` is set to a single directory, its value replaces
|
||||
both :file:`{prefix}` and :file:`{exec_prefix}`. To specify different values
|
||||
for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}``.
|
||||
|
||||
|
||||
.. envvar:: PYTHONPATH
|
||||
|
||||
Augments the default search path for module files. The format is the same as
|
||||
the shell's :envvar:`PATH`: one or more directory pathnames separated by
|
||||
colons. Non-existent directories are silently ignored.
|
||||
|
||||
The default search path is installation dependent, but generally begins with
|
||||
:file:`{prefix}/lib/python<version>`` (see :envvar:`PYTHONHOME` above). It
|
||||
is *always* appended to :envvar:`PYTHONPATH`.
|
||||
|
||||
If a script argument is given, the directory containing the script is
|
||||
inserted in the path in front of :envvar:`PYTHONPATH`. The search path can
|
||||
be manipulated from within a Python program as the variable :data:`sys.path`.
|
||||
|
||||
|
||||
.. envvar:: PYTHONSTARTUP
|
||||
|
||||
If this is the name of a readable file, the Python commands in that file are
|
||||
executed before the first prompt is displayed in interactive mode. The file
|
||||
is executed in the same name space where interactive commands are executed so
|
||||
that objects defined or imported in it can be used without qualification in
|
||||
the interactive session. You can also change the prompts :data:`sys.ps1` and
|
||||
:data:`sys.ps2` in this file.
|
||||
|
||||
|
||||
.. envvar:: PYTHONY2K
|
||||
|
||||
Set this to a non-empty string to cause the :mod:`time` module to require
|
||||
dates specified as strings to include 4-digit years, otherwise 2-digit years
|
||||
are converted based on rules described in the :mod:`time` module
|
||||
documentation.
|
||||
|
||||
|
||||
.. envvar:: PYTHONOPTIMIZE
|
||||
|
||||
If this is set to a non-empty string it is equivalent to specifying the
|
||||
:option:`-O` option. If set to an integer, it is equivalent to specifying
|
||||
:option:`-O` multiple times.
|
||||
|
||||
|
||||
.. envvar:: PYTHONDEBUG
|
||||
|
||||
If this is set to a non-empty string it is equivalent to specifying the
|
||||
:option:`-d` option. If set to an integer, it is equivalent to specifying
|
||||
:option:`-d` multiple times.
|
||||
|
||||
|
||||
.. envvar:: PYTHONINSPECT
|
||||
|
||||
If this is set to a non-empty string it is equivalent to specifying the
|
||||
:option:`-i` option.
|
||||
|
||||
|
||||
.. envvar:: PYTHONUNBUFFERED
|
||||
|
||||
If this is set to a non-empty string it is equivalent to specifying the
|
||||
:option:`-u` option.
|
||||
|
||||
|
||||
.. envvar:: PYTHONVERBOSE
|
||||
|
||||
If this is set to a non-empty string it is equivalent to specifying the
|
||||
:option:`-v` option. If set to an integer, it is equivalent to specifying
|
||||
:option:`-v` multiple times.
|
||||
|
||||
|
||||
.. envvar:: PYTHONCASEOK
|
||||
|
||||
If this is set, Python ignores case in :keyword:`import` statements. This
|
||||
only works on Windows.
|
||||
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
.. _using-index:
|
||||
|
||||
################
|
||||
Using Python
|
||||
################
|
||||
|
||||
|
||||
This part of the documentation is devoted to general information on the setup
|
||||
of the Python environment on different platform, the invocation of the
|
||||
interpreter and things that make working with Python easier.
|
||||
|
||||
|
||||
.. toctree::
|
||||
|
||||
cmdline.rst
|
||||
mac.rst
|
||||
|
||||
Loading…
Reference in New Issue