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