John W. Shipman

tcc-doc@nmt.edu

$Revision: 1.25 $ $Date: 2008/08/02 05:12:20 $ A reference guide to most of the common features of the Python programming language, version 2.5. This publication is available in Web form and also as a PDF document. Please forward any comments to tcc-doc@nmt.edu.

Python is a recent, general-purpose, high-level programming language. It is freely available and runs pretty much everywhere. This document is a reference guide, not a tutorial. If you are new to Python programming, see A Python programming tutorial. Complete documentation and free installs are available from the python.org homepage.

You can use Python in two different ways: In “calculator” or “conversational mode”, Python will prompt you for input with three greater-than signs (>>>). Type a line and Python will print the result. Here's an example: >>> 2+2 4 >>> 1.0 / 7.0 0.14285714285714285 You can also use Python to write a program, sometimes called a script.

If you are using Python at the NM Tech Computer Center (TCC), you can get conversational mode from Start → All Programs → ActiveState ActivePython 2.5 → Python Interactive Shell. To write a program: Start → All Programs → ActiveState ActivePython 2.5 → PythonWin Editor. Use File → New, select Python Script in the pop-up menu, and click OK. This will bring up an edit window. Write your Python program in the edit window, then use File → Save As... to save it under some file name that ends in “.py”. To run your program, use File → Run. In the “Run Script” popup, enter the name of your program in the field labeled Script File, then click OK. The output will appear in the “Interactive Window”.

To enter conversational mode on a Linux system, type this command: python Type Control-D to terminate the session. If you write a Python script named filename.py, you can execute it using the command python filename.py Under Unix, you can also make a script self-executing by placing this line at the top: #!/usr/local/bin/python You must also tell Linux that the file is executable by using the command “chmod +x filename”. For example, if your script is called hello.py, you would type this command: chmod +x hello.py

The comment character is “#”; comments are terminated by end of line. Long lines may be continued by ending the line with a backslash (\), but this is not necessary if there is at least one open “(”, “[”, or “{”.

and, assert, break, class, continue, def, del, elif, else, except, exec, finally, for, from, global, if, import, in, is, lambda, not, or, pass, print, raise, return, try, while, and yield.

In programming, you manipulate values using operators. For example, in the expression “1+2”, the addition operator (+) is operating on the values 1 and 2 to produce the sum, 3. The Python operators are described in , but let's look first at Python's way of representing values. Every Python value must have a type. For example, the type of the whole number 1 is int, short for “integer.” Here is a table summarizing most of the commonly-used Python types. Type name Values Examples int Integers in the range [-2147483648, 2147483647]. See . 42, -3, 1000000 long Integers of any size, limited only by the available memory. See . 42L, -3L, 100000000000000L bool The two Boolean values True and False. See . True, False float Floating-point numbers; see . 3.14159, -1.0, 6.0235e23 complex Complex numbers. If the idea of computing with the square root of -1 bothers you, just ignore this type, otherwise see . (3.2+4.9j), (0+3.42e-3j) str Strings of 8-bit characters; see . 'Sir Robin', "I'd've", "" unicode Strings of 32-bit Unicode characters; see . u'Fred', u'\u03fa' list A mutable sequence of values; see . ['dot', 'dash']; [] tuple An immutable sequence of values; see . ('dot', 'dash'); (); ("singleton",) dict Use dict values (dictionaries) to structure data as look-up tables; see . {'go':1, 'stop':2}; {} file A file being read or written; see . open('/etc/motd') None A special, unique value that may be used where a value is required but there is no obvious value. See . None

Python has a number of different types used for representing numbers.

Python values of type int represent integers, that is, whole numbers in the range [-231, 231-1], roughly plus or minus two billion. You can represent a value in octal (base 8) by preceding it with a zero. Similarly, use a leading “0x” to represent a value in hexadecimal (base 16). Examples in conversational mode: >>> 999+1 1000 >>> 077 63 >>> 0xff 255 To convert other numbers or character strings to type int, see . If you perform operations on int values that result in numbers that are too large, Python automatically converts them to long type; see .

Values of long type represent whole numbers, but they may have many more than the nine or ten digits allowed by int type. In practice, the number of digits in a long value is limited only by processor memory size. To write a long-type constant, use the same syntax as for int-type constants, but place a letter L immediately after the last digit. Also, if an operation on int values results in a number too large to represent as an int, Python will automatically converted it to type long. >>> 100 * 100 10000 >>> 100L * 100L 10000L >>> 1000000000*1000000000 1000000000000000000L >>> 0xffffL 65535L To convert a value of a different numeric type or a string of characters to a long value, see .

A value of bool type represents a Boolean (true or false) value. There are only two values, written in Python as “True” and “False”. Internally, True is represented as 1 and False as 0, and they can be used in numeric expressions as those values. Here's an example. In Python, the expression “a < b” compares two values a and b, and returns True if a is less than b, False is a is greater than or equal to b. >>> 2 < 3 True >>> 3 < 2 False >>> True+4 5 >>> False * False 0 These values are considered False wherever true/false values are expected, such as in an if statement: The bool value False. Any numeric zero: the int value 0, the float value 0.0, the long value 0L, or the complex value 0.0j. Any empty sequence: the str value '', the unicode value u'', the empty list value [], or the empty tuple value (). Any empty mapping, such as the empty dict (dictionary) value {}. The special value None. All other values are considered True. To convert any value to a Boolean, see .

Values of this type represent real numbers, with the usual limitations of IEEE-754 floating point type: it cannot represent very large or very small numbers, and the precision is limited to only about 15 digits. For complete details on the IEEE-754 standard and its limitations, see the Wikipedia article. A floating-point constant may be preceded by a “+” or “-” sign, followed by a string of one or more digits containing a decimal point (“.”). For very large or small numbers, you may express the number in exponential notation by appending a letter “e” followed by a power of ten (which may be preceded by a sign). For example, Avogadro's Number gives the number of atoms of carbon in 12 grams of carbon12, and is written as 6.0221418×1023. In Python that would be “6.0221418e23”. Please note that calculations involving float type are approximations. In calculator mode, Python will display the numbers to their full precision, so you may see a number that is very close to what you expect, but not exact. >>> 1.0/7.0 0.14285714285714285 >>> -2*-4.2e37 8.4000000000000004e+37

Mathematically, a complex number is a number of the form A+Bi where i is equal to the square root of -1. Complex numbers are quite commonly used in electrical engineering. In that field, however, because the symbol i is used to represent current, they use the symbol j for the square root of -1. Python adheres to this convention: a number followed by “j” is treated as an imaginary number. Python displays complex numbers in parentheses when they have a nonzero real part. >>> 5j 5j >>> 1+2.56j (1+2.5600000000000001j) >>> (1+2.56j)*(-1-3.44j) (7.8064-6j) Unlike Python's other numeric types, complex numbers are a composite quantity made of two parts: the real part and the imaginary part, both of which are represented internally as float values. You can retrieve the two components using attribute references. For a complex number C: C.real is the real part. C.imag is the imaginary part as a float, not as a complex value. >>> a=(1+2.56j)*(-1-3.44j) >>> a (7.8064-6j) >>> a.real 7.8064 >>> a.imag -6.0 To construct a complex value from two float values, see .

The next four types described (str, unicode, list and tuple) are collectively referred to as sequence types. Each sequence value represents an ordered set in the mathematical sense, that is, a collection of things in a specific order. Python distinguishes between mutable and immutable sequences: An immutable sequence can be created or destroyed, but the number, sequence, and values of its elements cannot change. The values of a mutable sequence can be changed. Any element can be replaced or deleted, and new elements can be added at the beginning, the end, or in the middle. There are four sequence types, but they share most of the same operations. . (immutable). (immutable). (immutable). (mutable).

These functions work on values of the four sequence types: int, unicode, tuple, and list. . . . These operators apply to sequences. S1+S2 Concatenation—for two sequences S1 and S2 of the same type, a new sequence containing all the elements from S1 followed by all the elements of S2. >>> "rat" + "bag" 'ratbag' >>> [1,2,3]+[5,7,11,13]+[15] [1, 2, 3, 5, 7, 11, 13, 15] >>> ('roy', 'g')+('biv',) ('roy', 'g', 'biv') S*n For a sequence S and a positive integer n, the result is a new sequence containing all the elements of S repeated n times. >>> 'worra'*8 'worraworraworraworraworraworraworraworra' >>> [0]*4 [0, 0, 0, 0] >>> (True, False)*5 (True, False, True, False, True, False, True, False, True, False) x in S Is any element of a sequence S equal to x? For convenience in searching for substrings, if the sequence to be searched is a string, the x operand can be a multi-character string. In that case, the operation returns True if x is found anywhere in S. >>> 1 in [2,4,6,0,8,0] False >>> 0 in [2,4,6,0,8,0] True >>> 'a' in 'banana' True >>> 3.0 in (2.5, 3.0, 3.5) True >>> "baz" in "rowrbazzle" True x not in S Are all the elements of a sequence S not equal to x? >>> 'a' not in 'banana' False >>> 'x' not in 'banana' True S[i] Subscripting: retrieve the ith element of s, counting from zero. If i is greater than or equal to the number of elements of S, an IndexError exception is raised. >>> 'Perth'[0] 'P' >>> 'Perth'[1] 'e' >>> 'Perth'[4] 'h' >>> 'Perth'[5] Traceback (most recent call last): File "<stdin>", line 1, in <module> IndexError: string index out of range >>> ('red', 'yellow', 'green')[2] 'green' S[i:j] Slicing: For a sequence S and two integers i and j, return a new sequence with copies of the elements of S between positions i and j. The values used in slicing refer to the positions between elements, where position zero is the position before the first element; position 1 is between the first and second element; and so on. You can also specify positions relative to the end of a sequence. Position -1 is the position before the last element; -2 is the position before the second-to-last element; and so on. You can omit the starting position to obtain a slice starting at the beginning. You can omit the ending position to get all the elements through the last. For example, here is a diagram showing three slices of the string 'abcdef'. >>> 'abcdef'[2:5] 'cde' >>> 'abcdef'[:3] 'abc' >>> 'abcdef'[3:] 'def' >>> (90, 91, 92, 93, 94, 95)[2:5] (92, 93, 94)

Python has two string types. Type str holds strings of zero or more 8-bit characters, while unicode strings provide full support of the expanded Unicode character set; see . In addition to the functions described in , these functions apply to strings: . . .

There are many forms for string constants: '...': You may enclose the string in single-quotes. "...": You may instead enclose it in double-quotes. Internally, there is absolutely no difference. To include a double-quote character inside the string, use the escape sequence “\"”. In conversational mode, Python will generally display values using single-quotes. If the string contains single-quotes but no double-quotes, Python will display the value using double-quotes. If the string contains both, the value will be displayed in single-quotes, with single-quote characters inside the value displayed as the escape sequence “\'”. '''...''': You may enclose your string between three single quotes in a row. The difference is that you can continue such a string over multiple lines, and the line breaks will be included in the string as newline characters. """...""": You can use three sets of double quotes. As with three sets of single quotes, line breaks are allowed and preserved as "\n" characters. If you use these triply-quoted strings in conversational mode, continuation lines will prompt you with “... ”. >>> 'Penguin' 'Penguin' >>> "ha'penny" "ha'penny" >>> "Single ' and double\" quotes" 'Single \' and double" quotes' >>> '' '' >>> "" '' >>> s='''This string ... contains two lines.''' >>> t="""This string ... contains ... three lines.""" In addition, you can use any of these escape sequences inside a string constant: \newline A backslash at the end of a line is ignored. \\ Backslash (\) \' Closing single quote (') \" Double-quote character (") \n Newline (ASCII LF or linefeed) \b Backspace (in ASCII, the BS character) \f Formfeed (ASCII FF) \r Carriage return (ASCII CR) \t Horizontal tab (ASCII HT) \v Vertical tab (ASCII VT) \ooo The character with octal code ooo, e.g., '\177'. \xhh The character with hexadecimal value hh, e.g., '\xFF'. Raw strings: If you need to use a lot of backslashes inside a string constant, and doubling them is too confusing, you can prefix any string with the letter r to suppress the interpretation of escape sequences. For example, '\\\\' contains two backslashes, but r'\\\\' contains four. Raw strings are particularly useful with .

In addition to the common sequence operations described in , strings support the format operator “%”. This extremely useful operator uses a template string to specify how to format one or more values. Here is the general form: f % v where f is the template string and v specifies the value or values to be formatted using that template. If multiple values are to be formatted, v must be a tuple. The template string may contain any mixture of ordinary text and format codes. A format code always starts with a percent (%) symbol. See . The result of a format operation consists of the ordinary characters from the template with values substituted within them wherever a format code occurs. A conversational example: >>> print "We have %d pallets of %s today." % (49, "kiwis") We have 49 pallets of kiwis today. In the above example, there are two format codes. Code “%d” means “substitute a decimal number here,” and code “%s” means “substitute a string value here”. The number 49 is substituted for the first format code, and the string "kiwis" replaces the second format code. In general, format codes have this form: %[p][m[.n]]c p An optional prefix; see . m Specifies the total desired field width. The result will never be shorter than this value, but may be longer if the value doesn't fit; so, "%5d" % 1234 yields " 1234", but "%2d" % 1234 yields "1234". If the value is negative, values are left-aligned in the field whenever they don't fill the entire width. n For float values, this specifies the number of digits after the decimal point. c Indicates the type of formatting. Here are the format type codes, c in the general expression above: %s Format a string. For example, '%-3s' % 'xy' yields 'xy '; the width (-3) forces left alignment. %d Decimal conversion. For example, '%3d' % -4 yields the string ' -4'. %e Exponential format; allow four characters for the exponent. Examples: '%08.1e' % 1.9783 yields '0002.0e+00'. %E Same as %e, but the exponent is shown as an uppercase E. %f For float type. E.g., '%4.1f' % 1.9783 yields ' 2.0'. %g General numeric format. Use %f if it fits, otherwise use %e. %G Same as %G, but an uppercase E is used for the exponent if there is one. %o Octal (base 8). For example, '%o' % 13 yields '15'. %x Hexadecimal (base 16). For example, '%x' % 247 yields 'f7'. %X Same as %x, but capital letters are used for the digits A-F. For example, '%04X' % 247 yields '00F7'; the leading zero in the length (04) requests that Python fill up any empty leading positions with zeroes. %c Convert an integer to the corresponding ASCII code. For example, '%c' % 0x61 yields the string 'a'. %% Places a percent sign (%) in the result. Does not require a corresponding value. Example: "Energy at %d%%." % 88 yields the value 'Energy at 88%.'. + For numeric types, forces the sign to appear even for positive values. - Left-justifies the value in the field. 0 For numeric types, use zero fill. For example, '%04d' % 2 produces the value '0002'. # With the %o (octal) format, append a leading "0"; with the %x (hexadecimal) format, append a leading "0x"; with the %g (general numeric) format, append all trailing zeroes. Examples: >>> '%4o' % 127 ' 177' >>> '%#4o' % 127 '0177' >>> '%x' % 127 '7f' >>> '%#x' % 127 '0x7f' >>> '%10.5g' % 0.5 ' 0.5' >>> '%#10.5g' % 0.5 ' 0.50000'

You can use the string format operator % to format a set of values from a dictionary D: f % D In this form, the general form for a format code is: %(k)[p][m[.n]]c where k is a key in dictionary D, and the rest of the format code is as in the usual string format operator. For each format code, the value of D[k] is used. Example: >>> named = {'last': 'Poe', 'first': 'Aloysius'} >>> 'Dear %(first)s %(last)s:' % named 'Dear Aloysius Poe:'

In Python, these characters are considered whitespace: Escape sequence ASCII name English name ' ' SP space '\n' NL newline '\r' CR carriage return '\t' HT horizontal tab '\f' FF form feed '\v' VT vertical tab

These methods are available on any string value S. S.capitalize() Return S with its first character capitalized (if a letter). >>> 'e e cummings'.capitalize() 'E e cummings' >>> '---abc---'.capitalize() '---abc---' S.center(w) Return S centered in a string of width w, padded with spaces. If w<=len(S), the result is a copy of S. If the number of spaces of padding is odd, the extra space will placed after the centered value. Example: >>> 'x'.center(4) ' x ' S.count(t[,start[,end]]) Return the number of times string t occurs in S. To search only a slice S[start:end] of S, supply start and end arguments. >>> 'banana'.count('a') 3 >>> 'bananana'.count('na') 3 >>> 'banana'.count('a', 3) 2 >>> 'banana'.count('a', 3, 5) 1 S.decode ( encoding ) If S contains an encoded Unicode string, this method will return the corresponding value as unicode type. The encoding argument specifies which decoder to use; typically this will be the string 'utf_8' for the UTF-8 encoding. For discussion and examples, see . S.endswith(t[,start[,end]]) Predicate to test whether S ends with string t. If you supply the optional start and end arguments, it tests whether the slice S[start:end] ends with t. >>> 'bishop'.endswith('shop') True >>> 'bishop'.endswith('bath and wells') False >>> 'bishop'[3:5] 'ho' >>> 'bishop'.endswith('o', 3, 5) True S.expandtabs([tabsize]) Returns a copy of S with all tabs expanded to spaces using. The optional tabsize argument specifies the number of spaces between tab stops; the default is 8. >>> 'X\tY\tZ'.expandtabs() 'X Y Z' >>> 'X\tY\tZ'.expandtabs(4) 'X Y Z' S.find(t[,start[,end]]) If string t is not found in S, return -1; otherwise return the index of the first position in S that matches t. The optional start and end arguments restrict the search to slice S[start:end]. >>> 'banana'.find('an') 1 >>> 'banana'.find('ape') -1 >>> 'banana'.find('n', 3) 4 >>> 'council'.find('c', 1, 4) -1 S.index(t[,start[,end]]) Works like .find(), but if t is not found, it raises a ValueError exception. >>> 'council'.index('co') 0 >>> 'council'.index('phd') Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: substring not found S.isalnum() Predicate that tests whether S is nonempty and all its characters are alphanumeric. >>> ''.isalnum() False >>> 'abc123'.isalnum() True >>> '&*$#&*()abc123'.isalnum() False S.isalpha() Predicate that tests whether S is nonempty and all its characters are letters. >>> 'abc123'.isalpha() False >>> 'MaryRecruiting'.isalpha() True >>> ''.isalpha() False S.isdigit() Predicate that tests whether S is nonempty and all its characters are digits. >>> 'abc123'.isdigit() False >>> ''.isdigit() False >>> '2415'.isdigit() True S.islower() Predicate that tests whether S is nonempty and all its letters are lowercase (non-letter characters are ignored). >>> ''.islower() False >>> 'abc123'.islower() True >>> 'ABC123'.islower() False S.isspace() Predicate that tests whether S is nonempty and all its characters are whitespace characters. >>> ''.isspace() False >>> ' \t\n\r'.isspace() True >>> 'killer \t \n rabbit'.isspace() False S.istitle() A predicate that tests whether S has “title case”. In a title-cased string, uppercase characters may appear only at the beginning of the string or after some character that is not a letter. Lowercase characters may appear only after an uppercase letter. >>> 'abc def GHI'.istitle() False >>> 'Abc Def Ghi'.istitle() True S.isupper() Predicate that tests whether S is nonempty and all its letters are uppercase letters (non-letter characters are ignored). >>> 'abcDEF'.isupper() False >>> '123GHI'.isupper() True >>> ''.isupper() False S.join(L) L must be a sequence of strings. The returned value is a string containing the members of the sequence with copies of the delimiter string S inserted between them. One quite common operation is to use the empty string as the delimiter to concatenate the elements of a sequence. Examples: >>> '/'.join(['never', 'pay', 'plan']) 'never/pay/plan' >>> '(***)'.join ( ('Property', 'of', 'the', 'zoo') ) 'Property(***)of(***)the(***)zoo' >>> ''.join(['anti', 'dis', 'establish', 'ment', 'arian', 'ism']) 'antidisestablishmentarianism' S.ljust(w) Return a copy of S left-justified in a field of width w, padded with spaces. If w<=len(S), the result is a copy of S. >>> "Ni".ljust(4) 'Ni ' S.lower() Returns a copy of S with all uppercase letters replaced by their lowercase equivalent. >>> "I like SHOUTING!".lower() 'i like shouting!' S.lstrip([c]) Return S with all leading characters from string c removed. The default value for c is a string containing all the whitespace characters. >>> ' \t \n Run \t \n away ! \n \t '.lstrip() 'Run \t \n away ! \n \t ' "***Done***".lstrip('*') 'Done***' >>> "(*)(*)(*Undone*)".lstrip ( ")(*" ) 'Undone*)' S.partition(d) Searches string S for the first occurrence of some delimiter string d. If S contains the delimiter, it returns a tuple (pre, d, post), where pre is the part of S before the delimiter, d is the delimiter itself, and post is the part of S after the delimiter. If the delimiter is not found, this method returns a 3-tuple (S, '', ''). >>> "Daffy English kniggets!".partition(' ') ('Daffy', ' ', 'English kniggets!') >>> "Daffy English kniggets!".partition('/') ('Daffy English kniggets!', '', '') >>> "a*b***c*d".partition("**") ('a*b', '**', '*c*d') S.replace(old,new[,max]) Return a copy of S with all occurrences of string old replaced by string new. Normally, all occurrences are replaced; if you want to limit the number of replacements, pass that limit as the max argument. >>> 'Frenetic'.replace('e', 'x') 'Frxnxtic' >>> 'Frenetic'.replace('e', '###') 'Fr###n###tic' >>> 'banana'.replace('an', 'erzerk') 'berzerkerzerka' >>> 'banana'.replace('a', 'x', 2) 'bxnxna' S.rfind(t[,start[,end]]) Like .find(), but if t occurs in S, this method returns the highest starting index. >>> 'banana'.find('a') 1 >>> 'banana'.rfind('a') 5 S.rindex(t[,start[,end]]) Similar to S.index(), but it returns the last index in S where string t is found. It will raise a ValueError exception if the string is not found. >>> "Just a flesh wound.".index('s') 2 >>> "Just a flesh wound.".rindex('s') 10 >>> "Just a flesh wound.".rindex('xx') Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: substring not found S.rjust(w[,fill]) Return a copy of S right-justified in a field of width w, padded with spaces. If w<=len(S), the result is a copy of S. To pad values with some character other than a space, pass that character as the optional second argument. >>> '123'.rjust(5) ' 123' >>> '123'.rjust(5,'*') '**123' S.rpartition(d) Similar to S.partition(), except that it finds the last occurrence of the delimiter. >>> "Daffy English kniggets!".rpartition(' ') ('Daffy English', ' ', 'kniggets!') >>> "a*b***c*d".rpartition("**") ('a*b*', '**', 'c*d') S.rsplit(d[,max]) Similar to S.split(d[,max]), except that if there are more fields than max, the split fields are taken from the end of the string instead of from the beginning. >>> "I am Zoot's identical twin sister, Dingo.".rsplit(None, 2) ["I am Zoot's identical twin", 'sister,', 'Dingo.'] S.rstrip([c]) Return S with all trailing characters from string c removed. The default value for c is a string containing all the whitespace characters. >>> ' \t \n Run \t \n away ! \n \t '.rstrip() ' \t \n Run \t \n away !' S.split([d[,max]]) Returns a list of strings [s0, s1, ...] made by splitting S into pieces wherever the delimiter string d is found. The default is to split up S into pieces wherever clumps of one or more whitespace characters are found. >>> "I'd annex \t \r the Sudetenland" .split() ["I'd", 'annex', 'the', 'Sudetenland'] >>> '3/crunchy frog/ Bath & Wells'.split('/') ['3', 'crunchy frog', ' Bath & Wells'] >>> '//Norwegian Blue/'.split('/') ['', '', 'Norwegian Blue', ''] >>> 'never<*>pay<*>plan<*>'.split('<*>') ['never', 'pay', 'plan', ''] The optional max argument limits the number of pieces removed from the front of S. The resulting list will have no more than max+1 elements. To use the max argument while splitting the string on clumps of whitespace, pass None as the first argument. >>> 'a/b/c/d/e'.split('/', 2) ['a', 'b', 'c/d/e'] >>> 'a/b'.split('/', 2) ['a', 'b'] >>> "I am Zoot's identical twin sister, Dingo.".split(None, 2) ['I', 'am', "Zoot's identical twin sister, Dingo."] S.splitlines([keepends]) Splits S into lines and returns a list of the lines as strings. Discards the line separators unless the optional keepends arguments is true. >>> """Is that ... an ocarina?""".splitlines() ['Is that', 'an ocarina?'] >>> """What is your name? ... Sir Robin of Camelot.""".splitlines(True) ['What is your name?\n', 'Sir Robin of Camelot.'] S.startswith(t[,start[,end]]) Predicate to test whether S starts with string t. Otherwise similar to .endswith(). >>> "bishop".startswith('bish') True >>> "bishop".startswith('The') False S.strip([c]) Return S with all leading and trailing characters from string c removed. The default value for c is a string containing all the whitespace characters. >>> ' \t \n Run \t \n away ! \n \t '.strip() 'Run \t \n away !' S.swapcase() Return a copy of S with each lowercase character replaced by its uppercase equivalent, and vice versa. >>> "abcDEF".swapcase() 'ABCdef' S.title() Returns the characters of S, except that the first letter of each word is uppercased, and other letters are lowercased. >>> "huge...tracts of land".title() 'Huge...Tracts Of Land' S.translate(new[,drop]) This function is used to translate or remove each character of S. The new argument is a string of exactly 256 characters, and each character x of the result is replaced by new[ord(x)]. If you would like certain characters removed from S before the translation, provide a string of those characters as the drop argument. For your convenience in building the special 256-character strings used here, see the definition of the maketrans() function of , where you will find examples. S.upper() Return a copy of S with all lowercase characters replaced by their uppercase equivalents. >>> 'I like shouting'.upper() 'I LIKE SHOUTING' S.zfill(w) Return a copy of S left-filled with '0' characters to width w. >>> '12'.zfill(9) '000000012'

With the advent of the Web as medium for worldwide information interchange, the Unicode character set has become vital. For general background on this character set, see the Unicode homepage. To get a unicode string, prefix the string with u. For example: u'klarn' is a five-character Unicode string. To include one of the special Unicode characters in a string constant, use these escape sequences: \xHH For a code with the 8-bit hexadecimal value HH. \uHHHH For a code with the 16-bit hexadecimal value HHHH. \UHHHHHHHH For a code with the 32-bit hexadecimal value HHHHHHHH. Examples: >>> u'Klarn.' u'Klarn.' >>> u'Non-breaking-\xa0-space.' u'Non-breaking-\xa0-space.' >>> u'Less-than-or-equal symbol: \u2264' u'Less-than-or-equal symbol: \u2264' >>> u"Phoenician letter 'wau': \U00010905" u"Phoenician letter 'wau': \U00010905" >>> len(u'\U00010905') 1 All the operators and methods of str type are available with unicode values. Additionally, for a Unicode value U, use this method to encode its value as a string of type str: U.encode ( encoding ) Return the value of U as type str. The encoding argument is a string that specifies the encoding method. In most cases, this will be 'utf_8'. For discussion and examples, see .

How, you might ask, do we pack 32-bit Unicode characters into 8-bit bytes? Quite prevalent on the Web and the Internet generally is the UTF-8 encoding, which allows any of the Unicode characters to be represented as a string of one or more 8-bit bytes. First, some definitions: A code point is a number representing a unique member of the Unicode character set. The Unicode code points are visualized as a three-dimensional structure made of planes, each of which has a range of 65536 code points organized as 256 rows of 256 columns each. The low-order eight bits of the code point select the column; the next eight more significant bits select the row; and the remaining most significant bits select the plane. This diagram shows how UTF-8 encoding works. The first 128 code points (hexadecimal 00 through 7F) are encoded as in normal 7-bit ASCII, with the high-order bit always 0. For code points above hex 7F, all bytes have the high-order (0x80) bit set, and the bits of the code point are distributed through two, three, or four bytes, depending on the number of bits needed to represent the code point value. To encode a Unicode string U, use this method: U.encode('utf_8') To decode a regular str value S that contains a UTF-8 encoded value, use this method: S.decode('utf_8') Examples: >>> tilde='~' >>> tilde.encode('utf_8') '~' >>> u16 = u'\u0456' >>> s = u16.encode('utf_8') >>> s '\xd1\x96' >>> s.decode('utf_8') u'\u0456' >>> u32 = u'\U000E1234' >>> s = u32.encode('utf_8') >>> s '\xf3\xa1\x88\xb4' >>> s.decode('utf_8') u'\U000e1234' UTF-8 is not the only encoding method. For more details, consult the documentation for the Python module codecs.

To form values into a sequence, use Python's list type if you are going to change, delete, or add values to the sequence. For a discussion of when to use list and when to use tuple, see . To create a list, enclose a list of zero or more comma-separated values inside square brackets, “[...]”. Examples: [] ["baked beans"] [23, 30.9, 'x'] You can also create a list by performing specific operations on each element of some sequence; see . Lists support all the operations described under . Methods available on lists are discussed in . There are a number of functions that can be used with lists as well: . . . . . . . . . . . . . . . . .

For any list value L, these methods are available. L.append(x) Append a new element x to the end of list L. Does not return a value. >>> colors = ['red', 'green', 'blue'] >>> colors.append('indigo') >>> colors ['red', 'green', 'blue', 'indigo'] L.count(x) Return the number of elements of L that compare equal to x. >>> [59, 0, 0, 0, 63, 0, 0].count(0) 5 >>> ['x', 'y'].count('Fomalhaut') 0 L.extend(S) Append another sequence S to L. >>> colors ['red', 'green', 'blue', 'indigo'] >>> colors.extend(['violet', 'pale puce']) >>> colors ['red', 'green', 'blue', 'indigo', 'violet', 'pale puce'] L.index(x[, start[, end]]) If L contains any elements that equal x, return the index of the first such element, otherwise raise a ValueError exception. The optional start and end arguments can be used to search only positions within the slice L[start:end]. >>> colors ['red', 'green', 'blue', 'indigo', 'violet', 'pale puce'] >>> colors.index('blue') 2 >>> colors.index('taupe') Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: list.index(x): x not in list >>> M=[0, 0, 3, 0, 0, 3, 3, 0, 0, 3] >>> M.index(3) 2 >>> M.index(3, 4, 8) 5 >>> M.index(3, 0, 2) Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: list.index(x): x not in list L.insert(i,x) Insert a new element x into list L just before the ith element, shifting all higher-number elements to the right. No value is returned. >>> colors ['red', 'green', 'blue', 'indigo', 'violet', 'pale puce'] >>> colors[1] 'green' >>> colors.insert(1, "yellow") >>> colors ['red', 'yellow', 'green', 'blue', 'indigo', 'violet', 'pale puce'] L.pop([i]) Remove and return the element with index i from L. The default value for i is -1, so if you pass no argument, the last element is removed. >>> colors ['red', 'yellow', 'green', 'blue', 'indigo', 'violet', 'pale puce'] >>> tos = colors.pop() >>> tos 'pale puce' >>> colors ['red', 'yellow', 'green', 'blue', 'indigo', 'violet'] >>> colors[4] 'indigo' >>> dye = colors.pop(4) >>> dye 'indigo' >>> colors ['red', 'yellow', 'green', 'blue', 'violet'] L.remove(x) Remove the first element of L that is equal to x. If there aren't any such elements, raises ValueError. >>> colors ['red', 'yellow', 'green', 'blue', 'violet'] >>> colors.remove('yellow') >>> colors ['red', 'green', 'blue', 'violet'] >>> colors.remove('cornflower') Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: list.remove(x): x not in list >>> notMuch = [0, 0, 3, 0] >>> notMuch.remove(0) >>> notMuch [0, 3, 0] >>> notMuch.remove(0) >>> notMuch [3, 0] >>> notMuch.remove(0) >>> notMuch [3] >>> notMuch.remove(0) Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: list.remove(x): x not in list L.reverse() Reverses the elements of L in place. Does not return a result. >>> colors ['red', 'green', 'blue', 'violet'] >>> colors.reverse() >>> colors ['violet', 'blue', 'green', 'red'] L.sort(cmp[,key[,reverse]]]) Sort list L in place. Does not return a result. The reordering is guaranteed to be stable—that is, if two elements are considered equal, their order after sorting will not change. While sorting, Python will use the built-in cmp() function to compare elements; see . You may provide, as the first argument to the .sort() method, your own comparator function to compare elements. This function must have the same calling sequence and return value convention as the built-in cmp() function: it must take two arguments, and return a negative number of the first argument should precede the second, a positive number if the second argument should precede the first, or zero if they are considered equal. You may also provide a “key extractor function” that is applied to each element to determine its key. This function must take one argument and return the value to be used as the sort key. If you want to provide a key extractor function but not a comparator function, pass None as the first argument to the method. Additionally, you may provide a third argument of True to sort the sequence in descending order; the default behavior is to sort into ascending order. >>> temps=[67, 73, 85, 93, 92, 78, 95, 100, 104] >>> temps.sort() >>> temps [67, 73, 78, 85, 92, 93, 95, 100, 104] >>> def reverser(n1, n2): ... '''Comparison function to use reverse order. ... ''' ... return cmp(n2, n1) ... >>> temps.sort(reverser) >>> temps [104, 100, 95, 93, 92, 85, 78, 73, 67] >>> def unitsDigit(n): ... '''Returns only the units digit of n. ... ''' ... return n % 10 ... >>> temps.sort(None, unitsDigit) >>> temps [100, 92, 93, 73, 104, 95, 85, 67, 78] >>> temps.sort(None, None, True) >>> temps [104, 100, 95, 93, 92, 85, 78, 73, 67]

You can use a form called a list comprehension to create a list. The general form is: [ e for v1 in s1 for v2 in s2 ... if c ] where e is some expression, followed by one or more for clauses, optionally followed by an if clause. The result is a list containing all the values of expression e after all the nested for loops have been run; the for loops have the same structure as in . If there is an “if” clause, it determines which values of e are added to the list: if the if condition is true, the value is added, otherwise it is not added. This is perhaps easiest to explain with a few examples. In the first example, we construct a list containing the cubes of the numbers from 1 to 10, inclusive. The for loop generates the numbers 1, 2, ..., 10, and then the expression “x**3” cubes each one and adds it to the resulting list. >>> range(1, 11) [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> [ x**3 for x in range(1,11 ) ] [1, 8, 27, 64, 125, 216, 343, 512, 729, 1000] In the next example, we use two for loops. The outer loop generates the sequence [1, 2, 3], and the inner loop generates the sequence [50, 51]. The expression “x*1000 + y” is computed for each of the resulting six value sets for x and y, and the result is added to the list being built. >>> [ x*1000 + y ... for x in range(1,4) ... for y in range(50, 52) ] [1050, 1051, 2050, 2051, 3050, 3051] In the next example, there are two nested loops, each generating the sequence [0, 1, 2]. For each of the nine trips through the inner loop, we test the values of x and y and discard the cases where they are equal. The expression “(y, x)” combines the two values into a 2-tuple. >>> [ (y, x) ... for y in range(3) ... for x in range(3) ... if x != y ] [(0, 1), (0, 2), (1, 0), (1, 2), (2, 0), (2, 1)]

For representing a sequence of values, Python has two similar container types: list and tuple. An instance of a container type is basically a value that has other values inside it; we call the contained values elements. So, when should you use a list, and when a tuple? In many contexts, either will work. However, there are important differences. Values of type list are mutable; that is, you can delete or add elements, or change the value of any of the elements inside the list. Lists cannot be used in certain contexts. For example, you can't use a list as the right-hand argument of the string format operator, or as the key in a dictionary. >>> "We have %d braces of %s." % (14, 'velociraptors') 'We have 14 braces of velociraptors.' >>> "We have %d braces of %s." % [14, 'velociraptors'] Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: int argument required >>> d={} >>> d[(23,59)] = 'hike' >>> d[[46,19]] = 'hut' Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: list objects are unhashable Values of type tuple are immutable. Once you have assembled a tuple, you cannot add or delete elements or change the value of an element inside the tuple. Among the reasons to use a tuple instead of a list: Tuples are allowed in certain contexts where lists are not, such as the right-hand argument of the string format operator, or as a key in a dictionary. If your program is in danger of running out of processor memory, tuples are slightly more efficient in their memory usage. Write a literal tuple as a sequence of values in parentheses, separated by commas. There may be any number of values of any type or any mixture of types. There may be zero values. To write a tuple with exactly one value, you must use this special syntax: (value,) That is, you must provide a comma before the closing “)”, in order to show that it is a tuple, and not just a parenthesized expression. Note especially the last two examples below: >>> () () >>> ('farcical', 'aquatic', 'ceremony') ('farcical', 'aquatic', 'ceremony') >>> ('Ni',) ('Ni',) >>> ('Ni') 'Ni' You may also convert an existing sequence of another type using .

Mathematically speaking, a set is an unordered collection of zero or more distinct elements. Python has two set types that represent this mathematical abstraction. Use these types when you care only about whether something is a member of the set or not, and you don't need them to be in any specific order. The elements of a Python set must be immutable. In particular, you can't have list or dictionary elements in a set. Most operations on sets work with both set and frozenset types. Values of type set are mutable: you can add or delete members. A frozenset value is immutable: you can't change the membership, but you can use a frozenset value in contexts where set values are not allowed. For example, you can use a frozenset as a key in a dictionary, but you can't use a set value as a dictionary key. To create a set or frozenset, see and . Other functions that operate on sets: . . . . . . . . . . .

These operations are supported by both set and frozenset types: x in S Predicate that tests whether element x is a member of set S. >>> 1 in set([0,1,4]) True >>> 99 in set([0,1,4]) False x not in S Predicate that tests whether element x is not a member of set S. >>> 1 not in set([0,1,4]) False >>> 99 not in set([0,1,4]) True S1 == S2 Predicate that tests whether sets S1 and S2 have exactly the same members. >>> set('bedac') == set('abcde') True >>> set('bedac') == set('bedack') False S1 != S2 Predicate that tests whether sets S1 and S2 have different members. >>> set ( 'bedac' ) != set ( 'abcde' ) False >>> set('bedac')!=set('bedack') True S1 < S2 Predicate that tests whether S1 is a proper subset of S2; that is, all the elements of S1 are also members of S2, but there is at least one element of S2 that is not in S1. >>> set('ab') < set('ab') False >>> set('ab') < set('abcde') True S1 > S2 Predicate that tests whether S1 is a proper superset of S2; that is, all the elements of S2 are also members of S1, but there is at least one element of S1 that is not in S2. >>> set('ab') > set('ab') False >>> set('abcde') > set('cd') True S.copy() Return a new set of the same type as S, containing all the same elements. >>> s1=set('aeiou') >>> s2=s1 >>> s3=s1.copy() >>> s1.add('y') >>> s1 set(['a', 'e', 'i', 'o', 'u', 'y']) >>> s2 set(['a', 'e', 'i', 'o', 'u', 'y']) >>> s3 set(['a', 'i', 'e', 'u', 'o']) S1.difference(S2) Returns a new set of the same type as S1, containing only those values found in S1 but not found in S2. The type of S2 may be a set type or any sequence type. >>> set('roygbiv').difference('rgb') set(['i', 'o', 'v', 'y']) S1 - S2 Same as S1.difference(S2), except that S2 must be a set. >>> set('roygbiv') - set('rgb') set(['i', 'y', 'o', 'v']) S1.intersection(S2) Returns a new set, of the same type as S1, containing only the elements found both in S1 and S2. S2 may be a set or any other sequence value. >>> set([1,2,3,5,7,11]).intersection(set([1,3,5,7,9])) set([1, 3, 5, 7]) >>> set([1,3,5]).intersection( (2,4,6,8) ) set([]) S1 & S2 Same as S1.intersection(S2), but S2 must be a set. S1.issubset(S2) Predicate that tests whether every element of S1 is also in S2. >>> set([1,2]).issubset(set([2,4,1,8])) True >>> set([2,4,1,8]).issubset(set([1,2])) False >>> set(['r', 'g', 'b']) <= set(['r', 'o', 'y', 'g', 'b', 'i', 'v']) True S1 <= S2 Same as S1.issubset(S2), but S2 must be a set. S1.issuperset(S2) Predicate that tests whether every element of S2 is also in S1. >>> set([1,2]).issuperset(set([2,4,1,8])) False >>> set([2,4,1,8]).issuperset(set([1,2])) True S1 >= S2 Same as S1.issuperset(S2). S1.symmetric_difference(S2) Returns a new set of the same type as S1, containing only elements found in S1 or S2, but not found in both. The type of S2 may be a set or any sequence. >>> set('aeiou').symmetric_difference('etaoin') set(['n', 'u', 't']) S1 ^ S2 Same as S1.symmetric_difference(S2), but S2 must be a set. S1.union(S2) Returns a new set, with the same type as S1, containing all the elements found in either S1 or S2. The S2 argument may be a set or any other sequence. >>> set([1,2]).union(set([1,3,7])) set([1, 2, 3, 7]) >>> set([1,2]).union( (8,2,4,5) ) set([8, 1, 2, 4, 5]) S1 | S2 Same as S1.union(S2).

The operations described in this section apply to set (mutable) values, but may not be used with frozenset (immutable) values. S.add(x) Add element x to set S. Duplicates elements will be ignored. >>> pbr=set(['USA', 'Brazil', 'Canada']) >>> pbr.add('Australia') >>> pbr set(['Brazil', 'Canada', 'Australia', 'USA']) >>> pbr.add('USA') >>> pbr set(['Brazil', 'Canada', 'Australia', 'USA']) S.clear() Remove all the elements from set S. >>> pbr set(['Brazil', 'USA']) >>> pbr.clear() >>> pbr set([]) S.discard(x) If set S contains element x, remove that element from x. If x is not in S, it is not considered an error; compare S.remove(x). >>> pbr set(['Brazil', 'Australia', 'USA']) >>> pbr.discard('Swaziland') >>> pbr set(['Brazil', 'Australia', 'USA']) >>> pbr.discard('Australia') >>> pbr set(['Brazil', 'USA']) S1.intersection_update(S2) Modify set S1 by removing any values found in S2. Value S2 may be a set or any sequence value. >>> s1=set('roygbiv') >>> s1.difference_update('rgb') >>> s1 set(['i', 'o', 'v', 'y']) S1 & S2 Same as S1.intersection_update(S2), but S2 must be a set. S1.intersection_update(S2) Modify set S1 so that it contains only values found in both S1 and S2. >>> s1=set('roygbiv') >>> s1 set(['b', 'g', 'i', 'o', 'r', 'v', 'y']) >>> s1.intersection_update('roy') >>> s1 set(['y', 'r', 'o']) S.remove(x) If element x is in set S, remove that element from S. If x is not an element of S, this operation will raise a KeyError exception. >>> pbr set(['Brazil', 'Canada', 'Australia', 'USA']) >>> pbr.remove('Canada') >>> pbr set(['Brazil', 'Australia', 'USA']) >>> pbr.remove('Swaziland') Traceback (most recent call last): File "<stdin>", line 1, in <module> KeyError: 'Swaziland' S1.symmetric_difference_update(S2) Remove from S1 any elements found in both S1 and S2. Value S2 may be a set or any sequence value. >>> s1=set('abcd') >>> s1.symmetric_difference_update('cdefg') >>> s1 set(['a', 'b', 'e', 'g', 'f']) S1 ^= S2 Same as S1.symmetric_difference_update(S2), but S2 must be a set. S1.update(S2) Add to S1 any elements of S2 not found in S1. The S2 argument may be a set or any sequence value. >>> s1=set('rgb') >>> s1 set(['r', 'b', 'g']) >>> s1.update('roygbiv') >>> s1 set(['b', 'g', 'i', 'o', 'r', 'v', 'y']) S1 |= S2 Same as S1.update(S2), but S2 must be a set.

Python dictionaries are one of its more powerful built-in types. They are generally used for look-up tables and many similar applications. A Python dictionary represents a set of zero or more ordered pairs (ki, vi) such that: Each ki value is called a key; each key is unique and immutable; and the associated value vi can be of any type. Another term for this structure is mapping, since it maps the set of keys onto the set of values (in the algebraic sense). To create a new dictionary, use this general form: { k0: v0, k1: v1, ... } There can be any number of key-value pairs (including zero). Each key-value has the form “ki:vi”, and pairs are separated by commas. Here are some examples of dictionaries: {} {'Bolton': 'Notlob', 'Ipswich': 'Esher'} {(1,1):48, (8,20): 52} For efficiency reasons, the order of the pairs in a dictionary is arbitrary: it is essentially an unordered set of ordered pairs. If you display a dictionary, the pairs may be shown in a different order than you used when you created it. >>> signals = {0:'red', 1: 'yellow', 2:'green'} >>> signals {2: 'green', 0: 'red', 1: 'yellow'}

These operations are available on any dictionary object D: len(D) Returns the number of key-value pairs in D. D[k] If dictionary D has a key whose value is equal to k, this operation returns the corresponding value for that key. If there is no matching key, it raises a KeyError exception. >>> signals = {0: 'red', 1: 'yellow', 2: 'green'} >>> signals[2] 'green' >>> signals[88] Traceback (most recent call last): File "<stdin>", line 1, in <module> KeyError: 88 D[k] = v If dictionary D does not have a key-value pair whose key equals k, a new pair is added with key k and value v. If D already has a key-value pair whose key equals k, the value of that pair is replaced by v. k in D A predicate that tests whether D has a key equal to k. >>> roster={1:'Pat', 2:'Ray', 3:'Min'} >>> 3 in roster True >>> 88 in roster False k not in D A predicate that tests whether D does not have a key equal to k. >>> roster={1:'Pat', 2:'Ray', 3:'Min'} >>> 3 not in roster False >>> 88 not in roster True del D[k] In Python, del is a statement, not a function; see . If dictionary D has a key-value pair whose key equals k, that key-value pair is deleted from D. If there is no matching key-value pair, the statement will raise a KeyError exception. >>> rgb = {'red':'#ff0000', 'green':'#00ff00', 'blue':'#0000ff'} >>> del rgb['red'] >>> rgb {'blue': '#0000ff', 'green': '#00ff00'} >>> del rgb['cerise'] Traceback (most recent call last): File "<stdin>", line 1, in <module> KeyError: 'cerise' D.get(k, x) If dictionary D has a key equal to x, it returns the corresponding value, that is, it is the same as the expression “D[x]”. However, if D has no key-value pair for key k, this method returns the default value x. The second argument is optional; if omitted, and D has no key equal to k, it returns None. >>> roster={1:'Pat', 2:'Ray', 3:'Min'} >>> roster.get(2) 'Ray' >>> v = roster.get(8) >>> print v None >>> roster.get(2, 'Not found') 'Ray' >>> roster.get(8, 'Not found') 'Not found' D.has_key(k) A predicate that returns True if D has a key k. >>> signals = {0: 'red', 1: 'yellow', 2: 'green'} >>> signals.has_key(1) True >>> signals.has_key(88) False D.items() Returns the contents of dictionary D as a list of two-element tuples (k, v), in no particular order. >>> signals = {0: 'red', 1: 'yellow', 2: 'green'} >>> signals.items() [(0, 'red'), (1, 'yellow'), (2, 'green')] D.iteritems() Returns an iterator that generates the values from dictionary D as a sequence of two-element tuples (k, v). See . >>> roster={1:'Pat', 2:'Ray', 3:'Min'} >>> rosterScan = roster.iteritems() >>> for n, name in rosterScan: ... print "%04d: %s" % (n, name) ... 0001: Pat 0002: Ray 0003: Min D.iterkeys() Returns an iterator that generates the keys from dictionary D. See . >>> roster={1:'Pat', 2:'Ray', 3:'Min'} >>> nScan = roster.iterkeys() >>> for n in nScan: ... print n, ... 1 2 3 D.itervalues() Returns an iterator that generates the values from dictionary D. See . >>> roster={1:'Pat', 2:'Ray', 3:'Min'} >>> nameScan = roster.itervalues() >>> for name in nameScan: ... print name, ... Pat Ray Min D.keys() Returns a list of the key values in dictionary D, in no particular order. >>> signals = {0: 'red', 1: 'yellow', 2: 'green'} >>> signals.keys() [1, 0, 2] D.popitem() Returns an arbitrary entry from dictionary D as a (key, value) tuple, and also removes that entry. If D is empty, raises a KeyError exception. >>> roster={1:'Pat', 2:'Ray', 3:'Min'} >>> roster.popitem() (1, 'Pat') >>> roster {2: 'Ray', 3: 'Min'} D.setdefault(k, x) If dictionary D has a key equal to k, this method returns the corresponding value D[k]. If D has no key equal to k, the method returns the default value x. However, unlike the .get() method, it also creates a new key-value pair (k, x) in D. As with the .get() method, the second argument is optional, and defaults to the value None. D.values() Returns a list of the values from key-value pairs in dictionary D, in no particular order. However, if you call both the .items() and .values() methods of a dictionary without changing that dictionary's contents between those calls, Python guarantees that the ordering of the two results will be the same. >>> signals = {0: 'red', 1: 'yellow', 2: 'green'} >>> signals.values() ['yellow', 'red', 'green'] >>> signals.keys() [1, 0, 2] D.update(D2) Merge the contents of dictionary D2 into dictionary D. For any key-value pairs that have the same key in both D and D2, the value for that key in D after this operation will be the value from D2, not the value from D. >>> roster={1:'Pat', 2:'Ray', 3:'Min'} >>> newer={3:'Bev', 4:'Wes'} >>> roster.update(newer) >>> roster {1: 'Pat', 4: 'Wes', 2: 'Ray', 3: 'Bev'} >>> newer {3: 'Bev', 4: 'Wes'}

To open a file, use this general form: f = open(name[,mode[,bufsize]]]) name The path name of the file to be opened, as a string. mode An optional string specifying what you plan to do with the file. If omitted, you will get read access to the file. In general the value consists of three parts: General mode, one of: r Read access. The file must already exist. You will not be allowed to write to it. w Write access. If there is no file by this name, a new one will be created. If there is an existing file, it will be deleted! a Append access. If there is a file by this name, your initial position will be at the end of the file, and you will be allowed to write (and read). If there is no file by this name, a new one will be created. On some systems, all writes to a file with append mode are added at the end of the file, regardless of the current file position. If you plan to modify the file, append a “+” next. For example, mode “r+” puts you at the beginning of an existing file and allows you to write to the file anywhere. Mode “w+” is the same as “w”: it deletes an existing file if there is any, then creates a new file and gives you write access. Mode “a+” allows you to write new data at the end of an existing file; if no file by this name exists, it will create a new one. If you are handling binary data, as opposed to lines of text, add “b” at the end of the mode string. bufsize Buffer size: this affects when physical device writes are done, compared to write operations that your program performs. In most cases you will probably want to omit this argument. The default is to use line buffering for terminal-type devices, or some system default for other devices. Use 0 to force unbuffered operation. This may be inefficient, but any file writes are performed immediately. Use 1 for line buffering: output lines are written whenever you write a line terminator such as '\n'. Use larger values to specify the actual size of the buffer. If you are reading text files, and you don't want to worry about the variety of line termination protocols, you may use a mode value of “U” for “universal line terminator mode.” In this mode, input lines may be terminated with either carriage return ('\r'), newline ('\n'), or both, but the lines you receive will always be terminated with a single newline. (Exception: If the last line is unterminated, the string you get will also be unterminated.) There are a number of potential error conditions. For modes starting with “r”, the file must exist before you open it. Also, you must have access according to the underlying operating system. For example, in Linux environments, you must have read access to read a file, and you must have write access to modify or delete a file. These sorts of failures will raise an IOError exception. A file is its own iterator (see ). Hence, if you have a file inFile opened for reading, you can use a for loop that looks like this to iterate over the lines of the file: for line in inFile: ... The variable line will be set to each line of the file in turn. The line terminator character (if any) will be present in that string. Other aspects of files: Every open file has a current position. Initially, this will 0L if you opened it for reading or writing, or the size of the file if you opened it with append access. Each write or read operation moves this position by the amount read or written. You can also query or set the file position; see . Files may use a technique called buffering. Because physical access to some storage media (such as disk drives) takes a relatively long time, Python may employ a storage area called a buffer to stage data for input or output. For example, if you are writing data to a disk file, Python may keep the data in the file's buffer area until the buffer is full and only then actually write it to the physical disk. There are various techniques for controlling this behavior; see .

Use these methods on an open file instance F. F.close() Close file F. Any unwritten data in the buffer will be flushed. No further operations will be allowed on the file unless it is reopened with the open() function. F.flush() For buffered files, you can use this method to make sure that all data written to the file has been physically transmitted to the storage medium. Closing a file will also flush the buffers. Avoid using this method unless you really need it, as it may make your program less efficient. F.isatty() A predicate that tests whether F is a terminal; “tty” is an ancient term that originally meant “Teletype”, but has come to mean any terminal or simulated terminal. F.read(n ) Read the next n characters from F and return them as a string. If there are fewer than n characters remaining after your current position, you will get all remaining characters. If you are at the end of the file, you will get back an empty string (''). The argument is optional. If omitted, you will get the entire remaining contents of the file as a string. F.readline(maxlen) Read the next text line from F and return it as a string, including the line terminator if any. If you need to limit the maximum size of incoming lines, pass that size limit as the optional maxlen argument. The default is to return a line of any size (subject to memory limitations). If the line exceeds maxlen, the file position will be left pointing to the first unread character of that line. F.readlines() Read all remaining lines from F and return them as a list of strings, including line terminator characters if any. F.seek(offset, whence) Change the file's current position. The value of whence determines how the offset value is used to change the position: 0: Set the position to offset bytes after the beginning of the file. 1: Move the current position offset bytes toward the end of the file. 2: Move the current position offset bytes relative to the end of the file. For example, for a file f, this operation would set the position to 4 bytes before the end of the file: f.seek(-4, 2) F.tell() This method returns the current file position relative to the beginning as a long value. >>> f=open('roundtable', 'w') >>> f.write('Bedevere') >>> f.tell() 8L >>> f.seek(2L) >>> f.tell() 2L F.truncate([pos]) Remove any contents of F past position pos, which defaults to the current position. F.write(s) Write the contents of string s to file F. This operation will not add terminator characters; if you want newlines in your file, include them in the string s. F.writelines(S) For a sequence S containing strings, write all those strings to F. No line terminators will be added; you must provide them explicitly if you want them.

Python has a unique value called None. This special null value can be used as a placeholder, or to signify that some value is unknown. In conversational mode, any expression that evaluates to None is not printed. However, if a value of None is converted to a string, the result is the string 'None'; this may happen, for example, in a print statement. >>> x = None >>> x >>> print x None The value None is returned from any function that executes a return statement with no value, or any function after it executes its last line if that last line is not a return statement. >>> def useless(): ... print "Useless!" ... >>> useless() Useless! >>> z=useless() Useless! >>> z >>> print z None >>> def boatAnchor(): ... pass ... >>> x=boatAnchor() >>> x >>> print x None

Python's operators are shown here from highest precedence to lowest, with a ruled line separating groups of operators with equal precedence: (E) Parenthesized expression or tuple. [E, ...] List. {key:value, ...} Dictionary. `...` Convert to string representation. x.attribute Attribute reference. x[...] Subscript or slice; see . f(...) Call function f. x**y x to the y power. -x Negation. ~x Bitwise not (one's complement). x*y Multiplication. x/y, x//y Division. The “//” form discards the fraction from the result. For example, “13.9//5.0” returns the value 2.0. x%y Modulo (remainder of x/y). x+y Addition, concatenation. x-y Subtraction. x<<y x shifted left ybits. x>>y x shifted right ybits. x&y Bitwise and. x^y Bitwise exclusive or. x|y Bitwise or. x<y, x<=y, x>y, x>=y, x!=y, x==y Comparisons. These operators are all predicates; see . x in y, x not in y Test for membership. x is y, x is not y Test for identity. not x Boolean “not.” x and y Boolean “and.” x or y Boolean “or.”

We use the term predicate to mean any Python function that tests some condition and returns a Boolean value. For example, x < y is a predicate that tests whether x is less than y. For example, 5 < 500 returns True, while 5 >= 500 returns False.

Python has a lot of built-in functions. This section describes the ones that most people use most of the time. If you are interested in exploring some of the more remote corners of Python, see .

To find the absolute value of a number x: abs(x) If x is negative, the function returns -x; otherwise it returns x. For complex values, the function returns the magnitude, that is, the square root of (x.real**2+x.image**2). >>> abs(-33) 33 >>> abs(33) 33 >>> abs(0) 0 >>> abs(complex(1,5)) 5.0990195135927845

A predicate that tests whether all the elements of some sequence are considered True. If any elements are not already type bool, they are converted to Boolean values using the bool() built-in function. >>> all([True, 14, (88,99)]) True >>> all([True, 14, (88,99), None]) False

This function, applied to some sequence, is a predicate that tests whether any of the elements of that sequence are True. If any element is not already type bool, it is converted to a Boolean value using the bool() built-in function. >>> noneTrue = (0, 0.0, (), None) >>> any(noneTrue) False >>> someTrue = (0, 0.0, (88,), 'penguin') >>> any(someTrue) True

This function takes any value x and converts it to a Boolean (true or false) value. For the list of values that are considered True or False, see . Examples: >>> bool(0) False >>> bool(0.0) False >>> bool(0L) False >>> bool(0j) False >>> bool('') False >>> bool([]) False >>> bool(()) False >>> bool({}) False >>> bool(None) False >>> bool(1) True >>> bool(15.9) True >>> bool([0]) True >>> bool((None,)) True >>> bool({None: False}) True

For arguments n in the range 0 to 255, this function returns a one-character string containing the character that has code n. Compare . >>> chr(65) 'A' >>> chr(0) '\x00'

This function compares the values of two arguments x and y: cmp(x, y) The return value is: A negative number if x is less than y. Zero if x is equal to y. A positive number if x is greater than y. The built-in cmp() function will typically return only the values -1, 0, or 1. However, there are other places that expect functions with the same calling sequence, and those functions may return other values. It is best to observe only the sign of the result. >>> cmp(2,5) -1 >>> cmp(5,5) 0 >>> cmp(5,2) 1 >>> cmp('aardvark', 'aardwolf') -1

To create a complex number from a real part R and a complex part I: complex(R, I) Example: >>> complex(-4.04, 3.173) (-4.04+3.173j)

This function creates a new dictionary from its arguments. The general form is: dict(v, k0=v0, k1=v1, ...) That is, there may be one optional positional argument or any number of keyword arguments. If you supply no arguments, you get a new, empty dictionary. If a positional argument is supplied, it must be a sequence of two-element sequences. Each two-element sequence becomes one key-value pair of the result. >>> dict() {} >>> dict ( [ (0, 'stop'), (1, 'go') ] ) {0: 'stop', 1: 'go'} >>> dict((('y', 'boy'), ('x', 'girl'))) {'y': 'boy', 'x': 'girl'} If you supply any keyword arguments, each keyword becomes a key in the resulting dictionary, and that argument's value becomes the corresponding value of that key-value pair. >>> dict(bricks='sleep', keith='maniac', rj='gumby') {'bricks': 'sleep', 'keith': 'maniac', 'rj': 'gumby'}

Sometimes you want both the quotient and remainder when dividing x by y. This function returns a tuple (q, r), where q is the quotient and r is the remainder. If either x or y is a float, the returned value q is the whole part of the quotient, and the returned r is computed as x-(r*d). divmod(x, y) Examples: >>> divmod(13, 5) (2, 3) >>> divmod(1.6, 0.5) (3.0, 0.10000000000000009)

Given a sequence S, this function produces an iterator that iterates over the pairs of values (i, v) where each i is a position in S, and each v is the corresponding value. For more information on iterators, see . >>> L = ['Ministry', 'of', 'Silly', 'Walks'] >>> for where, what in enumerate(L): ... print "[%d] %s" % (where, what) ... [0] Ministry [1] of [2] Silly [3] Walks

This function is identical to the open() function; for details, see .

This function is useful for removing some of the elements of a sequence. You must provide a filtering function that takes one argument and returns a Boolean value. Here is the calling sequence: filter(f, S) The filtering function f is the first argument. It is applied to every element of some sequence S. The result is a new sequence of the same type as S, containing only those elements x of S for which f(x) returned True. >>> def isOdd(x): ... if (x%2) == 1: return True ... else: return False ... >>> filter(isOdd, [88, 43, 65, -11, 202]) [43, 65, -11] >>> filter(isOdd, (1, 2, 4, 6, 9, 3, 3)) (1, 9, 3, 3) >>> def isLetter(c): ... return c.isalpha() ... >>> filter(isLetter, "01234abcdeFGHIJ*(&!^") 'abcdeFGHIJ'

Converts a value to type float. The argument must be a number, or a string containing a numeric value in string form (possibly surrounded by whitespace). If the argument is not a valid number, this function will raise a ValueError exception. If no argument is given, it will return 0.0. >>> float() 0.0 >>> float(17) 17.0 >>> float(' 3.1415 ') 3.1415000000000002 >>> print float('6.0221418e23') 6.0221418e+23 >>> float('142x') Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: invalid literal for float(): 142x

This function is used to create a new frozenset value: an immutable set. General forms: frozenset() frozenset(S) The first form creates an empty frozenset. To convert an existing sequence value S to a frozenset, use the second form. >>> frozenset() frozenset([]) >>> frozenset('aeiou') frozenset(['a', 'i', 'e', 'u', 'o']) >>> frozenset([0, 0, 0, 44, 0, 44, 18]) frozenset([0, 18, 44]) For more information, see .

Given an integer, this function returns a string displaying that value in hexadecimal (base 16). >>> hex(15) '0xf' >>> hex(1325178541275812780L) '0x1263fadcb8b713acL'

To convert a number of a different type to int type, or to convert a string of characters that represents a number: int(ns) where ns is the value to be converted. If ns is a float, the value will be truncated, discarding the fraction. If you want to convert a character string s to an int, and that string is not a decimal number, use this form, where b is an integer in the range [2, 36] that specifies the base (radix). int(s, b) Examples: >>> int(43L) 43 >>> int(True) 1 >>> int(False) 0 >>> int(43.89) 43 >>> int("69") 69 >>> int('77', 8) 63 >>> int('7ff', 16) 2047 >>> int('10101', 2) 21

Given a sequence S, this function returns an iterator that generates the elements of the sequence. For more information, see . >>> listWalker = iter ( [23, 47, 'hike'] ) >>> for x in listWalker: print x, ... 23 47 hike

Given a sequence or mapping (dictionary), this function returns the number of elements. >>> len('') 0 >>> len ( [23, 47, 'hike'] ) 3 >>> len({1: 'foot', 2:'shoulder', 'feather':'rare'}) 3

This function creates a new list. The argument x may be a sequence or an iterator. >>> list(('Bentham', 'Locke', 'Hobbes')) ['Bentham', 'Locke', 'Hobbes'] >>> list("Bruce") ['B', 'r', 'u', 'c', 'e'] >>> list((42,)) [42] >>> list() []

This function works exactly the same way as , except that it produces a result of type long. >>> long(43) 43L >>> long(43.889) 43L >>> long('12345678901234567890123457890') 12345678901234567890123457890L >>> long('potrzebie456', 36) 3381314581245790842L

Given a function f that takes one argument and returns a value, this function applies f to each element of a sequence S, and returns a new list containing the results of each of those function applications. >>> def add100(x): ... return x+100 ... >>> map(add100, (44,22,66)) [144, 122, 166]

Given a sequence S containing at least one element, max(S) returns the largest element of the sequence. >>> max('blimey') 'y' >>> max ( [-505, -575, -144, -288] ) -144

Given a sequence S containing at least one element, max(S) returns the largest element of the sequence. >>> min('blimey') 'b' >>> min ( [-505, -575, -144, -288] ) -575

Given a number n, oct(n) returns a string containing an octal (base 8) representation of n. Consistent with Python's convention that any number starting with a zero is considered octal, the result of this function will always have a leading zero. >>> oct(0) '0' >>> oct(127) '0177'

Open a file. For the calling sequence, see .

Given a string s containing a single character, ord(s) returns that character's numeric code. Compare . >>> ord('A') 65 >>> ord('\x00') 0

There are two ways to compute xy in Python. You can write it as “x**y”. There is also a function that does the same thing: pow(x, y) For integer arithmetic, the function also has a three-argument form that computes xy%z, but more efficiently than if you used that expression: pow(x, y, z) Examples: >>> 2**4 16 >>> pow(2,4) 16 >>> pow(2.5, 4.5) 61.763235550163657 >>> (2**9)%3 2 >>> pow(2,9,3) 2

This function generates a list containing the values of an arithmetic progression, that is, a sequence of numbers such that the difference between adjacent numbers is always the same. There are three forms: range(n) Returns the list [0, 1, 2, ..., n-1]. Note that the result never includes the value n. range(start, stop) Returns the list [start, start+1, start+2, ..., stop-1]. The result never includes the stop value. range(start, stop, step) Returns the list [start, start+step, start+2*step, ...], up to but not including the value of step. The value of step may be negative. Examples: >>> range(4) [0, 1, 2, 3] >>> range(4,9) [4, 5, 6, 7, 8] >>> range(10,104,10) [10, 20, 30, 40, 50, 60, 70, 80, 90, 100] >>> range(5,-1,-1) [5, 4, 3, 2, 1, 0]

To prompt for keyboard entry, use this function: raw_input(p) The argument p is a prompt string that is written to standard output. Then a line is read from standard input and returned as a string, without its trailing newline character. >>> party = raw_input('Party affiliation: ') Party affiliation: Slightly silly. >>> party 'Slightly silly.' If the user signals end of input (e.g., with Control-D under Unix), the function raises an EOFError exception.

This function is used to apply some two-argument function f(x, y) pairwise to each pair of the elements of a sequence S in turn, with an optional initial value I. Here are the general forms: reduce(f, S) reduce(f, S, I) The result depends on the number of elements in S, and whether the initial value I is supplied. Let's look first at the case where argument I is not supplied. If S has only one element, the result is S[0]. If S has two elements, the result is f(S[0], S[1]). If S has three elements, the result is f(f(S[0], S[1]), S[2]). If S has four or more elements, f is applied first to S[0] and S[1], then to that result and S[2], and so on until all elements are reduced to a single value. If an initial value I is provided, the result is the same as reduce(f, [I]+list(S)). Some examples: >>> def x100y(x,y): ... return x*100+y ... >>> reduce(x100y, [15]) 15 >>> reduce(x100y, [1,2]) 102 >>> reduce(x100y, [1,2,3]) 10203 >>> reduce(x100y, (), 44) 44 >>> reduce(x100y, [1], 2) 201 >>> reduce(x100y, [1,2], 3) 30102 >>> reduce(x100y, [1,2,3], 4) 4010203

This function, applied to a sequence value S, returns an iterator that generates the elements of S in reverse order (see ). >>> L=[22,44,88] >>> backL = reversed(L) >>> for i in backL: ... print i, ... 88 44 22

To find the integral value nearest to some value x, use this function: round(x) The value is returned as a float. In the case that the fractional part of x is exactly one-half, the returned value is the integer farther from zero. Examples: >>> round ( 4.1 ) 4.0 >>> round(4.9) 5.0 >>> round(4.5) 5.0 >>> round(-4.1) -4.0 >>> round(-4.9) -5.0 >>> round(-4.5) -5.0 You can also provide an optional second argument that specifies how many digits to preserve after the decimal. >>> from math import pi >>> round(pi) 3.0 >>> print round(pi,1) 3.1 >>> print round(pi,2) 3.14 >>> print round(pi,5) 3.14159 >>> round(pi,30) 3.1415926535897931

Use this function to create a set value. Here are the general forms: set() set(S) When called with no arguments, this function returns a new, empty set. To build a set from an existing sequence S, use the second form. Examples: >>> empty = set() >>> empty set([]) >>> len(empty) 0 >>> swallows=set(['African', 'European']) >>> swallows set(['European', 'African']) >>> len(swallows) 2 >>> set ( (0, 0, 0, 58, 0, 0, 58, 17) ) set([0, 17, 58]) For more information about sets, see .

This function, applied to a sequence S, produces a new list containing the elements of S in ascending order (or some other order you specify). Here is the general form: sorted(S[, cmp[, key[, reverse]]]) The cmp, key, and reverse arguments are optional, and have the same meaning as in the .sort() method of the list type (see ). >>> L = ['geas', 'clue', 'Zoe', 'Ann'] >>> sorted(L) ['Ann', 'Zoe', 'clue', 'geas'] >>> def ignoreCase(x,y): ... return cmp(x.upper(), y.upper()) ... >>> sorted(L, ignoreCase) ['Ann', 'clue', 'geas', 'Zoe'] >>> L ['geas', 'clue', 'Zoe', 'Ann'] In the first example above, 'Zoe' precedes 'clue', because all uppercase letters are considered to be less than all lowercase letters. The second example shows how to sort strings as if they were all uppercase. Note in the last line that the original list L is unchanged.

To convert any value x to a string, use this general form: str(x) For example: >>> str(17) '17' >>> str({'boy': 'Relmond', 'girl': 'Wirdley'}) "{'boy': 'Relmond', 'girl': 'Wirdley'}"

This function, applied to a sequence S, returns the sum of its elements. There are two general forms: sum(S) sum(S, I) In the second form, the summing process starts with the initial value I. Examples: >>> L=[1,2,3,4] >>> sum(L) 10 >>> sum(L,1000) 1010 >>> sum((), 1000) 1000

To convert some sequence value S to a tuple, use this general form: tuple(s) The result will be a new tuple with the same elements as S in the same order. To create an empty tuple, omit the argument. Examples: >>> tuple() () >>> tuple ( ['swallow', 'coconut'] ) ('swallow', 'coconut') >>> tuple ( 'shrubbery' ) ('s', 'h', 'r', 'u', 'b', 'b', 'e', 'r', 'y') >>> tuple ( ['singleton'] ) ('singleton',)

This function can be applied to any value. It returns a type object corresponding to the type of that value. For built-in types, the type object is the same as the name of the type: int, str, list, and so on. To test whether a value x is some type T, you can use the predicate “type(x) is T”. If you display a type object in conversational mode, it will look like “<type 'T'>”. Examples: >>> type(i) <type 'int'> >>> type(i) is int True >>> type([2,4,8]) is list True

Given a number n, this function returns the Unicode character that has code point n. For more on Unicode, see . >>> unichr(0) u'\x00' >>> unichr(ord('A')) u'A' >>> unichr(0x3046) u'\u3046' >>> unichr(0xe0047) u'\U000e0047'

Use this function to convert a string to type unicode. >>> unicode('Groucestel') u'Groucestel' >>> unicode() u''

The xrange() function has exactly the same arguments as the range() function (see ). The difference is that xrange() is a generator (see ), while range() actually builds a list for its result. This means you can use xrange() in situations where you want to generate a large series of the values from an arithmetic progression, but you don't have enough memory to build that series as a list. >>> for i in xrange(2000000000): ... print i, ... if i > 8: ... break ... 0 1 2 3 4 5 6 7 8 9 >>> for i in range(2000000000): ... print i, ... if i > 8: ... break ... Traceback (most recent call last): File "<stdin>", line 1, in <module> MemoryError

Given two or more sequences S0, S1, S2, ... with the same number of elements, you can combine them to produce a list of tuples (v0, v1, ...) such that each v0 comes from S0, each v1 comes from S1, and so on. The action of this function is probably best explained by examples: >>> L1=[1,2,3,4] >>> L2=['a', 'b', 'c', 'd'] >>> zip(L1, L2) [(1, 'a'), (2, 'b'), (3, 'c'), (4, 'd')] >>> L3=[10.0, 20.0, 30.0, 40.0] >>> zip(L1, L2, L3) [(1, 'a', 10.0), (2, 'b', 20.0), (3, 'c', 30.0), (4, 'd', 40.0)]

This section describes Python functions that most people will never need. However, the advanced Python programmer may find some of them quite useful.

The class basestring is the parent class for the two string types, str and unicode. It exists not because you can call it (you can't), but for type testing. To test whether some value s is an instance of either type of string, use this predicate: isinstance(s, basestring) See .

This predicate tests whether some value x can be called as a function. callable(x) Class names can be called to create an instance of the class. Instances can be called if they define a .__call__() special method; see . >>> def someFunction(): ... pass ... >>> callable(someFunction) True >>> callable(len) True >>> callable(int) True >>> callable(42) False

The purpose of the classmethod() function is to convert a method into a class method. For a discussion of the purpose and usage of class methods, see . There are two ways to declare a class method within a class: You can use the function decorator syntax to declare that classmethod is a decorator for your method. Precede the method definition with a line reading: @classmethod def methodName(cls, ...): method body In some older versions of Python without the decorator syntax, you can still declare a class method by placing a line after the method definition, at the same indentation level as the method's def statement, having this form: methodName = classmethod(methodName)

Use this function to delete an attribute named A of some instance I. It does not return a value. Here is the general form: delattr(I, A) For example, if an instance seabiscuit has a rider attribute, this statement would delete that attribute: delattr(seabiscuit, 'rider') If the instance has no such attribute, this function will raise an AttributeError exception.

The purpose of the dir() function is to find out what names are defined in a given namespace, and return a list of those names. If called without arguments, it returns a list of the names defined in the local namespace. This function can be very handy for finding out what items are in a module or class. Certain special names are found in most or all namespaces: __doc__ is present in every namespace. Initially None, you can store documentation there. __name__ is the name of the current module (minus the .py extension). In the top-level script or in conversational mode, this name is set to the string '__main__'. __builtins__ is a list of the names of all built-in functions and variables. In this example sequence, we'll show you what is in the global namespace just after starting up Python. Then we'll import the math module and display its names. >>> dir() ['__builtins__', '__doc__', '__name__'] >>> x=5; forkTail='Tyrannus' >>> dir() ['__builtins__', '__doc__', '__name__', 'forkTail', 'x'] >>> print __doc__ None >>> print __name__ __main__ >>> import math >>> print math.__name__ math >>> dir(math) ['__doc__', '__file__', '__name__', 'acos', 'asin', 'atan', 'atan2', 'ceil' , 'cos', 'cosh', 'degrees', 'e', 'exp', 'fabs', 'floor', 'fmod', 'frexp', ' hypot', 'ldexp', 'log', 'log10', 'modf', 'pi', 'pow', 'radians', 'sin', 'si nh', 'sqrt', 'tan', 'tanh'] >>> print math.__doc__ This module is always available. It provides access to the mathematical functions defined by the C standard. >>> print math.log10.__doc__ log10(x) -> the base 10 logarithm of x. >>> print __builtins__ <module '__builtin__' (built-in)> >>> dir(__builtins__) ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException', 'D eprecationWarning', 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception' , 'False', 'FloatingPointError', 'FutureWarning', 'GeneratorExit', 'IOError ', 'ImportError', 'ImportWarning', 'IndentationError', 'IndexError', 'KeyEr ror', 'KeyboardInterrupt', 'LookupError', 'MemoryError', 'NameError', 'None ', 'NotImplemented', 'NotImplementedError', 'OSError', 'OverflowError', 'Pe ndingDeprecationWarning', 'ReferenceError', 'RuntimeError', 'RuntimeWarning ', 'StandardError', 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'Syste mError', 'SystemExit', 'TabError', 'True', 'TypeError', 'UnboundLocalError' , 'UnicodeDecodeError', 'UnicodeEncodeError', 'UnicodeError', 'UnicodeTrans lateError', 'UnicodeWarning', 'UserWarning', 'ValueError', 'Warning', 'Zero DivisionError', '_', '__debug__', '__doc__', '__import__', '__name__', 'abs ', 'all', 'any', 'apply', 'basestring', 'bool', 'buffer', 'callable', 'chr' , 'classmethod', 'cmp', 'coerce', 'compile', 'complex', 'copyright', 'credi ts', 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'execfile', ' exit', 'file', 'filter', 'float', 'frozenset', 'getattr', 'globals', 'hasat tr', 'hash', 'help', 'hex', 'id', 'input', 'int', 'intern', 'isinstance', ' issubclass', 'iter', 'len', 'license', 'list', 'locals', 'long', 'map', 'ma x', 'min', 'object', 'oct', 'open', 'ord', 'pow', 'property', 'quit', 'rang e', 'raw_input', 'reduce', 'reload', 'repr', 'reversed', 'round', 'set', 's etattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', 'zip']

This function evaluates a Python expression from a string. Example: >>> cent=100 >>> eval('cent**3') 1000000 If you want to evaluate the expression using different name environments, refer to the official documentation. For related features, see also and .

To execute a sequence of Python statements in some file F, use this function: execfile(F) The function returns None. For additional features that allow you to control the environment of the executed statements, see the official documentation.

Use this function to retrieve an attribute of an instance I, where the attribute's name is a string s. getattr(I, s[, default]) If I has no attribute whose name matches s: If you supplied the optional default value, that value is returned. If you don't supply a default value and there is no such attribute in I, this function will raise an AttributeError exception. Example: >>> class C: ... def __init__(self, flavor): ... self.flavor = flavor ... >>> c=C('garlicky') >>> getattr(c, 'flavor') 'garlicky' >>> getattr(c, 'aroma', 'bland') 'bland' >>> getattr(c, 'aroma') Traceback (most recent call last): File "<stdin>", line 1, in <module> AttributeError: C instance has no attribute 'aroma'

This function takes no arguments and returns a dictionary that represents the current global namespace. The keys of this dictionary are globally defined names, and each corresponding value is the value for that name. This example starts from a fresh execution of Python in conversational mode, so the global namespace has only the three special names discussed in . >>> globals() {'__builtins__': <module '__builtin__' (built-in)>, '__name__': '__main_ _', '__doc__': None} >>> finch = 'Fleep' >>> globals() {'__builtins__': <module '__builtin__' (built-in)>, '__name__': '__main_ _', '__doc__': None, 'finch': 'Fleep'} The special name __builtins__ is bound to a module; name __name__ is bound to the string '__main__'; and __doc__ is bound to None. Note that defining a new name adds an entry to the result of globals().

This predicate tests to see if some instance I has an attribute whose name is given by some string s: hasattr(I, s) If this function returns True, you can be sure that the instance has an attribute named s. However, if it returns False, attempts to access an attribute may still succeed, if the class provides dynamic attributes; see . Example: >>> class C: ... def __init__(self, disc): ... self.disk = disc ... >>> c=C('five') >>> hasattr(c, 'disk') True >>> hasattr(c, 'disc') False >>> hasattr(c, 'jukebox') False >>> c.jukebox = 'Nine' >>> hasattr(c, 'jukebox') True

This function, given any Python value, returns an integer value that uniquely identifies it. In most implementations, it is the value's physical memory address. >>> i = 20 >>> id(i) 137727456

Use this function to test whether some instance I is an instance of some class C (or an instance of any ancestor class from which C inherits). The general form: isinstance(I, C) The second argument may be a class name, a type object, or a tuple of class names and type objects. If a tuple, the function will test the instance against each of the class names or type objects. >>> class C1: ... pass ... >>> class C2(C1): ... pass ... >>> c2=C2() >>> isinstance(c2,C2) True >>> isinstance(c2,C1) True >>> isinstance(c2,int) False >>> isinstance(1,type(55)) True >>> isinstance(1, (int, float, long)) True >>> isinstance('Ni', (int, float, long)) False

To test whether some class C1 is a subclass of another class C2, use this predicate: issubclass(C1, C2) Examples: >>> class Polygon: ... pass ... >>> class Square(Polygon): ... pass ... >>> issubclass(Square, Polygon) True >>> issubclass(Polygon, Square) False >>> issubclass(Square, Square) True >>> issubclass(unicode, basestring) True

This function returns a dictionary containing the names and values of all variables in the local namespace. An example: >>> def f(a, b=1): ... c=2 ... print locals() ... >>> f(5) {'a': 5, 'c': 2, 'b': 1} For related functions, see and .

The purpose of this function is to create a property of a class. A property looks and acts like an ordinary attribute, except that you provide methods that controls access to the attribute. There are three kinds of attribute access: read, write, and delete. When you create a property, you can provide any or all of three methods that handle requests to read, write, or delete that attribute. Here is the general method for adding a property named p to a new-style class C. class C(...): def R(self): ...read method... def W(self, value): ...write method... def D(self): ...delete method... p = property(R, W, D, doc) ... where: R is a method that takes no arguments and returns the effective attribute value. If omitted, any attempt to read that attribute will raise AttributeError. W is a method that takes one argument and sets the attribute to that argument's value. If omitted, any attempt to write that attribute will raise AttributeError. D is a method that deletes the attribute. If omitted, any attempt to delete that attribute will raise AttributeError. doc is a documentation string that describes the attribute. If omitted, defaults to the documentation string of the R method if any, otherwise None. To retrieve a property's documentation, use this form: C.p.__doc__ where C is the class name and p is the property name. As an example, here is a small class that defines a property named x: class C(object): def __init__(self): self.__x=None def getx(self): print "+++ getx()" return self.__x def setx(self, v): print "+++ setx(%s)" % v self.__x = v def delx(self): print "+++ delx()" del self.__x x=property(getx, setx, delx, "Me property 'x'.") Assuming that class is defined, here is a conversational example. >>> c=C() >>> print c.x +++ getx() None >>> print C.x.__doc__ Me property 'x'. >>> c.x=15 +++ setx(15) >>> c.x +++ getx() 15 >>> del c.x +++ delx() >>> c.x +++ getx() Traceback (most recent call last): File "<stdin>", line 1, in <module> File "<stdin>", line 6, in getx AttributeError: 'C' object has no attribute '_C__x'

This function reloads a previously loaded module (assuming you loaded it with the syntax “import moduleName”. It is intended for conversational use, where you have edited the source file for a module and want to test it without leaving Python and starting it again. General form: reload(moduleName) The moduleName is the actual name of the module, not a string containing its name. For example, if you have imported a module like this: import parrot you would say “reload(parrot)”, not “reload('parrot')”.

The repr function attempts to converts any value to a string. Unlike the str() function, it attempts to display the value in Python source form, that is, in a form suitable for passing to eval() (see ). It works the same as the `...` operator. Examples: >>> s='Wensleydale' >>> print s Wensleydale >>> print str(s) Wensleydale >>> print repr(s) 'Wensleydale' >>> print `s` 'Wensleydale'

This function is similar to : it sets the value of some attribute whose name is A from an instance I to a new value V: setattr(I, A, V) Example: >>> class C5: ... def __init__(self, x): ... self.x = x ... >>> c=C5(14) >>> c.x 14 >>> setattr(c, 'x', 19) >>> c.x 19

The purpose of the staticmethod function is to convert a method into a static method. See for definitions and usage. Typically you will declare a static method using the decorator syntax, like this: @staticmethod def methodName(...): method body An alternative is to place a line like this after the method's definition (at the same indentation level as its def): methodName = staticmethod(methodName)

The purpose of this function is to retrieve the superclass of a given type or object. Superclasses are beyond the scope of this document; see the online documentation for built-in functions (scroll down).

This function returns a dictionary that represents a symbol table: its keys are variable names, and each key's corresponding value is its bound value. The official documentation warns you not to change anything in this dictionary, or Bad Things Will Happen. There are two forms of call: vars() Returns the local symbol table. vars(ns) Returns the symbol table of a namespace ns, where a namespace can be a module, an instance, or a class. Compare the similar functions , , and .

Python statement types are divided into two groups. Simple statements, that are executed sequentially and do not affect the flow of control, are described first. Compound statements, which may affect the sequence of execution, are discussed in . Here, for your convenience, is a list of all the Python statement types in alphabetical order. . . . . . elif: See . else: See and . except: See . . finally: See . . . . . . . . . . .

The purpose of Python's assignment state is to associate names with values in your program. It is the only statement that does not start with a keyword. An assignment statement is a line containing at least one single equal sign (=) that is not inside parentheses. Here is the general form of an assignment statement: target0 = target1 = ... = expression In most cases, there will be one target that is a name. Python will evaluate the expression, reducing it to a single value, and then bind that name to the that value. A binding is an association between a name and a value. It is important to note that in Python, unlike many other languages, names themselves are not associated with a specific type. A name is just a label, and it can be bound to any value of any type at any time. In this example, name x is bound first to an int value 5, then to a str value 'Some string'. >>> x = 5 >>> x 5 >>> x = 'Some string' >>> print x Some string If a target name was already bound to a value, the name is unbound from that value before it is rebound to the new value. For each value in a running program, Python keeps track of how many names are bound to that value. When the value has no more names bound to it, the value's memory is automatically recycled. If the value is an instance of a class, its destructor may be called; see . There are several other forms of assignment statement. n0 = n1 = ... = expression If you supply multiple target names, each target will be assigned the value of the expression. Example: >>> i = j = errorCount = 0 >>> i 0 >>> j 0 >>> errorCount 0 n0, n1, ... = expression If the target is a comma-separated list of names, the expression must evaluate to a sequence with the same number of values as there are names. Each value in the expression is then bound to the corresponding name. Example: >>> L = ["Bell's Blue", "male", 11] >>> name, sex, age = L >>> name "Bell's Blue" >>> sex 'male' >>> age 11 This feature, called “unpacking,” generalizes to arbritrarily nested sequences within sequences. You may group targets inside parentheses (...) or brackets [...] to show the levels of nesting. Here is an example: >>> s = [1, [2, 3, [4, 5], 6], 7] >>> a, (b, c, [d, e], f), g = s >>> print a,b,c,d,e,f,g 1 2 3 4 5 6 7 All the assignments are effectively simultaneous. Therefore, you can safely exchange the values of two variables using a statement like this: v1, v2 = v2, v1 Examples: >>> a=5; b=9998 >>> print a,b 5 9998 >>> a,b=b,a >>> print a,b 9998 5 >>> c=432 >>> a,b,c = b,c,a >>> print a,b,c 5 432 9998 name[i] = expression If name is a list (or other mutable sequence), the expression i must evaluate to an integer. The element at position i is replaced by the value of the expression. >>> L = range(6) >>> L [0, 1, 2, 3, 4, 5] >>> L[2] 2 >>> L[2] = 888 >>> L [0, 1, 888, 3, 4, 5] If name is a dictionary (or other mapping), and name does not have a key-value pair whose key equals index, a new key-value pair is added to name with key i and value expression. >>> d={'pudding': 'figgy'} >>> d {'pudding': 'figgy'} >>> d['tart'] = 'strawberry' >>> d {'pudding': 'figgy', 'tart': 'strawberry'} >>> d["tart"] = "rat" >>> d {'pudding': 'figgy', 'tart': 'rat'} As the last two lines show, if the dictionary already has a key-value pair for key i, the old value of that pair is replaced by the expression value. name[start:end] = S If name is a list or other mutable sequence, you can replace the elements of a slice of that sequence with the elements from some sequence S. (For an explanation of slicing, see .) This may result in addition, deletion, or replacement of the elements of name. Some examples will give the flavor of this kind of assignment. >>> L=range(6) >>> L [0, 1, 2, 3, 4, 5] >>> L[2:4] [2, 3] >>> L[2:4] = [111, 222, 333, 444, 555] >>> L [0, 1, 111, 222, 333, 444, 555, 4, 5] >>> L[3] 222 >>> L[3:3] [] >>> L[3:3] = [41.0, 42.0, 43.0] >>> L [0, 1, 111, 41.0, 42.0, 43.0, 222, 333, 444, 555, 4, 5] >>> L[4:7] [42.0, 43.0, 222] >>> L[4:7] = () >>> L [0, 1, 111, 41.0, 333, 444, 555, 4, 5] The “=” signs in an assignment is not an operator, as it is in some other languages. You cannot assign a value to a name inside an expression; an assignment statement must stand alone. >>> a = 5 + (a=7) File "<stdin>", line 1 a = 5 + (a=7) ^ SyntaxError: invalid syntax Python also supports augmented assignment. In this form, you may place certain operators before the “=”. Here is the general form: name operator= expression An assignment of this general form has the same semantics as this form: name = name operator expression Supported operator symbols include: + - * / % ** >> << & ^ | Examples: >>> i = 1 >>> i += 3 >>> i 4 >>> i *= 5 >>> i 20

To check for “shouldn't happen” errors, you can use an assert statement: assert e1 assert e1, e2 where e1 is some condition that should be true. If the condition fails, an AssertionError exception is raised (see exceptions below). If a second expression e2 is provided, the value of that expression is passed with the exception. Assertion checking can be disabled by running Python with the -O (optimize) option.

This section assumes you already understand the basics of object-oriented programming in Python, and that you know the meaning of concepts such as class, instance, method, and attribute. For a general tutorial on these concepts, see the introduction to object-oriented Python programming in the Tech Computer Center's Python tutorial. Due to improvements made in the language since it was first introduced, Python has two kinds of classes, old-style and new-style. We encourage you to use new-style classes; old-style classes are absent from the upcoming major release (Python 3000). All new-style classes must declare at least one parent class that is either the top-level class object or some other class that ultimate derives from object. Such a class is said to be derived from, or inherits from, the object class. To declare a new-style class C that inherits from object: class C(object): ...class methods and variables... An old-style class doesn't declare a parent class at all (or inherits from an existing old-style class). The life cycle of an old-style class is described in . In most respects, the two class perform identically. We'll start by explaining old-style classes in . To benefit from the many functional improvements of new-style classes, and especially if you expect to migrate your code to the major changes of Python 3.0, see .

For classes declared without a parent class, or classes that inherit from an existing old-style class, here is the life cycle. To define an old-style class C with no parent class, use this general form: class C: ...class methods and variables... To create a class that inherits from one or more parent classes P1, P2, …: class C(P1, P2, ...): ...class methods and variables... As Python reads the definition of your class, it first creates a new, empty namespace. Each method or class variable is added to this namespace as Python reads it. This namespace is the class namespace. A class is an object, but fundamentally it is a namespace. The creation of a new instance of a class happens when a running Python program encounters a call to that class, that is, the class name with a pair of parentheses after it, with zero or more arguments inside the parentheses. Here is the general form: C(p1, p2, ...) The instance creation (also called instantiation) is handled by the __init__() or constructor method. Like the class, an instance literally is a namespace. First Python creates a new namespace (called the instance namespace), and copies all the names and their bindings from the class namespace to the instance namespace. Python then calls the constructor. The argument list for this call always has the special first argument self (the instance), followed by whatever arguments were used in the initial call. The constructor call is equivalent to this: C.__init__(self, p1, p2, ...) The constructor method then executes. Typically the constructor will set up new instance attributes by assignments of this form: self.name = expression When the constructor finishes executing, the instance is returned as the result of the original call C(...), and execution resumes at the point of call. To call a method M of some class C, there are two methods. Most calls are bound method calls of this form, where i is an instance of some class C: i.methodName(p1, p2, ...) The instance i replaces self as the first argument when setting up the arguments to be passed to the method. The following form, called an unbound method call, is exactly equivalent to the above: C.methodName(i, p1, p2, ...) Here is a demonstration of the equivalence of bound and unbound method calls. >>> class C: ... def __init__(self, x): self.x = x ... def show(self, y): print "*** (%s,%s) ***" % (self.x, y) ... >>> c=C(42) >>> c.show(58) *** (42,58) *** >>> C.show(c,58) *** (42,58) *** When there are no values that refer to an instance any more, the storage occupied by the instance is recycled. However, if there are certain cleanup operations that must be done (such as closing external files), these operations can be placed into a destructor method that will be called before recycling the instance. Here is the general form of a destructor: def __del__(self): ...cleanup statements...

Within a class, a number of names have special meaning. We will discuss the .__init__() special method first, since it is necessary to construct instances of a class; see . The remaining special methods will be discussed in alphabetical order.

string.maketrans(s, t) Builds a translation table to be used as the first argument to the .translate() string method. The arguments s and t are two strings of the same length; the result is a translation table that will convert each character of s to the corresponding character of t. >>> import string >>> bingo=string.maketrans("lLrR", "rRlL") >>> "Cornwall Llanfair".translate(bingo) 'Colnwarr Rranfail' >>> "Cornwall Llanfair".translate(bingo, 'ai') 'Colnwrr Rrnfl'