cpython: ea401e7c55e4 (original) (raw)

Mercurial > cpython

changeset 92467:ea401e7c55e4

merge from 3.4 Issue #16827: Make Interpreter introduction section of the tutorial more focussed and move advanced section and customization information to a separate file called appendix. Patch credits: Jamayla Wiley, Ya-Ting Huang and James Brewer. [#16827]

Senthil Kumaran senthil@uthcode.com
date	Thu, 18 Sep 2014 21:37:26 +0800
parents	a0372781eafb(current diff)1e81c7a261a7(diff)
children	49dfe2630ae3
files	Doc/tutorial/appendix.rst Doc/tutorial/interpreter.rst
diffstat	3 files changed, 128 insertions(+), 110 deletions(-)[+] [-] Doc/tutorial/appendix.rst 124 Doc/tutorial/index.rst 1 Doc/tutorial/interpreter.rst 113

line wrap: on

line diff

new file mode 100644 --- /dev/null +++ b/Doc/tutorial/appendix.rst @@ -0,0 +1,124 @@ +.. _tut-appendix: + + +Appendix + + + +.. _tut-interac: + +Interactive Mode +================ + +.. tut-error: + +Error Handling +-------------- + +When an error occurs, the interpreter prints an error message and a stack trace. +In interactive mode, it then returns to the primary prompt; when input came from +a file, it exits with a nonzero exit status after printing the stack trace. +(Exceptions handled by an :keyword:except clause in a :keyword:try statement +are not errors in this context.) Some errors are unconditionally fatal and +cause an exit with a nonzero exit; this applies to internal inconsistencies and +some cases of running out of memory. All error messages are written to the +standard error stream; normal output from executed commands is written to +standard output. + +Typing the interrupt character (usually Control-C or DEL) to the primary or +secondary prompt cancels the input and returns to the primary prompt. [#] +Typing an interrupt while a command is executing raises the +:exc:KeyboardInterrupt exception, which may be handled by a :keyword:try +statement. + + +.. _tut-scripts: + +Executable Python Scripts +------------------------- + +On BSD'ish Unix systems, Python scripts can be made directly executable, like +shell scripts, by putting the line :: +

#!/usr/bin/env python3.5

+ +(assuming that the interpreter is on the user's :envvar:PATH) at the beginning +of the script and giving the file an executable mode. The #! must be the +first two characters of the file. On some platforms, this first line must end +with a Unix-style line ending ('\n'), not a Windows ('\r\n') line +ending. Note that the hash, or pound, character, '#', is used to start a +comment in Python. + +The script can be given an executable mode, or permission, using the +:program:chmod command. + +.. code-block:: bash +

$ chmod +x myscript.py +

+On Windows systems, there is no notion of an "executable mode". The Python +installer automatically associates .py files with python.exe so that +a double-click on a Python file will run it as a script. The extension can +also be .pyw, in that case, the console window that normally appears is +suppressed. + + +.. _tut-startup: + +The Interactive Startup File +---------------------------- + +When you use Python interactively, it is frequently handy to have some standard +commands executed every time the interpreter is started. You can do this by +setting an environment variable named :envvar:PYTHONSTARTUP to the name of a +file containing your start-up commands. This is similar to the :file:.profile +feature of the Unix shells. + +This file is only read in interactive sessions, not when Python reads commands +from a script, and not when :file:/dev/tty is given as the explicit source of +commands (which otherwise behaves like an interactive session). It is executed +in the same namespace where interactive commands are executed, so that objects +that it defines or imports can be used without qualification in the interactive +session. You can also change the prompts sys.ps1 and sys.ps2 in this +file. + +If you want to read an additional start-up file from the current directory, you +can program this in the global start-up file using code like if[](#l1.90) +os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read()). +If you want to use the startup file in a script, you must do this explicitly +in the script:: +

import os
filename = os.environ.get('PYTHONSTARTUP')
if filename and os.path.isfile(filename):

  with open(filename) as fobj:[](#l1.98)

     startup_file = fobj.read()[](#l1.99)

```
  exec(startup_file)[](#l1.100)
```

+ + +.. _tut-customize: + +The Customization Modules +------------------------- + +Python provides two hooks to let you customize it: :mod:sitecustomize and +:mod:usercustomize. To see how it works, you need first to find the location +of your user site-packages directory. Start Python and run this code:: +

import site
site.getusersitepackages()
'/home/user/.local/lib/python3.5/site-packages' +

+Now you can create a file named :file:usercustomize.py in that directory and +put anything you want in it. It will affect every invocation of Python, unless +it is started with the :option:-s option to disable the automatic import. + +:mod:sitecustomize works in the same way, but is typically created by an +administrator of the computer in the global site-packages directory, and is +imported before :mod:usercustomize. See the documentation of the :mod:site +module for more details. + + +.. rubric:: Footnotes + +.. [#] A problem with the GNU Readline package may prevent this.

--- a/Doc/tutorial/index.rst +++ b/Doc/tutorial/index.rst @@ -56,3 +56,4 @@ The :ref:glossary is also worth going whatnow.rst interactive.rst floatingpoint.rst

appendix.rst

--- a/Doc/tutorial/interpreter.rst +++ b/Doc/tutorial/interpreter.rst @@ -112,63 +112,15 @@ example, take a look at this :keyword:i[](#l3.3) Be careful not to fall off![](#l3.4) [](#l3.5) [](#l3.6) +For more on interactive mode, see :ref:tut-interac.[](#l3.7) +[](#l3.8) +[](#l3.9) .. _tut-interp:[](#l3.10) [](#l3.11) The Interpreter and Its Environment[](#l3.12) ===================================[](#l3.13) [](#l3.14) [](#l3.15) -.. _tut-error:[](#l3.16) -[](#l3.17) -Error Handling[](#l3.18) ---------------[](#l3.19) -[](#l3.20) -When an error occurs, the interpreter prints an error message and a stack trace.[](#l3.21) -In interactive mode, it then returns to the primary prompt; when input came from[](#l3.22) -a file, it exits with a nonzero exit status after printing the stack trace.[](#l3.23) -(Exceptions handled by an :keyword:except clause in a :keyword:try statement[](#l3.24) -are not errors in this context.) Some errors are unconditionally fatal and[](#l3.25) -cause an exit with a nonzero exit; this applies to internal inconsistencies and[](#l3.26) -some cases of running out of memory. All error messages are written to the[](#l3.27) -standard error stream; normal output from executed commands is written to[](#l3.28) -standard output.[](#l3.29) -[](#l3.30) -Typing the interrupt character (usually Control-C or DEL) to the primary or[](#l3.31) -secondary prompt cancels the input and returns to the primary prompt. [#]_[](#l3.32) -Typing an interrupt while a command is executing raises the[](#l3.33) -:exc:KeyboardInterrupt exception, which may be handled by a :keyword:try` -statement. - - -.. _tut-scripts: - -Executable Python Scripts -------------------------- - -On BSD'ish Unix systems, Python scripts can be made directly executable, like -shell scripts, by putting the line :: -

#! /usr/bin/env python3.5

- -(assuming that the interpreter is on the user's :envvar:PATH) at the beginning -of the script and giving the file an executable mode. The #! must be the -first two characters of the file. On some platforms, this first line must end -with a Unix-style line ending ('\n'), not a Windows ('\r\n') line -ending. Note that the hash, or pound, character, '#', is used to start a -comment in Python. - -The script can be given an executable mode, or permission, using the -:program:chmod command:: -

$ chmod +x myscript.py -

-On Windows systems, there is no notion of an "executable mode". The Python -installer automatically associates .py files with python.exe so that -a double-click on a Python file will run it as a script. The extension can -also be .pyw, in that case, the console window that normally appears is -suppressed. - - .. _tut-source-encoding: Source Code Encoding @@ -202,67 +154,8 @@ files. The special encoding comment mus within the file. -.. _tut-startup: - -The Interactive Startup File ----------------------------- - -When you use Python interactively, it is frequently handy to have some standard -commands executed every time the interpreter is started. You can do this by -setting an environment variable named :envvar:PYTHONSTARTUP to the name of a -file containing your start-up commands. This is similar to the :file:.profile -feature of the Unix shells. - -.. XXX This should probably be dumped in an appendix, since most people

don't use Python interactively in non-trivial ways. -

-This file is only read in interactive sessions, not when Python reads commands -from a script, and not when :file:/dev/tty is given as the explicit source of -commands (which otherwise behaves like an interactive session). It is executed -in the same namespace where interactive commands are executed, so that objects -that it defines or imports can be used without qualification in the interactive -session. You can also change the prompts sys.ps1 and sys.ps2 in this -file. - -If you want to read an additional start-up file from the current directory, you -can program this in the global start-up file using code like if[](#l3.97) -os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read()). -If you want to use the startup file in a script, you must do this explicitly -in the script:: -

import os
filename = os.environ.get('PYTHONSTARTUP')
if filename and os.path.isfile(filename):

  exec(open(filename).read())[](#l3.105)

- - -.. _tut-customize: - -The Customization Modules -------------------------- - -Python provides two hooks to let you customize it: :mod:sitecustomize and -:mod:usercustomize. To see how it works, you need first to find the location -of your user site-packages directory. Start Python and run this code: -

import site
site.getusersitepackages()
'/home/user/.local/lib/python3.2/site-packages' -

-Now you can create a file named :file:usercustomize.py in that directory and -put anything you want in it. It will affect every invocation of Python, unless -it is started with the :option:-s option to disable the automatic import. - -:mod:sitecustomize works in the same way, but is typically created by an -administrator of the computer in the global site-packages directory, and is -imported before :mod:usercustomize. See the documentation of the :mod:site -module for more details. - - .. rubric:: Footnotes .. [#] On Unix, the Python 3.x interpreter is by default not installed with the executable named python, so that it does not conflict with a simultaneously installed Python 2.x executable. - -.. [#] A problem with the GNU Readline package may prevent this.