cpython/Doc/tutorial/controlflow.rst

941 lines
32 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:22 -03:00
.. _tut-morecontrol:
***********************
More Control Flow Tools
***********************
Besides the :keyword:`while` statement just introduced, Python uses the usual
flow control statements known from other languages, with some twists.
2007-08-15 11:28:22 -03:00
.. _tut-if:
:keyword:`!if` Statements
=========================
2007-08-15 11:28:22 -03:00
Perhaps the most well-known statement type is the :keyword:`if` statement. For
example::
>>> x = int(input("Please enter an integer: "))
2008-09-13 14:18:21 -03:00
Please enter an integer: 42
2007-08-15 11:28:22 -03:00
>>> if x < 0:
2013-11-17 16:07:48 -04:00
... x = 0
... print('Negative changed to zero')
2007-08-15 11:28:22 -03:00
... elif x == 0:
2013-11-17 16:07:48 -04:00
... print('Zero')
2007-08-15 11:28:22 -03:00
... elif x == 1:
2013-11-17 16:07:48 -04:00
... print('Single')
2007-08-15 11:28:22 -03:00
... else:
2013-11-17 16:07:48 -04:00
... print('More')
2008-09-13 14:18:21 -03:00
...
More
2007-08-15 11:28:22 -03:00
There can be zero or more :keyword:`elif` parts, and the :keyword:`else` part is
optional. The keyword ':keyword:`!elif`' is short for 'else if', and is useful
to avoid excessive indentation. An :keyword:`!if` ... :keyword:`!elif` ...
:keyword:`!elif` ... sequence is a substitute for the ``switch`` or
``case`` statements found in other languages.
2007-08-15 11:28:22 -03:00
.. _tut-for:
:keyword:`!for` Statements
==========================
2007-08-15 11:28:22 -03:00
.. index::
statement: for
The :keyword:`for` statement in Python differs a bit from what you may be used
to in C or Pascal. Rather than always iterating over an arithmetic progression
of numbers (like in Pascal), or giving the user the ability to define both the
iteration step and halting condition (as C), Python's :keyword:`!for` statement
2007-08-15 11:28:22 -03:00
iterates over the items of any sequence (a list or a string), in the order that
they appear in the sequence. For example (no pun intended):
.. One suggestion was to give a real C example here, but that may only serve to
confuse non-C programmers.
2007-08-15 11:28:22 -03:00
::
>>> # Measure some strings:
... words = ['cat', 'window', 'defenestrate']
>>> for w in words:
... print(w, len(w))
2009-01-03 17:18:54 -04:00
...
2007-08-15 11:28:22 -03:00
cat 3
window 6
defenestrate 12
Code that modifies a collection while iterating over that same collection can
be tricky to get right. Instead, it is usually more straight-forward to loop
over a copy of the collection or to create a new collection::
# Strategy: Iterate over a copy
for user, status in users.copy().items():
if status == 'inactive':
del users[user]
# Strategy: Create a new collection
active_users = {}
for user, status in users.items():
if status == 'active':
active_users[user] = status
2016-02-15 12:50:33 -04:00
2007-08-15 11:28:22 -03:00
.. _tut-range:
The :func:`range` Function
==========================
If you do need to iterate over a sequence of numbers, the built-in function
:func:`range` comes in handy. It generates arithmetic progressions::
>>> for i in range(5):
... print(i)
...
0
1
2
3
4
2009-01-03 17:18:54 -04:00
2010-06-27 07:59:19 -03:00
The given end point is never part of the generated sequence; ``range(10)`` generates
10 values, the legal indices for items of a sequence of length 10. It
2007-08-15 11:28:22 -03:00
is possible to let the range start at another number, or to specify a different
increment (even negative; sometimes this is called the 'step')::
2009-01-03 17:18:54 -04:00
range(5, 10)
5, 6, 7, 8, 9
2009-01-03 17:18:54 -04:00
range(0, 10, 3)
0, 3, 6, 9
2009-01-03 17:18:54 -04:00
range(-10, -100, -30)
-10, -40, -70
2007-08-15 11:28:22 -03:00
Merged revisions 67531-67532,67538,67553-67554,67556-67557,67571,67574-67575,67579-67580,67591,67597,67608,67631 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67531 | georg.brandl | 2008-12-04 19:54:05 +0100 (Thu, 04 Dec 2008) | 2 lines Add reference to enumerate() to indices example. ........ r67532 | georg.brandl | 2008-12-04 19:59:16 +0100 (Thu, 04 Dec 2008) | 2 lines Add another heapq example. ........ r67538 | georg.brandl | 2008-12-04 22:28:16 +0100 (Thu, 04 Dec 2008) | 2 lines Clarification to avoid confusing output with file descriptors. ........ r67553 | georg.brandl | 2008-12-05 08:49:49 +0100 (Fri, 05 Dec 2008) | 2 lines #4408: document regex.groups. ........ r67554 | georg.brandl | 2008-12-05 08:52:26 +0100 (Fri, 05 Dec 2008) | 2 lines #4409: fix asterisks looking like footnotes. ........ r67556 | georg.brandl | 2008-12-05 09:02:17 +0100 (Fri, 05 Dec 2008) | 2 lines #4441: improve doc for os.open() flags. ........ r67557 | georg.brandl | 2008-12-05 09:06:57 +0100 (Fri, 05 Dec 2008) | 2 lines Add an index entry for "subclassing immutable types". ........ r67571 | georg.brandl | 2008-12-05 10:13:45 +0100 (Fri, 05 Dec 2008) | 2 lines Use markup. ........ r67574 | georg.brandl | 2008-12-05 10:25:32 +0100 (Fri, 05 Dec 2008) | 2 lines #4441 followup: Add link to open() docs for Windows. ........ r67575 | georg.brandl | 2008-12-05 12:34:51 +0100 (Fri, 05 Dec 2008) | 2 lines #4544: add `dedent` to textwrap.__all__. ........ r67579 | georg.brandl | 2008-12-05 16:29:39 +0100 (Fri, 05 Dec 2008) | 2 lines #4517: add "special method" glossary entry and clarify when __getattribute__ is bypassed. ........ r67580 | georg.brandl | 2008-12-05 16:32:29 +0100 (Fri, 05 Dec 2008) | 2 lines #4478: document that copyfile() can raise Error. ........ r67591 | georg.brandl | 2008-12-05 19:00:06 +0100 (Fri, 05 Dec 2008) | 2 lines Followup to #4511: add link from decorator glossary entry to definition. ........ r67597 | georg.brandl | 2008-12-05 20:03:19 +0100 (Fri, 05 Dec 2008) | 2 lines Remove confusing sentence part. ........ r67608 | georg.brandl | 2008-12-06 12:57:12 +0100 (Sat, 06 Dec 2008) | 2 lines Follow-up to #4488: document PIPE and STDOUT properly. ........ r67631 | georg.brandl | 2008-12-07 12:54:07 +0100 (Sun, 07 Dec 2008) | 2 lines Add link to the favicon to the docs. ........
2008-12-07 11:06:20 -04:00
To iterate over the indices of a sequence, you can combine :func:`range` and
:func:`len` as follows::
2007-08-15 11:28:22 -03:00
>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
>>> for i in range(len(a)):
... print(i, a[i])
2009-01-03 17:18:54 -04:00
...
2007-08-15 11:28:22 -03:00
0 Mary
1 had
2 a
3 little
4 lamb
Merged revisions 67531-67532,67538,67553-67554,67556-67557,67571,67574-67575,67579-67580,67591,67597,67608,67631 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67531 | georg.brandl | 2008-12-04 19:54:05 +0100 (Thu, 04 Dec 2008) | 2 lines Add reference to enumerate() to indices example. ........ r67532 | georg.brandl | 2008-12-04 19:59:16 +0100 (Thu, 04 Dec 2008) | 2 lines Add another heapq example. ........ r67538 | georg.brandl | 2008-12-04 22:28:16 +0100 (Thu, 04 Dec 2008) | 2 lines Clarification to avoid confusing output with file descriptors. ........ r67553 | georg.brandl | 2008-12-05 08:49:49 +0100 (Fri, 05 Dec 2008) | 2 lines #4408: document regex.groups. ........ r67554 | georg.brandl | 2008-12-05 08:52:26 +0100 (Fri, 05 Dec 2008) | 2 lines #4409: fix asterisks looking like footnotes. ........ r67556 | georg.brandl | 2008-12-05 09:02:17 +0100 (Fri, 05 Dec 2008) | 2 lines #4441: improve doc for os.open() flags. ........ r67557 | georg.brandl | 2008-12-05 09:06:57 +0100 (Fri, 05 Dec 2008) | 2 lines Add an index entry for "subclassing immutable types". ........ r67571 | georg.brandl | 2008-12-05 10:13:45 +0100 (Fri, 05 Dec 2008) | 2 lines Use markup. ........ r67574 | georg.brandl | 2008-12-05 10:25:32 +0100 (Fri, 05 Dec 2008) | 2 lines #4441 followup: Add link to open() docs for Windows. ........ r67575 | georg.brandl | 2008-12-05 12:34:51 +0100 (Fri, 05 Dec 2008) | 2 lines #4544: add `dedent` to textwrap.__all__. ........ r67579 | georg.brandl | 2008-12-05 16:29:39 +0100 (Fri, 05 Dec 2008) | 2 lines #4517: add "special method" glossary entry and clarify when __getattribute__ is bypassed. ........ r67580 | georg.brandl | 2008-12-05 16:32:29 +0100 (Fri, 05 Dec 2008) | 2 lines #4478: document that copyfile() can raise Error. ........ r67591 | georg.brandl | 2008-12-05 19:00:06 +0100 (Fri, 05 Dec 2008) | 2 lines Followup to #4511: add link from decorator glossary entry to definition. ........ r67597 | georg.brandl | 2008-12-05 20:03:19 +0100 (Fri, 05 Dec 2008) | 2 lines Remove confusing sentence part. ........ r67608 | georg.brandl | 2008-12-06 12:57:12 +0100 (Sat, 06 Dec 2008) | 2 lines Follow-up to #4488: document PIPE and STDOUT properly. ........ r67631 | georg.brandl | 2008-12-07 12:54:07 +0100 (Sun, 07 Dec 2008) | 2 lines Add link to the favicon to the docs. ........
2008-12-07 11:06:20 -04:00
In most such cases, however, it is convenient to use the :func:`enumerate`
function, see :ref:`tut-loopidioms`.
A strange thing happens if you just print a range::
>>> print(range(10))
range(0, 10)
In many ways the object returned by :func:`range` behaves as if it is a list,
2009-01-03 17:18:54 -04:00
but in fact it isn't. It is an object which returns the successive items of
the desired sequence when you iterate over it, but it doesn't really make
the list, thus saving space.
We say such an object is :term:`iterable`, that is, suitable as a target for
2009-01-03 17:18:54 -04:00
functions and constructs that expect something from which they can
obtain successive items until the supply is exhausted. We have seen that
the :keyword:`for` statement is such a construct, while an example of function
that takes an iterable is :func:`sum`::
>>> sum(range(4)) # 0 + 1 + 2 + 3
6
Later we will see more functions that return iterables and take iterables as
arguments. Lastly, maybe you are curious about how to get a list from a range.
Here is the solution::
>>> list(range(4))
[0, 1, 2, 3]
2007-08-15 11:28:22 -03:00
In chapter :ref:`tut-structures`, we will discuss in more detail about
:func:`list`.
Merged revisions 67531-67532,67538,67553-67554,67556-67557,67571,67574-67575,67579-67580,67591,67597,67608,67631 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67531 | georg.brandl | 2008-12-04 19:54:05 +0100 (Thu, 04 Dec 2008) | 2 lines Add reference to enumerate() to indices example. ........ r67532 | georg.brandl | 2008-12-04 19:59:16 +0100 (Thu, 04 Dec 2008) | 2 lines Add another heapq example. ........ r67538 | georg.brandl | 2008-12-04 22:28:16 +0100 (Thu, 04 Dec 2008) | 2 lines Clarification to avoid confusing output with file descriptors. ........ r67553 | georg.brandl | 2008-12-05 08:49:49 +0100 (Fri, 05 Dec 2008) | 2 lines #4408: document regex.groups. ........ r67554 | georg.brandl | 2008-12-05 08:52:26 +0100 (Fri, 05 Dec 2008) | 2 lines #4409: fix asterisks looking like footnotes. ........ r67556 | georg.brandl | 2008-12-05 09:02:17 +0100 (Fri, 05 Dec 2008) | 2 lines #4441: improve doc for os.open() flags. ........ r67557 | georg.brandl | 2008-12-05 09:06:57 +0100 (Fri, 05 Dec 2008) | 2 lines Add an index entry for "subclassing immutable types". ........ r67571 | georg.brandl | 2008-12-05 10:13:45 +0100 (Fri, 05 Dec 2008) | 2 lines Use markup. ........ r67574 | georg.brandl | 2008-12-05 10:25:32 +0100 (Fri, 05 Dec 2008) | 2 lines #4441 followup: Add link to open() docs for Windows. ........ r67575 | georg.brandl | 2008-12-05 12:34:51 +0100 (Fri, 05 Dec 2008) | 2 lines #4544: add `dedent` to textwrap.__all__. ........ r67579 | georg.brandl | 2008-12-05 16:29:39 +0100 (Fri, 05 Dec 2008) | 2 lines #4517: add "special method" glossary entry and clarify when __getattribute__ is bypassed. ........ r67580 | georg.brandl | 2008-12-05 16:32:29 +0100 (Fri, 05 Dec 2008) | 2 lines #4478: document that copyfile() can raise Error. ........ r67591 | georg.brandl | 2008-12-05 19:00:06 +0100 (Fri, 05 Dec 2008) | 2 lines Followup to #4511: add link from decorator glossary entry to definition. ........ r67597 | georg.brandl | 2008-12-05 20:03:19 +0100 (Fri, 05 Dec 2008) | 2 lines Remove confusing sentence part. ........ r67608 | georg.brandl | 2008-12-06 12:57:12 +0100 (Sat, 06 Dec 2008) | 2 lines Follow-up to #4488: document PIPE and STDOUT properly. ........ r67631 | georg.brandl | 2008-12-07 12:54:07 +0100 (Sun, 07 Dec 2008) | 2 lines Add link to the favicon to the docs. ........
2008-12-07 11:06:20 -04:00
2007-08-15 11:28:22 -03:00
.. _tut-break:
:keyword:`!break` and :keyword:`!continue` Statements, and :keyword:`!else` Clauses on Loops
============================================================================================
2007-08-15 11:28:22 -03:00
The :keyword:`break` statement, like in C, breaks out of the innermost enclosing
2007-08-15 11:28:22 -03:00
:keyword:`for` or :keyword:`while` loop.
Loop statements may have an :keyword:`!else` clause; it is executed when the loop
terminates through exhaustion of the iterable (with :keyword:`for`) or when the
2007-08-15 11:28:22 -03:00
condition becomes false (with :keyword:`while`), but not when the loop is
terminated by a :keyword:`break` statement. This is exemplified by the
following loop, which searches for prime numbers::
>>> for n in range(2, 10):
... for x in range(2, n):
... if n % x == 0:
2008-05-01 15:06:50 -03:00
... print(n, 'equals', x, '*', n//x)
2007-08-15 11:28:22 -03:00
... break
... else:
... # loop fell through without finding a factor
... print(n, 'is a prime number')
2009-01-03 17:18:54 -04:00
...
2007-08-15 11:28:22 -03:00
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3
(Yes, this is the correct code. Look closely: the ``else`` clause belongs to
the :keyword:`for` loop, **not** the :keyword:`if` statement.)
When used with a loop, the ``else`` clause has more in common with the
``else`` clause of a :keyword:`try` statement than it does with that of
:keyword:`if` statements: a :keyword:`try` statement's ``else`` clause runs
when no exception occurs, and a loop's ``else`` clause runs when no ``break``
occurs. For more on the :keyword:`!try` statement and exceptions, see
:ref:`tut-handling`.
The :keyword:`continue` statement, also borrowed from C, continues with the next
iteration of the loop::
>>> for num in range(2, 10):
2012-08-18 03:50:09 -03:00
... if num % 2 == 0:
... print("Found an even number", num)
... continue
... print("Found a number", num)
Found an even number 2
Found a number 3
Found an even number 4
Found a number 5
Found an even number 6
Found a number 7
Found an even number 8
Found a number 9
2007-08-15 11:28:22 -03:00
.. _tut-pass:
:keyword:`!pass` Statements
===========================
2007-08-15 11:28:22 -03:00
The :keyword:`pass` statement does nothing. It can be used when a statement is
required syntactically but the program requires no action. For example::
>>> while True:
2008-09-13 14:18:21 -03:00
... pass # Busy-wait for keyboard interrupt (Ctrl+C)
2009-01-03 17:18:54 -04:00
...
2007-08-15 11:28:22 -03:00
Merged revisions 67889-67892,67895,67898,67904-67907,67912,67918,67920-67921,67923-67924,67926-67927,67930,67943 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ................ r67889 | benjamin.peterson | 2008-12-20 19:04:32 -0600 (Sat, 20 Dec 2008) | 1 line sphinx.web is long gone ................ r67890 | benjamin.peterson | 2008-12-20 19:12:26 -0600 (Sat, 20 Dec 2008) | 1 line update readme ................ r67891 | benjamin.peterson | 2008-12-20 19:14:47 -0600 (Sat, 20 Dec 2008) | 1 line there are way too many places which need to have the current version added ................ r67892 | benjamin.peterson | 2008-12-20 19:29:32 -0600 (Sat, 20 Dec 2008) | 9 lines Merged revisions 67809 via svnmerge from svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3 ........ r67809 | benjamin.peterson | 2008-12-15 21:54:45 -0600 (Mon, 15 Dec 2008) | 1 line fix logic error ........ ................ r67895 | neal.norwitz | 2008-12-21 08:28:32 -0600 (Sun, 21 Dec 2008) | 2 lines Add Tarek for work on distutils. ................ r67898 | benjamin.peterson | 2008-12-21 15:00:53 -0600 (Sun, 21 Dec 2008) | 1 line compute DISTVERSION with patchlevel.py ................ r67904 | benjamin.peterson | 2008-12-22 14:44:58 -0600 (Mon, 22 Dec 2008) | 1 line less attitude ................ r67905 | benjamin.peterson | 2008-12-22 14:51:15 -0600 (Mon, 22 Dec 2008) | 1 line fix #4720: the format to PyArg_ParseTupleAndKeywords can now start with '|' ................ r67906 | benjamin.peterson | 2008-12-22 14:52:53 -0600 (Mon, 22 Dec 2008) | 1 line add NEWS note ................ r67907 | benjamin.peterson | 2008-12-22 16:12:19 -0600 (Mon, 22 Dec 2008) | 1 line silence compiler warning ................ r67912 | georg.brandl | 2008-12-23 06:37:21 -0600 (Tue, 23 Dec 2008) | 2 lines Fix missing "svn" command. ................ r67918 | georg.brandl | 2008-12-23 09:44:25 -0600 (Tue, 23 Dec 2008) | 2 lines Markup fix. ................ r67920 | benjamin.peterson | 2008-12-23 14:09:28 -0600 (Tue, 23 Dec 2008) | 1 line use a global variable, so the compiler doesn't optimize the assignment out ................ r67921 | benjamin.peterson | 2008-12-23 14:12:33 -0600 (Tue, 23 Dec 2008) | 1 line make global static ................ r67923 | benjamin.peterson | 2008-12-24 09:10:27 -0600 (Wed, 24 Dec 2008) | 1 line #4736 BufferRWPair.closed shouldn't try to call another property as a function ................ r67924 | benjamin.peterson | 2008-12-24 10:10:05 -0600 (Wed, 24 Dec 2008) | 1 line pretend exceptions don't exist a while longer ................ r67926 | tarek.ziade | 2008-12-24 13:10:05 -0600 (Wed, 24 Dec 2008) | 1 line fixed #4400 : distutils .pypirc default generated file was broken. ................ r67927 | benjamin.peterson | 2008-12-26 17:26:30 -0600 (Fri, 26 Dec 2008) | 1 line python version is included in file name now ................ r67930 | hirokazu.yamamoto | 2008-12-26 22:19:48 -0600 (Fri, 26 Dec 2008) | 2 lines Issue #4740: Use HIGHEST_PROTOCOL in pickle test. (There is no behavior difference in 2.x because HIGHEST_PROTOCOL == 2) ................ r67943 | alexandre.vassalotti | 2008-12-27 04:02:59 -0600 (Sat, 27 Dec 2008) | 2 lines Fix bogus unicode tests in pickletester. ................
2008-12-27 12:00:54 -04:00
This is commonly used for creating minimal classes::
Merged revisions 67889-67892,67895,67898,67904-67907,67912,67918,67920-67921,67923-67924,67926-67927,67930,67943 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ................ r67889 | benjamin.peterson | 2008-12-20 19:04:32 -0600 (Sat, 20 Dec 2008) | 1 line sphinx.web is long gone ................ r67890 | benjamin.peterson | 2008-12-20 19:12:26 -0600 (Sat, 20 Dec 2008) | 1 line update readme ................ r67891 | benjamin.peterson | 2008-12-20 19:14:47 -0600 (Sat, 20 Dec 2008) | 1 line there are way too many places which need to have the current version added ................ r67892 | benjamin.peterson | 2008-12-20 19:29:32 -0600 (Sat, 20 Dec 2008) | 9 lines Merged revisions 67809 via svnmerge from svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3 ........ r67809 | benjamin.peterson | 2008-12-15 21:54:45 -0600 (Mon, 15 Dec 2008) | 1 line fix logic error ........ ................ r67895 | neal.norwitz | 2008-12-21 08:28:32 -0600 (Sun, 21 Dec 2008) | 2 lines Add Tarek for work on distutils. ................ r67898 | benjamin.peterson | 2008-12-21 15:00:53 -0600 (Sun, 21 Dec 2008) | 1 line compute DISTVERSION with patchlevel.py ................ r67904 | benjamin.peterson | 2008-12-22 14:44:58 -0600 (Mon, 22 Dec 2008) | 1 line less attitude ................ r67905 | benjamin.peterson | 2008-12-22 14:51:15 -0600 (Mon, 22 Dec 2008) | 1 line fix #4720: the format to PyArg_ParseTupleAndKeywords can now start with '|' ................ r67906 | benjamin.peterson | 2008-12-22 14:52:53 -0600 (Mon, 22 Dec 2008) | 1 line add NEWS note ................ r67907 | benjamin.peterson | 2008-12-22 16:12:19 -0600 (Mon, 22 Dec 2008) | 1 line silence compiler warning ................ r67912 | georg.brandl | 2008-12-23 06:37:21 -0600 (Tue, 23 Dec 2008) | 2 lines Fix missing "svn" command. ................ r67918 | georg.brandl | 2008-12-23 09:44:25 -0600 (Tue, 23 Dec 2008) | 2 lines Markup fix. ................ r67920 | benjamin.peterson | 2008-12-23 14:09:28 -0600 (Tue, 23 Dec 2008) | 1 line use a global variable, so the compiler doesn't optimize the assignment out ................ r67921 | benjamin.peterson | 2008-12-23 14:12:33 -0600 (Tue, 23 Dec 2008) | 1 line make global static ................ r67923 | benjamin.peterson | 2008-12-24 09:10:27 -0600 (Wed, 24 Dec 2008) | 1 line #4736 BufferRWPair.closed shouldn't try to call another property as a function ................ r67924 | benjamin.peterson | 2008-12-24 10:10:05 -0600 (Wed, 24 Dec 2008) | 1 line pretend exceptions don't exist a while longer ................ r67926 | tarek.ziade | 2008-12-24 13:10:05 -0600 (Wed, 24 Dec 2008) | 1 line fixed #4400 : distutils .pypirc default generated file was broken. ................ r67927 | benjamin.peterson | 2008-12-26 17:26:30 -0600 (Fri, 26 Dec 2008) | 1 line python version is included in file name now ................ r67930 | hirokazu.yamamoto | 2008-12-26 22:19:48 -0600 (Fri, 26 Dec 2008) | 2 lines Issue #4740: Use HIGHEST_PROTOCOL in pickle test. (There is no behavior difference in 2.x because HIGHEST_PROTOCOL == 2) ................ r67943 | alexandre.vassalotti | 2008-12-27 04:02:59 -0600 (Sat, 27 Dec 2008) | 2 lines Fix bogus unicode tests in pickletester. ................
2008-12-27 12:00:54 -04:00
>>> class MyEmptyClass:
... pass
Merged revisions 67889-67892,67895,67898,67904-67907,67912,67918,67920-67921,67923-67924,67926-67927,67930,67943 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ................ r67889 | benjamin.peterson | 2008-12-20 19:04:32 -0600 (Sat, 20 Dec 2008) | 1 line sphinx.web is long gone ................ r67890 | benjamin.peterson | 2008-12-20 19:12:26 -0600 (Sat, 20 Dec 2008) | 1 line update readme ................ r67891 | benjamin.peterson | 2008-12-20 19:14:47 -0600 (Sat, 20 Dec 2008) | 1 line there are way too many places which need to have the current version added ................ r67892 | benjamin.peterson | 2008-12-20 19:29:32 -0600 (Sat, 20 Dec 2008) | 9 lines Merged revisions 67809 via svnmerge from svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3 ........ r67809 | benjamin.peterson | 2008-12-15 21:54:45 -0600 (Mon, 15 Dec 2008) | 1 line fix logic error ........ ................ r67895 | neal.norwitz | 2008-12-21 08:28:32 -0600 (Sun, 21 Dec 2008) | 2 lines Add Tarek for work on distutils. ................ r67898 | benjamin.peterson | 2008-12-21 15:00:53 -0600 (Sun, 21 Dec 2008) | 1 line compute DISTVERSION with patchlevel.py ................ r67904 | benjamin.peterson | 2008-12-22 14:44:58 -0600 (Mon, 22 Dec 2008) | 1 line less attitude ................ r67905 | benjamin.peterson | 2008-12-22 14:51:15 -0600 (Mon, 22 Dec 2008) | 1 line fix #4720: the format to PyArg_ParseTupleAndKeywords can now start with '|' ................ r67906 | benjamin.peterson | 2008-12-22 14:52:53 -0600 (Mon, 22 Dec 2008) | 1 line add NEWS note ................ r67907 | benjamin.peterson | 2008-12-22 16:12:19 -0600 (Mon, 22 Dec 2008) | 1 line silence compiler warning ................ r67912 | georg.brandl | 2008-12-23 06:37:21 -0600 (Tue, 23 Dec 2008) | 2 lines Fix missing "svn" command. ................ r67918 | georg.brandl | 2008-12-23 09:44:25 -0600 (Tue, 23 Dec 2008) | 2 lines Markup fix. ................ r67920 | benjamin.peterson | 2008-12-23 14:09:28 -0600 (Tue, 23 Dec 2008) | 1 line use a global variable, so the compiler doesn't optimize the assignment out ................ r67921 | benjamin.peterson | 2008-12-23 14:12:33 -0600 (Tue, 23 Dec 2008) | 1 line make global static ................ r67923 | benjamin.peterson | 2008-12-24 09:10:27 -0600 (Wed, 24 Dec 2008) | 1 line #4736 BufferRWPair.closed shouldn't try to call another property as a function ................ r67924 | benjamin.peterson | 2008-12-24 10:10:05 -0600 (Wed, 24 Dec 2008) | 1 line pretend exceptions don't exist a while longer ................ r67926 | tarek.ziade | 2008-12-24 13:10:05 -0600 (Wed, 24 Dec 2008) | 1 line fixed #4400 : distutils .pypirc default generated file was broken. ................ r67927 | benjamin.peterson | 2008-12-26 17:26:30 -0600 (Fri, 26 Dec 2008) | 1 line python version is included in file name now ................ r67930 | hirokazu.yamamoto | 2008-12-26 22:19:48 -0600 (Fri, 26 Dec 2008) | 2 lines Issue #4740: Use HIGHEST_PROTOCOL in pickle test. (There is no behavior difference in 2.x because HIGHEST_PROTOCOL == 2) ................ r67943 | alexandre.vassalotti | 2008-12-27 04:02:59 -0600 (Sat, 27 Dec 2008) | 2 lines Fix bogus unicode tests in pickletester. ................
2008-12-27 12:00:54 -04:00
...
Another place :keyword:`pass` can be used is as a place-holder for a function or
Merged revisions 67889-67892,67895,67898,67904-67907,67912,67918,67920-67921,67923-67924,67926-67927,67930,67943 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ................ r67889 | benjamin.peterson | 2008-12-20 19:04:32 -0600 (Sat, 20 Dec 2008) | 1 line sphinx.web is long gone ................ r67890 | benjamin.peterson | 2008-12-20 19:12:26 -0600 (Sat, 20 Dec 2008) | 1 line update readme ................ r67891 | benjamin.peterson | 2008-12-20 19:14:47 -0600 (Sat, 20 Dec 2008) | 1 line there are way too many places which need to have the current version added ................ r67892 | benjamin.peterson | 2008-12-20 19:29:32 -0600 (Sat, 20 Dec 2008) | 9 lines Merged revisions 67809 via svnmerge from svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3 ........ r67809 | benjamin.peterson | 2008-12-15 21:54:45 -0600 (Mon, 15 Dec 2008) | 1 line fix logic error ........ ................ r67895 | neal.norwitz | 2008-12-21 08:28:32 -0600 (Sun, 21 Dec 2008) | 2 lines Add Tarek for work on distutils. ................ r67898 | benjamin.peterson | 2008-12-21 15:00:53 -0600 (Sun, 21 Dec 2008) | 1 line compute DISTVERSION with patchlevel.py ................ r67904 | benjamin.peterson | 2008-12-22 14:44:58 -0600 (Mon, 22 Dec 2008) | 1 line less attitude ................ r67905 | benjamin.peterson | 2008-12-22 14:51:15 -0600 (Mon, 22 Dec 2008) | 1 line fix #4720: the format to PyArg_ParseTupleAndKeywords can now start with '|' ................ r67906 | benjamin.peterson | 2008-12-22 14:52:53 -0600 (Mon, 22 Dec 2008) | 1 line add NEWS note ................ r67907 | benjamin.peterson | 2008-12-22 16:12:19 -0600 (Mon, 22 Dec 2008) | 1 line silence compiler warning ................ r67912 | georg.brandl | 2008-12-23 06:37:21 -0600 (Tue, 23 Dec 2008) | 2 lines Fix missing "svn" command. ................ r67918 | georg.brandl | 2008-12-23 09:44:25 -0600 (Tue, 23 Dec 2008) | 2 lines Markup fix. ................ r67920 | benjamin.peterson | 2008-12-23 14:09:28 -0600 (Tue, 23 Dec 2008) | 1 line use a global variable, so the compiler doesn't optimize the assignment out ................ r67921 | benjamin.peterson | 2008-12-23 14:12:33 -0600 (Tue, 23 Dec 2008) | 1 line make global static ................ r67923 | benjamin.peterson | 2008-12-24 09:10:27 -0600 (Wed, 24 Dec 2008) | 1 line #4736 BufferRWPair.closed shouldn't try to call another property as a function ................ r67924 | benjamin.peterson | 2008-12-24 10:10:05 -0600 (Wed, 24 Dec 2008) | 1 line pretend exceptions don't exist a while longer ................ r67926 | tarek.ziade | 2008-12-24 13:10:05 -0600 (Wed, 24 Dec 2008) | 1 line fixed #4400 : distutils .pypirc default generated file was broken. ................ r67927 | benjamin.peterson | 2008-12-26 17:26:30 -0600 (Fri, 26 Dec 2008) | 1 line python version is included in file name now ................ r67930 | hirokazu.yamamoto | 2008-12-26 22:19:48 -0600 (Fri, 26 Dec 2008) | 2 lines Issue #4740: Use HIGHEST_PROTOCOL in pickle test. (There is no behavior difference in 2.x because HIGHEST_PROTOCOL == 2) ................ r67943 | alexandre.vassalotti | 2008-12-27 04:02:59 -0600 (Sat, 27 Dec 2008) | 2 lines Fix bogus unicode tests in pickletester. ................
2008-12-27 12:00:54 -04:00
conditional body when you are working on new code, allowing you to keep thinking
at a more abstract level. The :keyword:`!pass` is silently ignored::
>>> def initlog(*args):
Merged revisions 67889-67892,67895,67898,67904-67907,67912,67918,67920-67921,67923-67924,67926-67927,67930,67943 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ................ r67889 | benjamin.peterson | 2008-12-20 19:04:32 -0600 (Sat, 20 Dec 2008) | 1 line sphinx.web is long gone ................ r67890 | benjamin.peterson | 2008-12-20 19:12:26 -0600 (Sat, 20 Dec 2008) | 1 line update readme ................ r67891 | benjamin.peterson | 2008-12-20 19:14:47 -0600 (Sat, 20 Dec 2008) | 1 line there are way too many places which need to have the current version added ................ r67892 | benjamin.peterson | 2008-12-20 19:29:32 -0600 (Sat, 20 Dec 2008) | 9 lines Merged revisions 67809 via svnmerge from svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3 ........ r67809 | benjamin.peterson | 2008-12-15 21:54:45 -0600 (Mon, 15 Dec 2008) | 1 line fix logic error ........ ................ r67895 | neal.norwitz | 2008-12-21 08:28:32 -0600 (Sun, 21 Dec 2008) | 2 lines Add Tarek for work on distutils. ................ r67898 | benjamin.peterson | 2008-12-21 15:00:53 -0600 (Sun, 21 Dec 2008) | 1 line compute DISTVERSION with patchlevel.py ................ r67904 | benjamin.peterson | 2008-12-22 14:44:58 -0600 (Mon, 22 Dec 2008) | 1 line less attitude ................ r67905 | benjamin.peterson | 2008-12-22 14:51:15 -0600 (Mon, 22 Dec 2008) | 1 line fix #4720: the format to PyArg_ParseTupleAndKeywords can now start with '|' ................ r67906 | benjamin.peterson | 2008-12-22 14:52:53 -0600 (Mon, 22 Dec 2008) | 1 line add NEWS note ................ r67907 | benjamin.peterson | 2008-12-22 16:12:19 -0600 (Mon, 22 Dec 2008) | 1 line silence compiler warning ................ r67912 | georg.brandl | 2008-12-23 06:37:21 -0600 (Tue, 23 Dec 2008) | 2 lines Fix missing "svn" command. ................ r67918 | georg.brandl | 2008-12-23 09:44:25 -0600 (Tue, 23 Dec 2008) | 2 lines Markup fix. ................ r67920 | benjamin.peterson | 2008-12-23 14:09:28 -0600 (Tue, 23 Dec 2008) | 1 line use a global variable, so the compiler doesn't optimize the assignment out ................ r67921 | benjamin.peterson | 2008-12-23 14:12:33 -0600 (Tue, 23 Dec 2008) | 1 line make global static ................ r67923 | benjamin.peterson | 2008-12-24 09:10:27 -0600 (Wed, 24 Dec 2008) | 1 line #4736 BufferRWPair.closed shouldn't try to call another property as a function ................ r67924 | benjamin.peterson | 2008-12-24 10:10:05 -0600 (Wed, 24 Dec 2008) | 1 line pretend exceptions don't exist a while longer ................ r67926 | tarek.ziade | 2008-12-24 13:10:05 -0600 (Wed, 24 Dec 2008) | 1 line fixed #4400 : distutils .pypirc default generated file was broken. ................ r67927 | benjamin.peterson | 2008-12-26 17:26:30 -0600 (Fri, 26 Dec 2008) | 1 line python version is included in file name now ................ r67930 | hirokazu.yamamoto | 2008-12-26 22:19:48 -0600 (Fri, 26 Dec 2008) | 2 lines Issue #4740: Use HIGHEST_PROTOCOL in pickle test. (There is no behavior difference in 2.x because HIGHEST_PROTOCOL == 2) ................ r67943 | alexandre.vassalotti | 2008-12-27 04:02:59 -0600 (Sat, 27 Dec 2008) | 2 lines Fix bogus unicode tests in pickletester. ................
2008-12-27 12:00:54 -04:00
... pass # Remember to implement this!
2009-01-03 17:18:54 -04:00
...
2007-08-15 11:28:22 -03:00
.. _tut-functions:
Defining Functions
==================
We can create a function that writes the Fibonacci series to an arbitrary
boundary::
>>> def fib(n): # write Fibonacci series up to n
... """Print a Fibonacci series up to n."""
... a, b = 0, 1
... while a < n:
... print(a, end=' ')
2007-08-15 11:28:22 -03:00
... a, b = b, a+b
... print()
2009-01-03 17:18:54 -04:00
...
2007-08-15 11:28:22 -03:00
>>> # Now call the function we just defined:
... fib(2000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
2007-08-15 11:28:22 -03:00
.. index::
single: documentation strings
single: docstrings
single: strings, documentation
The keyword :keyword:`def` introduces a function *definition*. It must be
followed by the function name and the parenthesized list of formal parameters.
The statements that form the body of the function start at the next line, and
2008-09-13 14:18:21 -03:00
must be indented.
2007-08-15 11:28:22 -03:00
2008-09-13 14:18:21 -03:00
The first statement of the function body can optionally be a string literal;
this string literal is the function's documentation string, or :dfn:`docstring`.
(More about docstrings can be found in the section :ref:`tut-docstrings`.)
2007-08-15 11:28:22 -03:00
There are tools which use docstrings to automatically produce online or printed
documentation, or to let the user interactively browse through code; it's good
2008-09-13 14:18:21 -03:00
practice to include docstrings in code that you write, so make a habit of it.
2007-08-15 11:28:22 -03:00
The *execution* of a function introduces a new symbol table used for the local
variables of the function. More precisely, all variable assignments in a
function store the value in the local symbol table; whereas variable references
Merged revisions 60151-60159,60161-60168,60170,60172-60173,60175 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60151 | christian.heimes | 2008-01-21 14:11:15 +0100 (Mon, 21 Jan 2008) | 1 line A bunch of header files were not listed as dependencies for object files. Changes to files like Parser/parser.h weren't picked up by make. ........ r60152 | georg.brandl | 2008-01-21 15:16:46 +0100 (Mon, 21 Jan 2008) | 3 lines #1087741: make mmap.mmap the type of mmap objects, not a factory function. Allow it to be subclassed. ........ r60153 | georg.brandl | 2008-01-21 15:18:14 +0100 (Mon, 21 Jan 2008) | 2 lines mmap is an extension module. ........ r60154 | georg.brandl | 2008-01-21 17:28:13 +0100 (Mon, 21 Jan 2008) | 2 lines Fix example. ........ r60155 | georg.brandl | 2008-01-21 17:34:07 +0100 (Mon, 21 Jan 2008) | 2 lines #1555501: document plistlib and move it to the general library. ........ r60156 | georg.brandl | 2008-01-21 17:36:00 +0100 (Mon, 21 Jan 2008) | 2 lines Add a stub for bundlebuilder documentation. ........ r60157 | georg.brandl | 2008-01-21 17:46:58 +0100 (Mon, 21 Jan 2008) | 2 lines Removing bundlebuilder docs again -- it's not to be used anymore (see #779825). ........ r60158 | georg.brandl | 2008-01-21 17:51:51 +0100 (Mon, 21 Jan 2008) | 2 lines #997912: acknowledge nested scopes in tutorial. ........ r60159 | vinay.sajip | 2008-01-21 18:02:26 +0100 (Mon, 21 Jan 2008) | 1 line Fix: #1836: Off-by-one bug in TimedRotatingFileHandler rollover calculation. Patch thanks to Kathryn M. Kowalski. ........ r60161 | georg.brandl | 2008-01-21 18:13:03 +0100 (Mon, 21 Jan 2008) | 2 lines Adapt pydoc to new doc URLs. ........ r60162 | georg.brandl | 2008-01-21 18:17:00 +0100 (Mon, 21 Jan 2008) | 2 lines Fix old link. ........ r60163 | georg.brandl | 2008-01-21 18:22:06 +0100 (Mon, 21 Jan 2008) | 2 lines #1726198: replace while 1: fp.readline() with file iteration. ........ r60164 | georg.brandl | 2008-01-21 18:29:23 +0100 (Mon, 21 Jan 2008) | 2 lines Clarify $ behavior in re docstring. #1631394. ........ r60165 | vinay.sajip | 2008-01-21 18:39:22 +0100 (Mon, 21 Jan 2008) | 1 line Minor documentation change - hyperlink tidied up. ........ r60166 | georg.brandl | 2008-01-21 18:42:40 +0100 (Mon, 21 Jan 2008) | 2 lines #1530959: change distutils build dir for --with-pydebug python builds. ........ r60167 | vinay.sajip | 2008-01-21 19:16:05 +0100 (Mon, 21 Jan 2008) | 1 line Updated to include news on recent logging fixes and documentation changes. ........ r60168 | georg.brandl | 2008-01-21 19:35:49 +0100 (Mon, 21 Jan 2008) | 3 lines Issue #1882: when compiling code from a string, encoding cookies in the second line of code were not always recognized correctly. ........ r60170 | georg.brandl | 2008-01-21 19:36:51 +0100 (Mon, 21 Jan 2008) | 2 lines Add NEWS entry for #1882. ........ r60172 | georg.brandl | 2008-01-21 19:41:24 +0100 (Mon, 21 Jan 2008) | 2 lines Use original location of document, which has translations. ........ r60173 | walter.doerwald | 2008-01-21 21:18:04 +0100 (Mon, 21 Jan 2008) | 2 lines Follow PEP 8 in module docstring. ........ r60175 | georg.brandl | 2008-01-21 21:20:53 +0100 (Mon, 21 Jan 2008) | 2 lines Adapt to latest doctools refactoring. ........
2008-01-21 16:36:10 -04:00
first look in the local symbol table, then in the local symbol tables of
enclosing functions, then in the global symbol table, and finally in the table
of built-in names. Thus, global variables and variables of enclosing functions
cannot be directly assigned a value within a function (unless, for global
variables, named in a :keyword:`global` statement, or, for variables of enclosing
functions, named in a :keyword:`nonlocal` statement), although they may be
referenced.
2007-08-15 11:28:22 -03:00
The actual parameters (arguments) to a function call are introduced in the local
symbol table of the called function when it is called; thus, arguments are
passed using *call by value* (where the *value* is always an object *reference*,
not the value of the object). [#]_ When a function calls another function, a new
local symbol table is created for that call.
A function definition introduces the function name in the current symbol table.
The value of the function name has a type that is recognized by the interpreter
as a user-defined function. This value can be assigned to another name which
can then also be used as a function. This serves as a general renaming
mechanism::
>>> fib
<function fib at 10042ed0>
>>> f = fib
>>> f(100)
0 1 1 2 3 5 8 13 21 34 55 89
2007-08-15 11:28:22 -03:00
2008-09-13 14:18:21 -03:00
Coming from other languages, you might object that ``fib`` is not a function but
a procedure since it doesn't return a value. In fact, even functions without a
:keyword:`return` statement do return a value, albeit a rather boring one. This
value is called ``None`` (it's a built-in name). Writing the value ``None`` is
normally suppressed by the interpreter if it would be the only value written.
You can see it if you really want to using :func:`print`::
2007-08-15 11:28:22 -03:00
#1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Merged revisions 58221-58741 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r58221 | georg.brandl | 2007-09-20 10:57:59 -0700 (Thu, 20 Sep 2007) | 2 lines Patch #1181: add os.environ.clear() method. ........ r58225 | sean.reifschneider | 2007-09-20 23:33:28 -0700 (Thu, 20 Sep 2007) | 3 lines Issue1704287: "make install" fails unless you do "make" first. Make oldsharedmods and sharedmods in "libinstall". ........ r58232 | guido.van.rossum | 2007-09-22 13:18:03 -0700 (Sat, 22 Sep 2007) | 4 lines Patch # 188 by Philip Jenvey. Make tell() mark CRLF as a newline. With unit test. ........ r58242 | georg.brandl | 2007-09-24 10:55:47 -0700 (Mon, 24 Sep 2007) | 2 lines Fix typo and double word. ........ r58245 | georg.brandl | 2007-09-24 10:59:28 -0700 (Mon, 24 Sep 2007) | 2 lines #1196: document default radix for int(). ........ r58247 | georg.brandl | 2007-09-24 11:08:24 -0700 (Mon, 24 Sep 2007) | 2 lines #1177: accept 2xx responses for https too, not only http. ........ r58249 | andrew.kuchling | 2007-09-24 16:45:51 -0700 (Mon, 24 Sep 2007) | 1 line Remove stray odd character; grammar fix ........ r58250 | andrew.kuchling | 2007-09-24 16:46:28 -0700 (Mon, 24 Sep 2007) | 1 line Typo fix ........ r58251 | andrew.kuchling | 2007-09-24 17:09:42 -0700 (Mon, 24 Sep 2007) | 1 line Add various items ........ r58268 | vinay.sajip | 2007-09-26 22:34:45 -0700 (Wed, 26 Sep 2007) | 1 line Change to flush and close logic to fix #1760556. ........ r58269 | vinay.sajip | 2007-09-26 22:38:51 -0700 (Wed, 26 Sep 2007) | 1 line Change to basicConfig() to fix #1021. ........ r58270 | georg.brandl | 2007-09-26 23:26:58 -0700 (Wed, 26 Sep 2007) | 2 lines #1208: document match object's boolean value. ........ r58271 | vinay.sajip | 2007-09-26 23:56:13 -0700 (Wed, 26 Sep 2007) | 1 line Minor date change. ........ r58272 | vinay.sajip | 2007-09-27 00:35:10 -0700 (Thu, 27 Sep 2007) | 1 line Change to LogRecord.__init__() to fix #1206. Note that archaic use of type(x) == types.DictType is because of keeping 1.5.2 compatibility. While this is much less relevant these days, there probably needs to be a separate commit for removing all archaic constructs at the same time. ........ r58288 | brett.cannon | 2007-09-30 12:45:10 -0700 (Sun, 30 Sep 2007) | 9 lines tuple.__repr__ did not consider a reference loop as it is not possible from Python code; but it is possible from C. object.__str__ had the issue of not expecting a type to doing something within it's tp_str implementation that could trigger an infinite recursion, but it could in C code.. Both found thanks to BaseException and how it handles its repr. Closes issue #1686386. Thanks to Thomas Herve for taking an initial stab at coming up with a solution. ........ r58289 | brett.cannon | 2007-09-30 13:37:19 -0700 (Sun, 30 Sep 2007) | 3 lines Fix error introduced by r58288; if a tuple is length 0 return its repr and don't worry about any self-referring tuples. ........ r58294 | facundo.batista | 2007-10-02 10:01:24 -0700 (Tue, 02 Oct 2007) | 11 lines Made the various is_* operations return booleans. This was discussed with Cawlishaw by mail, and he basically confirmed that to these is_* operations, there's no need to return Decimal(0) and Decimal(1) if the language supports the False and True booleans. Also added a few tests for the these functions in extra.decTest, since they are mostly untested (apart from the doctests). Thanks Mark Dickinson ........ r58295 | facundo.batista | 2007-10-02 11:21:18 -0700 (Tue, 02 Oct 2007) | 4 lines Added a class to store the digits of log(10), so that they can be made available when necessary without recomputing. Thanks Mark Dickinson ........ r58299 | mark.summerfield | 2007-10-03 01:53:21 -0700 (Wed, 03 Oct 2007) | 4 lines Added note in footnote about string comparisons about unicodedata.normalize(). ........ r58304 | raymond.hettinger | 2007-10-03 14:18:11 -0700 (Wed, 03 Oct 2007) | 1 line enumerate() is no longer bounded to using sequences shorter than LONG_MAX. The possibility of overflow was sending some newsgroup posters into a tizzy. ........ r58305 | raymond.hettinger | 2007-10-03 17:20:27 -0700 (Wed, 03 Oct 2007) | 1 line itertools.count() no longer limited to sys.maxint. ........ r58306 | kurt.kaiser | 2007-10-03 18:49:54 -0700 (Wed, 03 Oct 2007) | 3 lines Assume that the user knows when he wants to end the line; don't insert something he didn't select or complete. ........ r58307 | kurt.kaiser | 2007-10-03 19:07:50 -0700 (Wed, 03 Oct 2007) | 2 lines Remove unused theme that was causing a fault in p3k. ........ r58308 | kurt.kaiser | 2007-10-03 19:09:17 -0700 (Wed, 03 Oct 2007) | 2 lines Clean up EditorWindow close. ........ r58309 | kurt.kaiser | 2007-10-03 19:53:07 -0700 (Wed, 03 Oct 2007) | 7 lines textView cleanup. Patch 1718043 Tal Einat. M idlelib/EditorWindow.py M idlelib/aboutDialog.py M idlelib/textView.py M idlelib/NEWS.txt ........ r58310 | kurt.kaiser | 2007-10-03 20:11:12 -0700 (Wed, 03 Oct 2007) | 3 lines configDialog cleanup. Patch 1730217 Tal Einat. ........ r58311 | neal.norwitz | 2007-10-03 23:00:48 -0700 (Wed, 03 Oct 2007) | 4 lines Coverity #151: Remove deadcode. All this code already exists above starting at line 653. ........ r58325 | fred.drake | 2007-10-04 19:46:12 -0700 (Thu, 04 Oct 2007) | 1 line wrap lines to <80 characters before fixing errors ........ r58326 | raymond.hettinger | 2007-10-04 19:47:07 -0700 (Thu, 04 Oct 2007) | 6 lines Add __asdict__() to NamedTuple and refine the docs. Add maxlen support to deque() and fixup docs. Partially fix __reduce__(). The None as a third arg was no longer supported. Still needs work on __reduce__() to handle recursive inputs. ........ r58327 | fred.drake | 2007-10-04 19:48:32 -0700 (Thu, 04 Oct 2007) | 3 lines move descriptions of ac_(in|out)_buffer_size to the right place http://bugs.python.org/issue1053 ........ r58329 | neal.norwitz | 2007-10-04 20:39:17 -0700 (Thu, 04 Oct 2007) | 3 lines dict could be NULL, so we need to XDECREF. Fix a compiler warning about passing a PyTypeObject* instead of PyObject*. ........ r58330 | neal.norwitz | 2007-10-04 20:41:19 -0700 (Thu, 04 Oct 2007) | 2 lines Fix Coverity #158: Check the correct variable. ........ r58332 | neal.norwitz | 2007-10-04 22:01:38 -0700 (Thu, 04 Oct 2007) | 7 lines Fix Coverity #159. This code was broken if save() returned a negative number since i contained a boolean value and then we compared i < 0 which should never be true. Will backport (assuming it's necessary) ........ r58334 | neal.norwitz | 2007-10-04 22:29:17 -0700 (Thu, 04 Oct 2007) | 1 line Add a note about fixing some more warnings found by Coverity. ........ r58338 | raymond.hettinger | 2007-10-05 12:07:31 -0700 (Fri, 05 Oct 2007) | 1 line Restore BEGIN/END THREADS macros which were squashed in the previous checkin ........ r58343 | gregory.p.smith | 2007-10-06 00:48:10 -0700 (Sat, 06 Oct 2007) | 3 lines Stab in the dark attempt to fix the test_bsddb3 failure on sparc and S-390 ubuntu buildbots. ........ r58344 | gregory.p.smith | 2007-10-06 00:51:59 -0700 (Sat, 06 Oct 2007) | 2 lines Allows BerkeleyDB 4.6.x >= 4.6.21 for the bsddb module. ........ r58348 | gregory.p.smith | 2007-10-06 08:47:37 -0700 (Sat, 06 Oct 2007) | 3 lines Use the host the author likely meant in the first place. pop.gmail.com is reliable. gmail.org is someones personal domain. ........ r58351 | neal.norwitz | 2007-10-06 12:16:28 -0700 (Sat, 06 Oct 2007) | 3 lines Ensure that this test will pass even if another test left an unwritable TESTFN. Also use the safe unlink in test_support instead of rolling our own here. ........ r58368 | georg.brandl | 2007-10-08 00:50:24 -0700 (Mon, 08 Oct 2007) | 3 lines #1123: fix the docs for the str.split(None, sep) case. Also expand a few other methods' docs, which had more info in the deprecated string module docs. ........ r58369 | georg.brandl | 2007-10-08 01:06:05 -0700 (Mon, 08 Oct 2007) | 2 lines Update docstring of sched, also remove an unused assignment. ........ r58370 | raymond.hettinger | 2007-10-08 02:14:28 -0700 (Mon, 08 Oct 2007) | 5 lines Add comments to NamedTuple code. Let the field spec be either a string or a non-string sequence (suggested by Martin Blais with use cases). Improve the error message in the case of a SyntaxError (caused by a duplicate field name). ........ r58371 | raymond.hettinger | 2007-10-08 02:56:29 -0700 (Mon, 08 Oct 2007) | 1 line Missed a line in the docs ........ r58372 | raymond.hettinger | 2007-10-08 03:11:51 -0700 (Mon, 08 Oct 2007) | 1 line Better variable names ........ r58376 | georg.brandl | 2007-10-08 07:12:47 -0700 (Mon, 08 Oct 2007) | 3 lines #1199: docs for tp_as_{number,sequence,mapping}, by Amaury Forgeot d'Arc. No need to merge this to py3k! ........ r58380 | raymond.hettinger | 2007-10-08 14:26:58 -0700 (Mon, 08 Oct 2007) | 1 line Eliminate camelcase function name ........ r58381 | andrew.kuchling | 2007-10-08 16:23:03 -0700 (Mon, 08 Oct 2007) | 1 line Eliminate camelcase function name ........ r58382 | raymond.hettinger | 2007-10-08 18:36:23 -0700 (Mon, 08 Oct 2007) | 1 line Make the error messages more specific ........ r58384 | gregory.p.smith | 2007-10-08 23:02:21 -0700 (Mon, 08 Oct 2007) | 10 lines Splits Modules/_bsddb.c up into bsddb.h and _bsddb.c and adds a C API object available as bsddb.db.api. This is based on the patch submitted by Duncan Grisby here: http://sourceforge.net/tracker/index.php?func=detail&aid=1551895&group_id=13900&atid=313900 See this thread for additional info: http://sourceforge.net/mailarchive/forum.php?thread_name=E1GAVDK-0002rk-Iw%40apasphere.com&forum_name=pybsddb-users It also cleans up the code a little by removing some ifdef/endifs for python prior to 2.1 and for unsupported Berkeley DB <= 3.2. ........ r58385 | gregory.p.smith | 2007-10-08 23:50:43 -0700 (Mon, 08 Oct 2007) | 5 lines Fix a double free when positioning a database cursor to a non-existant string key (and probably a few other situations with string keys). This was reported with a patch as pybsddb sourceforge bug 1708868 by jjjhhhlll at gmail. ........ r58386 | gregory.p.smith | 2007-10-09 00:19:11 -0700 (Tue, 09 Oct 2007) | 3 lines Use the highest cPickle protocol in bsddb.dbshelve. This comes from sourceforge pybsddb patch 1551443 by w_barnes. ........ r58394 | gregory.p.smith | 2007-10-09 11:26:02 -0700 (Tue, 09 Oct 2007) | 2 lines remove another sleepycat reference ........ r58396 | kurt.kaiser | 2007-10-09 12:31:30 -0700 (Tue, 09 Oct 2007) | 3 lines Allow interrupt only when executing user code in subprocess Patch 1225 Tal Einat modified from IDLE-Spoon. ........ r58399 | brett.cannon | 2007-10-09 17:07:50 -0700 (Tue, 09 Oct 2007) | 5 lines Remove file-level typedefs that were inconsistently used throughout the file. Just move over to the public API names. Closes issue1238. ........ r58401 | raymond.hettinger | 2007-10-09 17:26:46 -0700 (Tue, 09 Oct 2007) | 1 line Accept Jim Jewett's api suggestion to use None instead of -1 to indicate unbounded deques. ........ r58403 | kurt.kaiser | 2007-10-09 17:55:40 -0700 (Tue, 09 Oct 2007) | 2 lines Allow cursor color change w/o restart. Patch 1725576 Tal Einat. ........ r58404 | kurt.kaiser | 2007-10-09 18:06:47 -0700 (Tue, 09 Oct 2007) | 2 lines show paste if > 80 columns. Patch 1659326 Tal Einat. ........ r58415 | thomas.heller | 2007-10-11 12:51:32 -0700 (Thu, 11 Oct 2007) | 5 lines On OS X, use os.uname() instead of gestalt.sysv(...) to get the operating system version. This allows to use ctypes when Python was configured with --disable-toolbox-glue. ........ r58419 | neal.norwitz | 2007-10-11 20:01:01 -0700 (Thu, 11 Oct 2007) | 1 line Get rid of warning about not being able to create an existing directory. ........ r58420 | neal.norwitz | 2007-10-11 20:01:30 -0700 (Thu, 11 Oct 2007) | 1 line Get rid of warnings on a bunch of platforms by using a proper prototype. ........ r58421 | neal.norwitz | 2007-10-11 20:01:54 -0700 (Thu, 11 Oct 2007) | 4 lines Get rid of compiler warning about retval being used (returned) without being initialized. (gcc warning and Coverity 202) ........ r58422 | neal.norwitz | 2007-10-11 20:03:23 -0700 (Thu, 11 Oct 2007) | 1 line Fix Coverity 168: Close the file before returning (exiting). ........ r58423 | neal.norwitz | 2007-10-11 20:04:18 -0700 (Thu, 11 Oct 2007) | 4 lines Fix Coverity 180: Don't overallocate. We don't need structs, but pointers. Also fix a memory leak. ........ r58424 | neal.norwitz | 2007-10-11 20:05:19 -0700 (Thu, 11 Oct 2007) | 5 lines Fix Coverity 185-186: If the passed in FILE is NULL, uninitialized memory would be accessed. Will backport. ........ r58425 | neal.norwitz | 2007-10-11 20:52:34 -0700 (Thu, 11 Oct 2007) | 1 line Get this module to compile with bsddb versions prior to 4.3 ........ r58430 | martin.v.loewis | 2007-10-12 01:56:52 -0700 (Fri, 12 Oct 2007) | 3 lines Bug #1216: Restore support for Visual Studio 2002. Will backport to 2.5. ........ r58433 | raymond.hettinger | 2007-10-12 10:53:11 -0700 (Fri, 12 Oct 2007) | 1 line Fix test of count.__repr__() to ignore the 'L' if the count is a long ........ r58434 | gregory.p.smith | 2007-10-12 11:44:06 -0700 (Fri, 12 Oct 2007) | 4 lines Fixes http://bugs.python.org/issue1233 - bsddb.dbshelve.DBShelf.append was useless due to inverted logic. Also adds a test case for RECNO dbs to test_dbshelve. ........ r58445 | georg.brandl | 2007-10-13 06:20:03 -0700 (Sat, 13 Oct 2007) | 2 lines Fix email example. ........ r58450 | gregory.p.smith | 2007-10-13 16:02:05 -0700 (Sat, 13 Oct 2007) | 2 lines Fix an uncollectable reference leak in bsddb.db.DBShelf.append ........ r58453 | neal.norwitz | 2007-10-13 17:18:40 -0700 (Sat, 13 Oct 2007) | 8 lines Let the O/S supply a port if none of the default ports can be used. This should make the tests more robust at the expense of allowing tests to be sloppier by not requiring them to cleanup after themselves. (It will legitamitely help when running two test suites simultaneously or if another process is already using one of the predefined ports.) Also simplifies (slightLy) the exception handling elsewhere. ........ r58459 | neal.norwitz | 2007-10-14 11:30:21 -0700 (Sun, 14 Oct 2007) | 2 lines Don't raise a string exception, they don't work anymore. ........ r58460 | neal.norwitz | 2007-10-14 11:40:37 -0700 (Sun, 14 Oct 2007) | 1 line Use unittest for assertions ........ r58468 | armin.rigo | 2007-10-15 00:48:35 -0700 (Mon, 15 Oct 2007) | 2 lines test_bigbits was not testing what it seemed to. ........ r58471 | guido.van.rossum | 2007-10-15 08:54:11 -0700 (Mon, 15 Oct 2007) | 3 lines Change a PyErr_Print() into a PyErr_Clear(), per discussion in issue 1031213. ........ r58500 | raymond.hettinger | 2007-10-16 12:18:30 -0700 (Tue, 16 Oct 2007) | 1 line Improve error messages ........ r58506 | raymond.hettinger | 2007-10-16 14:28:32 -0700 (Tue, 16 Oct 2007) | 1 line More docs, error messages, and tests ........ r58507 | andrew.kuchling | 2007-10-16 15:58:03 -0700 (Tue, 16 Oct 2007) | 1 line Add items ........ r58508 | brett.cannon | 2007-10-16 16:24:06 -0700 (Tue, 16 Oct 2007) | 3 lines Remove ``:const:`` notation on None in parameter list. Since the markup is not rendered for parameters it just showed up as ``:const:`None` `` in the output. ........ r58509 | brett.cannon | 2007-10-16 16:26:45 -0700 (Tue, 16 Oct 2007) | 3 lines Re-order some functions whose parameters differ between PyObject and const char * so that they are next to each other. ........ r58522 | armin.rigo | 2007-10-17 11:46:37 -0700 (Wed, 17 Oct 2007) | 5 lines Fix the overflow checking of list_repeat. Introduce overflow checking into list_inplace_repeat. Backport candidate, possibly. ........ r58530 | facundo.batista | 2007-10-17 20:16:03 -0700 (Wed, 17 Oct 2007) | 7 lines Issue #1580738. When HTTPConnection reads the whole stream with read(), it closes itself. When the stream is read in several calls to read(n), it should behave in the same way if HTTPConnection knows where the end of the stream is (through self.length). Added a test case for this behaviour. ........ r58531 | facundo.batista | 2007-10-17 20:44:48 -0700 (Wed, 17 Oct 2007) | 3 lines Issue 1289, just a typo. ........ r58532 | gregory.p.smith | 2007-10-18 00:56:54 -0700 (Thu, 18 Oct 2007) | 4 lines cleanup test_dbtables to use mkdtemp. cleanup dbtables to pass txn as a keyword argument whenever possible to avoid bugs and confusion. (dbtables.py line 447 self.db.get using txn as a non-keyword was an actual bug due to this) ........ r58533 | gregory.p.smith | 2007-10-18 01:34:20 -0700 (Thu, 18 Oct 2007) | 4 lines Fix a weird bug in dbtables: if it chose a random rowid string that contained NULL bytes it would cause the database all sorts of problems in the future leading to very strange random failures and corrupt dbtables.bsdTableDb dbs. ........ r58534 | gregory.p.smith | 2007-10-18 09:32:02 -0700 (Thu, 18 Oct 2007) | 3 lines A cleaner fix than the one committed last night. Generate random rowids that do not contain null bytes. ........ r58537 | gregory.p.smith | 2007-10-18 10:17:57 -0700 (Thu, 18 Oct 2007) | 2 lines mention bsddb fixes. ........ r58538 | raymond.hettinger | 2007-10-18 14:13:06 -0700 (Thu, 18 Oct 2007) | 1 line Remove useless warning ........ r58539 | gregory.p.smith | 2007-10-19 00:31:20 -0700 (Fri, 19 Oct 2007) | 2 lines squelch the warning that this test is supposed to trigger. ........ r58542 | georg.brandl | 2007-10-19 05:32:39 -0700 (Fri, 19 Oct 2007) | 2 lines Clarify wording for apply(). ........ r58544 | mark.summerfield | 2007-10-19 05:48:17 -0700 (Fri, 19 Oct 2007) | 3 lines Added a cross-ref to each other. ........ r58545 | georg.brandl | 2007-10-19 10:38:49 -0700 (Fri, 19 Oct 2007) | 2 lines #1284: "S" means "seen", not unread. ........ r58548 | thomas.heller | 2007-10-19 11:11:41 -0700 (Fri, 19 Oct 2007) | 4 lines Fix ctypes on 32-bit systems when Python is configured --with-system-ffi. See also https://bugs.launchpad.net/bugs/72505. Ported from release25-maint branch. ........ r58550 | facundo.batista | 2007-10-19 12:25:57 -0700 (Fri, 19 Oct 2007) | 8 lines The constructor from tuple was way too permissive: it allowed bad coefficient numbers, floats in the sign, and other details that generated directly the wrong number in the best case, or triggered misfunctionality in the alorithms. Test cases added for these issues. Thanks Mark Dickinson. ........ r58559 | georg.brandl | 2007-10-20 06:22:53 -0700 (Sat, 20 Oct 2007) | 2 lines Fix code being interpreted as a target. ........ r58561 | georg.brandl | 2007-10-20 06:36:24 -0700 (Sat, 20 Oct 2007) | 2 lines Document new "cmdoption" directive. ........ r58562 | georg.brandl | 2007-10-20 08:21:22 -0700 (Sat, 20 Oct 2007) | 2 lines Make a path more Unix-standardy. ........ r58564 | georg.brandl | 2007-10-20 10:51:39 -0700 (Sat, 20 Oct 2007) | 2 lines Document new directive "envvar". ........ r58567 | georg.brandl | 2007-10-20 11:08:14 -0700 (Sat, 20 Oct 2007) | 6 lines * Add new toplevel chapter, "Using Python." (how to install, configure and setup python on different platforms -- at least in theory.) * Move the Python on Mac docs in that chapter. * Add a new chapter about the command line invocation, by stargaming. ........ r58568 | georg.brandl | 2007-10-20 11:33:20 -0700 (Sat, 20 Oct 2007) | 2 lines Change title, for now. ........ r58569 | georg.brandl | 2007-10-20 11:39:25 -0700 (Sat, 20 Oct 2007) | 2 lines Add entry to ACKS. ........ r58570 | georg.brandl | 2007-10-20 12:05:45 -0700 (Sat, 20 Oct 2007) | 2 lines Clarify -E docs. ........ r58571 | georg.brandl | 2007-10-20 12:08:36 -0700 (Sat, 20 Oct 2007) | 2 lines Even more clarification. ........ r58572 | andrew.kuchling | 2007-10-20 12:25:37 -0700 (Sat, 20 Oct 2007) | 1 line Fix protocol name ........ r58573 | andrew.kuchling | 2007-10-20 12:35:18 -0700 (Sat, 20 Oct 2007) | 1 line Various items ........ r58574 | andrew.kuchling | 2007-10-20 12:39:35 -0700 (Sat, 20 Oct 2007) | 1 line Use correct header line ........ r58576 | armin.rigo | 2007-10-21 02:14:15 -0700 (Sun, 21 Oct 2007) | 3 lines Add a crasher for the long-standing issue with closing a file while another thread uses it. ........ r58577 | georg.brandl | 2007-10-21 03:01:56 -0700 (Sun, 21 Oct 2007) | 2 lines Remove duplicate crasher. ........ r58578 | georg.brandl | 2007-10-21 03:24:20 -0700 (Sun, 21 Oct 2007) | 2 lines Unify "byte code" to "bytecode". Also sprinkle :term: markup for it. ........ r58579 | georg.brandl | 2007-10-21 03:32:54 -0700 (Sun, 21 Oct 2007) | 2 lines Add markup to new function descriptions. ........ r58580 | georg.brandl | 2007-10-21 03:45:46 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for descriptors. ........ r58581 | georg.brandl | 2007-10-21 03:46:24 -0700 (Sun, 21 Oct 2007) | 2 lines Unify "file-descriptor" to "file descriptor". ........ r58582 | georg.brandl | 2007-10-21 03:52:38 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term: for generators. ........ r58583 | georg.brandl | 2007-10-21 05:10:28 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for iterator. ........ r58584 | georg.brandl | 2007-10-21 05:15:05 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for "new-style class". ........ r58588 | neal.norwitz | 2007-10-21 21:47:54 -0700 (Sun, 21 Oct 2007) | 1 line Add Chris Monson so he can edit PEPs. ........ r58594 | guido.van.rossum | 2007-10-22 09:27:19 -0700 (Mon, 22 Oct 2007) | 4 lines Issue #1307, patch by Derek Shockey. When "MAIL" is received without args, an exception happens instead of sending a 501 syntax error response. ........ r58598 | travis.oliphant | 2007-10-22 19:40:56 -0700 (Mon, 22 Oct 2007) | 1 line Add phuang patch from Issue 708374 which adds offset parameter to mmap module. ........ r58601 | neal.norwitz | 2007-10-22 22:44:27 -0700 (Mon, 22 Oct 2007) | 2 lines Bug #1313, fix typo (wrong variable name) in example. ........ r58609 | georg.brandl | 2007-10-23 11:21:35 -0700 (Tue, 23 Oct 2007) | 2 lines Update Pygments version from externals. ........ r58618 | guido.van.rossum | 2007-10-23 12:25:41 -0700 (Tue, 23 Oct 2007) | 3 lines Issue 1307 by Derek Shockey, fox the same bug for RCPT. Neal: please backport! ........ r58620 | raymond.hettinger | 2007-10-23 13:37:41 -0700 (Tue, 23 Oct 2007) | 1 line Shorter name for namedtuple() ........ r58621 | andrew.kuchling | 2007-10-23 13:55:47 -0700 (Tue, 23 Oct 2007) | 1 line Update name ........ r58622 | raymond.hettinger | 2007-10-23 14:23:07 -0700 (Tue, 23 Oct 2007) | 1 line Fixup news entry ........ r58623 | raymond.hettinger | 2007-10-23 18:28:33 -0700 (Tue, 23 Oct 2007) | 1 line Optimize sum() for integer and float inputs. ........ r58624 | raymond.hettinger | 2007-10-23 19:05:51 -0700 (Tue, 23 Oct 2007) | 1 line Fixup error return and add support for intermixed ints and floats/ ........ r58628 | vinay.sajip | 2007-10-24 03:47:06 -0700 (Wed, 24 Oct 2007) | 1 line Bug #1321: Fixed logic error in TimedRotatingFileHandler.__init__() ........ r58641 | facundo.batista | 2007-10-24 12:11:08 -0700 (Wed, 24 Oct 2007) | 4 lines Issue 1290. CharacterData.__repr__ was constructing a string in response that keeped having a non-ascii character. ........ r58643 | thomas.heller | 2007-10-24 12:50:45 -0700 (Wed, 24 Oct 2007) | 1 line Added unittest for calling a function with paramflags (backport from py3k branch). ........ r58645 | matthias.klose | 2007-10-24 13:00:44 -0700 (Wed, 24 Oct 2007) | 2 lines - Build using system ffi library on arm*-linux*. ........ r58651 | georg.brandl | 2007-10-24 14:40:38 -0700 (Wed, 24 Oct 2007) | 2 lines Bug #1287: make os.environ.pop() work as expected. ........ r58652 | raymond.hettinger | 2007-10-24 19:26:58 -0700 (Wed, 24 Oct 2007) | 1 line Missing DECREFs ........ r58653 | matthias.klose | 2007-10-24 23:37:24 -0700 (Wed, 24 Oct 2007) | 2 lines - Build using system ffi library on arm*-linux*, pass --with-system-ffi to CONFIG_ARGS ........ r58655 | thomas.heller | 2007-10-25 12:47:32 -0700 (Thu, 25 Oct 2007) | 2 lines ffi_type_longdouble may be already #defined. See issue 1324. ........ r58656 | kurt.kaiser | 2007-10-25 15:43:45 -0700 (Thu, 25 Oct 2007) | 3 lines Correct an ancient bug in an unused path by removing that path: register() is now idempotent. ........ r58660 | kurt.kaiser | 2007-10-25 17:10:09 -0700 (Thu, 25 Oct 2007) | 4 lines 1. Add comments to provide top-level documentation. 2. Refactor to use more descriptive names. 3. Enhance tests in main(). ........ r58675 | georg.brandl | 2007-10-26 11:30:41 -0700 (Fri, 26 Oct 2007) | 2 lines Fix new pop() method on os.environ on ignorecase-platforms. ........ r58696 | neal.norwitz | 2007-10-27 15:32:21 -0700 (Sat, 27 Oct 2007) | 1 line Update URL for Pygments. 0.8.1 is no longer available ........ r58697 | hyeshik.chang | 2007-10-28 04:19:02 -0700 (Sun, 28 Oct 2007) | 3 lines - Add support for FreeBSD 8 which is recently forked from FreeBSD 7. - Regenerate IN module for most recent maintenance tree of FreeBSD 6 and 7. ........ r58698 | hyeshik.chang | 2007-10-28 05:38:09 -0700 (Sun, 28 Oct 2007) | 2 lines Enable platform-specific tweaks for FreeBSD 8 (exactly same to FreeBSD 7's yet) ........ r58700 | kurt.kaiser | 2007-10-28 12:03:59 -0700 (Sun, 28 Oct 2007) | 2 lines Add confirmation dialog before printing. Patch 1717170 Tal Einat. ........ r58706 | guido.van.rossum | 2007-10-29 13:52:45 -0700 (Mon, 29 Oct 2007) | 3 lines Patch 1353 by Jacob Winther. Add mp4 mapping to mimetypes.py. ........ r58709 | guido.van.rossum | 2007-10-29 15:15:05 -0700 (Mon, 29 Oct 2007) | 6 lines Backport fixes for the code that decodes octal escapes (and for PyString also hex escapes) -- this was reaching beyond the end of the input string buffer, even though it is not supposed to be \0-terminated. This has no visible effect but is clearly the correct thing to do. (In 3.0 it had a visible effect after removing ob_sstate from PyString.) ........ r58710 | kurt.kaiser | 2007-10-29 19:38:54 -0700 (Mon, 29 Oct 2007) | 7 lines check in Tal Einat's update to tabpage.py Patch 1612746 M configDialog.py M NEWS.txt AM tabbedpages.py ........ r58715 | georg.brandl | 2007-10-30 10:51:18 -0700 (Tue, 30 Oct 2007) | 2 lines Use correct markup. ........ r58716 | georg.brandl | 2007-10-30 10:57:12 -0700 (Tue, 30 Oct 2007) | 2 lines Make example about hiding None return values at the prompt clearer. ........ r58728 | neal.norwitz | 2007-10-30 23:33:20 -0700 (Tue, 30 Oct 2007) | 1 line Fix some compiler warnings for signed comparisons on Unix and Windows. ........ r58731 | martin.v.loewis | 2007-10-31 10:19:33 -0700 (Wed, 31 Oct 2007) | 2 lines Adding Christian Heimes. ........ r58737 | raymond.hettinger | 2007-10-31 14:57:58 -0700 (Wed, 31 Oct 2007) | 1 line Clarify the reasons why pickle is almost always better than marshal ........ r58739 | raymond.hettinger | 2007-10-31 15:15:49 -0700 (Wed, 31 Oct 2007) | 1 line Sets are marshalable. ........
2007-11-01 17:32:30 -03:00
>>> fib(0)
>>> print(fib(0))
2007-08-15 11:28:22 -03:00
None
It is simple to write a function that returns a list of the numbers of the
Fibonacci series, instead of printing it::
>>> def fib2(n): # return Fibonacci series up to n
2007-08-15 11:28:22 -03:00
... """Return a list containing the Fibonacci series up to n."""
... result = []
... a, b = 0, 1
... while a < n:
... result.append(a) # see below
2007-08-15 11:28:22 -03:00
... a, b = b, a+b
... return result
2009-01-03 17:18:54 -04:00
...
2007-08-15 11:28:22 -03:00
>>> f100 = fib2(100) # call it
>>> f100 # write the result
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
2007-08-15 11:28:22 -03:00
This example, as usual, demonstrates some new Python features:
* The :keyword:`return` statement returns with a value from a function.
:keyword:`!return` without an expression argument returns ``None``. Falling off
2008-09-13 14:18:21 -03:00
the end of a function also returns ``None``.
2007-08-15 11:28:22 -03:00
* The statement ``result.append(a)`` calls a *method* of the list object
2007-08-15 11:28:22 -03:00
``result``. A method is a function that 'belongs' to an object and is named
``obj.methodname``, where ``obj`` is some object (this may be an expression),
and ``methodname`` is the name of a method that is defined by the object's type.
Different types define different methods. Methods of different types may have
the same name without causing ambiguity. (It is possible to define your own
object types and methods, using *classes*, see :ref:`tut-classes`)
2007-08-15 11:28:22 -03:00
The method :meth:`append` shown in the example is defined for list objects; it
adds a new element at the end of the list. In this example it is equivalent to
``result = result + [a]``, but more efficient.
2007-08-15 11:28:22 -03:00
.. _tut-defining:
More on Defining Functions
==========================
It is also possible to define functions with a variable number of arguments.
There are three forms, which can be combined.
.. _tut-defaultargs:
Default Argument Values
-----------------------
The most useful form is to specify a default value for one or more arguments.
This creates a function that can be called with fewer arguments than it is
defined to allow. For example::
def ask_ok(prompt, retries=4, reminder='Please try again!'):
2007-08-15 11:28:22 -03:00
while True:
ok = input(prompt)
if ok in ('y', 'ye', 'yes'):
return True
if ok in ('n', 'no', 'nop', 'nope'):
return False
2007-08-15 11:28:22 -03:00
retries = retries - 1
2007-09-09 21:39:52 -03:00
if retries < 0:
raise ValueError('invalid user response')
print(reminder)
2007-08-15 11:28:22 -03:00
This function can be called in several ways:
* giving only the mandatory argument:
``ask_ok('Do you really want to quit?')``
* giving one of the optional arguments:
``ask_ok('OK to overwrite the file?', 2)``
* or even giving all arguments:
``ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')``
2007-08-15 11:28:22 -03:00
This example also introduces the :keyword:`in` keyword. This tests whether or
not a sequence contains a certain value.
The default values are evaluated at the point of function definition in the
*defining* scope, so that ::
i = 5
def f(arg=i):
print(arg)
2007-08-15 11:28:22 -03:00
i = 6
f()
will print ``5``.
**Important warning:** The default value is evaluated only once. This makes a
difference when the default is a mutable object such as a list, dictionary, or
instances of most classes. For example, the following function accumulates the
arguments passed to it on subsequent calls::
def f(a, L=[]):
L.append(a)
return L
print(f(1))
print(f(2))
print(f(3))
2007-08-15 11:28:22 -03:00
This will print ::
[1]
[1, 2]
[1, 2, 3]
If you don't want the default to be shared between subsequent calls, you can
write the function like this instead::
def f(a, L=None):
if L is None:
L = []
L.append(a)
return L
.. _tut-keywordargs:
Keyword Arguments
-----------------
Functions can also be called using :term:`keyword arguments <keyword argument>`
of the form ``kwarg=value``. For instance, the following function::
2007-08-15 11:28:22 -03:00
def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
print("-- This parrot wouldn't", action, end=' ')
print("if you put", voltage, "volts through it.")
print("-- Lovely plumage, the", type)
print("-- It's", state, "!")
2007-08-15 11:28:22 -03:00
accepts one required argument (``voltage``) and three optional arguments
(``state``, ``action``, and ``type``). This function can be called in any
of the following ways::
2007-08-15 11:28:22 -03:00
parrot(1000) # 1 positional argument
parrot(voltage=1000) # 1 keyword argument
parrot(voltage=1000000, action='VOOOOOM') # 2 keyword arguments
parrot(action='VOOOOOM', voltage=1000000) # 2 keyword arguments
parrot('a million', 'bereft of life', 'jump') # 3 positional arguments
parrot('a thousand', state='pushing up the daisies') # 1 positional, 1 keyword
2007-08-15 11:28:22 -03:00
but all the following calls would be invalid::
2007-08-15 11:28:22 -03:00
parrot() # required argument missing
parrot(voltage=5.0, 'dead') # non-keyword argument after a keyword argument
parrot(110, voltage=220) # duplicate value for the same argument
parrot(actor='John Cleese') # unknown keyword argument
In a function call, keyword arguments must follow positional arguments.
All the keyword arguments passed must match one of the arguments
accepted by the function (e.g. ``actor`` is not a valid argument for the
``parrot`` function), and their order is not important. This also includes
non-optional arguments (e.g. ``parrot(voltage=1000)`` is valid too).
No argument may receive a value more than once.
Here's an example that fails due to this restriction::
2007-08-15 11:28:22 -03:00
>>> def function(a):
... pass
2009-01-03 17:18:54 -04:00
...
2007-08-15 11:28:22 -03:00
>>> function(0, a=0)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
2007-08-15 11:28:22 -03:00
TypeError: function() got multiple values for keyword argument 'a'
When a final formal parameter of the form ``**name`` is present, it receives a
dictionary (see :ref:`typesmapping`) containing all keyword arguments except for
those corresponding to a formal parameter. This may be combined with a formal
parameter of the form ``*name`` (described in the next subsection) which
receives a :ref:`tuple <tut-tuples>` containing the positional
arguments beyond the formal parameter list. (``*name`` must occur
before ``**name``.) For example, if we define a function like this::
2007-08-15 11:28:22 -03:00
def cheeseshop(kind, *arguments, **keywords):
2008-09-13 14:18:21 -03:00
print("-- Do you have any", kind, "?")
print("-- I'm sorry, we're all out of", kind)
2010-10-15 12:32:05 -03:00
for arg in arguments:
print(arg)
2008-09-13 14:18:21 -03:00
print("-" * 40)
for kw in keywords:
2010-10-15 12:32:05 -03:00
print(kw, ":", keywords[kw])
2007-08-15 11:28:22 -03:00
It could be called like this::
2008-09-13 14:18:21 -03:00
cheeseshop("Limburger", "It's very runny, sir.",
2007-08-15 11:28:22 -03:00
"It's really very, VERY runny, sir.",
2008-09-13 14:18:21 -03:00
shopkeeper="Michael Palin",
client="John Cleese",
sketch="Cheese Shop Sketch")
2007-08-15 11:28:22 -03:00
and of course it would print:
.. code-block:: none
2007-08-15 11:28:22 -03:00
-- Do you have any Limburger ?
-- I'm sorry, we're all out of Limburger
It's very runny, sir.
It's really very, VERY runny, sir.
----------------------------------------
shopkeeper : Michael Palin
client : John Cleese
2007-08-15 11:28:22 -03:00
sketch : Cheese Shop Sketch
Note that the order in which the keyword arguments are printed is guaranteed
to match the order in which they were provided in the function call.
Special parameters
------------------
By default, arguments may be passed to a Python function either by position
or explicitly by keyword. For readability and performance, it makes sense to
restrict the way arguments can be passed so that a developer need only look
at the function definition to determine if items are passed by position, by
position or keyword, or by keyword.
A function definition may look like:
.. code-block:: none
def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
----------- ---------- ----------
| | |
| Positional or keyword |
| - Keyword only
-- Positional only
where ``/`` and ``*`` are optional. If used, these symbols indicate the kind of
parameter by how the arguments may be passed to the function:
positional-only, positional-or-keyword, and keyword-only. Keyword parameters
are also referred to as named parameters.
-------------------------------
Positional-or-Keyword Arguments
-------------------------------
If ``/`` and ``*`` are not present in the function definition, arguments may
be passed to a function by position or by keyword.
--------------------------
Positional-Only Parameters
--------------------------
Looking at this in a bit more detail, it is possible to mark certain parameters
as *positional-only*. If *positional-only*, the parameters' order matters, and
the parameters cannot be passed by keyword. Positional-only parameters are
placed before a ``/`` (forward-slash). The ``/`` is used to logically
separate the positional-only parameters from the rest of the parameters.
If there is no ``/`` in the function definition, there are no positional-only
parameters.
Parameters following the ``/`` may be *positional-or-keyword* or *keyword-only*.
----------------------
Keyword-Only Arguments
----------------------
To mark parameters as *keyword-only*, indicating the parameters must be passed
by keyword argument, place an ``*`` in the arguments list just before the first
*keyword-only* parameter.
-----------------
Function Examples
-----------------
Consider the following example function definitions paying close attention to the
markers ``/`` and ``*``::
>>> def standard_arg(arg):
... print(arg)
...
>>> def pos_only_arg(arg, /):
... print(arg)
...
>>> def kwd_only_arg(*, arg):
... print(arg)
...
>>> def combined_example(pos_only, /, standard, *, kwd_only):
... print(pos_only, standard, kwd_only)
The first function definition, ``standard_arg``, the most familiar form,
places no restrictions on the calling convention and arguments may be
passed by position or keyword::
>>> standard_arg(2)
2
>>> standard_arg(arg=2)
2
The second function ``pos_only_arg`` is restricted to only use positional
parameters as there is a ``/`` in the function definition::
>>> pos_only_arg(1)
1
>>> pos_only_arg(arg=1)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: pos_only_arg() got an unexpected keyword argument 'arg'
The third function ``kwd_only_args`` only allows keyword arguments as indicated
by a ``*`` in the function definition::
>>> kwd_only_arg(3)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: kwd_only_arg() takes 0 positional arguments but 1 was given
>>> kwd_only_arg(arg=3)
3
And the last uses all three calling conventions in the same function
definition::
>>> combined_example(1, 2, 3)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: combined_example() takes 2 positional arguments but 3 were given
>>> combined_example(1, 2, kwd_only=3)
1 2 3
>>> combined_example(1, standard=2, kwd_only=3)
1 2 3
>>> combined_example(pos_only=1, standard=2, kwd_only=3)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: combined_example() got an unexpected keyword argument 'pos_only'
Finally, consider this function definition which has a potential collision between the positional argument ``name`` and ``**kwds`` which has ``name`` as a key::
def foo(name, **kwds):
return 'name' in kwds
There is no possible call that will make it return ``True`` as the keyword ``'name'``
will always to bind to the first parameter. For example::
>>> foo(1, **{'name': 2})
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: foo() got multiple values for argument 'name'
>>>
But using ``/`` (positional only arguments), it is possible since it allows ``name`` as a positional argument and ``'name'`` as a key in the keyword arguments::
def foo(name, /, **kwds):
return 'name' in kwds
>>> foo(1, **{'name': 2})
True
In other words, the names of positional-only parameters can be used in
``**kwds`` without ambiguity.
-----
Recap
-----
The use case will determine which parameters to use in the function definition::
def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
As guidance:
* Use positional-only if you want the name of the parameters to not be
available to the user. This is useful when parameter names have no real
meaning, if you want to enforce the order of the arguments when the function
is called or if you need to take some positional parameters and arbitrary
keywords.
* Use keyword-only when names have meaning and the function definition is
more understandable by being explicit with names or you want to prevent
users relying on the position of the argument being passed.
* For an API, use positional-only to prevent breaking API changes
if the parameter's name is modified in the future.
2007-08-15 11:28:22 -03:00
.. _tut-arbitraryargs:
Arbitrary Argument Lists
------------------------
Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r62350 | nick.coghlan | 2008-04-15 12:25:31 +0200 (Tue, 15 Apr 2008) | 1 line Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore) ........ r62351 | nick.coghlan | 2008-04-15 12:28:14 +0200 (Tue, 15 Apr 2008) | 1 line Add test file missing from rev 62350 ........ r62352 | benjamin.peterson | 2008-04-15 13:58:46 +0200 (Tue, 15 Apr 2008) | 2 lines Add myself to Doc/ACKS.txt ........ r62353 | andrew.kuchling | 2008-04-15 15:10:07 +0200 (Tue, 15 Apr 2008) | 6 lines Add *,**,@ to index, as suggested by http://farmdev.com/thoughts/24/what-does-the-def-star-variable-or-def-asterisk-parameter-syntax-do-in-python-/ The right entry type to use isn't clear; operator seems wrong, because *,**,@ aren't being used in expressions here. I put them as 'statement'; 'syntax' might be better. ........ r62354 | andrew.kuchling | 2008-04-15 15:10:41 +0200 (Tue, 15 Apr 2008) | 1 line Typo fix ........ r62355 | mark.dickinson | 2008-04-15 22:51:18 +0200 (Tue, 15 Apr 2008) | 3 lines Fix for possible signed overflow: the behaviour of -LONG_MIN is undefined in ANSI C. ........ r62358 | jeroen.ruigrok | 2008-04-16 14:47:01 +0200 (Wed, 16 Apr 2008) | 2 lines Reformat to 80 columns prior to adding documentation. ........ r62359 | jeroen.ruigrok | 2008-04-16 14:57:43 +0200 (Wed, 16 Apr 2008) | 2 lines Add details about the return value for mmap.flush(). ........ r62364 | raymond.hettinger | 2008-04-17 12:48:31 +0200 (Thu, 17 Apr 2008) | 1 line Issue 2648: Add leading zero to money format recipe in the docs. ........ r62365 | jeroen.ruigrok | 2008-04-17 14:39:45 +0200 (Thu, 17 Apr 2008) | 2 lines Be consistent in the use of read-only. ........ r62370 | andrew.kuchling | 2008-04-17 22:44:06 +0200 (Thu, 17 Apr 2008) | 1 line Typo fixes ........ r62372 | andrew.kuchling | 2008-04-18 04:40:47 +0200 (Fri, 18 Apr 2008) | 1 line Use correct parameter name ........ r62373 | andrew.kuchling | 2008-04-18 18:53:09 +0200 (Fri, 18 Apr 2008) | 1 line #2654: fix typo ........ r62374 | andrew.kuchling | 2008-04-18 20:28:23 +0200 (Fri, 18 Apr 2008) | 4 lines Remove personal note from Jim Roskind; it no longer applies, and the e-mail address is for a previous employer. Can we move the big long copyright statement into a sidebar or something? ........ r62375 | andrew.kuchling | 2008-04-18 20:39:55 +0200 (Fri, 18 Apr 2008) | 1 line Rewrite introductory section, and remove old section. (It was already commented-out, but why keep it?) ........ r62378 | skip.montanaro | 2008-04-18 22:35:46 +0200 (Fri, 18 Apr 2008) | 1 line resolve issue 2014 ........ r62379 | benjamin.peterson | 2008-04-18 22:45:33 +0200 (Fri, 18 Apr 2008) | 2 lines Fix indentation in sysmodule.c ........ r62381 | amaury.forgeotdarc | 2008-04-19 01:31:33 +0200 (Sat, 19 Apr 2008) | 3 lines Some tests did not pass on repeated calls (regrtest -R::) Perform additional cleanup, mostly deleting from sys.modules, or clearing the warnings registry. ........
2008-04-18 21:55:37 -03:00
.. index::
single: * (asterisk); in function calls
Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r62350 | nick.coghlan | 2008-04-15 12:25:31 +0200 (Tue, 15 Apr 2008) | 1 line Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore) ........ r62351 | nick.coghlan | 2008-04-15 12:28:14 +0200 (Tue, 15 Apr 2008) | 1 line Add test file missing from rev 62350 ........ r62352 | benjamin.peterson | 2008-04-15 13:58:46 +0200 (Tue, 15 Apr 2008) | 2 lines Add myself to Doc/ACKS.txt ........ r62353 | andrew.kuchling | 2008-04-15 15:10:07 +0200 (Tue, 15 Apr 2008) | 6 lines Add *,**,@ to index, as suggested by http://farmdev.com/thoughts/24/what-does-the-def-star-variable-or-def-asterisk-parameter-syntax-do-in-python-/ The right entry type to use isn't clear; operator seems wrong, because *,**,@ aren't being used in expressions here. I put them as 'statement'; 'syntax' might be better. ........ r62354 | andrew.kuchling | 2008-04-15 15:10:41 +0200 (Tue, 15 Apr 2008) | 1 line Typo fix ........ r62355 | mark.dickinson | 2008-04-15 22:51:18 +0200 (Tue, 15 Apr 2008) | 3 lines Fix for possible signed overflow: the behaviour of -LONG_MIN is undefined in ANSI C. ........ r62358 | jeroen.ruigrok | 2008-04-16 14:47:01 +0200 (Wed, 16 Apr 2008) | 2 lines Reformat to 80 columns prior to adding documentation. ........ r62359 | jeroen.ruigrok | 2008-04-16 14:57:43 +0200 (Wed, 16 Apr 2008) | 2 lines Add details about the return value for mmap.flush(). ........ r62364 | raymond.hettinger | 2008-04-17 12:48:31 +0200 (Thu, 17 Apr 2008) | 1 line Issue 2648: Add leading zero to money format recipe in the docs. ........ r62365 | jeroen.ruigrok | 2008-04-17 14:39:45 +0200 (Thu, 17 Apr 2008) | 2 lines Be consistent in the use of read-only. ........ r62370 | andrew.kuchling | 2008-04-17 22:44:06 +0200 (Thu, 17 Apr 2008) | 1 line Typo fixes ........ r62372 | andrew.kuchling | 2008-04-18 04:40:47 +0200 (Fri, 18 Apr 2008) | 1 line Use correct parameter name ........ r62373 | andrew.kuchling | 2008-04-18 18:53:09 +0200 (Fri, 18 Apr 2008) | 1 line #2654: fix typo ........ r62374 | andrew.kuchling | 2008-04-18 20:28:23 +0200 (Fri, 18 Apr 2008) | 4 lines Remove personal note from Jim Roskind; it no longer applies, and the e-mail address is for a previous employer. Can we move the big long copyright statement into a sidebar or something? ........ r62375 | andrew.kuchling | 2008-04-18 20:39:55 +0200 (Fri, 18 Apr 2008) | 1 line Rewrite introductory section, and remove old section. (It was already commented-out, but why keep it?) ........ r62378 | skip.montanaro | 2008-04-18 22:35:46 +0200 (Fri, 18 Apr 2008) | 1 line resolve issue 2014 ........ r62379 | benjamin.peterson | 2008-04-18 22:45:33 +0200 (Fri, 18 Apr 2008) | 2 lines Fix indentation in sysmodule.c ........ r62381 | amaury.forgeotdarc | 2008-04-19 01:31:33 +0200 (Sat, 19 Apr 2008) | 3 lines Some tests did not pass on repeated calls (regrtest -R::) Perform additional cleanup, mostly deleting from sys.modules, or clearing the warnings registry. ........
2008-04-18 21:55:37 -03:00
2007-08-15 11:28:22 -03:00
Finally, the least frequently used option is to specify that a function can be
called with an arbitrary number of arguments. These arguments will be wrapped
2008-09-13 14:18:21 -03:00
up in a tuple (see :ref:`tut-tuples`). Before the variable number of arguments,
zero or more normal arguments may occur. ::
2007-08-15 11:28:22 -03:00
Merged revisions 63724,63726,63732,63744,63754-63755,63757-63758,63760,63775,63781-63782,63787,63805-63808,63818-63819,63823-63824 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r63724 | gregory.p.smith | 2008-05-26 22:22:14 +0200 (Mon, 26 May 2008) | 6 lines Fixes issue2791: subprocess.Popen.communicate leaked a file descripton until the last reference to the Popen instance was dropped. Adding explicit close() calls fixes it. Candidate for backport to release25-maint. ........ r63726 | benjamin.peterson | 2008-05-26 22:43:24 +0200 (Mon, 26 May 2008) | 2 lines fix minor grammar typo ........ r63732 | benjamin.peterson | 2008-05-26 23:44:26 +0200 (Mon, 26 May 2008) | 2 lines remove duplication in test module ........ r63744 | lars.gustaebel | 2008-05-27 14:39:23 +0200 (Tue, 27 May 2008) | 3 lines Do not close external file objects passed to tarfile.open(mode='w:bz2') when the TarFile is closed. ........ r63754 | benjamin.peterson | 2008-05-28 03:12:35 +0200 (Wed, 28 May 2008) | 2 lines update tutorial function with more appropiate one from Eric Smith ........ r63755 | mark.hammond | 2008-05-28 03:54:55 +0200 (Wed, 28 May 2008) | 2 lines bdist_wininst now works correctly when both --skip-build and --plat-name are specified. ........ r63757 | georg.brandl | 2008-05-28 13:21:39 +0200 (Wed, 28 May 2008) | 2 lines #2989: add PyType_Modified(). ........ r63758 | benjamin.peterson | 2008-05-28 13:51:41 +0200 (Wed, 28 May 2008) | 2 lines fix spelling ........ r63760 | georg.brandl | 2008-05-28 17:41:36 +0200 (Wed, 28 May 2008) | 2 lines #2990: prevent inconsistent state while updating method cache. ........ r63775 | georg.brandl | 2008-05-29 09:18:17 +0200 (Thu, 29 May 2008) | 2 lines Two fixes in bytearray docs. ........ r63781 | georg.brandl | 2008-05-29 09:38:37 +0200 (Thu, 29 May 2008) | 2 lines #2988: add note about catching CookieError when parsing untrusted cookie data. ........ r63782 | georg.brandl | 2008-05-29 09:45:26 +0200 (Thu, 29 May 2008) | 2 lines #2985: allow i8 in XMLRPC responses. ........ r63787 | georg.brandl | 2008-05-29 16:35:39 +0200 (Thu, 29 May 2008) | 2 lines Revert #2990 patch; it's not necessary as Armin showed. ........ r63805 | raymond.hettinger | 2008-05-30 08:37:27 +0200 (Fri, 30 May 2008) | 1 line Issue 2784: fix leaks in exception exit. ........ r63806 | raymond.hettinger | 2008-05-30 08:49:47 +0200 (Fri, 30 May 2008) | 1 line Issue 2855: Fix obscure crasher by slowing down the entire module. Mimics what was done to dictionaries in r59223. ........ r63807 | raymond.hettinger | 2008-05-30 09:16:53 +0200 (Fri, 30 May 2008) | 1 line Issue 2903: Add __name__ in globals for namedtuple namespace. ........ r63808 | georg.brandl | 2008-05-30 09:54:16 +0200 (Fri, 30 May 2008) | 2 lines #2999: fix name of third parameter in unicode.replace()'s docstring. ........ r63818 | georg.brandl | 2008-05-30 21:12:13 +0200 (Fri, 30 May 2008) | 2 lines getloadavg() is not available on Windows. ........ r63819 | georg.brandl | 2008-05-30 21:17:29 +0200 (Fri, 30 May 2008) | 2 lines Better quote with single quotes. ........ r63823 | benjamin.peterson | 2008-05-30 22:44:39 +0200 (Fri, 30 May 2008) | 2 lines fix grammar ........ r63824 | marc-andre.lemburg | 2008-05-30 22:52:18 +0200 (Fri, 30 May 2008) | 5 lines Update the locale module alias table. Closes #3011. ........
2008-06-10 13:57:31 -03:00
def write_multiple_items(file, separator, *args):
file.write(separator.join(args))
2007-08-15 11:28:22 -03:00
2009-01-03 17:18:54 -04:00
Normally, these ``variadic`` arguments will be last in the list of formal
2009-01-03 17:18:54 -04:00
parameters, because they scoop up all remaining input arguments that are
passed to the function. Any formal parameters which occur after the ``*args``
2009-01-03 17:18:54 -04:00
parameter are 'keyword-only' arguments, meaning that they can only be used as
keywords rather than positional arguments. ::
2009-01-03 17:18:54 -04:00
>>> def concat(*args, sep="/"):
... return sep.join(args)
...
>>> concat("earth", "mars", "venus")
'earth/mars/venus'
>>> concat("earth", "mars", "venus", sep=".")
'earth.mars.venus'
2007-08-15 11:28:22 -03:00
.. _tut-unpacking-arguments:
Unpacking Argument Lists
------------------------
The reverse situation occurs when the arguments are already in a list or tuple
but need to be unpacked for a function call requiring separate positional
arguments. For instance, the built-in :func:`range` function expects separate
*start* and *stop* arguments. If they are not available separately, write the
function call with the ``*``\ -operator to unpack the arguments out of a list
2007-08-15 11:28:22 -03:00
or tuple::
>>> list(range(3, 6)) # normal call with separate arguments
2007-08-15 11:28:22 -03:00
[3, 4, 5]
>>> args = [3, 6]
>>> list(range(*args)) # call with arguments unpacked from a list
2007-08-15 11:28:22 -03:00
[3, 4, 5]
Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r62350 | nick.coghlan | 2008-04-15 12:25:31 +0200 (Tue, 15 Apr 2008) | 1 line Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore) ........ r62351 | nick.coghlan | 2008-04-15 12:28:14 +0200 (Tue, 15 Apr 2008) | 1 line Add test file missing from rev 62350 ........ r62352 | benjamin.peterson | 2008-04-15 13:58:46 +0200 (Tue, 15 Apr 2008) | 2 lines Add myself to Doc/ACKS.txt ........ r62353 | andrew.kuchling | 2008-04-15 15:10:07 +0200 (Tue, 15 Apr 2008) | 6 lines Add *,**,@ to index, as suggested by http://farmdev.com/thoughts/24/what-does-the-def-star-variable-or-def-asterisk-parameter-syntax-do-in-python-/ The right entry type to use isn't clear; operator seems wrong, because *,**,@ aren't being used in expressions here. I put them as 'statement'; 'syntax' might be better. ........ r62354 | andrew.kuchling | 2008-04-15 15:10:41 +0200 (Tue, 15 Apr 2008) | 1 line Typo fix ........ r62355 | mark.dickinson | 2008-04-15 22:51:18 +0200 (Tue, 15 Apr 2008) | 3 lines Fix for possible signed overflow: the behaviour of -LONG_MIN is undefined in ANSI C. ........ r62358 | jeroen.ruigrok | 2008-04-16 14:47:01 +0200 (Wed, 16 Apr 2008) | 2 lines Reformat to 80 columns prior to adding documentation. ........ r62359 | jeroen.ruigrok | 2008-04-16 14:57:43 +0200 (Wed, 16 Apr 2008) | 2 lines Add details about the return value for mmap.flush(). ........ r62364 | raymond.hettinger | 2008-04-17 12:48:31 +0200 (Thu, 17 Apr 2008) | 1 line Issue 2648: Add leading zero to money format recipe in the docs. ........ r62365 | jeroen.ruigrok | 2008-04-17 14:39:45 +0200 (Thu, 17 Apr 2008) | 2 lines Be consistent in the use of read-only. ........ r62370 | andrew.kuchling | 2008-04-17 22:44:06 +0200 (Thu, 17 Apr 2008) | 1 line Typo fixes ........ r62372 | andrew.kuchling | 2008-04-18 04:40:47 +0200 (Fri, 18 Apr 2008) | 1 line Use correct parameter name ........ r62373 | andrew.kuchling | 2008-04-18 18:53:09 +0200 (Fri, 18 Apr 2008) | 1 line #2654: fix typo ........ r62374 | andrew.kuchling | 2008-04-18 20:28:23 +0200 (Fri, 18 Apr 2008) | 4 lines Remove personal note from Jim Roskind; it no longer applies, and the e-mail address is for a previous employer. Can we move the big long copyright statement into a sidebar or something? ........ r62375 | andrew.kuchling | 2008-04-18 20:39:55 +0200 (Fri, 18 Apr 2008) | 1 line Rewrite introductory section, and remove old section. (It was already commented-out, but why keep it?) ........ r62378 | skip.montanaro | 2008-04-18 22:35:46 +0200 (Fri, 18 Apr 2008) | 1 line resolve issue 2014 ........ r62379 | benjamin.peterson | 2008-04-18 22:45:33 +0200 (Fri, 18 Apr 2008) | 2 lines Fix indentation in sysmodule.c ........ r62381 | amaury.forgeotdarc | 2008-04-19 01:31:33 +0200 (Sat, 19 Apr 2008) | 3 lines Some tests did not pass on repeated calls (regrtest -R::) Perform additional cleanup, mostly deleting from sys.modules, or clearing the warnings registry. ........
2008-04-18 21:55:37 -03:00
.. index::
single: **; in function calls
Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r62350 | nick.coghlan | 2008-04-15 12:25:31 +0200 (Tue, 15 Apr 2008) | 1 line Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore) ........ r62351 | nick.coghlan | 2008-04-15 12:28:14 +0200 (Tue, 15 Apr 2008) | 1 line Add test file missing from rev 62350 ........ r62352 | benjamin.peterson | 2008-04-15 13:58:46 +0200 (Tue, 15 Apr 2008) | 2 lines Add myself to Doc/ACKS.txt ........ r62353 | andrew.kuchling | 2008-04-15 15:10:07 +0200 (Tue, 15 Apr 2008) | 6 lines Add *,**,@ to index, as suggested by http://farmdev.com/thoughts/24/what-does-the-def-star-variable-or-def-asterisk-parameter-syntax-do-in-python-/ The right entry type to use isn't clear; operator seems wrong, because *,**,@ aren't being used in expressions here. I put them as 'statement'; 'syntax' might be better. ........ r62354 | andrew.kuchling | 2008-04-15 15:10:41 +0200 (Tue, 15 Apr 2008) | 1 line Typo fix ........ r62355 | mark.dickinson | 2008-04-15 22:51:18 +0200 (Tue, 15 Apr 2008) | 3 lines Fix for possible signed overflow: the behaviour of -LONG_MIN is undefined in ANSI C. ........ r62358 | jeroen.ruigrok | 2008-04-16 14:47:01 +0200 (Wed, 16 Apr 2008) | 2 lines Reformat to 80 columns prior to adding documentation. ........ r62359 | jeroen.ruigrok | 2008-04-16 14:57:43 +0200 (Wed, 16 Apr 2008) | 2 lines Add details about the return value for mmap.flush(). ........ r62364 | raymond.hettinger | 2008-04-17 12:48:31 +0200 (Thu, 17 Apr 2008) | 1 line Issue 2648: Add leading zero to money format recipe in the docs. ........ r62365 | jeroen.ruigrok | 2008-04-17 14:39:45 +0200 (Thu, 17 Apr 2008) | 2 lines Be consistent in the use of read-only. ........ r62370 | andrew.kuchling | 2008-04-17 22:44:06 +0200 (Thu, 17 Apr 2008) | 1 line Typo fixes ........ r62372 | andrew.kuchling | 2008-04-18 04:40:47 +0200 (Fri, 18 Apr 2008) | 1 line Use correct parameter name ........ r62373 | andrew.kuchling | 2008-04-18 18:53:09 +0200 (Fri, 18 Apr 2008) | 1 line #2654: fix typo ........ r62374 | andrew.kuchling | 2008-04-18 20:28:23 +0200 (Fri, 18 Apr 2008) | 4 lines Remove personal note from Jim Roskind; it no longer applies, and the e-mail address is for a previous employer. Can we move the big long copyright statement into a sidebar or something? ........ r62375 | andrew.kuchling | 2008-04-18 20:39:55 +0200 (Fri, 18 Apr 2008) | 1 line Rewrite introductory section, and remove old section. (It was already commented-out, but why keep it?) ........ r62378 | skip.montanaro | 2008-04-18 22:35:46 +0200 (Fri, 18 Apr 2008) | 1 line resolve issue 2014 ........ r62379 | benjamin.peterson | 2008-04-18 22:45:33 +0200 (Fri, 18 Apr 2008) | 2 lines Fix indentation in sysmodule.c ........ r62381 | amaury.forgeotdarc | 2008-04-19 01:31:33 +0200 (Sat, 19 Apr 2008) | 3 lines Some tests did not pass on repeated calls (regrtest -R::) Perform additional cleanup, mostly deleting from sys.modules, or clearing the warnings registry. ........
2008-04-18 21:55:37 -03:00
In the same fashion, dictionaries can deliver keyword arguments with the
``**``\ -operator::
2007-08-15 11:28:22 -03:00
>>> def parrot(voltage, state='a stiff', action='voom'):
... print("-- This parrot wouldn't", action, end=' ')
... print("if you put", voltage, "volts through it.", end=' ')
... print("E's", state, "!")
2007-08-15 11:28:22 -03:00
...
>>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
>>> parrot(**d)
-- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !
.. _tut-lambda:
Lambda Expressions
------------------
Small anonymous functions can be created with the :keyword:`lambda` keyword.
This function returns the sum of its two arguments: ``lambda a, b: a+b``.
Lambda functions can be used wherever function objects are required. They are
syntactically restricted to a single expression. Semantically, they are just
syntactic sugar for a normal function definition. Like nested function
definitions, lambda functions can reference variables from the containing
scope::
2007-08-15 11:28:22 -03:00
>>> def make_incrementor(n):
... return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43
The above example uses a lambda expression to return a function. Another use
is to pass a small function as an argument::
>>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
>>> pairs.sort(key=lambda pair: pair[1])
>>> pairs
[(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]
2007-08-15 11:28:22 -03:00
.. _tut-docstrings:
Documentation Strings
---------------------
.. index::
single: docstrings
single: documentation strings
single: strings, documentation
Here are some conventions about the content and formatting of documentation
2009-01-03 17:18:54 -04:00
strings.
2007-08-15 11:28:22 -03:00
The first line should always be a short, concise summary of the object's
purpose. For brevity, it should not explicitly state the object's name or type,
since these are available by other means (except if the name happens to be a
verb describing a function's operation). This line should begin with a capital
letter and end with a period.
If there are more lines in the documentation string, the second line should be
blank, visually separating the summary from the rest of the description. The
following lines should be one or more paragraphs describing the object's calling
conventions, its side effects, etc.
The Python parser does not strip indentation from multi-line string literals in
Python, so tools that process documentation have to strip indentation if
desired. This is done using the following convention. The first non-blank line
*after* the first line of the string determines the amount of indentation for
the entire documentation string. (We can't use the first line since it is
generally adjacent to the string's opening quotes so its indentation is not
apparent in the string literal.) Whitespace "equivalent" to this indentation is
then stripped from the start of all lines of the string. Lines that are
indented less should not occur, but if they occur all their leading whitespace
should be stripped. Equivalence of whitespace should be tested after expansion
of tabs (to 8 spaces, normally).
Here is an example of a multi-line docstring::
>>> def my_function():
... """Do nothing, but document it.
2009-01-03 17:18:54 -04:00
...
2007-08-15 11:28:22 -03:00
... No, really, it doesn't do anything.
... """
... pass
2009-01-03 17:18:54 -04:00
...
>>> print(my_function.__doc__)
2007-08-15 11:28:22 -03:00
Do nothing, but document it.
No, really, it doesn't do anything.
.. _tut-annotations:
Function Annotations
--------------------
.. sectionauthor:: Zachary Ware <zachary.ware@gmail.com>
.. index::
pair: function; annotations
single: ->; function annotations
single: : (colon); function annotations
:ref:`Function annotations <function>` are completely optional metadata
information about the types used by user-defined functions (see :pep:`3107` and
:pep:`484` for more information).
:term:`Annotations <function annotation>` are stored in the :attr:`__annotations__`
attribute of the function as a dictionary and have no effect on any other part of the
function. Parameter annotations are defined by a colon after the parameter name, followed
by an expression evaluating to the value of the annotation. Return annotations are
defined by a literal ``->``, followed by an expression, between the parameter
list and the colon denoting the end of the :keyword:`def` statement. The
following example has a positional argument, a keyword argument, and the return
value annotated::
>>> def f(ham: str, eggs: str = 'eggs') -> str:
... print("Annotations:", f.__annotations__)
... print("Arguments:", ham, eggs)
... return ham + ' and ' + eggs
...
>>> f('spam')
Annotations: {'ham': <class 'str'>, 'return': <class 'str'>, 'eggs': <class 'str'>}
Arguments: spam eggs
'spam and eggs'
.. _tut-codingstyle:
Intermezzo: Coding Style
========================
.. sectionauthor:: Georg Brandl <georg@python.org>
.. index:: pair: coding; style
Now that you are about to write longer, more complex pieces of Python, it is a
good time to talk about *coding style*. Most languages can be written (or more
concise, *formatted*) in different styles; some are more readable than others.
Making it easy for others to read your code is always a good idea, and adopting
a nice coding style helps tremendously for that.
Merged revisions 62350-62355,62358-62359,62364-62365,62370,62372-62375,62378-62379,62381 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r62350 | nick.coghlan | 2008-04-15 12:25:31 +0200 (Tue, 15 Apr 2008) | 1 line Issue 2439: add pkgutils.get_data() as a convenience wrapper for the PEP 302 get_data() API (contributed by Paul Moore) ........ r62351 | nick.coghlan | 2008-04-15 12:28:14 +0200 (Tue, 15 Apr 2008) | 1 line Add test file missing from rev 62350 ........ r62352 | benjamin.peterson | 2008-04-15 13:58:46 +0200 (Tue, 15 Apr 2008) | 2 lines Add myself to Doc/ACKS.txt ........ r62353 | andrew.kuchling | 2008-04-15 15:10:07 +0200 (Tue, 15 Apr 2008) | 6 lines Add *,**,@ to index, as suggested by http://farmdev.com/thoughts/24/what-does-the-def-star-variable-or-def-asterisk-parameter-syntax-do-in-python-/ The right entry type to use isn't clear; operator seems wrong, because *,**,@ aren't being used in expressions here. I put them as 'statement'; 'syntax' might be better. ........ r62354 | andrew.kuchling | 2008-04-15 15:10:41 +0200 (Tue, 15 Apr 2008) | 1 line Typo fix ........ r62355 | mark.dickinson | 2008-04-15 22:51:18 +0200 (Tue, 15 Apr 2008) | 3 lines Fix for possible signed overflow: the behaviour of -LONG_MIN is undefined in ANSI C. ........ r62358 | jeroen.ruigrok | 2008-04-16 14:47:01 +0200 (Wed, 16 Apr 2008) | 2 lines Reformat to 80 columns prior to adding documentation. ........ r62359 | jeroen.ruigrok | 2008-04-16 14:57:43 +0200 (Wed, 16 Apr 2008) | 2 lines Add details about the return value for mmap.flush(). ........ r62364 | raymond.hettinger | 2008-04-17 12:48:31 +0200 (Thu, 17 Apr 2008) | 1 line Issue 2648: Add leading zero to money format recipe in the docs. ........ r62365 | jeroen.ruigrok | 2008-04-17 14:39:45 +0200 (Thu, 17 Apr 2008) | 2 lines Be consistent in the use of read-only. ........ r62370 | andrew.kuchling | 2008-04-17 22:44:06 +0200 (Thu, 17 Apr 2008) | 1 line Typo fixes ........ r62372 | andrew.kuchling | 2008-04-18 04:40:47 +0200 (Fri, 18 Apr 2008) | 1 line Use correct parameter name ........ r62373 | andrew.kuchling | 2008-04-18 18:53:09 +0200 (Fri, 18 Apr 2008) | 1 line #2654: fix typo ........ r62374 | andrew.kuchling | 2008-04-18 20:28:23 +0200 (Fri, 18 Apr 2008) | 4 lines Remove personal note from Jim Roskind; it no longer applies, and the e-mail address is for a previous employer. Can we move the big long copyright statement into a sidebar or something? ........ r62375 | andrew.kuchling | 2008-04-18 20:39:55 +0200 (Fri, 18 Apr 2008) | 1 line Rewrite introductory section, and remove old section. (It was already commented-out, but why keep it?) ........ r62378 | skip.montanaro | 2008-04-18 22:35:46 +0200 (Fri, 18 Apr 2008) | 1 line resolve issue 2014 ........ r62379 | benjamin.peterson | 2008-04-18 22:45:33 +0200 (Fri, 18 Apr 2008) | 2 lines Fix indentation in sysmodule.c ........ r62381 | amaury.forgeotdarc | 2008-04-19 01:31:33 +0200 (Sat, 19 Apr 2008) | 3 lines Some tests did not pass on repeated calls (regrtest -R::) Perform additional cleanup, mostly deleting from sys.modules, or clearing the warnings registry. ........
2008-04-18 21:55:37 -03:00
For Python, :pep:`8` has emerged as the style guide that most projects adhere to;
it promotes a very readable and eye-pleasing coding style. Every Python
developer should read it at some point; here are the most important points
extracted for you:
* Use 4-space indentation, and no tabs.
4 spaces are a good compromise between small indentation (allows greater
nesting depth) and large indentation (easier to read). Tabs introduce
confusion, and are best left out.
* Wrap lines so that they don't exceed 79 characters.
This helps users with small displays and makes it possible to have several
code files side-by-side on larger displays.
* Use blank lines to separate functions and classes, and larger blocks of
code inside functions.
* When possible, put comments on a line of their own.
* Use docstrings.
* Use spaces around operators and after commas, but not directly inside
bracketing constructs: ``a = f(1, 2) + g(3, 4)``.
* Name your classes and functions consistently; the convention is to use
``UpperCamelCase`` for classes and ``lowercase_with_underscores`` for functions
2008-09-13 14:18:21 -03:00
and methods. Always use ``self`` as the name for the first method argument
(see :ref:`tut-firstclasses` for more on classes and methods).
* Don't use fancy encodings if your code is meant to be used in international
environments. Python's default, UTF-8, or even plain ASCII work best in any
case.
* Likewise, don't use non-ASCII characters in identifiers if there is only the
slightest chance people speaking a different language will read or maintain
the code.
2007-08-15 11:28:22 -03:00
.. rubric:: Footnotes
.. [#] Actually, *call by object reference* would be a better description,
since if a mutable object is passed, the caller will see any changes the
callee makes to it (items inserted into a list).