Debian Codegraph @

Doc/reference/toplevel_components.rst

raw
1
2 .. _top-level:
3
4 ********************
5 Top-level components
6 ********************
7
8 .. index:: single: interpreter
9
10 The Python interpreter can get its input from a number of sources: from a script
11 passed to it as standard input or as program argument, typed in interactively,
12 from a module source file, etc. This chapter gives the syntax used in these
13 cases.
14
15
16 .. _programs:
17
18 Complete Python programs
19 ========================
20
21 .. index:: single: program
22
23 .. index::
24 pair: module; sys
25 pair: module; __main__
26 pair: module; builtins
27
28 While a language specification need not prescribe how the language interpreter
29 is invoked, it is useful to have a notion of a complete Python program. A
30 complete Python program is executed in a minimally initialized environment: all
31 built-in and standard modules are available, but none have been initialized,
32 except for :mod:`sys` (various system services), :mod:`builtins` (built-in
33 functions, exceptions and ``None``) and :mod:`__main__`. The latter is used to
34 provide the local and global namespace for execution of the complete program.
35
36 The syntax for a complete Python program is that for file input, described in
37 the next section.
38
39 .. index::
40 single: interactive mode
41 pair: module; __main__
42
43 The interpreter may also be invoked in interactive mode; in this case, it does
44 not read and execute a complete program but reads and executes one statement
45 (possibly compound) at a time. The initial environment is identical to that of
46 a complete program; each statement is executed in the namespace of
47 :mod:`__main__`.
48
49 .. index::
50 single: UNIX
51 single: Windows
52 single: command line
53 single: standard input
54
55 A complete program can be passed to the interpreter
56 in three forms: with the :option:`-c` *string* command line option, as a file
57 passed as the first command line argument, or as standard input. If the file
58 or standard input is a tty device, the interpreter enters interactive mode;
59 otherwise, it executes the file as a complete program.
60
61
62 .. _file-input:
63
64 File input
65 ==========
66
67 All input read from non-interactive files has the same form:
68
69 .. grammar-snippet::
70 :group: python-grammar
71
72 file_input: (NEWLINE | `statement`)* ENDMARKER
73
74 This syntax is used in the following situations:
75
76 * when parsing a complete Python program (from a file or from a string);
77
78 * when parsing a module;
79
80 * when parsing a string passed to the :func:`exec` function;
81
82
83 .. _interactive:
84
85 Interactive input
86 =================
87
88 Input in interactive mode is parsed using the following grammar:
89
90 .. grammar-snippet::
91 :group: python-grammar
92
93 interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE | ENDMARKER
94
95 Note that a (top-level) compound statement must be followed by a blank line in
96 interactive mode; this is needed to help the parser detect the end of the input.
97
98
99 .. _expression-input:
100
101 Expression input
102 ================
103
104 .. index:: single: input
105 .. index:: pair: built-in function; eval
106
107 :func:`eval` is used for expression input. It ignores leading whitespace. The
108 string argument to :func:`eval` must have the following form:
109
110 .. grammar-snippet::
111 :group: python-grammar
112
113 eval_input: `expression_list` NEWLINE* ENDMARKER