Doc/reference/toplevel_components.rst

   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    module: sys
  25    module: __main__
  26    module: __builtin__
  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:`__builtin__` (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    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: command line
  52    single: standard input
  53
  54 Under Unix, a complete program can be passed to the interpreter in three forms:
  55 with the :option:`-c` *string* command line option, as a file passed as the
  56 first command line argument, or as standard input. If the file or standard input
  57 is a tty device, the interpreter enters interactive mode; otherwise, it executes
  58 the file as a complete program.
  59
  60
  61 .. _file-input:
  62
  63 File input
  64 ==========
  65
  66 All input read from non-interactive files has the same form:
  67
  68 .. productionlist::
  69    file_input: (NEWLINE | `statement`)*
  70
  71 This 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
  82 Interactive input
  83 =================
  84
  85 Input in interactive mode is parsed using the following grammar:
  86
  87 .. productionlist::
  88    interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE
  89
  90 Note that a (top-level) compound statement must be followed by a blank line in
  91 interactive mode; this is needed to help the parser detect the end of the input.
  92
  93
  94 .. _expression-input:
  95
  96 Expression input
  97 ================
  98
  99 .. index:: single: input
 100
 101 .. index:: builtin: eval
 102
 103 There are two forms of expression input.  Both ignore leading whitespace. The
 104 string argument to :func:`eval` must have the following form:
 105
 106 .. productionlist::
 107    eval_input: `expression_list` NEWLINE*
 108
 109 .. index:: builtin: input
 110
 111 The 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
 123 Note: to read 'raw' input line without interpretation, you can use the built-in
 124 function :func:`raw_input` or the :meth:`readline` method of file objects.
 125