New Mexico Tech Computer Center Python 2.7 quick reference New Mexico Tech Computer Center Python 2.7 quick reference Python 2.7 quick reference New Mexico Tech Computer Center Python 2.7 quick reference New Mexico Tech Computer Center Python 2.7 quick reference John W. Shipman 2011-11-03 13:11 Abstract A reference guide to most of the common features of the Python programming language, version 2.7. This publication is available in Web form11 http://www.nmt.edu/tcc/help/pubs/python27/web/ and also as a PDF document22 http://www.nmt.edu/tcc/help/pubs/python27/python27.pdf. Please forward any comments to tcc-doc@nmt.edu. Table of Contents 1. Introduction: What is Python? 2. Python 2.7 and Python 3.x 3. Starting Python 3.1. Using Python in Windows 3.2. Using Python in Linux 4. Line syntax 5. Names and keywords 6. Basic types 7. Numeric types 7.1. Type int: Integers 7.2. Type long: Extended-precision integers 7.3. Type bool: Boolean truth values 7.4. Type float: Floating-point numbers 7.5. Type complex: Imaginary numbers 8. Sequence types 8.1. Operations common to all the sequence types 9. Type str: Strings of 8-bit characters 9.1. String constants 9.2. Definition of “whitespace” 9.3. Methods on str values 9.4. The string .format() method 9.4.1. General form of a format code 9.4.2. The name part 9.4.3. The conversion part 9.4.4. The spec part 9.4.5. Formatting a field of variable length 9.5. The older string format operator 10. Type unicode: Strings of 32-bit characters 10.1. The UTF-8 encoding 11. Type list: Mutable sequences 11.1. Methods on lists 11.2. List comprehensions 12. Type tuple: Immutable sequences 13. The bytes type 13.1. Using the bytes type in 3.x conversion 14. The bytearray type 15. Types set and frozenset: Set types 15.1. Operations on mutable and immutable sets 15.2. Operations on mutable sets 16. Type dict: Dictionaries 16.1. Operations on dictionaries 16.2. Dictionary comprehensions 17. Type file: Input and output files 17.1. Methods on file objects 18. None: The special placeholder value 19. Operators and expressions 19.1. What is a predicate? 19.2. What is an iterable? 19.3. Duck typing, or: what is an interface? 20. Basic functions 20.1. abs(): Absolute value 20.2. all(): Are all the elements of an iterable true? 20.3. any(): Are any of the members of an iterable true? 20.4. bin(): Convert to binary 20.5. bool(): Convert to Boolean 20.6. bytearray(): Create a byte array 20.7. chr(): Get the character with a given code 20.8. cmp(): Compare two values 20.9. complex(): Convert to complex type 20.10. dict(): Convert to a dictionary 20.11. divmod(): Quotient and remainder 20.12. enumerate(): Step through indices and values of an iterable 20.13. file(): Open a file 20.14. filter(): Extract qualifying elements from an iterable 20.15. float(): Convert to float type 20.16. format(): Format a value 20.17. frozenset(): Create a frozen set 20.18. hex(): Convert to base 16 20.19. int(): Convert to int type 20.20. input(): Read an expression from the user 20.21. iter(): Produce an iterator over a sequence 20.22. len(): Number of elements 20.23. list(): Convert to a list 20.24. long(): Convert to long type 20.25. map(): Apply a function to each element of an iterable 20.26. max(): Largest element of an iterable 20.27. min(): Smallest element of an iterable 20.28. next(): Call an iterator 20.29. oct(): Convert to base 8 20.30. open(): Open a file 20.31. ord(): Find the numeric code for a character 20.32. pow(): Exponentiation 20.33. range(): Generate an arithmetic progression as a list 20.34. raw_input(): Prompt and read a string from the user 20.35. reduce(): Sequence reduction 20.36. reversed(): Produce a reverse iterator 20.37. round(): Round to the nearest integral value 20.38. set(): Create an algebraic set 20.39. sorted(): Sort a sequence 20.40. str(): Convert to str type 20.41. sum(): Total the elements of a sequence 20.42. tuple(): Convert to a tuple 20.43. type(): Return a value's type 20.44. unichr(): Convert a numeric code to a Unicode character 20.45. unicode(): Convert to a Unicode string 20.46. xrange(): Arithmetic progression generator 20.47. zip(): Combine multiple sequences 21. Advanced functions 21.1. basestring: The string base class 21.2. callable(): Is this thing callable? 21.3. classmethod(): Create a class method 21.4. delattr(): Delete a named attribute 21.5. dir(): Display a namespace's names 21.6. eval(): Evaluate an expression in source form 21.7. execfile(): Execute a Python source file 21.8. getattr(): Retrieve an attribute of a given name 21.9. globals(): Dictionary of global name bindings 21.10. hasattr(): Does a value have an attribute of a given name? 21.11. id(): Unique identifier 21.12. isinstance(): Is a value an instance of some class or type? 21.13. issubclass(): Is a class a subclass of some other class? 21.14. locals(): Dictionary of local name bindings 21.15. property(): Create an access-controlled attribute 21.16. reload(): Reload a module 21.17. repr(): Representation 21.18. setattr(): Set an attribute 21.19. slice(): Create a slice instance 21.20. staticmethod(): Create a static method 21.21. super(): Superclass 21.22. vars(): Local variables 22. Simple statements 22.1. The assignment statement: name = expression 22.2. The assert statement: Verify preconditions 22.3. The del statement: Delete a name or part of a value 22.4. The exec statement: Execute Python source code 22.5. The global statement: Declare access to a global name 22.6. The import statement: Use a module 22.7. The pass statement: Do nothing 22.8. The print statement: Display output values 22.9. The print() function 23. Compound statements 23.1. Python's block structure 23.2. The break statement: Exit a for or while loop 23.3. The continue statement: Jump to the next cycle of a for or while 23.4. The for statement: Iteration over a sequence 23.5. The if statement: Conditional execution 23.6. The raise statement: Cause an exception 23.7. The return statement: Exit a function or method 23.8. The try statement: Anticipate exceptions 23.9. The with statement and context managers 23.10. The yield statement: Generate one result from a generator 24. def(): Defining your own functions 24.1. A function's local namespace 24.2. Iterators: Values that can produce a sequence of values 24.3. Generators: Functions that can produce a sequence of values 24.4. Decorators 25. Exceptions: Error signaling and handling 25.1. Definitions of exception terms 25.2. Life cycle of an exception 25.3. Built-in exceptions 26. Classes: Defining your own types 26.1. Old-style classes 26.1.1. Defining an old-style class 26.1.2. Instantiation of an old-style class: The constructor, .__init__() 26.1.3. Attribute references in old-style classes 26.1.4. Method calls in an old-style class 26.1.5. Instance deletion: the destructor, .__del__() 26.2. Life cycle of a new-style class 26.2.1. __new__(): New instance creation 26.2.2. Attribute access control in new-style classes 26.2.3. Properties in new-style classes: Fine-grained attribute access control 26.2.4. Conserving memory with __slots__ 26.3. Special method names 26.3.1. Rich comparison methods 26.3.2. Special methods for binary operators 26.3.3. Unary operator special methods 26.3.4. Special methods to emulate built-in functions 26.3.5. __call__(): What to do when someone calls an instance 26.3.6. __cmp__(): Generalized comparison 26.3.7. __contains__(): The “in” and “not in” operators 26.3.8. __del__(): Destructor 26.3.9. __delattr__(): Delete an attribute 26.3.10. __delitem__(): Delete one item of a sequence 26.3.11. __enter__: Context manager initialization 26.3.12. __exit__: Context manager cleanup 26.3.13. __format__: Implement the format() function 26.3.14. __getattr__(): Handle a reference to an unknown attribute 26.3.15. __getattribute__(): Intercept all attribute references 26.3.16. __getitem__(): Get one item from a sequence or mapping 26.3.17. __iter__(): Create an iterator 26.3.18. __nonzero__(): True/false evaluation 26.3.19. __repr__(): String representation 26.3.20. __reversed__(): Implement the reversed() function 26.3.21. __setattr__(): Intercept all attribute changes 26.3.22. __setitem__(): Assign a value to one item of a sequence 26.4. Static methods 26.5. Class methods 27. pdb: The Python interactive debugger 27.1. Starting up pdb 27.2. Functions exported by pdb 27.3. Commands available in pdb 28. Commonly used modules 28.1. math: Common mathematical operations 28.2. string: Utility functions for strings 28.3. random: Random number generation 28.4. time: Clock and calendar functions 28.5. re: Regular expression pattern-matching 28.5.1. Characters in regular expressions 28.5.2. Functions in the re module 28.5.3. Compiled regular expression objects 28.5.4. Methods on a MatchObject 28.6. sys: Universal system interface 28.7. os: The operating system interface 28.8. stat: Interpretation of file status 28.9. os.path: File and directory interface Introduction: What is Python? 1. Introduction: What is Python? 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 tutorial33 http://www.nmt.edu/tcc/help/pubs/lang/pytut/. • Complete documentation and free installs are available from the python.org homepage44 http://www.python.org/. This document does not describe every single feature of Python 2.7. A few interesting features that 99% of Python users will never need, such as metaclasses, are not described here. Refer to the official documentation for the full feature set. Python 2.7 and Python 3.x 2. Python 2.7 and Python 3.x At this writing, both Python 2.7 and Python 3.2 are officially maintained implementations. The 3.0 release marked the first release in the development of Python that a new version was incompatible with the old one. If you are using 2.x releases of Python, there is no hurry to convert to the 3.x series. Release 2.7 is guaranteed to be around for many years. Furthermore, there are tools to help you automate much of the conversion process. Notes throughout this document will discuss specific features of 2.7 that are intended to ease the transition. Starting Python 3. Starting Python 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. Using Python in Windows 3.1. Using Python in Windows If you are using Python at the NM Tech Computer Center (TCC), you can get conversational mode from Start → All Programs → ActiveState ActivePython 2.6 → Python Interactive Shell. To write a program: 1. Start → All Programs → ActiveState ActivePython 2.6 → PythonWin Editor. 2. Use File → New, select Python Script in the pop-up menu, and click OK. This will bring up an edit window. 3. Write your Python program in the edit window, then use File → Save As... to save it under some file name that ends in “.py”. Use your U: drive. This drive is mounted everywhere at the TCC, and contains your personal files. It is backed up regularly. 4. 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”. You may also run a Python script by double-clicking on it, provided that its name ends with “.py”. Using Python in Linux 3.2. Using Python in Linux 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/bin/env 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 Line syntax 4. Line syntax 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 “{”. Names and keywords 5. Names and keywords Python names (also called identifiers) can be any length and follow these rules: • The first or only character must be a letter (uppercase or lowercase) or the underbar character, “_”. • Any additional characters may be letters, underbars, or digits. Examples: coconuts, sirRobin, blanche_hickey_869, __secretWord. Case is significant in Python. The name “Robin” is not the same name as “robin”. The names below are keywords, also known as reserved words. They have special meaning in Python and cannot be used as names or identifiers. and def finally in print yield as del for is raise assert elif from lambda return break else global not try class except if or with continue exec import pass while Basic types 6. Basic types 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 Section 19, “Operators and expressions” (p. ), 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. Table 1. Python's common types Type name Values Examples int Integers in the range [-2147483648, 2147483647]. See Section 7.1, “Type int: Integers” (p. ). 42, -3, 1000000 long Integers of any size, limited only by the available memory. See Section 7.2, “Type long: Extended-precision integers” (p. ). 42L, -3L, 100000000000000L bool The two Boolean values True and False. See Section 7.3, “Type bool: Boolean truth values” (p. ). True, False float Floating-point numbers; see Section 7.4, “Type float: Floating-point numbers” (p. ). 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 Section 7.5, “Type complex: Imaginary numbers” (p. ). (3.2+4.9j), (0+3.42e-3j) str Strings of 8-bit characters; see Section 9, “Type str: Strings of 8-bit characters” (p. ). Strings can be empty: write such as a string as “""” or “''”. 'Sir Robin', "xyz", "I'd've" unicode Strings of 32-bit Unicode characters; see Section 10, “Type unicode: Strings of 32-bit characters” (p. ). u'Fred', u'\u03fa' list A mutable sequence of values; see Section 11, “Type list: Mutable sequences” (p. ). ['dot', 'dash']; [] tuple An immutable sequence of values; see Section 12, “Type tuple: Immutable sequences” (p. ). ('dot', 'dash'); (); ("singleton",) dict Use dict values (dictionaries) to structure data as look-up tables; see Section 16, “Type dict: Dictionaries” (p. ). {'go':1, 'stop':2}; {} bytearray A mutable sequence of 8-bit bytes; see Section 14, “The bytearray type” (p. ). bytearray('Bletchley') file A file being read or written; see Section 17, “Type file: Input and output files” (p. ). open('/etc/motd') None A special, unique value that may be used where a value is required but there is no obvious value. See Section 18, “None: The special placeholder value” (p. ). None Numeric types 7. Numeric types Python has a number of different types used for representing numbers. Type int: Integers 7.1. Type int: Integers 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 “0o”. Similarly, use a leading “0x” to represent a value in hexadecimal (base 16), or “0b” for binary. Examples in conversational mode: >>> 999+1 1000 >>> 0o77 63 >>> 0xff 255 >>> 0b1001 9 Note The 0o and 0b prefixes work only in Python versions 2.6 and later. In 2.5 and earlier versions, any number starting with “0” was considered to be octal. This functionality is retained in the 2.6+ versions, but will not work in the Python 3.x versions. To convert other numbers or character strings to type int, see Section 20.19, “int(): Convert to int type” (p. ). If you perform operations on int values that result in numbers that are too large, Python automatically converts them to long type; see Section 7.2, “Type long: Extended-precision integers” (p. ). Type long: Extended-precision integers 7.2. Type long: Extended-precision integers 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 Section 20.24, “long(): Convert to long type” (p. ). Type bool: Boolean truth values 7.3. Type bool: Boolean truth values 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 Section 20.5, “bool(): Convert to Boolean” (p. ). Type float: Floating-point numbers 7.4. Type float: Floating-point numbers 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 article55 http://en.wikipedia.org/wiki/IEEE_754-1985. 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 Type complex: Imaginary numbers 7.5. Type complex: Imaginary numbers Mathematically, a complex number is a number of the form A+Bi where i is the imaginary number, 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 Section 20.9, “complex(): Convert to complex type” (p. ). Sequence types 8. Sequence types 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. • Section 8.1, “Operations common to all the sequence types” (p. ). • Section 9, “Type str: Strings of 8-bit characters” (p. ) (immutable). • Section 10, “Type unicode: Strings of 32-bit characters” (p. ) (immutable). • Section 11, “Type list: Mutable sequences” (p. ) (mutable). • Section 12, “Type tuple: Immutable sequences” (p. ) (immutable). Operations common to all the sequence types 8.1. Operations common to all the sequence types These functions work on values of the four sequence types: int, unicode, tuple, and list. • Section 20.22, “len(): Number of elements” (p. ). • Section 20.26, “max(): Largest element of an iterable” (p. ). • Section 20.27, “min(): Smallest element of an iterable” (p. ). 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. >>> "vi" + "car" 'vicar' >>> [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) S[i:j:k] You can use a slice expression like this to select every kth element. Examples: >>> teens = range(13,20) >>> teens [13, 14, 15, 16, 17, 18, 19] >>> teens[::2] [13, 15, 17, 19] >>> teens[1::2] [14, 16, 18] >>> teens[1:5] [14, 15, 16, 17] >>> teens[1:5:2] [14, 16] Type str: Strings of 8-bit characters 9. Type str: Strings of 8-bit characters 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 Section 10, “Type unicode: Strings of 32-bit characters” (p. ). In addition to the functions described in Section 8.1, “Operations common to all the sequence types” (p. ), these functions apply to strings: • Section 20.34, “raw_input(): Prompt and read a string from the user” (p. ). • Section 20.40, “str(): Convert to str type” (p. ). • Section 20.45, “unicode(): Convert to a Unicode string” (p. ). String constants 9.1. String constants 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: Table 2. String escape sequences \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 Section 28.5, “re: Regular expression pattern-matching” (p. ). Definition of “whitespace” 9.2. Definition of “whitespace” In Python, these characters are considered whitespace: Escape sequence ASCII66 http://en.wikipedia.org/wiki/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 Methods on str values 9.3. Methods on str values 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 Section 10.1, “The UTF-8 encoding” (p. ). 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 replaced by one or more spaces. Each tab is interpreted as a request to move to the next “tab stop”. The optional tabsize argument specifies the number of spaces between tab stops; the default is 8. Here is how the function actually works. The characters of S are copied to a new string T one at a time. If the character is a tab, it is replaced by enough tabs so the new length of T is a multiple of the tab size (but always at least one space). >>> 'X\tY\tZ'.expandtabs() 'X Y Z' >>> 'X\tY\tZ'.expandtabs(4) 'X Y Z' >>> 'a\tbb\tccc\tdddd\teeeee\tfffff'.expandtabs(4) 'a bb ccc dddd eeeee fffff' 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 .format(*p, **kw) See Section 9.4, “The string .format() method” (p. ). 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 an iterable that produces 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 Section 28.2, “string: Utility functions for strings” (p. ), 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' The string .format() method 9.4. The string .format() method The .format() method of the str type is an extremely convenient way to format text exactly the way you want it. Note This method was added in Python 2.6. Quite often, we want to embed data values in some explanatory text. For example, if we are displaying the number of nematodes in a hectare, it is a lot more meaningful to display it as "There were 37.9 nematodes per hectare" than just "37.9". So what we need is a way to mix constant text like "nematodes per hectare" with values from elsewhere in your program. Here is the general form: template.format(p0, p1, ..., k0=v0, k1=v1, ...) The template is a string containing a mixture of one or more format codes embedded in constant text. The format method uses its arguments to substitute an appropriate value for each format code in the template. The arguments to the .format() method are of two types. The list starts with zero or more positional arguments pi, followed by zero or more keyword arguments of the form ki=vi, where each ki is a name with an associated value vi. Just to give you the general flavor of how this works, here's a simple conversational example. In this example, the format code “{0}” is replaced by the first positional argument (49), and “{1}” is replaced by the second positional argument, the string "okra". >>> "We have {0} hectares planted to {1}.".format(49, "okra") 'We have 49 hectares planted to okra.' >>> In the next example, we supply the values using keyword arguments. The arguments may be supplied in any order. The keyword names must be valid Python names (see Section 5, “Names and keywords” (p. )). >>> "{monster} has now eaten {city}".format( ... city='Tokyo', monster='Mothra') 'Mothra has now eaten Tokyo' You may mix references to positional and keyword arguments: >>> "The {structure} sank {0} times in {1} years.".format( ... 3, 2, structure='castle') 'The castle sank 3 times in 2 years.' If you need to include actual “{” and “}” characters in the result, double them, like this: >>> "There are {0} members in set {{a}}.".format(15) 'There are 15 members in set {a}.' 9.4.1. General form of a format code Here is the general form of a format code, where optional parts in [brackets], and actual characters are in "double quotes": "{" [name] ["!" conversion] [":" spec] "}" • For the name portion, see Section 9.4.2, “The name part” (p. ). • For the conversion part, see Section 9.4.3, “The conversion part” (p. ). • For the spec part, see Section 9.4.4, “The spec part” (p. ). 9.4.2. The name part The name part of a format code specifies the source of the value to be formatted here. Numbers refer to positional arguments passed to the .format() method, starting at 0 for the first argument. You may also use any Python name to refer to one of the keyword arguments. • If the associated argument is an iterable, you may append an expression of this form to retrieve one of its elements: "[" index "]" For example: >>> signal=['red', 'yellow', 'green'] >>> signal[2] 'green' >>> "The light is {0[2]}!".format(signal) 'The light is green!' • If the associated argument has attributes, you can append an expression of this form to refer to that attribute: "."name For example: >>> import string >>> string.digits '0123456789' >>> "Our digits are '{s.digits}'.".format(s=string) "Our digits are '0123456789'." In general, you can use any combination of these features. For example: >>> "The sixth digit is '{s.digits[5]}'".format(s=string) "The sixth digit is '5'" Starting with Python 2.7, you may omit all of the numbers that refer to positional arguments, and they will be used in the sequence they occur. For example: >>> "The date is {}-{}-{}.".format(2012, 5, 1) 'The date is 2012-5-1.' If you use this convention, you must omit all those numbers. You can, however, omit all the numbers and still use the keyword names feature: >>> "Can I have {} pounds to {excuse}?".format( ... 50, excuse='mend the shed') 'Can I have 50 pounds to mend the shed?' 9.4.3. The conversion part Following the name part of a format code, you can use one of these two forms to force the value to be converted by a standard function: !s str() !r repr() Here's an example: >>> "{}".format('Don\'t') "Don't" >>> "{!r}".format('Don\'t') '"Don\'t"' 9.4.4. The spec part After the name and conversion parts of a format code, you may use a colon (“:”) and a format specifier to supply more details about how to format the related value. Here is the general form of a format specifier. ":" [[fill] align] [sign] ["#"] ["0"] [width] [","] ["." prec] [type] fill You may specify any fill character except “}”. This character is used to pad a short value to the specified length. It may be specified only in combination with an align character. align Specifies how to align values that are not long enough to occupy the specified length. There are four values: < Left-justify the value. This is the default alignment for string values. > Right-justify the value. This is the default alignment for numbers. ^ Center the value. = For numbers using a sign specifier, add the padding between the sign and the rest of the value. Here are some examples of the use of fill and align. >>> "{:>8}".format(13) ' 13' >>> "{:>8}".format('abc') ' abc' >>> "{:*>8}".format('abc') '*****abc' >>> "{:*<8}".format('abc') 'abc*****' >>> "{:>5d}".format(14) ' 14' >>> "{:#>5d}".format(14) '###14' >>> "{:<6}".format('Git') 'Git ' >>> "{:*<6}".format('Git') 'Git***' >>> "{:=^8}".format('Git') '==Git===' >>> "{:*=-9d}".format(-3) '-*******3' sign This option controls whether an arithmetic sign is displayed. There are three possible values: + Always display a sign: + for positive, - for negative. - Display - only for negative values. (one space) Display one space for positive values, - for negative. Here are some examples of use of the sign options. >>> '{} {}'.format(17, -17) '17 -17' >>> '{:5} {:5}'.format(17, -17) ' 17 -17' >>> '{:<5} {:<5}'.format(17, -17) '17 -17 ' >>> '{:@<5} {:@<5}'.format(17, -17) '17@@@ -17@@' >>> '{:@>5} {:@>5}'.format(17, -17) '@@@17 @@-17' >>> '{:@^5} {:@^5}'.format(17, -17) '@17@@ @-17@' >>> '{:@^+5} {:@^+5}'.format(17, -17) '@+17@ @-17@' >>> '{:@^-5} {:@^-5}'.format(17, -17) '@17@@ @-17@' >>> '{:@^ 5} {:@^ 5}'.format(17, -17) '@ 17@ @-17@' "#" This option selects the “alternate form” of output for some types. • When formatting integers as binary, octal, or hexadecimal, the alternate form adds “0b”, “0o”, or “0x” before the value, to show the radix explicitly. >>> "{:4x}".format(255) ' ff' >>> "{:#4x}".format(255) '0xff' >>> "{:9b}".format(62) ' 111110' >>> "{:#9b}".format(62) ' 0b111110' >>> "{:<#9b}".format(62) '0b111110 ' • When formatting float, complex, or Decimal values, the “#” option forces the result to contain a decimal point, even if it is a whole number. >>> "{:5.0f}".format(36) ' 36' >>> "{:#5.0f}".format(36) ' 36.' >>> from decimal import Decimal >>> w=Decimal(36) >>> "{:g}".format(w) '36' >>> "{:#g}".format(w) '36.' "0" To fill the field with left zeroes, place a “0” at this position in your format code. >>> "{:5d}".format(36) ' 36' >>> "{:05d}".format(36) '00036' >>> "{:021.15}".format(1.0/7.0) '00000.142857142857143' width Place a number at this position to specify the total width of the displayed value. >>> "Beware the {}!".format('Penguin') 'Beware the Penguin!' >>> "Beware the {:11}!".format('Penguin') 'Beware the Penguin !' >>> "Beware the {:>11}!".format('Penguin') 'Beware the Penguin!' "," Place a comma at this position in your format code to display commas between groups of three digits in whole numbers. Note This feature was added in Python 2.7. >>> "{:,d}".format(12345678901234) '12,345,678,901,234' >>> "{:,f}".format(1234567890123.456789) '1,234,567,890,123.456787' >>> "{:25,f}".format(98765432.10987) ' 98,765,432.109870' "." precision Use this part to specify the number of digits after the decimal point. >>> from math import pi >>> "{}".format(pi) '3.141592653589793' >>> "{:.3}".format(pi) '3.14' >>> "{:25,.3f}".format(1234567890123.456789) ' 1,234,567,890,123.457' type This code specifies the general type of format used. The default is to convert the value of a string as if using the str() function. Refer to the table below for allowed values. b Format an integer in binary. c Given a number, display the character that has that code. d Display a number in decimal (base 10). e Display a float value using the exponential format. E Same as e, but use a capital “E” in the exponent. f Format a number in fixed-point form. g General numeric format: use either f or g, whichever is appropriate. G Same as “g”, but uses a capital “E” in the exponential form. n For formatting numbers, this format uses the current local setting to insert separator characters. For example, a number that Americans would show as “1,234.56”, Europeans would show it as “1.234,56”. o Display an integer in octal format. x Display an integer in hexadecimal (base 16). Digits greater than 9 are displayed as lowercase characters. X Display an integer in hexadecimal (base 16). Digits greater than 9 are displayed as uppercase characters. % Display a number as a percentage: its value is multiplied by 100, followed by a “%” character. Examples: >>> "{:b}".format(9) '1001' >>> "{:08b}".format(9) '00001001' >>> "{:c}".format(97) 'a' >>> "{:d}".format(0xff) '255' >>> from math import pi >>> "{:e}".format(pi*1e10) '3.141593e+10' >>> "{:E}".format(pi*1e10) '3.141593E+10' >>> "{:f}".format(pi) '3.141593' >>> "{:g}".format(pi) '3.14159' >>> "{:g}".format(pi*1e37) '3.14159e+37' >>> "{:G}".format(pi*1e37) '3.14159E+37' >>> "{:o}".format(255) '377' >>> "{:#o}".format(255) '0o377' >>> "{:x}".format(105199) '19aef' >>> "{:X}".format(105199) '19AEF' >>> "{:<#9X}".format(105199) '0X19AEF ' >>> "{:%}".format(0.6789) '67.890000%' >>> "{:15.3%}".format(0.6789) ' 67.890%' 9.4.5. Formatting a field of variable length Sometimes you need to format a field using a length that is available only once the program is running. To do this, you can use a number or name in {braces} inside a format code at the width position. This item then refers to either a positional or keyword argument to the .format() method as usual. Here's an example. Suppose you want to format a number n using d digits. Here are examples showing this with and without left-zero fill: >>> n = 42 >>> d = 8 >>> "{0:{1}d}".format(42, 8) ' 42' >>> "{0:0{1}d}".format(42, 8) '00000042' >>> You can, of course, also use keyword arguments to specify the field width. This trick also works for variable precision. "{count:0{width}d}".format(width=8, count=42) '00000042' >>> The same technique applies to substituting any of the pieces of a format code. >>> "{:&<14,d}".format(123456) '123,456&&&&&&&' >>> "{1:{0}{2}{3},{4}}".format('&', 123456, '<', 14, 'd') '123,456&&&&&&&' >>> "{:@^14,d}".format(1234567) '@@1,234,567@@@' >>> "{n:{fil}{al}{w},{kind}}".format( ... kind='d', w=14, al='^', fil='@', n=1234567) '@@1,234,567@@@' The older string format operator 9.5. The older string format operator Python versions before 2.6 did not have the string .format() method described in Section 9.4, “The string .format() method” (p. ). Instead, string formatting used this general form: f % v where f is a 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 Table 4, “Format codes” (p. ). 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 Table 3. Parts of the format operator p An optional prefix; see Table 5, “Format code prefixes” (p. ). 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: Table 4. Format codes %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%.'. Table 5. Format code prefixes + 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 also use the string format operator % to format a set of values from a dictionary D (see Section 16, “Type dict: Dictionaries” (p. )): 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:' Type unicode: Strings of 32-bit characters 10. Type unicode: Strings of 32-bit characters 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 homepage77 http://www.unicode.org/. 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[, error ) 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 Section 10.1, “The UTF-8 encoding” (p. ). The optional error string specifies what to do with characters that do not have exact equivalents. For example, if you are converting to the ASCII character set, the encoding argument is 'ascii'. Values of the error argument are given in the table below. 'strict' Raise a UnicodeError exception if any character has no ASCII equivalent. This is the default behavior. 'ignore' Leave out characters that have no equivalent. 'replace' Substitute a '?' for each character that has no equivalent. 'xmlcharrefreplace' Use the XML character entity escape sequence for characters with no ASCII equivalent. The general form of this sequence is "&#N;", where N is the decimal value of the character's code point. This feature is very handy for generating internationalized Web pages. 'backslashreplace' Use Python backslash escape sequences to represent characters with no equivalent. Here are some examples to demonstrate error argument values. >>> s = u"a\u262ez" >>> len(s) 3 >>> s u'a\u262ez' >>> s.encode('ascii') Traceback (most recent call last): File "<stdin>", line 1, in <module> UnicodeEncodeError: 'ascii' codec can't encode character u'\u262e' in position 1: ordinal not in range(128) >>> s.encode('ascii', 'ignore') 'az' >>> s.encode('ascii', 'replace') 'a?z' >>> s.encode('ascii', 'xmlcharrefreplace') 'a&#9774;z' >>> hex(9774) '0x262e' >>> t = s.encode('ascii', 'backslashreplace') >>> t 'a\\u262eb' >>> print t a\u262eb >>> len(t) 8 >>> t[1] '\\' The UTF-8 encoding 10.1. The UTF-8 encoding 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 codecs88 http://docs.python.org/library/module-codecs.html. Type list: Mutable sequences 11. Type list: Mutable sequences 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 Section 12, “Type tuple: Immutable sequences” (p. ). 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 Section 11.2, “List comprehensions” (p. ). Lists support all the operations described under Section 8.1, “Operations common to all the sequence types” (p. ). Methods available on lists are discussed in Section 11.1, “Methods on lists” (p. ). There are a number of functions that can be used with lists as well: • Section 20.2, “all(): Are all the elements of an iterable true?” (p. ). • Section 20.3, “any(): Are any of the members of an iterable true?” (p. ). • Section 20.8, “cmp(): Compare two values” (p. ). • Section 20.12, “enumerate(): Step through indices and values of an iterable” (p. ) • Section 20.14, “filter(): Extract qualifying elements from an iterable” (p. ). • Section 20.21, “iter(): Produce an iterator over a sequence” (p. ). • Section 20.22, “len(): Number of elements” (p. ). • Section 20.23, “list(): Convert to a list” (p. ). • Section 20.25, “map(): Apply a function to each element of an iterable” (p. ). • Section 20.26, “max(): Largest element of an iterable” (p. ). • Section 20.27, “min(): Smallest element of an iterable” (p. ). • Section 20.33, “range(): Generate an arithmetic progression as a list” (p. ). • Section 20.35, “reduce(): Sequence reduction” (p. ). • Section 20.36, “reversed(): Produce a reverse iterator” (p. ). • Section 20.39, “sorted(): Sort a sequence” (p. ). • Section 20.41, “sum(): Total the elements of a sequence” (p. ). • Section 20.46, “xrange(): Arithmetic progression generator” (p. ). • Section 20.47, “zip(): Combine multiple sequences” (p. ). Methods on lists 11.1. Methods on lists 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. Compare Section 20.36, “reversed(): Produce a reverse iterator” (p. ). >>> 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. Compare Section 20.39, “sorted(): Sort a sequence” (p. ). 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 Section 20.8, “cmp(): Compare two values” (p. ). 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 precedes the second, a positive number if the second argument precedes 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] List comprehensions 11.2. List comprehensions 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 Section 23.4, “The for statement: Iteration over a sequence” (p. ). 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 appends 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 appended 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)] Type tuple: Immutable sequences 12. Type tuple: Immutable sequences 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 key in a dictionary. >>> 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 any iterable into a tuple using Section 20.42, “tuple(): Convert to a tuple” (p. ). The tuple type does not have comprehensions (see Section 11.2, “List comprehensions” (p. )), but you can get the equivalent by applying the tuple() function to a list comprehension. Here is an example: >>> tuple([x**2 for x in (2,3,8)]) (4, 9, 64) >>> Tuples also support the .index() and .count() methods as described in Section 11.1, “Methods on lists” (p. ). The bytes type 13. The bytes type To understand why Python version 2.6 and beyond have a bytes type, it is necessary to review a little history. Most early computing used 7- and 8-bit character codes, but these character sets are very limited. In particular, life was difficult for Francophone countries when “è” and “é” are very different letters. The 32-bit character set of the Unicode standard99 http://www.unicode.org/ is the current preferred practice, and provides enough characters to last a good while into the future. Text handling in the Python 2.x releases was awkward due to the presence of two different types for representing character data: str and unicode. Consequently, in the upcoming major incompatible 3.x releases, all character data will be represented internally by 32-bit characters. Therefore, in Python 2.6 the bytes type was added to aid transition to the 3.0 family, which has a separate bytes type for 8-bit character strings. In the 3.x versions, a bytes value is a sequence of zero or more unsigned 8-bit integers, each in the range 0–255, inclusive. In Python 2.6 and subsequent versions, the bytes type is a synonym for str. The bytes() function works exactly like the str() function. >>> s=bytes(987) >>> s '987' >>> type(s) <type 'str'> Use this type where your program expects 8-bit characters, and it will ease the transition to Python 3.x, because the semi-automated translation process will know that values of bytes type are intended for sequences of 8-bit characters. Using the bytes type in 3.x conversion 13.1. Using the bytes type in 3.x conversion Versions 2.6+ support a new notation: to create a literal of type bytes, place a “b” just before the opening quote. >>> s = b'abc' >>> s 'abc' >>> type(s) <type 'str'> Such literals are exactly like regular string literals. The difference comes when you convert your program to the 3.x versions. In Python 3.x, a string of the form b'...' will have type bytes, which will be different than the str (32-bit character) type in 3.x. One step in converting your 2.x programs to 3.x is to add this import before all the other imports in your program: from __future__ import unicode_literals In programs that start with this declaration, all string literals will automatically be considered unicode type without using the u'...' prefix. This means you may also include escape sequences of the form '\uXXXX', each of which designates a 16-bit Unicode code point as four hexadecimal digits XXXX. Here is a demonstration of the difference. Before the import, the \u escape is not recognized, and the value has type str. Afterwards, the return value is type unicode >>> s = '\u2672' >>> len(s) 6 >>> s '\\u2672' >>> type(s) <type 'str'> >>> from __future__ import unicode_literals >>> t = '\u2672' >>> len(t) 1 >>> type(t) <type 'unicode'> >>> t u'\u2672' The bytearray type 14. The bytearray type New in Python 2.6 is the bytearray type. Each instance is a sequence of 8-bit bytes, each of which is an unsigned integer in the range 0 <= 255. Unlike the str type, however, bytearray values are mutable: you can delete, insert, or replace arbitrary values or slices. As with the features described in Section 13, “The bytes type” (p. ), this type is intended to ease the transition to Python 3.x versions. Use it for situations where you are handling sequences of 8-bit bytes that are not intended as textual representations, such as raw binary data. Values of this type support almost all of the operators and methods of the str type (with the exception of .encode() and .format() methods). They also support these methods of the list type: .extend(), .insert(), .pop(), .remove(), .reverse(). You can also replace values using either integers or the b'...' (bytes) literals. Some examples: >>> s=bytearray('abcdef') >>> s bytearray(b'abcdef') >>> type(s) <type 'bytearray'> >>> s[3] 100 >>> s.insert(0, b'^') >>> s bytearray(b'^abcdef') >>> s.reverse() >>> s bytearray(b'fedcba^') >>> s[2:6] bytearray(b'dcba') >>> s[2:6] = b'#' >>> s bytearray(b'fe#^') >>> s[0]=63 >>> s bytearray(b'?e#^') >>> The bytearray type also has a static method named .fromhex() that creates a bytearray value from a Unicode string containing hexadecimal characters (which may be separated by spaces for legibility). >>> ao = bytearray.fromhex(u'00 ff') >>> ao bytearray(b'\x00\xff') >>> ao[1] 255 Types set and frozenset: Set types 15. Types set and frozenset: Set types 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. There are two ways to create a mutable set. • In all Python versions of the 2.x series, the set(S) function operates on a sequence S and returns a mutable set containing the unique elements of S. The argument is optional; if omitted, you get a new, empty set. >>> s1 = set([1, 1, 1, 9, 1, 8, 9, 8, 3]) set([8, 1, 3, 9]) >>> s1 = set([1, 1, 1, 9, 1, 8, 9, 8, 3]) >>> s2 = set() >>> s1 set([8, 1, 3, 9]) >>> s2 set([]) >>> print len(s1), len(s2) 4 0 >>> s3 = set("notlob bolton") >>> s3 s3 set([' ', 'b', 'l', 'o', 'n', 't']) • Starting in Python 2.7, you can create a set by simply enclosing one or more elements within braces {...} separated by commas. s1 = {1, 1, 1, 9, 1, 8, 9, 8, 3} >>> s1 set([8, 9, 3, 1]) Note the wording “one or more:” an empty pair of braces “{}” is an empty dictionary, not an empty set. • 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 Section 20.38, “set(): Create an algebraic set” (p. ) and Section 20.17, “frozenset(): Create a frozen set” (p. ). A number of functions that work on sequences also work on sets. In each case, the set is converted to a list before being passed to the function. • Section 20.2, “all(): Are all the elements of an iterable true?” (p. ). Predicate to test whether all members of a set are True. • Section 20.3, “any(): Are any of the members of an iterable true?” (p. ). Predicate to test whether any member of a set is true. • Section 20.14, “filter(): Extract qualifying elements from an iterable” (p. ). Returns a list of the elements that pass through a filtering function. • Section 20.21, “iter(): Produce an iterator over a sequence” (p. ). Returns an iterator that will visit every element of the set. • Section 20.22, “len(): Number of elements” (p. ). Returns the length (cardinality) of the set. • Section 20.23, “list(): Convert to a list” (p. ). Returns the elements of the set as a list. • Section 20.25, “map(): Apply a function to each element of an iterable” (p. ). Returns a list containing the result of the application of a function to each element of a set. • Section 20.26, “max(): Largest element of an iterable” (p. ). Returns the largest element of a set. • Section 20.27, “min(): Smallest element of an iterable” (p. ). Returns the smallest element of a set. • Section 20.35, “reduce(): Sequence reduction” (p. ). Returns the result of the application of a given function pairwise to all the elements of a set. • Section 20.39, “sorted(): Sort a sequence” (p. ). Returns a list containing the sorted elements of the set. Another new feature in Python 2.7 is the set comprehension. This is similar to the feature described in Section 11.2, “List comprehensions” (p. ). Here is the general form: { e for v1 in s1 for v2 in s2 ... if c } As with a list comprehension, you use one or more for clauses to iterate over sets of values, and the expression e is evaluated for every combination of the values in the sequences si. If there is no “if” clause, or if the “if” condition evaluates as True, the value is added to the sequence from which a set is then constructed. Here is an example. Function takeUppers() takes one string argument and returns a set of the unique letters in that string, uppercased. The for clause iterates over the characters in the argument s; the if clause discards characters that aren't letters; and the .upper() method converts lowercase letters to uppercase. >>> def takeUpper(s): ... return { c.upper() ... for c in s ... if c.isalpha() } ... >>> takeUpper("A a|ccCc^#zZ") set(['A', 'C', 'Z']) Operations on mutable and immutable sets 15.1. Operations on mutable and immutable 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 S2 argument may be a set or a sequence. >>> 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 a sequence. >>> 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. S2 may be a set or a sequence. >>> 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. S2 may be a set or a sequence. >>> 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 S2 argument may be a set or a 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 a 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). Operations on mutable sets 15.2. Operations on mutable sets 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. Duplicate 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 S. 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.difference_update(S2) Modify set S1 by removing any values found in S2. Value S2 may be a set or a sequence. >>> s1=set('roygbiv') >>> s1.difference_update('rgb') >>> s1 set(['i', 'o', 'v', 'y']) S1 -= S2 Same as S1.difference_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']) S1 &= S2 Same as S1.intersection_update(S2), but S2 must be a set. 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 a sequence. >>> 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 a sequence. >>> 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. Type dict: Dictionaries 16. Type dict: Dictionaries 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'} Operations on dictionaries 16.1. Operations on dictionaries 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 Section 22.3, “The del statement: Delete a name or part of a value” (p. ). 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 Section 24.2, “Iterators: Values that can produce a sequence of values” (p. ). >>> roster={1:'Pat', 2:'Ray', 3:'Min'} >>> rosterScan = roster.iteritems() >>> for n, name in rosterScan: ... print "{0:04d}: {1}".format(n, name) ... 0001: Pat 0002: Ray 0003: Min D.iterkeys() Returns an iterator that generates the keys from dictionary D. See Section 24.2, “Iterators: Values that can produce a sequence of values” (p. ). >>> 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 Section 24.2, “Iterators: Values that can produce a sequence of values” (p. ). >>> 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'} Dictionary comprehensions 16.2. Dictionary comprehensions New in Python 2.7 are dictionary comprehensions: a construct that allows you to build a dictionary dynamically, somewhat like Section 11.2, “List comprehensions” (p. ). Here is the general form: { ek: ev for v1 in s1 for v2 in s2 ... if c } As with list comprehensions, you provide one or more for clauses and an optional if clause. For all possible combinations of the values in the for clauses that have a true value for the if clause, two expressions ek and ev are evaluated, and a new dictionary entry is added with key ek and value ev. Here is an example. The Wikipedia article on the game of Scrabble1010 http://en.wikipedia.org/wiki/Scrabble_letter_distributions gives the Scrabble score for each letter of the alphabet. What we would like is a dictionary whose keys are letters, and each related value is the score. However, the Wikipedia article shows the score values grouped by score: the 1's together, the 2's together, and so on. So, to make it easy to check that we have entered the right score values and letters, we can use a list of tuples, where the first element of each tuple is the score and the second element is a string of all the letters with that score. We can then convert that list to the desired dictionary using a dictionary comprehension. >>> scrabbleTuples = [ (1, "EAOINRTLSU"), (2, "DG"), (3, "BCMP"), ... (4, "FHVWY"), (5, "K"), (8, "JX"), (10, "QZ")] >>> scrabbleMap = { letter: score ... for score, letterList in scrabbleTuples ... for letter in letterList } >>> scrabbleMap['A'] 1 >>> scrabbleMap['Z'] 10 Evaluating the set comprehension proceeds as follows. 1. In the first for clause, the first tuple is unpacked, setting score to 1 and letterList to "EAOINRTLSU". 2. In the second for clause, letter is set to "E". 3. A new entry is added to the dictionary, with key "E" and value 1. 4. In the second for clause, letter is set to "A". 5. A new entry is added with key "A" and value 1. Execution proceeds in this manner until all the for clauses are complete. Then the name scrabbleMap is bound to the resulting dictionary. Type file: Input and output files 17. Type file: Input and output files 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. Important 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. • For modes beginning with 'r', you may append a capital 'U' to request universal newline treatment. This is handy when you are reading files made on a platform with different line termination conventions. When reading lines from a file opened in this way, any line terminator ('\n', '\r', or '\r\n') will appear in the return value as the standard '\n'. Also, files so opened will have an attribute named .newlines; this attribute will be None initially, but after any line terminators have been read, it will be a tuple containing all the different line terminator strings seen so far. 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. • Use a negative value to request the system defaults. 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 Section 24.2, “Iterators: Values that can produce a sequence of values” (p. )). 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 Section 17.1, “Methods on file objects” (p. ). • 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 as a holding area for data being 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 Section 17.1, “Methods on file objects” (p. ). Methods on file objects 17.1. Methods on file objects 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. None: The special placeholder value 18. None: The special placeholder value 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 Operators and expressions 19. Operators and expressions Python's operators are shown here from highest precedence to lowest, with a ruled line separating groups of operators with equal precedence: Table 6. Python operator precedence (E) Parenthesized expression or tuple. [E, ...] List. {key:value, ...} Dictionary or set. `...` Convert to string representation. x.attribute Attribute reference. x[...] Subscript or slice; see Section 8.1, “Operations common to all the sequence types” (p. ). 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 Section 19.1, “What is a predicate?” (p. ). 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.” What is a predicate? 19.1. What is a predicate? 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. What is an iterable? 19.2. What is an iterable? To iterate over a sequence means to visit each element of the sequence, and do some operation for each element. In Python, we say that a value is an iterable when your program can iterate over it. In short, an iterable is a value that represents a sequence of one more values. All instances of Python's sequence types are iterables. These types may be referred to as container types: a unicode string string is a container for 32-bit characters, and lists and tuples are general-purpose containers that can contain any sequence. One of the most common uses for an iterable is in a for statement, where you want to perform some operation on a sequence of values. For example, if you have a tuple named celsiuses containing Celsius temperatures, and you want to print them with their Fahrenheit equivalents, and you have written a function cToF() that converts Celsius to Fahrenheit, this code does it: >>> def cToF(c): return c*9.0/5.0 + 32.0 ... >>> celsiuses = (0, 20, 23.6, 100) >>> for celsius in celsiuses: ... print "{0:.1f} C = {1:.1f} F".format(celsius, cToF(celsius)) ... 0.0 C = 32.0 F 20.0 C = 68.0 F 23.6 C = 74.5 F 100.0 C = 212.0 F However, Python also supports mechanisms for lazy evaluation: a piece of program that acts like a sequence, but produces its contained values one at a time. Keep in mind that the above code works exactly the same if celsiuses is an iterator (see Section 24.2, “Iterators: Values that can produce a sequence of values” (p. )). You may find many uses for iterators in your programs. For example, celsiuses might be a system that goes off and reads an actual thermometer and returns the readings every ten seconds. In this application, the code above doesn't care where celsiuses gets the values, it cares only about how to convert and print them. Duck typing, or: what is an interface? 19.3. Duck typing, or: what is an interface? When I see a bird that walks like a duck and swims like a duck and quacks like a duck, I call that bird a duck. —James Whitcomb Riley The term duck typing comes from this quote. In programming terms, this means that the important thing about a value is what it can do, not its type. As the excellent Wikipedia article on duck typing1111 http://en.wikipedia.org/wiki/Duck_typing says, “Simply stated: provided you can perform the job, we don't care who your parents are.” One common example of duck typing is in the Python term “file-like object”. If you open a file for reading using the open() function, you get back a value of type file: >>> inFile = open('input') >>> type(inFile) <type 'file'> Let's suppose that you write a function called numberIt() that takes a readable file as an argument and prints the lines from a file preceded by five-digit line numbers. Here's the function and an example of its use: >>> def numberIt(f): ... for lineNo, line in enumerate(f): ... print "{0:05d} {1}".format(lineNo, line.rstrip()) ... >>> numberIt(inFile) 00000 Kant 00001 Heidegger 00002 Hume The way you have written the numberIt() function, it works for files, but it also works for any iterable. Thus, when you see the statement that some Python feature works with a “file-like object,” that means that the object must have an interface like that of the file type; Python doesn't care about the type, just the operations that it supports. In practice, the enumerate() function works with any iterable, so your function will also work with any iterable: >>> numberIt(['Kant', 'Heidegger', 'Hume']) 00000 Kant 00001 Heidegger 00002 Hume So in Python when we say that we expect some value to have an interface, we mean that it must provide certain methods or functions, but the actual type of the value is immaterial. More formally, when we say that a value supports the iterable interface, that value must provide either of the following features: • A .__getitem__() method as described in Section 26.3.16, “__getitem__(): Get one item from a sequence or mapping” (p. ). • A .__iter__() method as described in Section 26.3.17, “__iter__(): Create an iterator” (p. ). Basic functions 20. Basic functions 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 Section 21, “Advanced functions” (p. ). abs(): Absolute value 20.1. abs(): Absolute value 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.imag**2). >>> abs(-33) 33 >>> abs(33) 33 >>> abs(0) 0 >>> abs(complex(1,5)) 5.0990195135927845 all(): Are all the elements of an iterable true? 20.2. all(): Are all the elements of an iterable true? A predicate that tests whether all the elements of some iterable 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 any(): Are any of the members of an iterable true? 20.3. any(): Are any of the members of an iterable true? This function, applied to some iterable, is a predicate that tests whether any of the elements of that iterable 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 bin(): Convert to binary 20.4. bin(): Convert to binary This function takes an integer argument and returns a string that represents that number in binary (base 2) starting with '0b'. >>> bin(7) '0b111' >>> bin(257) '0b100000001' bool(): Convert to Boolean 20.5. bool(): Convert to Boolean 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 Section 7.3, “Type bool: Boolean truth values” (p. ). 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 bytearray(): Create a byte array 20.6. bytearray(): Create a byte array See Section 14, “The bytearray type” (p. ). chr(): Get the character with a given code 20.7. chr(): Get the character with a given code For arguments n in the range 0 to 255, this function returns a one-character string containing the character that has code n. Compare Section 20.31, “ord(): Find the numeric code for a character” (p. ). >>> chr(65) 'A' >>> chr(0) '\x00' cmp(): Compare two values 20.8. cmp(): Compare two values 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 complex(): Convert to complex type 20.9. complex(): Convert to complex type To create a complex number from a real part R and a complex part I: complex(R, I) Both arguments are optional. • With two arguments, both arguments must be numbers of any numeric type. With one numeric argument, it returns a complex number with real part R and an imaginary part of zero. To convert a complex number in string form, pass that string as the only argument. If the string is not a valid complex number, the function raises a ValueError exception. • If called with no arguments, it returns a complex zero. Examples: >>> complex(-4.04, 3.173) (-4.04+3.173j) >>> complex(-4.04) (-4.04+0j) >>> complex() 0j >>> c1=4+5j >>> c2=6+7j >>> complex(c1, c2) # Equals (4+5j)+(6+7j)j = 4+5j+6j-7 (-3+11j) >>> c1 + c2*1.0j (-3+11j) dict(): Convert to a dictionary 20.10. dict(): Convert to a dictionary 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 one positional argument is supplied, it must be a iterable containing two-element iterables. Each two-element iterable 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'} divmod(): Quotient and remainder 20.11. divmod(): Quotient and remainder divmod(x, y) 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). Examples: >>> divmod(13, 5) (2, 3) >>> divmod(1.6, 0.5) (3.0, 0.10000000000000009) enumerate(): Step through indices and values of an iterable 20.12. enumerate(): Step through indices and values of an iterable Given an iterable S, enumerate(S) produces an iterator that iterates over the pairs of values (i, S[i]), for i having the values in range(len(S)). For more information on iterators, see Section 24.2, “Iterators: Values that can produce a sequence of values” (p. ). >>> L = ['Ministry', 'of', 'Silly', 'Walks'] >>> for where, what in enumerate(L): ... print "[{0}] {1}".format(where, what) ... [0] Ministry [1] of [2] Silly [3] Walks If you would like the numbers to start at a different origin, pass that origin as the second argument to the enumerate() function. You will still get all the elements of the sequence, but the numbers will start at the value you provide. (Python 2.6 and later versions only.) >>> for where, what in enumerate(L, 1): ... print "[{0}] {1}".format(where, what) ... [1] Ministry [2] of [3] Silly [4] Walks file(): Open a file 20.13. file(): Open a file This function is identical to the open() function; for details, see Section 17, “Type file: Input and output files” (p. ). filter(): Extract qualifying elements from an iterable 20.14. filter(): Extract qualifying elements from an iterable This function is useful for removing some of the elements of an iterable. You must provide a filtering function that takes one argument and returns a bool 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 iterable S. The result is a new sequence containing only those elements x of S for which f(x) returned True. • If f is a string or tuple, the result has the same type, otherwise the result is a list. • If f is None, you get a sequence of the true elements of S. In this case, the filtering function is effectively the bool() function. >>> 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' >>> maybes = [0, 1, (), (2,), 0.0, 0.25] >>> filter(None, maybes) [1, (2,), 0.25] >>> filter(bool, maybes) [1, (2,), 0.25] float(): Convert to float type 20.15. float(): Convert to float type 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 format(): Format a value 20.16. format(): Format a value This function converts a value to a formatted representation. The general form is: format(value[, spec]) • For built-in types, the spec has the syntax as that described in Section 9.4, “The string .format() method” (p. ) between “:” and the closing “}”. >>> x = 34.56 >>> format(x, '9.4f') ' 34.5600' >>> '{0:9.4f}'.format(x) ' 34.5600' • You can define how this function works for a user-defined class by defining the special method described in Section 26.3.13, “__format__: Implement the format() function” (p. ). • If the spec argument is omitted, the result is the same as str(value). frozenset(): Create a frozen set 20.17. frozenset(): Create a frozen set This function is used to create a new frozenset value: an immutable set. General form: frozenset(S) This function converts an existing iterable S to a frozenset. The argument is optional; if omitted, you get a frozen empty set. >>> 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 Section 15, “Types set and frozenset: Set types” (p. ). hex(): Convert to base 16 20.18. hex(): Convert to base 16 Given an integer, this function returns a string displaying that value in hexadecimal (base 16). >>> hex(15) '0xf' >>> hex(255) '0xff' >>> hex(256) '0x100' >>> hex(1325178541275812780L) '0x1263fadcb8b713ac' See also Section 9.4, “The string .format() method” (p. ): hexadecimal conversion is supported by specifying a type code of 'x' or 'X'. int(): Convert to int type 20.19. int(): Convert to int type 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, expressed in a radix (base) other than 10, to an int, use this form, where b is an integer in the range [2, 36] that specifies the 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 input(): Read an expression from the user 20.20. input(): Read an expression from the user This function asks the user to type something, then evaluates it as a Python expression. Here is the general form: input([prompt]) If you supply a string as the optional prompt argument, that string will be written to the user before the input is read. In any case, the result is the value of the expression. Of course, if the user types something that isn't a valid Python expression, the function will raise an exception. >>> input() 2+2 4 >>> print "The answer was '{0}'.".format(input()) 2+3*4 The answer was '14'. >>> print "The answer was '{0}'.".format(input("Type an expression:")) Type an expression:2+3*4 The answer was '14'. >>> print input() 1/0 Traceback (most recent call last): File "<stdin>", line 1, in <module> File "<string>", line 1, in <module> ZeroDivisionError: integer division or modulo by zero iter(): Produce an iterator over a sequence 20.21. iter(): Produce an iterator over a sequence Given a sequence S, this function returns an iterator that generates the elements of the sequence. For more information, see Section 24.2, “Iterators: Values that can produce a sequence of values” (p. ). >>> listWalker = iter ( [23, 47, 'hike'] ) >>> for x in listWalker: print x, ... 23 47 hike In general, the calling sequence is: iter(s[, sentinel]) • If the sentinel argument is omitted, the first argument must be either a sequence value that implements the .__getitem__() method or an instance of a class that has the .__iter__() method. • If you provide a sentinel argument, the s argument must be callable. The iterator returned will call s() with no arguments and generate the values it returns until the return value equals sentinel, at which point it will raise StopIteration. len(): Number of elements 20.22. len(): Number of elements Given a sequence or dictionary, this function returns the number of elements. >>> len('') 0 >>> len ( [23, 47, 'hike'] ) 3 >>> len({1: 'foot', 2:'shoulder', 'feather': 'rare'}) 3 list(): Convert to a list 20.23. list(): Convert to a list This function creates a new list. The argument x may be any iterable (see Section 19.2, “What is an iterable?” (p. )). >>> list(('Bentham', 'Locke', 'Hobbes')) ['Bentham', 'Locke', 'Hobbes'] >>> list("Bruce") ['B', 'r', 'u', 'c', 'e'] >>> list((42,)) [42] >>> list() [] long(): Convert to long type 20.24. long(): Convert to long type This function works exactly the same way as Section 20.19, “int(): Convert to int type” (p. ), except that it produces a result of type long. >>> long(43) 43L >>> long(43.889) 43L >>> long('12345678901234567890123457890') 12345678901234567890123457890L >>> long('potrzebie456', 36) 3381314581245790842L map(): Apply a function to each element of an iterable 20.25. map(): Apply a function to each element of an iterable The purpose of this function is to perform some operation on each element of an iterable. It returns a list containing the result of those operations. Here is the general form: map(f, S) • f is a function that takes one argument and returns a value. • S is any iterable. >>> def add100(x): ... return x+100 ... >>> map(add100, (44,22,66)) [144, 122, 166] To apply a function with multiple arguments to a set of sequences, just provide multiple iterables as arguments, like this. >>> def abc(a, b, c): ... return a*10000 + b*100 + c ... >>> map(abc, (1, 2, 3), (4, 5, 6), (7, 8, 9)) [10407, 20508, 30609] If you pass None as the first argument, Python uses the identity function to build the resulting list. This is useful if you want to build a list of tuples containing items from two or more iterables. >>> map(None, range(3)) [0, 1, 2] >>> map(None, range(3), 'abc', [44, 55, 66]) [(0, 'a', 44), (1, 'b', 55), (2, 'c', 66)] max(): Largest element of an iterable 20.26. max(): Largest element of an iterable Given an iterable S that contains at least one element, max(S) returns the largest element of the sequence. >>> max('blimey') 'y' >>> max ( [-505, -575, -144, -288] ) -144 >>> max([]) Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: max() arg is an empty sequence You can also pass multiple arguments, and max() will return the largest. In the example below, 'cheddar' is the largest because lowercase letters have higher codes than uppercase letters. >>> max('Gumby', 'Lambert', 'Sartre', 'cheddar') 'cheddar' If you want to redefine the comparison function, you may provide a keyword argument key=f, where f is a function that takes one argument and returns a value suitable for comparisons. In this example, we use the .upper() method of the str class to compare the uppercased strings, then return the original string whose uppercased value is largest. >>> max('Gumby', 'Lambert', 'Sartre', 'cheddar', key=str.upper) 'Sartre' min(): Smallest element of an iterable 20.27. min(): Smallest element of an iterable Given an iterable S containing at least one element, max(S) returns the largest element of S. >>> min('blimey') 'b' >>> min ( [-505, -575, -144, -288] ) -575 You may also pass multiple arguments, and the min() function will return the smallest. >>> min(-505, -575, -144, -288) -575 If you would like to use a different function to define the ordering, specify that function as a keyword argument key=f, where f is a function that takes one argument and returns a value suitable for comparisons. In this example, we want to order the values based on their inverse. >>> def rev(x): ... return -x ... >>> min(-505, -575, -144, -288, key=rev) -144 next(): Call an iterator 20.28. next(): Call an iterator This function attempts to get the next value from some iterator I (see Section 24.2, “Iterators: Values that can produce a sequence of values” (p. )). (New in version 2.6.) next(I[, default) • If the iterator produces another value, that value is returned by this function. • If the iterator is exhausted and you provide a default value, that value is returned. • If the iterator is exhausted and you do not provide a default value, the next() function raises a StopIteration exception. Here is an example. >>> it = iter(xrange(0,2)) >>> next(it, 'Done') 0 >>> next(it, 'Done') 1 >>> next(it, 'Done') 'Done' >>> next(it) Traceback (most recent call last): File "<stdin>", line 1, in <module> StopIteration oct(): Convert to base 8 20.29. oct(): Convert to base 8 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' See also Section 9.4, “The string .format() method” (p. ): octal conversion is supported by specifying type code 'o'. open(): Open a file 20.30. open(): Open a file Open a file. For the calling sequence, see Section 17, “Type file: Input and output files” (p. ). ord(): Find the numeric code for a character 20.31. ord(): Find the numeric code for a character Given a string s containing a single character, ord(s) returns that character's numeric code. Compare Section 20.7, “chr(): Get the character with a given code” (p. ). >>> ord('A') 65 >>> ord('\x00') 0 >>> ord(u'\u262e') 9774 >>> hex(9774) '0x262e' pow(): Exponentiation 20.32. pow(): Exponentiation 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 range(): Generate an arithmetic progression as a list 20.33. range(): Generate an arithmetic progression as a list 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 stop. 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] raw_input(): Prompt and read a string from the user 20.34. raw_input(): Prompt and read a string from the user 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. reduce(): Sequence reduction 20.35. reduce(): Sequence reduction The idea of reduction comes from the world of functional programming. There is a good introductory article on this concept in Wikipedia1212 http://en.wikipedia.org/wiki/Fold_(higher-order_function). In simple terms, a function of two arguments is applied repeatedly to the elements of an iterable to build up a final value. • The idea of a “sum of elements of a sequence” is a reduction of those elements using “+” as the function. For example, the +-reduction of [2, 3, 5] is 2+3+5 or 10. • Similarly, the product of a series of numbers is a reduction using the “*” operator: the multiply reduction of [2, 3, 5] is 2*3*5 or 30. There are two general forms: reduce(f, S) reduce(f, S, I) • f is a function that takes two arguments and returns a value. • S is an iterable. 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 S is empty and no initial value was provided, the function raises a TypeError exception. 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 >>> reduce(x100y, []) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: reduce() of empty sequence with no initial value reversed(): Produce a reverse iterator 20.36. reversed(): Produce a reverse iterator This function, applied to a sequence S, returns an iterator that generates the elements of S in reverse order (see Section 24.2, “Iterators: Values that can produce a sequence of values” (p. )). >>> L=[22,44,88] >>> backL = reversed(L) >>> for i in backL: ... print i, ... 88 44 22 The allowable values for S include all the types described in Section 8, “Sequence types” (p. ). It also works for any class provided one of these two conditions is met: • The method described in Section 26.3.20, “__reversed__(): Implement the reversed() function” (p. ). • If the class has no .__reversed__() method, reversed() will still work provided that instances act like a sequence; that is, the class has a .__len__() method and a .__getitem__() method. round(): Round to the nearest integral value 20.37. round(): Round to the nearest integral value 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 retain 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, 4) 3.1416 >>> round(pi,30) 3.1415926535897931 set(): Create an algebraic set 20.38. set(): Create an algebraic set Use this function to create a set value. Here is the general form: set(S) The optional argument S is any iterable; the return value is a new set instance containing the unique values from S. When called with no arguments, this function returns a new, empty set. 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 Section 15, “Types set and frozenset: Set types” (p. ). sorted(): Sort a sequence 20.39. sorted(): Sort a sequence This function, applied to any iterable 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 Section 11.1, “Methods on lists” (p. )). >>> 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'] >>> sorted(L, None, str.upper) ['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 the use of a cmp argument to sort strings as if they were all uppercase; the third example shows how to achieve the same result using the .upper() method of the str class as the key argument. Note in the last line that the original list L is unchanged. str(): Convert to str type 20.40. str(): Convert to str type 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'}" For general information, see Section 9, “Type str: Strings of 8-bit characters” (p. ). sum(): Total the elements of a sequence 20.41. sum(): Total the elements of a sequence This function, applied to an iterable 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 tuple(): Convert to a tuple 20.42. tuple(): Convert to a tuple To convert some iterable 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. For general information, see Section 12, “Type tuple: Immutable sequences” (p. ). 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',) type(): Return a value's type 20.43. type(): Return a value's type 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 unichr(): Convert a numeric code to a Unicode character 20.44. unichr(): Convert a numeric code to a Unicode character Given a number n, this function returns the Unicode character that has code point n. For more on Unicode, see Section 10, “Type unicode: Strings of 32-bit characters” (p. ). >>> unichr(0) u'\x00' >>> unichr(ord('A')) u'A' >>> unichr(0x3046) u'\u3046' >>> unichr(0xe0047) u'\U000e0047' unicode(): Convert to a Unicode string 20.45. unicode(): Convert to a Unicode string Use this function to convert a string to type unicode. For more information about Unicode, see Section 10, “Type unicode: Strings of 32-bit characters” (p. ). >>> unicode('Pratt') u'Pratt' >>> unicode() u'' xrange(): Arithmetic progression generator 20.46. xrange(): Arithmetic progression generator The xrange() function has exactly the same arguments as the range() function (see Section 20.33, “range(): Generate an arithmetic progression as a list” (p. )). The difference is that xrange() is a generator (see Section 24.3, “Generators: Functions that can produce a sequence of values” (p. )), 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 zip(): Combine multiple sequences 20.47. zip(): Combine multiple sequences The purpose of this function is to build a list of tuples from two or more iterables of the same length. Here is the general form: zip(S0, S1, S2, ...) Each Si must be in iterable. The result is a list [T0, T1, ...], where each Ti is the tuple (S0[i], S1[i], S2[i], ...). Here are some 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)] Advanced functions 21. Advanced functions This section describes Python functions that most people will never need. However, the advanced Python programmer may find some of them quite useful. basestring: The string base class 21.1. basestring: The string base class 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 Section 21.12, “isinstance(): Is a value an instance of some class or type?” (p. ). callable(): Is this thing callable? 21.2. callable(): Is this thing callable? 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 Section 26.3.5, “__call__(): What to do when someone calls an instance” (p. ). >>> def someFunction(): ... pass ... >>> callable(someFunction) True >>> callable(len) True >>> callable(int) True >>> callable(42) False classmethod(): Create a class method 21.3. classmethod(): Create a class method 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 Section 26.5, “Class methods” (p. ). 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: