Home | History | Annotate | Download | only in reference 
      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 
    126