Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(21634)

Side by Side Diff: Doc/reference/expressions.rst

Issue 11682: PEP 380 reference implementation for 3.3
Patch Set: Created 7 years, 4 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
OLDNEW
1 1
2 .. _expressions: 2 .. _expressions:
3 3
4 *********** 4 ***********
5 Expressions 5 Expressions
6 *********** 6 ***********
7 7
8 .. index:: expression, BNF 8 .. index:: expression, BNF
9 9
10 This chapter explains the meaning of the elements of expressions in Python. 10 This chapter explains the meaning of the elements of expressions in Python.
(...skipping 300 matching lines...) Expand 10 before | Expand all | Expand 10 after
311 Yield expressions 311 Yield expressions
312 ----------------- 312 -----------------
313 313
314 .. index:: 314 .. index::
315 keyword: yield 315 keyword: yield
316 pair: yield; expression 316 pair: yield; expression
317 pair: generator; function 317 pair: generator; function
318 318
319 .. productionlist:: 319 .. productionlist::
320 yield_atom: "(" `yield_expression` ")" 320 yield_atom: "(" `yield_expression` ")"
321 yield_expression: "yield" [`expression_list`] 321 yield_expression: "yield" [`expression_list` | "from" `expression`]
322 322
323 The :keyword:`yield` expression is only used when defining a generator function, 323 The :keyword:`yield` expression is only used when defining a generator function,
324 and can only be used in the body of a function definition. Using a 324 and can only be used in the body of a function definition. Using a
325 :keyword:`yield` expression in a function definition is sufficient to cause that 325 :keyword:`yield` expression in a function definition is sufficient to cause that
326 definition to create a generator function instead of a normal function. 326 definition to create a generator function instead of a normal function.
327 327
328 When a generator function is called, it returns an iterator known as a 328 When a generator function is called, it returns an iterator known as a
329 generator. That generator then controls the execution of a generator function. 329 generator. That generator then controls the execution of a generator function.
330 The execution starts when one of the generator's methods is called. At that 330 The execution starts when one of the generator's methods is called. At that
331 time, the execution proceeds to the first :keyword:`yield` expression, where it 331 time, the execution proceeds to the first :keyword:`yield` expression, where it
332 is suspended again, returning the value of :token:`expression_list` to 332 is suspended again, returning the value of :token:`expression_list` to
333 generator's caller. By suspended we mean that all local state is retained, 333 generator's caller. By suspended we mean that all local state is retained,
334 including the current bindings of local variables, the instruction pointer, and 334 including the current bindings of local variables, the instruction pointer, and
335 the internal evaluation stack. When the execution is resumed by calling one of 335 the internal evaluation stack. When the execution is resumed by calling one of
336 the generator's methods, the function can proceed exactly as if the 336 the generator's methods, the function can proceed exactly as if the
337 :keyword:`yield` expression was just another external call. The value of the 337 :keyword:`yield` expression was just another external call. The value of the
338 :keyword:`yield` expression after resuming depends on the method which resumed 338 :keyword:`yield` expression after resuming depends on the method which resumed
339 the execution. 339 the execution. If :meth:`__next__` is used (typically via either a
340 :keyword:`for` or the :func:`next` builtin) then the result is :const:`None`,
341 otherwise, if :meth:`send` is used, then the result will be the value passed
342 in to that method.
340 343
341 .. index:: single: coroutine 344 .. index:: single: coroutine
342 345
343 All of this makes generator functions quite similar to coroutines; they yield 346 All of this makes generator functions quite similar to coroutines; they yield
344 multiple times, they have more than one entry point and their execution can be 347 multiple times, they have more than one entry point and their execution can be
345 suspended. The only difference is that a generator function cannot control 348 suspended. The only difference is that a generator function cannot control
346 where should the execution continue after it yields; the control is always 349 where should the execution continue after it yields; the control is always
347 transferred to the generator's caller. 350 transferred to the generator's caller.
348 351
349 The :keyword:`yield` statement is allowed in the :keyword:`try` clause of a 352 :keyword:`yield` expressions are allowed in the :keyword:`try` clause of a
350 :keyword:`try` ... :keyword:`finally` construct. If the generator is not 353 :keyword:`try` ... :keyword:`finally` construct. If the generator is not
351 resumed before it is finalized (by reaching a zero reference count or by being 354 resumed before it is finalized (by reaching a zero reference count or by being
352 garbage collected), the generator-iterator's :meth:`close` method will be 355 garbage collected), the generator-iterator's :meth:`close` method will be
353 called, allowing any pending :keyword:`finally` clauses to execute. 356 called, allowing any pending :keyword:`finally` clauses to execute.
354 357
358 When ``yield from expression`` is used, it treats the supplied expression as
359 a subiterator. All values produced by that subiterator are passed directly
360 to the caller of the current generator's methods. Any values passed in with
361 :meth:`send` and any exceptions passed in with :meth:`throw` are passed to
362 the underlying iterator if it has the appropriate methods. If this is not the
363 case, then :meth:`send` will raise :exc:`AttributeError` or :exc:`TypeError`,
364 while :meth:`throw` will just raise the passed in exception immediately.
365
366 When the underlying iterator is complete, the :attr:`~StopIteration.value`
367 attribute of the raised :exc:`StopIteration` instance becomes the value of
368 the yield expression. It can be either set explicitly when raising
369 :exc:`StopIteration`, or automatically when the sub-iterator is a generator
370 (by returning a value from the sub-generator).
371
372 The parentheses can be omitted when the :keyword:`yield` expression is the
373 sole expression on the right hand side of an assignment statement.
374
355 .. index:: object: generator 375 .. index:: object: generator
356 376
357 The following generator's methods can be used to control the execution of a 377 The following generator's methods can be used to control the execution of a
358 generator function: 378 generator function:
359 379
360 .. index:: exception: StopIteration 380 .. index:: exception: StopIteration
361 381
362 382
363 .. method:: generator.__next__() 383 .. method:: generator.__next__()
364 384
(...skipping 71 matching lines...) Expand 10 before | Expand all | Expand 10 after
436 456
437 457
438 .. seealso:: 458 .. seealso::
439 459
440 :pep:`0255` - Simple Generators 460 :pep:`0255` - Simple Generators
441 The proposal for adding generators and the :keyword:`yield` statement to P ython. 461 The proposal for adding generators and the :keyword:`yield` statement to P ython.
442 462
443 :pep:`0342` - Coroutines via Enhanced Generators 463 :pep:`0342` - Coroutines via Enhanced Generators
444 The proposal to enhance the API and syntax of generators, making them 464 The proposal to enhance the API and syntax of generators, making them
445 usable as simple coroutines. 465 usable as simple coroutines.
466
467 :pep:`0380` - Syntax for Delegating to a Subgenerator
468 The proposal to introduce the :token:`yield_from` syntax, making delegatio n
469 to sub-generators easy.
446 470
447 471
448 .. _primaries: 472 .. _primaries:
449 473
450 Primaries 474 Primaries
451 ========= 475 =========
452 476
453 .. index:: single: primary 477 .. index:: single: primary
454 478
455 Primaries represent the most tightly bound operations of the language. Their 479 Primaries represent the most tightly bound operations of the language. Their
(...skipping 892 matching lines...) Expand 10 before | Expand all | Expand 10 after
1348 .. [#] Due to automatic garbage-collection, free lists, and the dynamic nature o f 1372 .. [#] Due to automatic garbage-collection, free lists, and the dynamic nature o f
1349 descriptors, you may notice seemingly unusual behaviour in certain uses of 1373 descriptors, you may notice seemingly unusual behaviour in certain uses of
1350 the :keyword:`is` operator, like those involving comparisons between instance 1374 the :keyword:`is` operator, like those involving comparisons between instance
1351 methods, or constants. Check their documentation for more info. 1375 methods, or constants. Check their documentation for more info.
1352 1376
1353 .. [#] The ``%`` operator is also used for string formatting; the same 1377 .. [#] The ``%`` operator is also used for string formatting; the same
1354 precedence applies. 1378 precedence applies.
1355 1379
1356 .. [#] The power operator ``**`` binds less tightly than an arithmetic or 1380 .. [#] The power operator ``**`` binds less tightly than an arithmetic or
1357 bitwise unary operator on its right, that is, ``2**-1`` is ``0.5``. 1381 bitwise unary operator on its right, that is, ``2**-1`` is ``0.5``.
OLDNEW

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+