/Doc/reference/simple_stmts.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 1017 lines · 769 code · 248 blank · 0 comment · 0 complexity · 267e4694c987b73b22e85cb1eb86ecc6 MD5 · raw file

  1. .. _simple:
  2. *****************
  3. Simple statements
  4. *****************
  5. .. index:: pair: simple; statement
  6. Simple statements are comprised within a single logical line. Several simple
  7. statements may occur on a single line separated by semicolons. The syntax for
  8. simple statements is:
  9. .. productionlist::
  10. simple_stmt: `expression_stmt`
  11. : | `assert_stmt`
  12. : | `assignment_stmt`
  13. : | `augmented_assignment_stmt`
  14. : | `pass_stmt`
  15. : | `del_stmt`
  16. : | `print_stmt`
  17. : | `return_stmt`
  18. : | `yield_stmt`
  19. : | `raise_stmt`
  20. : | `break_stmt`
  21. : | `continue_stmt`
  22. : | `import_stmt`
  23. : | `global_stmt`
  24. : | `exec_stmt`
  25. .. _exprstmts:
  26. Expression statements
  27. =====================
  28. .. index::
  29. pair: expression; statement
  30. pair: expression; list
  31. Expression statements are used (mostly interactively) to compute and write a
  32. value, or (usually) to call a procedure (a function that returns no meaningful
  33. result; in Python, procedures return the value ``None``). Other uses of
  34. expression statements are allowed and occasionally useful. The syntax for an
  35. expression statement is:
  36. .. productionlist::
  37. expression_stmt: `expression_list`
  38. An expression statement evaluates the expression list (which may be a single
  39. expression).
  40. .. index::
  41. builtin: repr
  42. object: None
  43. pair: string; conversion
  44. single: output
  45. pair: standard; output
  46. pair: writing; values
  47. pair: procedure; call
  48. In interactive mode, if the value is not ``None``, it is converted to a string
  49. using the built-in :func:`repr` function and the resulting string is written to
  50. standard output (see section :ref:`print`) on a line by itself. (Expression
  51. statements yielding ``None`` are not written, so that procedure calls do not
  52. cause any output.)
  53. .. _assignment:
  54. Assignment statements
  55. =====================
  56. .. index::
  57. pair: assignment; statement
  58. pair: binding; name
  59. pair: rebinding; name
  60. object: mutable
  61. pair: attribute; assignment
  62. Assignment statements are used to (re)bind names to values and to modify
  63. attributes or items of mutable objects:
  64. .. productionlist::
  65. assignment_stmt: (`target_list` "=")+ (`expression_list` | `yield_expression`)
  66. target_list: `target` ("," `target`)* [","]
  67. target: `identifier`
  68. : | "(" `target_list` ")"
  69. : | "[" `target_list` "]"
  70. : | `attributeref`
  71. : | `subscription`
  72. : | `slicing`
  73. (See section :ref:`primaries` for the syntax definitions for the last three
  74. symbols.)
  75. .. index:: pair: expression; list
  76. An assignment statement evaluates the expression list (remember that this can be
  77. a single expression or a comma-separated list, the latter yielding a tuple) and
  78. assigns the single resulting object to each of the target lists, from left to
  79. right.
  80. .. index::
  81. single: target
  82. pair: target; list
  83. Assignment is defined recursively depending on the form of the target (list).
  84. When a target is part of a mutable object (an attribute reference, subscription
  85. or slicing), the mutable object must ultimately perform the assignment and
  86. decide about its validity, and may raise an exception if the assignment is
  87. unacceptable. The rules observed by various types and the exceptions raised are
  88. given with the definition of the object types (see section :ref:`types`).
  89. .. index:: triple: target; list; assignment
  90. Assignment of an object to a target list is recursively defined as follows.
  91. * If the target list is a single target: The object is assigned to that target.
  92. * If the target list is a comma-separated list of targets: The object must be an
  93. iterable with the same number of items as there are targets in the target list,
  94. and the items are assigned, from left to right, to the corresponding targets.
  95. (This rule is relaxed as of Python 1.5; in earlier versions, the object had to
  96. be a tuple. Since strings are sequences, an assignment like ``a, b = "xy"`` is
  97. now legal as long as the string has the right length.)
  98. Assignment of an object to a single target is recursively defined as follows.
  99. * If the target is an identifier (name):
  100. .. index:: statement: global
  101. * If the name does not occur in a :keyword:`global` statement in the current
  102. code block: the name is bound to the object in the current local namespace.
  103. * Otherwise: the name is bound to the object in the current global namespace.
  104. .. index:: single: destructor
  105. The name is rebound if it was already bound. This may cause the reference count
  106. for the object previously bound to the name to reach zero, causing the object to
  107. be deallocated and its destructor (if it has one) to be called.
  108. * If the target is a target list enclosed in parentheses or in square brackets:
  109. The object must be an iterable with the same number of items as there are
  110. targets in the target list, and its items are assigned, from left to right,
  111. to the corresponding targets.
  112. .. index:: pair: attribute; assignment
  113. * If the target is an attribute reference: The primary expression in the
  114. reference is evaluated. It should yield an object with assignable attributes;
  115. if this is not the case, :exc:`TypeError` is raised. That object is then asked
  116. to assign the assigned object to the given attribute; if it cannot perform the
  117. assignment, it raises an exception (usually but not necessarily
  118. :exc:`AttributeError`).
  119. .. index::
  120. pair: subscription; assignment
  121. object: mutable
  122. * If the target is a subscription: The primary expression in the reference is
  123. evaluated. It should yield either a mutable sequence object (such as a list) or
  124. a mapping object (such as a dictionary). Next, the subscript expression is
  125. evaluated.
  126. .. index::
  127. object: sequence
  128. object: list
  129. If the primary is a mutable sequence object (such as a list), the subscript must
  130. yield a plain integer. If it is negative, the sequence's length is added to it.
  131. The resulting value must be a nonnegative integer less than the sequence's
  132. length, and the sequence is asked to assign the assigned object to its item with
  133. that index. If the index is out of range, :exc:`IndexError` is raised
  134. (assignment to a subscripted sequence cannot add new items to a list).
  135. .. index::
  136. object: mapping
  137. object: dictionary
  138. If the primary is a mapping object (such as a dictionary), the subscript must
  139. have a type compatible with the mapping's key type, and the mapping is then
  140. asked to create a key/datum pair which maps the subscript to the assigned
  141. object. This can either replace an existing key/value pair with the same key
  142. value, or insert a new key/value pair (if no key with the same value existed).
  143. .. index:: pair: slicing; assignment
  144. * If the target is a slicing: The primary expression in the reference is
  145. evaluated. It should yield a mutable sequence object (such as a list). The
  146. assigned object should be a sequence object of the same type. Next, the lower
  147. and upper bound expressions are evaluated, insofar they are present; defaults
  148. are zero and the sequence's length. The bounds should evaluate to (small)
  149. integers. If either bound is negative, the sequence's length is added to it.
  150. The resulting bounds are clipped to lie between zero and the sequence's length,
  151. inclusive. Finally, the sequence object is asked to replace the slice with the
  152. items of the assigned sequence. The length of the slice may be different from
  153. the length of the assigned sequence, thus changing the length of the target
  154. sequence, if the object allows it.
  155. (In the current implementation, the syntax for targets is taken to be the same
  156. as for expressions, and invalid syntax is rejected during the code generation
  157. phase, causing less detailed error messages.)
  158. WARNING: Although the definition of assignment implies that overlaps between the
  159. left-hand side and the right-hand side are 'safe' (for example ``a, b = b, a``
  160. swaps two variables), overlaps *within* the collection of assigned-to variables
  161. are not safe! For instance, the following program prints ``[0, 2]``::
  162. x = [0, 1]
  163. i = 0
  164. i, x[i] = 1, 2
  165. print x
  166. .. _augassign:
  167. Augmented assignment statements
  168. -------------------------------
  169. .. index::
  170. pair: augmented; assignment
  171. single: statement; assignment, augmented
  172. Augmented assignment is the combination, in a single statement, of a binary
  173. operation and an assignment statement:
  174. .. productionlist::
  175. augmented_assignment_stmt: `augtarget` `augop` (`expression_list` | `yield_expression`)
  176. augtarget: `identifier` | `attributeref` | `subscription` | `slicing`
  177. augop: "+=" | "-=" | "*=" | "/=" | "//=" | "%=" | "**="
  178. : | ">>=" | "<<=" | "&=" | "^=" | "|="
  179. (See section :ref:`primaries` for the syntax definitions for the last three
  180. symbols.)
  181. An augmented assignment evaluates the target (which, unlike normal assignment
  182. statements, cannot be an unpacking) and the expression list, performs the binary
  183. operation specific to the type of assignment on the two operands, and assigns
  184. the result to the original target. The target is only evaluated once.
  185. An augmented assignment expression like ``x += 1`` can be rewritten as ``x = x +
  186. 1`` to achieve a similar, but not exactly equal effect. In the augmented
  187. version, ``x`` is only evaluated once. Also, when possible, the actual operation
  188. is performed *in-place*, meaning that rather than creating a new object and
  189. assigning that to the target, the old object is modified instead.
  190. With the exception of assigning to tuples and multiple targets in a single
  191. statement, the assignment done by augmented assignment statements is handled the
  192. same way as normal assignments. Similarly, with the exception of the possible
  193. *in-place* behavior, the binary operation performed by augmented assignment is
  194. the same as the normal binary operations.
  195. For targets which are attribute references, the initial value is retrieved with
  196. a :meth:`getattr` and the result is assigned with a :meth:`setattr`. Notice
  197. that the two methods do not necessarily refer to the same variable. When
  198. :meth:`getattr` refers to a class variable, :meth:`setattr` still writes to an
  199. instance variable. For example::
  200. class A:
  201. x = 3 # class variable
  202. a = A()
  203. a.x += 1 # writes a.x as 4 leaving A.x as 3
  204. .. _assert:
  205. The :keyword:`assert` statement
  206. ===============================
  207. .. index::
  208. statement: assert
  209. pair: debugging; assertions
  210. Assert statements are a convenient way to insert debugging assertions into a
  211. program:
  212. .. productionlist::
  213. assert_stmt: "assert" `expression` ["," `expression`]
  214. The simple form, ``assert expression``, is equivalent to ::
  215. if __debug__:
  216. if not expression: raise AssertionError
  217. The extended form, ``assert expression1, expression2``, is equivalent to ::
  218. if __debug__:
  219. if not expression1: raise AssertionError, expression2
  220. .. index::
  221. single: __debug__
  222. exception: AssertionError
  223. These equivalences assume that :const:`__debug__` and :exc:`AssertionError` refer to
  224. the built-in variables with those names. In the current implementation, the
  225. built-in variable :const:`__debug__` is ``True`` under normal circumstances,
  226. ``False`` when optimization is requested (command line option -O). The current
  227. code generator emits no code for an assert statement when optimization is
  228. requested at compile time. Note that it is unnecessary to include the source
  229. code for the expression that failed in the error message; it will be displayed
  230. as part of the stack trace.
  231. Assignments to :const:`__debug__` are illegal. The value for the built-in variable
  232. is determined when the interpreter starts.
  233. .. _pass:
  234. The :keyword:`pass` statement
  235. =============================
  236. .. index::
  237. statement: pass
  238. pair: null; operation
  239. .. productionlist::
  240. pass_stmt: "pass"
  241. :keyword:`pass` is a null operation --- when it is executed, nothing happens.
  242. It is useful as a placeholder when a statement is required syntactically, but no
  243. code needs to be executed, for example::
  244. def f(arg): pass # a function that does nothing (yet)
  245. class C: pass # a class with no methods (yet)
  246. .. _del:
  247. The :keyword:`del` statement
  248. ============================
  249. .. index::
  250. statement: del
  251. pair: deletion; target
  252. triple: deletion; target; list
  253. .. productionlist::
  254. del_stmt: "del" `target_list`
  255. Deletion is recursively defined very similar to the way assignment is defined.
  256. Rather that spelling it out in full details, here are some hints.
  257. Deletion of a target list recursively deletes each target, from left to right.
  258. .. index::
  259. statement: global
  260. pair: unbinding; name
  261. Deletion of a name removes the binding of that name from the local or global
  262. namespace, depending on whether the name occurs in a :keyword:`global` statement
  263. in the same code block. If the name is unbound, a :exc:`NameError` exception
  264. will be raised.
  265. .. index:: pair: free; variable
  266. It is illegal to delete a name from the local namespace if it occurs as a free
  267. variable in a nested block.
  268. .. index:: pair: attribute; deletion
  269. Deletion of attribute references, subscriptions and slicings is passed to the
  270. primary object involved; deletion of a slicing is in general equivalent to
  271. assignment of an empty slice of the right type (but even this is determined by
  272. the sliced object).
  273. .. _print:
  274. The :keyword:`print` statement
  275. ==============================
  276. .. index:: statement: print
  277. .. productionlist::
  278. print_stmt: "print" ([`expression` ("," `expression`)* [","]]
  279. : | ">>" `expression` [("," `expression`)+ [","]])
  280. :keyword:`print` evaluates each expression in turn and writes the resulting
  281. object to standard output (see below). If an object is not a string, it is
  282. first converted to a string using the rules for string conversions. The
  283. (resulting or original) string is then written. A space is written before each
  284. object is (converted and) written, unless the output system believes it is
  285. positioned at the beginning of a line. This is the case (1) when no characters
  286. have yet been written to standard output, (2) when the last character written to
  287. standard output is a whitespace character except ``' '``, or (3) when the last
  288. write operation on standard output was not a :keyword:`print` statement.
  289. (In some cases it may be functional to write an empty string to standard output
  290. for this reason.)
  291. .. note::
  292. Objects which act like file objects but which are not the built-in file objects
  293. often do not properly emulate this aspect of the file object's behavior, so it
  294. is best not to rely on this.
  295. .. index::
  296. single: output
  297. pair: writing; values
  298. pair: trailing; comma
  299. pair: newline; suppression
  300. A ``'\n'`` character is written at the end, unless the :keyword:`print`
  301. statement ends with a comma. This is the only action if the statement contains
  302. just the keyword :keyword:`print`.
  303. .. index::
  304. pair: standard; output
  305. module: sys
  306. single: stdout (in module sys)
  307. exception: RuntimeError
  308. Standard output is defined as the file object named ``stdout`` in the built-in
  309. module :mod:`sys`. If no such object exists, or if it does not have a
  310. :meth:`write` method, a :exc:`RuntimeError` exception is raised.
  311. .. index:: single: extended print statement
  312. :keyword:`print` also has an extended form, defined by the second portion of the
  313. syntax described above. This form is sometimes referred to as ":keyword:`print`
  314. chevron." In this form, the first expression after the ``>>`` must evaluate to a
  315. "file-like" object, specifically an object that has a :meth:`write` method as
  316. described above. With this extended form, the subsequent expressions are
  317. printed to this file object. If the first expression evaluates to ``None``,
  318. then ``sys.stdout`` is used as the file for output.
  319. .. _return:
  320. The :keyword:`return` statement
  321. ===============================
  322. .. index::
  323. statement: return
  324. pair: function; definition
  325. pair: class; definition
  326. .. productionlist::
  327. return_stmt: "return" [`expression_list`]
  328. :keyword:`return` may only occur syntactically nested in a function definition,
  329. not within a nested class definition.
  330. If an expression list is present, it is evaluated, else ``None`` is substituted.
  331. :keyword:`return` leaves the current function call with the expression list (or
  332. ``None``) as return value.
  333. .. index:: keyword: finally
  334. When :keyword:`return` passes control out of a :keyword:`try` statement with a
  335. :keyword:`finally` clause, that :keyword:`finally` clause is executed before
  336. really leaving the function.
  337. In a generator function, the :keyword:`return` statement is not allowed to
  338. include an :token:`expression_list`. In that context, a bare :keyword:`return`
  339. indicates that the generator is done and will cause :exc:`StopIteration` to be
  340. raised.
  341. .. _yield:
  342. The :keyword:`yield` statement
  343. ==============================
  344. .. index::
  345. statement: yield
  346. single: generator; function
  347. single: generator; iterator
  348. single: function; generator
  349. exception: StopIteration
  350. .. productionlist::
  351. yield_stmt: `yield_expression`
  352. The :keyword:`yield` statement is only used when defining a generator function,
  353. and is only used in the body of the generator function. Using a :keyword:`yield`
  354. statement in a function definition is sufficient to cause that definition to
  355. create a generator function instead of a normal function.
  356. When a generator function is called, it returns an iterator known as a generator
  357. iterator, or more commonly, a generator. The body of the generator function is
  358. executed by calling the generator's :meth:`next` method repeatedly until it
  359. raises an exception.
  360. When a :keyword:`yield` statement is executed, the state of the generator is
  361. frozen and the value of :token:`expression_list` is returned to :meth:`next`'s
  362. caller. By "frozen" we mean that all local state is retained, including the
  363. current bindings of local variables, the instruction pointer, and the internal
  364. evaluation stack: enough information is saved so that the next time :meth:`next`
  365. is invoked, the function can proceed exactly as if the :keyword:`yield`
  366. statement were just another external call.
  367. As of Python version 2.5, the :keyword:`yield` statement is now allowed in the
  368. :keyword:`try` clause of a :keyword:`try` ... :keyword:`finally` construct. If
  369. the generator is not resumed before it is finalized (by reaching a zero
  370. reference count or by being garbage collected), the generator-iterator's
  371. :meth:`close` method will be called, allowing any pending :keyword:`finally`
  372. clauses to execute.
  373. .. note::
  374. In Python 2.2, the :keyword:`yield` statement was only allowed when the
  375. ``generators`` feature has been enabled. This ``__future__``
  376. import statement was used to enable the feature::
  377. from __future__ import generators
  378. .. seealso::
  379. :pep:`0255` - Simple Generators
  380. The proposal for adding generators and the :keyword:`yield` statement to Python.
  381. :pep:`0342` - Coroutines via Enhanced Generators
  382. The proposal that, among other generator enhancements, proposed allowing
  383. :keyword:`yield` to appear inside a :keyword:`try` ... :keyword:`finally` block.
  384. .. _raise:
  385. The :keyword:`raise` statement
  386. ==============================
  387. .. index::
  388. statement: raise
  389. single: exception
  390. pair: raising; exception
  391. .. productionlist::
  392. raise_stmt: "raise" [`expression` ["," `expression` ["," `expression`]]]
  393. If no expressions are present, :keyword:`raise` re-raises the last exception
  394. that was active in the current scope. If no exception is active in the current
  395. scope, a :exc:`TypeError` exception is raised indicating that this is an error
  396. (if running under IDLE, a :exc:`Queue.Empty` exception is raised instead).
  397. Otherwise, :keyword:`raise` evaluates the expressions to get three objects,
  398. using ``None`` as the value of omitted expressions. The first two objects are
  399. used to determine the *type* and *value* of the exception.
  400. If the first object is an instance, the type of the exception is the class of
  401. the instance, the instance itself is the value, and the second object must be
  402. ``None``.
  403. If the first object is a class, it becomes the type of the exception. The second
  404. object is used to determine the exception value: If it is an instance of the
  405. class, the instance becomes the exception value. If the second object is a
  406. tuple, it is used as the argument list for the class constructor; if it is
  407. ``None``, an empty argument list is used, and any other object is treated as a
  408. single argument to the constructor. The instance so created by calling the
  409. constructor is used as the exception value.
  410. .. index:: object: traceback
  411. If a third object is present and not ``None``, it must be a traceback object
  412. (see section :ref:`types`), and it is substituted instead of the current
  413. location as the place where the exception occurred. If the third object is
  414. present and not a traceback object or ``None``, a :exc:`TypeError` exception is
  415. raised. The three-expression form of :keyword:`raise` is useful to re-raise an
  416. exception transparently in an except clause, but :keyword:`raise` with no
  417. expressions should be preferred if the exception to be re-raised was the most
  418. recently active exception in the current scope.
  419. Additional information on exceptions can be found in section :ref:`exceptions`,
  420. and information about handling exceptions is in section :ref:`try`.
  421. .. _break:
  422. The :keyword:`break` statement
  423. ==============================
  424. .. index::
  425. statement: break
  426. statement: for
  427. statement: while
  428. pair: loop; statement
  429. .. productionlist::
  430. break_stmt: "break"
  431. :keyword:`break` may only occur syntactically nested in a :keyword:`for` or
  432. :keyword:`while` loop, but not nested in a function or class definition within
  433. that loop.
  434. .. index:: keyword: else
  435. It terminates the nearest enclosing loop, skipping the optional :keyword:`else`
  436. clause if the loop has one.
  437. .. index:: pair: loop control; target
  438. If a :keyword:`for` loop is terminated by :keyword:`break`, the loop control
  439. target keeps its current value.
  440. .. index:: keyword: finally
  441. When :keyword:`break` passes control out of a :keyword:`try` statement with a
  442. :keyword:`finally` clause, that :keyword:`finally` clause is executed before
  443. really leaving the loop.
  444. .. _continue:
  445. The :keyword:`continue` statement
  446. =================================
  447. .. index::
  448. statement: continue
  449. statement: for
  450. statement: while
  451. pair: loop; statement
  452. keyword: finally
  453. .. productionlist::
  454. continue_stmt: "continue"
  455. :keyword:`continue` may only occur syntactically nested in a :keyword:`for` or
  456. :keyword:`while` loop, but not nested in a function or class definition or
  457. :keyword:`finally` clause within that loop. It continues with the next
  458. cycle of the nearest enclosing loop.
  459. When :keyword:`continue` passes control out of a :keyword:`try` statement with a
  460. :keyword:`finally` clause, that :keyword:`finally` clause is executed before
  461. really starting the next loop cycle.
  462. .. _import:
  463. .. _from:
  464. The :keyword:`import` statement
  465. ===============================
  466. .. index::
  467. statement: import
  468. single: module; importing
  469. pair: name; binding
  470. keyword: from
  471. .. productionlist::
  472. import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )*
  473. : | "from" `relative_module` "import" `identifier` ["as" `name`]
  474. : ( "," `identifier` ["as" `name`] )*
  475. : | "from" `relative_module` "import" "(" `identifier` ["as" `name`]
  476. : ( "," `identifier` ["as" `name`] )* [","] ")"
  477. : | "from" `module` "import" "*"
  478. module: (`identifier` ".")* `identifier`
  479. relative_module: "."* `module` | "."+
  480. name: `identifier`
  481. Import statements are executed in two steps: (1) find a module, and initialize
  482. it if necessary; (2) define a name or names in the local namespace (of the scope
  483. where the :keyword:`import` statement occurs). The statement comes in two
  484. forms differing on whether it uses the :keyword:`from` keyword. The first form
  485. (without :keyword:`from`) repeats these steps for each identifier in the list.
  486. The form with :keyword:`from` performs step (1) once, and then performs step
  487. (2) repeatedly.
  488. .. index::
  489. single: package
  490. To understand how step (1) occurs, one must first understand how Python handles
  491. hierarchical naming of modules. To help organize modules and provide a
  492. hierarchy in naming, Python has a concept of packages. A package can contain
  493. other packages and modules while modules cannot contain other modules or
  494. packages. From a file system perspective, packages are directories and modules
  495. are files. The original `specification for packages
  496. <http://www.python.org/doc/essays/packages.html>`_ is still available to read,
  497. although minor details have changed since the writing of that document.
  498. .. index::
  499. single: sys.modules
  500. Once the name of the module is known (unless otherwise specified, the term
  501. "module" will refer to both packages and modules), searching
  502. for the module or package can begin. The first place checked is
  503. :data:`sys.modules`, the cache of all modules that have been imported
  504. previously. If the module is found there then it is used in step (2) of import.
  505. .. index::
  506. single: sys.meta_path
  507. single: finder
  508. pair: finder; find_module
  509. single: __path__
  510. If the module is not found in the cache, then :data:`sys.meta_path` is searched
  511. (the specification for :data:`sys.meta_path` can be found in :pep:`302`).
  512. The object is a list of :term:`finder` objects which are queried in order as to
  513. whether they know how to load the module by calling their :meth:`find_module`
  514. method with the name of the module. If the module happens to be contained
  515. within a package (as denoted by the existence of a dot in the name), then a
  516. second argument to :meth:`find_module` is given as the value of the
  517. :attr:`__path__` attribute from the parent package (everything up to the last
  518. dot in the name of the module being imported). If a finder can find the module
  519. it returns a :term:`loader` (discussed later) or returns :keyword:`None`.
  520. .. index::
  521. single: sys.path_hooks
  522. single: sys.path_importer_cache
  523. single: sys.path
  524. If none of the finders on :data:`sys.meta_path` are able to find the module
  525. then some implicitly defined finders are queried. Implementations of Python
  526. vary in what implicit meta path finders are defined. The one they all do
  527. define, though, is one that handles :data:`sys.path_hooks`,
  528. :data:`sys.path_importer_cache`, and :data:`sys.path`.
  529. The implicit finder searches for the requested module in the "paths" specified
  530. in one of two places ("paths" do not have to be file system paths). If the
  531. module being imported is supposed to be contained within a package then the
  532. second argument passed to :meth:`find_module`, :attr:`__path__` on the parent
  533. package, is used as the source of paths. If the module is not contained in a
  534. package then :data:`sys.path` is used as the source of paths.
  535. Once the source of paths is chosen it is iterated over to find a finder that
  536. can handle that path. The dict at :data:`sys.path_importer_cache` caches
  537. finders for paths and is checked for a finder. If the path does not have a
  538. finder cached then :data:`sys.path_hooks` is searched by calling each object in
  539. the list with a single argument of the path, returning a finder or raises
  540. :exc:`ImportError`. If a finder is returned then it is cached in
  541. :data:`sys.path_importer_cache` and then used for that path entry. If no finder
  542. can be found but the path exists then a value of :keyword:`None` is
  543. stored in :data:`sys.path_importer_cache` to signify that an implicit,
  544. file-based finder that handles modules stored as individual files should be
  545. used for that path. If the path does not exist then a finder which always
  546. returns :keyword:`None` is placed in the cache for the path.
  547. .. index::
  548. single: loader
  549. pair: loader; load_module
  550. exception: ImportError
  551. If no finder can find the module then :exc:`ImportError` is raised. Otherwise
  552. some finder returned a loader whose :meth:`load_module` method is called with
  553. the name of the module to load (see :pep:`302` for the original definition of
  554. loaders). A loader has several responsibilities to perform on a module it
  555. loads. First, if the module already exists in :data:`sys.modules` (a
  556. possibility if the loader is called outside of the import machinery) then it
  557. is to use that module for initialization and not a new module. But if the
  558. module does not exist in :data:`sys.modules` then it is to be added to that
  559. dict before initialization begins. If an error occurs during loading of the
  560. module and it was added to :data:`sys.modules` it is to be removed from the
  561. dict. If an error occurs but the module was already in :data:`sys.modules` it
  562. is left in the dict.
  563. .. index::
  564. single: __name__
  565. single: __file__
  566. single: __path__
  567. single: __package__
  568. single: __loader__
  569. The loader must set several attributes on the module. :data:`__name__` is to be
  570. set to the name of the module. :data:`__file__` is to be the "path" to the file
  571. unless the module is built-in (and thus listed in
  572. :data:`sys.builtin_module_names`) in which case the attribute is not set.
  573. If what is being imported is a package then :data:`__path__` is to be set to a
  574. list of paths to be searched when looking for modules and packages contained
  575. within the package being imported. :data:`__package__` is optional but should
  576. be set to the name of package that contains the module or package (the empty
  577. string is used for module not contained in a package). :data:`__loader__` is
  578. also optional but should be set to the loader object that is loading the
  579. module.
  580. .. index::
  581. exception: ImportError
  582. If an error occurs during loading then the loader raises :exc:`ImportError` if
  583. some other exception is not already being propagated. Otherwise the loader
  584. returns the module that was loaded and initialized.
  585. When step (1) finishes without raising an exception, step (2) can begin.
  586. The first form of :keyword:`import` statement binds the module name in the local
  587. namespace to the module object, and then goes on to import the next identifier,
  588. if any. If the module name is followed by :keyword:`as`, the name following
  589. :keyword:`as` is used as the local name for the module.
  590. .. index::
  591. pair: name; binding
  592. exception: ImportError
  593. The :keyword:`from` form does not bind the module name: it goes through the list
  594. of identifiers, looks each one of them up in the module found in step (1), and
  595. binds the name in the local namespace to the object thus found. As with the
  596. first form of :keyword:`import`, an alternate local name can be supplied by
  597. specifying ":keyword:`as` localname". If a name is not found,
  598. :exc:`ImportError` is raised. If the list of identifiers is replaced by a star
  599. (``'*'``), all public names defined in the module are bound in the local
  600. namespace of the :keyword:`import` statement..
  601. .. index:: single: __all__ (optional module attribute)
  602. The *public names* defined by a module are determined by checking the module's
  603. namespace for a variable named ``__all__``; if defined, it must be a sequence of
  604. strings which are names defined or imported by that module. The names given in
  605. ``__all__`` are all considered public and are required to exist. If ``__all__``
  606. is not defined, the set of public names includes all names found in the module's
  607. namespace which do not begin with an underscore character (``'_'``).
  608. ``__all__`` should contain the entire public API. It is intended to avoid
  609. accidentally exporting items that are not part of the API (such as library
  610. modules which were imported and used within the module).
  611. The :keyword:`from` form with ``*`` may only occur in a module scope. If the
  612. wild card form of import --- ``import *`` --- is used in a function and the
  613. function contains or is a nested block with free variables, the compiler will
  614. raise a :exc:`SyntaxError`.
  615. .. index::
  616. single: relative; import
  617. When specifying what module to import you do not have to specify the absolute
  618. name of the module. When a module or package is contained within another
  619. package it is possible to make a relative import within the same top package
  620. without having to mention the package name. By using leading dots in the
  621. specified module or package after :keyword:`from` you can specify how high to
  622. traverse up the current package hierarchy without specifying exact names. One
  623. leading dot means the current package where the module making the import
  624. exists. Two dots means up one package level. Three dots is up two levels, etc.
  625. So if you execute ``from . import mod`` from a module in the ``pkg`` package
  626. then you will end up importing ``pkg.mod``. If you execute ``from ..subpkg2
  627. imprt mod`` from within ``pkg.subpkg1`` you will import ``pkg.subpkg2.mod``.
  628. The specification for relative imports is contained within :pep:`328`.
  629. .. index:: builtin: __import__
  630. The built-in function :func:`__import__` is provided to support applications
  631. that determine which modules need to be loaded dynamically; refer to
  632. :ref:`built-in-funcs` for additional information.
  633. .. _future:
  634. Future statements
  635. -----------------
  636. .. index:: pair: future; statement
  637. A :dfn:`future statement` is a directive to the compiler that a particular
  638. module should be compiled using syntax or semantics that will be available in a
  639. specified future release of Python. The future statement is intended to ease
  640. migration to future versions of Python that introduce incompatible changes to
  641. the language. It allows use of the new features on a per-module basis before
  642. the release in which the feature becomes standard.
  643. .. productionlist:: *
  644. future_statement: "from" "__future__" "import" feature ["as" name]
  645. : ("," feature ["as" name])*
  646. : | "from" "__future__" "import" "(" feature ["as" name]
  647. : ("," feature ["as" name])* [","] ")"
  648. feature: identifier
  649. name: identifier
  650. A future statement must appear near the top of the module. The only lines that
  651. can appear before a future statement are:
  652. * the module docstring (if any),
  653. * comments,
  654. * blank lines, and
  655. * other future statements.
  656. The features recognized by Python 2.6 are ``unicode_literals``,
  657. ``print_function``, ``absolute_import``, ``division``, ``generators``,
  658. ``nested_scopes`` and ``with_statement``. ``generators``, ``with_statement``,
  659. ``nested_scopes`` are redundant in Python version 2.6 and above because they are
  660. always enabled.
  661. A future statement is recognized and treated specially at compile time: Changes
  662. to the semantics of core constructs are often implemented by generating
  663. different code. It may even be the case that a new feature introduces new
  664. incompatible syntax (such as a new reserved word), in which case the compiler
  665. may need to parse the module differently. Such decisions cannot be pushed off
  666. until runtime.
  667. For any given release, the compiler knows which feature names have been defined,
  668. and raises a compile-time error if a future statement contains a feature not
  669. known to it.
  670. The direct runtime semantics are the same as for any import statement: there is
  671. a standard module :mod:`__future__`, described later, and it will be imported in
  672. the usual way at the time the future statement is executed.
  673. The interesting runtime semantics depend on the specific feature enabled by the
  674. future statement.
  675. Note that there is nothing special about the statement::
  676. import __future__ [as name]
  677. That is not a future statement; it's an ordinary import statement with no
  678. special semantics or syntax restrictions.
  679. Code compiled by an :keyword:`exec` statement or calls to the builtin functions
  680. :func:`compile` and :func:`execfile` that occur in a module :mod:`M` containing
  681. a future statement will, by default, use the new syntax or semantics associated
  682. with the future statement. This can, starting with Python 2.2 be controlled by
  683. optional arguments to :func:`compile` --- see the documentation of that function
  684. for details.
  685. A future statement typed at an interactive interpreter prompt will take effect
  686. for the rest of the interpreter session. If an interpreter is started with the
  687. :option:`-i` option, is passed a script name to execute, and the script includes
  688. a future statement, it will be in effect in the interactive session started
  689. after the script is executed.
  690. .. seealso::
  691. :pep:`236` - Back to the __future__
  692. The original proposal for the __future__ mechanism.
  693. .. _global:
  694. The :keyword:`global` statement
  695. ===============================
  696. .. index::
  697. statement: global
  698. triple: global; name; binding
  699. .. productionlist::
  700. global_stmt: "global" `identifier` ("," `identifier`)*
  701. The :keyword:`global` statement is a declaration which holds for the entire
  702. current code block. It means that the listed identifiers are to be interpreted
  703. as globals. It would be impossible to assign to a global variable without
  704. :keyword:`global`, although free variables may refer to globals without being
  705. declared global.
  706. Names listed in a :keyword:`global` statement must not be used in the same code
  707. block textually preceding that :keyword:`global` statement.
  708. Names listed in a :keyword:`global` statement must not be defined as formal
  709. parameters or in a :keyword:`for` loop control target, :keyword:`class`
  710. definition, function definition, or :keyword:`import` statement.
  711. (The current implementation does not enforce the latter two restrictions, but
  712. programs should not abuse this freedom, as future implementations may enforce
  713. them or silently change the meaning of the program.)
  714. .. index::
  715. statement: exec
  716. builtin: eval
  717. builtin: execfile
  718. builtin: compile
  719. **Programmer's note:** the :keyword:`global` is a directive to the parser. It
  720. applies only to code parsed at the same time as the :keyword:`global` statement.
  721. In particular, a :keyword:`global` statement contained in an :keyword:`exec`
  722. statement does not affect the code block *containing* the :keyword:`exec`
  723. statement, and code contained in an :keyword:`exec` statement is unaffected by
  724. :keyword:`global` statements in the code containing the :keyword:`exec`
  725. statement. The same applies to the :func:`eval`, :func:`execfile` and
  726. :func:`compile` functions.
  727. .. _exec:
  728. The :keyword:`exec` statement
  729. =============================
  730. .. index:: statement: exec
  731. .. productionlist::
  732. exec_stmt: "exec" `or_expr` ["in" `expression` ["," `expression`]]
  733. This statement supports dynamic execution of Python code. The first expression
  734. should evaluate to either a string, an open file object, or a code object. If
  735. it is a string, the string is parsed as a suite of Python statements which is
  736. then executed (unless a syntax error occurs). [#]_ If it is an open file, the file
  737. is parsed until EOF and executed. If it is a code object, it is simply
  738. executed. In all cases, the code that's executed is expected to be valid as
  739. file input (see section :ref:`file-input`). Be aware that the
  740. :keyword:`return` and :keyword:`yield` statements may not be used outside of
  741. function definitions even within the context of code passed to the
  742. :keyword:`exec` statement.
  743. In all cases, if the optional parts are omitted, the code is executed in the
  744. current scope. If only the first expression after :keyword:`in` is specified,
  745. it should be a dictionary, which will be used for both the global and the local
  746. variables. If two expressions are given, they are used for the global and local
  747. variables, respectively. If provided, *locals* can be any mapping object.
  748. .. versionchanged:: 2.4
  749. Formerly, *locals* was required to be a dictionary.
  750. .. index::
  751. single: __builtins__
  752. module: __builtin__
  753. As a side effect, an implementation may insert additional keys into the
  754. dictionaries given besides those corresponding to variable names set by the
  755. executed code. For example, the current implementation may add a reference to
  756. the dictionary of the built-in module :mod:`__builtin__` under the key
  757. ``__builtins__`` (!).
  758. .. index::
  759. builtin: eval
  760. builtin: globals
  761. builtin: locals
  762. **Programmer's hints:** dynamic evaluation of expressions is supported by the
  763. built-in function :func:`eval`. The built-in functions :func:`globals` and
  764. :func:`locals` return the current global and local dictionary, respectively,
  765. which may be useful to pass around for use by :keyword:`exec`.
  766. .. rubric:: Footnotes
  767. .. [#] Note that the parser only accepts the Unix-style end of line convention.
  768. If you are reading the code from a file, make sure to use universal
  769. newline mode to convert Windows or Mac-style newlines.