Debian Codegraph @

Doc/tutorial/appendix.rst

raw
1 .. _tut-appendix:
2
3 ********
4 Appendix
5 ********
6
7
8 .. _tut-interac:
9
10 Interactive Mode
11 ================
12
13 There are two variants of the interactive :term:`REPL`. The classic
14 basic interpreter is supported on all platforms with minimal line
15 control capabilities.
16
17 Since Python 3.13, a new interactive shell is used by default.
18 This one supports color, multiline editing, history browsing, and
19 paste mode. To disable color, see :ref:`using-on-controlling-color` for
20 details. Function keys provide some additional functionality.
21 :kbd:`F1` enters the interactive help browser :mod:`pydoc`.
22 :kbd:`F2` allows for browsing command-line history with neither output nor the
23 :term:`>>>` and :term:`...` prompts. :kbd:`F3` enters "paste mode", which
24 makes pasting larger blocks of code easier. Press :kbd:`F3` to return to
25 the regular prompt.
26
27 When using the new interactive shell, exit the shell by typing :kbd:`exit`
28 or :kbd:`quit`. Adding call parentheses after those commands is not
29 required.
30
31 If the new interactive shell is not desired, it can be disabled via
32 the :envvar:`PYTHON_BASIC_REPL` environment variable.
33
34 .. _tut-error:
35
36 Error Handling
37 --------------
38
39 When an error occurs, the interpreter prints an error message and a stack trace.
40 In interactive mode, it then returns to the primary prompt; when input came from
41 a file, it exits with a nonzero exit status after printing the stack trace.
42 (Exceptions handled by an :keyword:`except` clause in a :keyword:`try` statement
43 are not errors in this context.) Some errors are unconditionally fatal and
44 cause an exit with a nonzero exit status; this applies to internal inconsistencies and
45 some cases of running out of memory. All error messages are written to the
46 standard error stream; normal output from executed commands is written to
47 standard output.
48
49 Typing the interrupt character (usually :kbd:`Control-C` or :kbd:`Delete`) to the primary or
50 secondary prompt cancels the input and returns to the primary prompt. [#]_
51 Typing an interrupt while a command is executing raises the
52 :exc:`KeyboardInterrupt` exception, which may be handled by a :keyword:`try`
53 statement.
54
55
56 .. _tut-scripts:
57
58 Executable Python Scripts
59 -------------------------
60
61 On BSD'ish Unix systems, Python scripts can be made directly executable, like
62 shell scripts, by putting the line ::
63
64 #!/usr/bin/env python3
65
66 (assuming that the interpreter is on the user's :envvar:`PATH`) at the beginning
67 of the script and giving the file an executable mode. The ``#!`` must be the
68 first two characters of the file. On some platforms, this first line must end
69 with a Unix-style line ending (``'\n'``), not a Windows (``'\r\n'``) line
70 ending. Note that the hash, or pound, character, ``'#'``, is used to start a
71 comment in Python.
72
73 The script can be given an executable mode, or permission, using the
74 :program:`chmod` command.
75
76 .. code-block:: shell-session
77
78 $ chmod +x myscript.py
79
80 On Windows systems, there is no notion of an "executable mode". The Python
81 installer automatically associates ``.py`` files with ``python.exe`` so that
82 a double-click on a Python file will run it as a script. The extension can
83 also be ``.pyw``, in that case, the console window that normally appears is
84 suppressed.
85
86
87 .. _tut-startup:
88
89 The Interactive Startup File
90 ----------------------------
91
92 When you use Python interactively, it is frequently handy to have some standard
93 commands executed every time the interpreter is started. You can do this by
94 setting an environment variable named :envvar:`PYTHONSTARTUP` to the name of a
95 file containing your start-up commands. This is similar to the :file:`.profile`
96 feature of the Unix shells.
97
98 This file is only read in interactive sessions, not when Python reads commands
99 from a script, and not when :file:`/dev/tty` is given as the explicit source of
100 commands (which otherwise behaves like an interactive session). It is executed
101 in the same namespace where interactive commands are executed, so that objects
102 that it defines or imports can be used without qualification in the interactive
103 session. You can also change the prompts ``sys.ps1`` and ``sys.ps2`` in this
104 file.
105
106 If you want to read an additional start-up file from the current directory, you
107 can program this in the global start-up file using code like ``if
108 os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read())``.
109 If you want to use the startup file in a script, you must do this explicitly
110 in the script::
111
112 import os
113 filename = os.environ.get('PYTHONSTARTUP')
114 if filename and os.path.isfile(filename):
115 with open(filename) as fobj:
116 startup_file = fobj.read()
117 exec(startup_file)
118
119
120 .. _tut-customize:
121
122 The Customization Modules
123 -------------------------
124
125 Python provides two hooks to let you customize it: :index:`sitecustomize` and
126 :index:`usercustomize`. To see how it works, you need first to find the location
127 of your user site-packages directory. Start Python and run this code::
128
129 >>> import site
130 >>> site.getusersitepackages()
131 '/home/user/.local/lib/python3.x/site-packages'
132
133 Now you can create a file named :file:`usercustomize.py` in that directory and
134 put anything you want in it. It will affect every invocation of Python, unless
135 it is started with the :option:`-s` option to disable the automatic import.
136
137 :index:`sitecustomize` works in the same way, but is typically created by an
138 administrator of the computer in the global site-packages directory, and is
139 imported before :index:`usercustomize`. See the documentation of the :mod:`site`
140 module for more details.
141
142
143 .. rubric:: Footnotes
144
145 .. [#] A problem with the GNU Readline package may prevent this.