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