blob: 0b4b9417e1b021d5c14f589ba5549b8c4943999b [file] [log] [blame]
Raymond Hettinger72348842003-01-25 21:22:52 +00001 Python 2.3 Quick Reference
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002
Guido van Rossumc8180cc1994-08-05 15:57:31 +00003
Raymond Hettinger72348842003-01-25 21:22:52 +00004 25 Jan 2003 upgraded by Raymond Hettinger for Python 2.3
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00005 16 May 2001 upgraded by Richard Gruet and Simon Brunning for Python 2.0
6 2000/07/18 upgraded by Richard Gruet, rgruet@intraware.com for Python 1.5.2
7from V1.3 ref
81995/10/30, by Chris Hoffmann, choffman@vicorp.com
Guido van Rossumc8180cc1994-08-05 15:57:31 +00009
Andrew M. Kuchling13423f32001-08-06 17:43:49 +000010Based on:
11 Python Bestiary, Author: Ken Manheimer, ken.manheimer@nist.gov
12 Python manuals, Authors: Guido van Rossum and Fred Drake
13 What's new in Python 2.0, Authors: A.M. Kuchling and Moshe Zadka
14 python-mode.el, Author: Tim Peters, tim_one@email.msn.com
15
16 and the readers of comp.lang.python
17
18Python's nest: http://www.python.org Developement: http://
19python.sourceforge.net/ ActivePython : http://www.ActiveState.com/ASPN/
20Python/
21newsgroup: comp.lang.python Help desk: help@python.org
Raymond Hettinger72348842003-01-25 21:22:52 +000022Resources: http://starship.python.net/
23 http://www.vex.net/parnassus/
24 http://aspn.activestate.com/ASPN/Cookbook/Python
25FAQ: http://www.python.org/cgi-bin/faqw.py
Andrew M. Kuchling13423f32001-08-06 17:43:49 +000026Full documentation: http://www.python.org/doc/
Raymond Hettinger72348842003-01-25 21:22:52 +000027Excellent reference books:
28 Python Essential Reference by David Beazley (New Riders)
29 Python Pocket Reference by Mark Lutz (O'Reilly)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +000030
31
32Invocation Options
33
34python [-diOStuUvxX?] [-c command | script | - ] [args]
35
36 Invocation Options
37Option Effect
Raymond Hettinger72348842003-01-25 21:22:52 +000038-c cmd program passed in as string (terminates option list)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +000039-d Outputs parser debugging information (also PYTHONDEBUG=x)
Raymond Hettinger72348842003-01-25 21:22:52 +000040-E ignore environment variables (such as PYTHONPATH)
41-h print this help message and exit
Andrew M. Kuchling13423f32001-08-06 17:43:49 +000042-i Inspect interactively after running script (also PYTHONINSPECT=x) and
43 force prompts, even if stdin appears not to be a terminal
Raymond Hettinger72348842003-01-25 21:22:52 +000044-O optimize generated bytecode (a tad; also PYTHONOPTIMIZE=x)
45-OO remove doc-strings in addition to the -O optimizations
46-Q arg division options: -Qold (default), -Qwarn, -Qwarnall, -Qnew
Andrew M. Kuchling13423f32001-08-06 17:43:49 +000047-S Don't perform 'import site' on initialization
48-t Issue warnings about inconsistent tab usage (-tt: issue errors)
49-u Unbuffered binary stdout and stderr (also PYTHONUNBUFFERED=x).
Andrew M. Kuchling13423f32001-08-06 17:43:49 +000050-v Verbose (trace import statements) (also PYTHONVERBOSE=x)
Raymond Hettinger72348842003-01-25 21:22:52 +000051-W arg : warning control (arg is action:message:category:module:lineno)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +000052-x Skip first line of source, allowing use of non-unix Forms of #!cmd
Andrew M. Kuchling13423f32001-08-06 17:43:49 +000053-? Help!
54-c Specify the command to execute (see next section). This terminates the
55command option list (following options are passed as arguments to the command).
56 the name of a python file (.py) to execute read from stdin.
57script Anything afterward is passed as options to python script or command,
58 not interpreted as an option to interpreter itself.
59args passed to script or command (in sys.argv[1:])
60 If no script or command, Python enters interactive mode.
61
62 * Available IDEs in std distrib: IDLE (tkinter based, portable), Pythonwin
63 (Windows).
64
65
66
67Environment variables
68
69 Environment variables
70 Variable Effect
71PYTHONHOME Alternate prefix directory (or prefix;exec_prefix). The
72 default module search path uses prefix/lib
73 Augments the default search path for module files. The format
74 is the same as the shell's $PATH: one or more directory
75 pathnames separated by ':' or ';' without spaces around
76 (semi-)colons!
77PYTHONPATH On Windows first search for Registry key HKEY_LOCAL_MACHINE\
78 Software\Python\PythonCore\x.y\PythonPath (default value). You
79 may also define a key named after your application with a
80 default string value giving the root directory path of your
81 app.
82 If this is the name of a readable file, the Python commands in
83PYTHONSTARTUP that file are executed before the first prompt is displayed in
84 interactive mode (no default).
85PYTHONDEBUG If non-empty, same as -d option
86PYTHONINSPECT If non-empty, same as -i option
87PYTHONSUPPRESS If non-empty, same as -s option
88PYTHONUNBUFFERED If non-empty, same as -u option
89PYTHONVERBOSE If non-empty, same as -v option
90PYTHONCASEOK If non-empty, ignore case in file/module names (imports)
91
92
93
94
95Notable lexical entities
96
97Keywords
98
99 and del for is raise
100 assert elif from lambda return
101 break else global not try
102 class except if or while
Raymond Hettinger72348842003-01-25 21:22:52 +0000103 continue exec import pass yield
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000104 def finally in print
105
106 * (list of keywords in std module: keyword)
107 * Illegitimate Tokens (only valid in strings): @ $ ?
108 * A statement must all be on a single line. To break a statement over
109 multiple lines use "\", as with the C preprocessor.
110 Exception: can always break when inside any (), [], or {} pair, or in
111 triple-quoted strings.
112 * More than one statement can appear on a line if they are separated with
113 semicolons (";").
114 * Comments start with "#" and continue to end of line.
115
116Identifiers
117
118 (letter | "_") (letter | digit | "_")*
119
120 * Python identifiers keywords, attributes, etc. are case-sensitive.
121 * Special forms: _ident (not imported by 'from module import *'); __ident__
122 (system defined name);
123 __ident (class-private name mangling)
124
125Strings
126
127 "a string enclosed by double quotes"
128 'another string delimited by single quotes and with a " inside'
129 '''a string containing embedded newlines and quote (') marks, can be
130 delimited with triple quotes.'''
131 """ may also use 3- double quotes as delimiters """
132 u'a unicode string' U"Another unicode string"
133 r'a raw string where \ are kept (literalized): handy for regular
134 expressions and windows paths!'
135 R"another raw string" -- raw strings cannot end with a \
136 ur'a unicode raw string' UR"another raw unicode"
137
138 Use \ at end of line to continue a string on next line.
139 adjacent strings are concatened, e.g. 'Monty' ' Python' is the same as
140 'Monty Python'.
141 u'hello' + ' world' --> u'hello world' (coerced to unicode)
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000142
143 String Literal Escapes
144
145 \newline Ignored (escape newline)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000146 \\ Backslash (\) \e Escape (ESC) \v Vertical Tab (VT)
147 \' Single quote (') \f Formfeed (FF) \OOO char with octal value OOO
148 \" Double quote (") \n Linefeed (LF)
149 \a Bell (BEL) \r Carriage Return (CR) \xHH char with hex value HH
150 \b Backspace (BS) \t Horizontal Tab (TAB)
151 \uHHHH unicode char with hex value HHHH, can only be used in unicode string
152 \UHHHHHHHH unicode char with hex value HHHHHHHH, can only be used in unicode string
153 \AnyOtherChar is left as-is
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000154
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000155 * NUL byte (\000) is NOT an end-of-string marker; NULs may be embedded in
156 strings.
157 * Strings (and tuples) are immutable: they cannot be modified.
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000158
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000159Numbers
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000160
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000161 Decimal integer: 1234, 1234567890546378940L (or l)
Raymond Hettinger72348842003-01-25 21:22:52 +0000162 Octal integer: 0177, 0177777777777777777 (begin with a 0)
163 Hex integer: 0xFF, 0XFFFFffffFFFFFFFFFF (begin with 0x or 0X)
164 Long integer (unlimited precision): 1234567890123456
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000165 Float (double precision): 3.14e-10, .001, 10., 1E3
166 Complex: 1J, 2+3J, 4+5j (ends with J or j, + separates (float) real and
167 imaginary parts)
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000168
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000169Sequences
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000170
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000171 * String of length 0, 1, 2 (see above)
172 '', '1', "12", 'hello\n'
173 * Tuple of length 0, 1, 2, etc:
174 () (1,) (1,2) # parentheses are optional if len > 0
175 * List of length 0, 1, 2, etc:
176 [] [1] [1,2]
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000177
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000178Indexing is 0-based. Negative indices (usually) mean count backwards from end
179of sequence.
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000180
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000181Sequence slicing [starting-at-index : but-less-than-index]. Start defaults to
182'0'; End defaults to 'sequence-length'.
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000183
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000184a = (0,1,2,3,4,5,6,7)
185 a[3] ==> 3
186 a[-1] ==> 7
187 a[2:4] ==> (2, 3)
188 a[1:] ==> (1, 2, 3, 4, 5, 6, 7)
189 a[:3] ==> (0, 1, 2)
190 a[:] ==> (0,1,2,3,4,5,6,7) # makes a copy of the sequence.
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000191
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000192Dictionaries (Mappings)
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000193
Raymond Hettinger72348842003-01-25 21:22:52 +0000194 {} # Zero length empty dictionary
195 {1 : 'first'} # Dictionary with one (key, value) pair
196 {1 : 'first', 'next': 'second'}
197 dict([('one',1),('two',2)]) # Construct a dict from an item list
198 dict('one'=1, 'two'=2) # Construct a dict using keyword args
199 dict.fromkeys(['one', 'keys']) # Construct a dict from a sequence
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000200
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000201Operators and their evaluation order
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000202
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000203 Operators and their evaluation order
204Highest Operator Comment
205 (...) [...] {...} `...` Tuple, list & dict. creation; string
206 conv.
207 s[i] s[i:j] s.attr f(...) indexing & slicing; attributes, fct
208 calls
209 +x, -x, ~x Unary operators
210 x**y Power
Raymond Hettingere685f942003-01-26 03:29:15 +0000211 x*y x/y x%y x//y mult, division, modulo, floor division
Georg Brandlf33d01d2005-08-22 19:35:18 +0000212 x+y x-y addition, subtraction
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000213 x<<y x>>y Bit shifting
214 x&y Bitwise and
215 x^y Bitwise exclusive or
216 x|y Bitwise or
217 x<y x<=y x>y x>=y x==y x!=y Comparison,
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000218 x is y x is not y membership
219 x in s x not in s
220 not x boolean negation
221 x and y boolean and
222 x or y boolean or
223Lowest lambda args: expr anonymous function
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000224
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000225Alternate names are defined in module operator (e.g. __add__ and add for +)
Raymond Hettinger72348842003-01-25 21:22:52 +0000226Most operators are overridable.
227
Raymond Hettinger5a772d32003-01-25 22:35:42 +0000228Many binary operators also support augmented assignment:
Raymond Hettinger72348842003-01-25 21:22:52 +0000229 x += 1 # Same as x = x + 1
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000230
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000231
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000232Basic Types and Their Operations
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000233
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000234Comparisons (defined between *any* types)
Guido van Rossumc8180cc1994-08-05 15:57:31 +0000235
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000236 Comparisons
237Comparison Meaning Notes
238< strictly less than (1)
239<= less than or equal to
240> strictly greater than
241>= greater than or equal to
242== equal to
Neal Norwitz3bd844e2006-08-29 04:39:12 +0000243!= not equal to
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000244is object identity (2)
245is not negated object identity (2)
246
247Notes :
248 Comparison behavior can be overridden for a given class by defining special
249method __cmp__.
Andrew M. Kuchling55be9ea2004-09-10 12:59:54 +0000250 The above comparisons return True or False which are of type bool
Raymond Hettinger5a772d32003-01-25 22:35:42 +0000251(a subclass of int) and behave exactly as 1 or 0 except for their type and
Raymond Hettinger72348842003-01-25 21:22:52 +0000252that they print as True or False instead of 1 or 0.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000253 (1) X < Y < Z < W has expected meaning, unlike C
254 (2) Compare object identities (i.e. id(object)), not object values.
255
256Boolean values and operators
257
258 Boolean values and operators
259 Value or Operator Returns Notes
260None, numeric zeros, empty sequences and False
261mappings
262all other values True
263not x True if x is False, else
264 True
265x or y if x is False then y, else (1)
266 x
267x and y if x is False then x, else (1)
268 y
269
270Notes :
271 Truth testing behavior can be overridden for a given class by defining
Jack Diederich62971282006-11-30 20:50:23 +0000272special method __bool__.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000273 (1) Evaluate second arg only if necessary to determine outcome.
274
275None
276
277 None is used as default return value on functions. Built-in single object
278 with type NoneType.
279 Input that evaluates to None does not print when running Python
280 interactively.
281
282Numeric types
283
284Floats, integers and long integers.
285
286 Floats are implemented with C doubles.
287 Integers are implemented with C longs.
288 Long integers have unlimited size (only limit is system resources)
289
290Operators on all numeric types
291
292 Operators on all numeric types
293 Operation Result
294abs(x) the absolute value of x
295int(x) x converted to integer
296long(x) x converted to long integer
297float(x) x converted to floating point
298-x x negated
299+x x unchanged
300x + y the sum of x and y
301x - y difference of x and y
302x * y product of x and y
303x / y quotient of x and y
304x % y remainder of x / y
305divmod(x, y) the tuple (x/y, x%y)
306x ** y x to the power y (the same as pow(x, y))
307
308Bit operators on integers and long integers
309
310 Bit operators
311Operation >Result
312~x the bits of x inverted
313x ^ y bitwise exclusive or of x and y
314x & y bitwise and of x and y
315x | y bitwise or of x and y
316x << n x shifted left by n bits
317x >> n x shifted right by n bits
318
319Complex Numbers
320
321 * represented as a pair of machine-level double precision floating point
322 numbers.
323 * The real and imaginary value of a complex number z can be retrieved through
324 the attributes z.real and z.imag.
325
326Numeric exceptions
327
328TypeError
329 raised on application of arithmetic operation to non-number
330OverflowError
331 numeric bounds exceeded
332ZeroDivisionError
333 raised when zero second argument of div or modulo op
Raymond Hettingere685f942003-01-26 03:29:15 +0000334FloatingPointError
335 raised when a floating point operation fails
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000336
337Operations on all sequence types (lists, tuples, strings)
338
339 Operations on all sequence types
340Operation Result Notes
Raymond Hettingere685f942003-01-26 03:29:15 +0000341x in s True if an item of s is equal to x, else False
342x not in s False if an item of s is equal to x, else True
Raymond Hettinger72348842003-01-25 21:22:52 +0000343for x in s: loops over the sequence
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000344s + t the concatenation of s and t
345s * n, n*s n copies of s concatenated
346s[i] i'th item of s, origin 0 (1)
347s[i:j] slice of s from i (included) to j (excluded) (1), (2)
348len(s) length of s
349min(s) smallest item of s
350max(s) largest item of (s)
Raymond Hettinger72348842003-01-25 21:22:52 +0000351iter(s) returns an iterator over s. iterators define __iter__ and next()
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000352
353Notes :
354 (1) if i or j is negative, the index is relative to the end of the string,
355ie len(s)+ i or len(s)+j is
356 substituted. But note that -0 is still 0.
357 (2) The slice of s from i to j is defined as the sequence of items with
358index k such that i <= k < j.
359 If i or j is greater than len(s), use len(s). If i is omitted, use
360len(s). If i is greater than or
361 equal to j, the slice is empty.
362
363Operations on mutable (=modifiable) sequences (lists)
364
365 Operations on mutable sequences
366 Operation Result Notes
367s[i] =x item i of s is replaced by x
368s[i:j] = t slice of s from i to j is replaced by t
369del s[i:j] same as s[i:j] = []
370s.append(x) same as s[len(s) : len(s)] = [x]
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000371s.count(x) return number of i's for which s[i] == x
Raymond Hettingere685f942003-01-26 03:29:15 +0000372s.extend(x) same as s[len(s):len(s)]= x
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000373s.index(x) return smallest i such that s[i] == x (1)
374s.insert(i, x) same as s[i:i] = [x] if i >= 0
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000375s.pop([i]) same as x = s[i]; del s[i]; return x (4)
Raymond Hettinger72348842003-01-25 21:22:52 +0000376s.remove(x) same as del s[s.index(x)] (1)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000377s.reverse() reverse the items of s in place (3)
378s.sort([cmpFct]) sort the items of s in place (2), (3)
379
380Notes :
381 (1) raise a ValueError exception when x is not found in s (i.e. out of
382range).
383 (2) The sort() method takes an optional argument specifying a comparison
384fct of 2 arguments (list items) which should
385 return -1, 0, or 1 depending on whether the 1st argument is
386considered smaller than, equal to, or larger than the 2nd
387 argument. Note that this slows the sorting process down considerably.
388 (3) The sort() and reverse() methods modify the list in place for economy
389of space when sorting or reversing a large list.
390 They don't return the sorted or reversed list to remind you of this
391side effect.
Raymond Hettinger72348842003-01-25 21:22:52 +0000392 (4) [New 1.5.2] The optional argument i defaults to -1, so that by default the last
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000393item is removed and returned.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000394
395
396
397Operations on mappings (dictionaries)
398
399 Operations on mappings
400 Operation Result Notes
401len(d) the number of items in d
402d[k] the item of d with key k (1)
403d[k] = x set d[k] to x
404del d[k] remove d[k] from d (1)
405d.clear() remove all items from d
406d.copy() a shallow copy of d
Raymond Hettinger72348842003-01-25 21:22:52 +0000407d.get(k,defaultval) the item of d with key k (4)
Raymond Hettingere685f942003-01-26 03:29:15 +0000408d.has_key(k) True if d has key k, else False
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000409d.items() a copy of d's list of (key, item) pairs (2)
Raymond Hettinger72348842003-01-25 21:22:52 +0000410d.iteritems() an iterator over (key, value) pairs (7)
411d.iterkeys() an iterator over the keys of d (7)
412d.itervalues() an iterator over the values of d (7)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000413d.keys() a copy of d's list of keys (2)
414d1.update(d2) for k, v in d2.items(): d1[k] = v (3)
415d.values() a copy of d's list of values (2)
Raymond Hettinger72348842003-01-25 21:22:52 +0000416d.pop(k) remove d[k] and return its value
417d.popitem() remove and return an arbitrary (6)
418 (key, item) pair
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000419d.setdefault(k,defaultval) the item of d with key k (5)
420
421 Notes :
422 TypeError is raised if key is not acceptable
423 (1) KeyError is raised if key k is not in the map
424 (2) Keys and values are listed in random order
425 (3) d2 must be of the same type as d1
426 (4) Never raises an exception if k is not in the map, instead it returns
427 defaultVal.
428 defaultVal is optional, when not provided and k is not in the map,
429 None is returned.
430 (5) Never raises an exception if k is not in the map, instead it returns
431 defaultVal, and adds k to map with value defaultVal. defaultVal is
432 optional. When not provided and k is not in the map, None is returned and
433 added to map.
Raymond Hettinger72348842003-01-25 21:22:52 +0000434 (6) Raises a KeyError if the dictionary is emtpy.
435 (7) While iterating over a dictionary, the values may be updated but
436 the keys cannot be changed.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000437
438Operations on strings
439
440Note that these string methods largely (but not completely) supersede the
441functions available in the string module.
442
443
444 Operations on strings
445 Operation Result Notes
446s.capitalize() return a copy of s with only its first character
447 capitalized.
448s.center(width) return a copy of s centered in a string of length width (1)
449 .
450s.count(sub[ return the number of occurrences of substring sub in (2)
451,start[,end]]) string s.
Raymond Hettinger72348842003-01-25 21:22:52 +0000452s.decode(([ return a decoded version of s. (3)
453 encoding
454 [,errors]])
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000455s.encode([ return an encoded version of s. Default encoding is the
Raymond Hettinger72348842003-01-25 21:22:52 +0000456 encoding current default string encoding. (3)
457 [,errors]])
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000458s.endswith(suffix return true if s ends with the specified suffix, (2)
Raymond Hettinger72348842003-01-25 21:22:52 +0000459 [,start[,end]]) otherwise return False.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000460s.expandtabs([ return a copy of s where all tab characters are (4)
461tabsize]) expanded using spaces.
462s.find(sub[,start return the lowest index in s where substring sub is (2)
463[,end]]) found. Return -1 if sub is not found.
464s.index(sub[ like find(), but raise ValueError when the substring is (2)
465,start[,end]]) not found.
Raymond Hettinger72348842003-01-25 21:22:52 +0000466s.isalnum() return True if all characters in s are alphanumeric, (5)
467 False otherwise.
468s.isalpha() return True if all characters in s are alphabetic, (5)
469 False otherwise.
470s.isdigit() return True if all characters in s are digit (5)
471 characters, False otherwise.
472s.islower() return True if all characters in s are lowercase, False (6)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000473 otherwise.
Raymond Hettinger72348842003-01-25 21:22:52 +0000474s.isspace() return True if all characters in s are whitespace (5)
475 characters, False otherwise.
476s.istitle() return True if string s is a titlecased string, False (7)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000477 otherwise.
Raymond Hettinger72348842003-01-25 21:22:52 +0000478s.isupper() return True if all characters in s are uppercase, False (6)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000479 otherwise.
480s.join(seq) return a concatenation of the strings in the sequence
481 seq, seperated by 's's.
482s.ljust(width) return s left justified in a string of length width. (1),
483 (8)
484s.lower() return a copy of s converted to lowercase.
485s.lstrip() return a copy of s with leading whitespace removed.
486s.replace(old, return a copy of s with all occurrences of substring (9)
487new[, maxsplit]) old replaced by new.
488s.rfind(sub[ return the highest index in s where substring sub is (2)
489,start[,end]]) found. Return -1 if sub is not found.
490s.rindex(sub[ like rfind(), but raise ValueError when the substring (2)
491,start[,end]]) is not found.
492s.rjust(width) return s right justified in a string of length width. (1),
493 (8)
494s.rstrip() return a copy of s with trailing whitespace removed.
495s.split([sep[ return a list of the words in s, using sep as the (10)
496,maxsplit]]) delimiter string.
497s.splitlines([ return a list of the lines in s, breaking at line (11)
498keepends]) boundaries.
499s.startswith return true if s starts with the specified prefix,
500(prefix[,start[ otherwise return false. (2)
501,end]])
502s.strip() return a copy of s with leading and trailing whitespace
503 removed.
504s.swapcase() return a copy of s with uppercase characters converted
505 to lowercase and vice versa.
506 return a titlecased copy of s, i.e. words start with
507s.title() uppercase characters, all remaining cased characters
508 are lowercase.
509s.translate(table return a copy of s mapped through translation table (12)
510[,deletechars]) table.
511s.upper() return a copy of s converted to uppercase.
Raymond Hettinger5a772d32003-01-25 22:35:42 +0000512s.zfill(width) return a string padded with zeroes on the left side and
Raymond Hettinger72348842003-01-25 21:22:52 +0000513 sliding a minus sign left if necessary. never truncates.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000514
515Notes :
516 (1) Padding is done using spaces.
517 (2) If optional argument start is supplied, substring s[start:] is
518processed. If optional arguments start and end are supplied, substring s[start:
519end] is processed.
520 (3) Optional argument errors may be given to set a different error handling
521scheme. The default for errors is 'strict', meaning that encoding errors raise
522a ValueError. Other possible values are 'ignore' and 'replace'.
523 (4) If optional argument tabsize is not given, a tab size of 8 characters
524is assumed.
525 (5) Returns false if string s does not contain at least one character.
526 (6) Returns false if string s does not contain at least one cased
527character.
528 (7) A titlecased string is a string in which uppercase characters may only
529follow uncased characters and lowercase characters only cased ones.
530 (8) s is returned if width is less than len(s).
531 (9) If the optional argument maxsplit is given, only the first maxsplit
532occurrences are replaced.
533 (10) If sep is not specified or None, any whitespace string is a separator.
534If maxsplit is given, at most maxsplit splits are done.
535 (11) Line breaks are not included in the resulting list unless keepends is
536given and true.
537 (12) table must be a string of length 256. All characters occurring in the
538optional argument deletechars are removed prior to translation.
539
540String formatting with the % operator
541
542formatString % args--> evaluates to a string
543
544 * formatString uses C printf format codes : %, c, s, i, d, u, o, x, X, e, E,
545 f, g, G, r (details below).
546 * Width and precision may be a * to specify that an integer argument gives
547 the actual width or precision.
548 * The flag characters -, +, blank, # and 0 are understood. (details below)
549 * %s will convert any type argument to string (uses str() function)
550 * args may be a single arg or a tuple of args
551
552 '%s has %03d quote types.' % ('Python', 2) # => 'Python has 002 quote types.'
553
554 * Right-hand-side can also be a mapping:
555
556 a = '%(lang)s has %(c)03d quote types.' % {'c':2, 'lang':'Python}
557(vars() function very handy to use on right-hand-side.)
558
559 Format codes
560Conversion Meaning
561d Signed integer decimal.
562i Signed integer decimal.
563o Unsigned octal.
564u Unsigned decimal.
565x Unsigned hexidecimal (lowercase).
566X Unsigned hexidecimal (uppercase).
567e Floating point exponential format (lowercase).
568E Floating point exponential format (uppercase).
569f Floating point decimal format.
570F Floating point decimal format.
571g Same as "e" if exponent is greater than -4 or less than precision,
572 "f" otherwise.
573G Same as "E" if exponent is greater than -4 or less than precision,
574 "F" otherwise.
575c Single character (accepts integer or single character string).
576r String (converts any python object using repr()).
577s String (converts any python object using str()).
578% No argument is converted, results in a "%" character in the result.
579 (The complete specification is %%.)
580
581 Conversion flag characters
582Flag Meaning
583# The value conversion will use the ``alternate form''.
5840 The conversion will be zero padded.
585- The converted value is left adjusted (overrides "-").
586 (a space) A blank should be left before a positive number (or empty
587 string) produced by a signed conversion.
588+ A sign character ("+" or "-") will precede the conversion (overrides a
589 "space" flag).
590
591File Objects
592
593Created with built-in function open; may be created by other modules' functions
594as well.
595
596Operators on file objects
597
598 File operations
599 Operation Result
600f.close() Close file f.
601f.fileno() Get fileno (fd) for file f.
602f.flush() Flush file f's internal buffer.
Raymond Hettingere685f942003-01-26 03:29:15 +0000603f.isatty() True if file f is connected to a tty-like dev, else False.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000604f.read([size]) Read at most size bytes from file f and return as a string
605 object. If size omitted, read to EOF.
606f.readline() Read one entire line from file f.
607f.readlines() Read until EOF with readline() and return list of lines read.
608 Set file f's position, like "stdio's fseek()".
609f.seek(offset[, whence == 0 then use absolute indexing.
610whence=0]) whence == 1 then offset relative to current pos.
611 whence == 2 then offset relative to file end.
612f.tell() Return file f's current position (byte offset).
613f.write(str) Write string to file f.
614f.writelines(list Write list of strings to file f.
615)
616
617File Exceptions
618
619 EOFError
620 End-of-file hit when reading (may be raised many times, e.g. if f is a
621 tty).
622 IOError
Raymond Hettingere685f942003-01-26 03:29:15 +0000623 Other I/O-related I/O operation failure.
624 OSError
625 OS system call failed.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000626
627
628 Advanced Types
629
630 -See manuals for more details -
631 + Module objects
632 + Class objects
633 + Class instance objects
634 + Type objects (see module: types)
635 + File objects (see above)
636 + Slice objects
637 + XRange objects
638 + Callable types:
639 o User-defined (written in Python):
640 # User-defined Function objects
641 # User-defined Method objects
642 o Built-in (written in C):
643 # Built-in Function objects
644 # Built-in Method objects
645 + Internal Types:
646 o Code objects (byte-compile executable Python code: bytecode)
647 o Frame objects (execution frames)
648 o Traceback objects (stack trace of an exception)
649
650
651 Statements
652
653 pass -- Null statement
654 del name[,name]* -- Unbind name(s) from object. Object will be indirectly
655 (and automatically) deleted only if no longer referenced.
656 print [>> fileobject,] [s1 [, s2 ]* [,]
657 -- Writes to sys.stdout, or to fileobject if supplied.
658 Puts spaces between arguments. Puts newline at end
659 unless statement ends with comma.
660 Print is not required when running interactively,
661 simply typing an expression will print its value,
662 unless the value is None.
663 exec x [in globals [,locals]]
664 -- Executes x in namespaces provided. Defaults
665 to current namespaces. x can be a string, file
666 object or a function object.
667 callable(value,... [id=value], [*args], [**kw])
668 -- Call function callable with parameters. Parameters can
669 be passed by name or be omitted if function
670 defines default values. E.g. if callable is defined as
671 "def callable(p1=1, p2=2)"
672 "callable()" <=> "callable(1, 2)"
673 "callable(10)" <=> "callable(10, 2)"
674 "callable(p2=99)" <=> "callable(1, 99)"
675 *args is a tuple of positional arguments.
676 **kw is a dictionary of keyword arguments.
677
678 Assignment operators
679
680 Caption
681 Operator Result Notes
682 a = b Basic assignment - assign object b to label a (1)
683 a += b Roughly equivalent to a = a + b (2)
684 a -= b Roughly equivalent to a = a - b (2)
685 a *= b Roughly equivalent to a = a * b (2)
686 a /= b Roughly equivalent to a = a / b (2)
687 a %= b Roughly equivalent to a = a % b (2)
688 a **= b Roughly equivalent to a = a ** b (2)
689 a &= b Roughly equivalent to a = a & b (2)
690 a |= b Roughly equivalent to a = a | b (2)
691 a ^= b Roughly equivalent to a = a ^ b (2)
692 a >>= b Roughly equivalent to a = a >> b (2)
693 a <<= b Roughly equivalent to a = a << b (2)
694
695 Notes :
696 (1) Can unpack tuples, lists, and strings.
697 first, second = a[0:2]; [f, s] = range(2); c1,c2,c3='abc'
698 Tip: x,y = y,x swaps x and y.
699 (2) Not exactly equivalent - a is evaluated only once. Also, where
700 possible, operation performed in-place - a is modified rather than
701 replaced.
702
703 Control Flow
704
705 if condition: suite
706 [elif condition: suite]*
707 [else: suite] -- usual if/else_if/else statement
708 while condition: suite
709 [else: suite]
710 -- usual while statement. "else" suite is executed
711 after loop exits, unless the loop is exited with
712 "break"
713 for element in sequence: suite
714 [else: suite]
715 -- iterates over sequence, assigning each element to element.
716 Use built-in range function to iterate a number of times.
717 "else" suite executed at end unless loop exited
718 with "break"
719 break -- immediately exits "for" or "while" loop
720 continue -- immediately does next iteration of "for" or "while" loop
721 return [result] -- Exits from function (or method) and returns result (use a tuple to
722 return more than one value). If no result given, then returns None.
Raymond Hettingere685f942003-01-26 03:29:15 +0000723 yield result -- Freezes the execution frame of a generator and returns the result
724 to the iterator's .next() method. Upon the next call to next(),
725 resumes execution at the frozen point with all of the local variables
726 still intact.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000727
728 Exception Statements
729
730 assert expr[, message]
731 -- expr is evaluated. if false, raises exception AssertionError
732 with message. Inhibited if __debug__ is 0.
733 try: suite1
734 [except [exception [, value]: suite2]+
735 [else: suite3]
736 -- statements in suite1 are executed. If an exception occurs, look
737 in "except" clauses for matching <exception>. If matches or bare
738 "except" execute suite of that clause. If no exception happens
739 suite in "else" clause is executed after suite1.
740 If exception has a value, it is put in value.
741 exception can also be tuple of exceptions, e.g.
742 "except (KeyError, NameError), val: print val"
743 try: suite1
744 finally: suite2
745 -- statements in suite1 are executed. If no
746 exception, execute suite2 (even if suite1 is
747 exited with a "return", "break" or "continue"
748 statement). If exception did occur, executes
749 suite2 and then immediately reraises exception.
750 raise exception [,value [, traceback]]
751 -- raises exception with optional value
752 value. Arg traceback specifies a traceback object to
753 use when printing the exception's backtrace.
754 raise -- a raise statement without arguments re-raises
755 the last exception raised in the current function
756An exception is either a string (object) or a class instance.
757 Can create a new one simply by creating a new string:
758
759 my_exception = 'You did something wrong'
760 try:
761 if bad:
762 raise my_exception, bad
763 except my_exception, value:
764 print 'Oops', value
765
766Exception classes must be derived from the predefined class: Exception, e.g.:
767 class text_exception(Exception): pass
768 try:
769 if bad:
770 raise text_exception()
771 # This is a shorthand for the form
772 # "raise <class>, <instance>"
773 except Exception:
774 print 'Oops'
775 # This will be printed because
776 # text_exception is a subclass of Exception
777When an error message is printed for an unhandled exception which is a
778class, the class name is printed, then a colon and a space, and
779finally the instance converted to a string using the built-in function
780str().
781All built-in exception classes derives from StandardError, itself
782derived from Exception.
783
784Name Space Statements
785
786[1.51: On Mac & Windows, the case of module file names must now match the case
787as used
788 in the import statement]
789Packages (>1.5): a package is a name space which maps to a directory including
790 module(s) and the special initialization module '__init__.py'
791 (possibly empty). Packages/dirs can be nested. You address a
792 module's symbol via '[package.[package...]module.symbol's.
793import module1 [as name1] [, module2]*
794 -- imports modules. Members of module must be
795 referred to by qualifying with [package.]module name:
796 "import sys; print sys.argv:"
797 "import package1.subpackage.module; package1.subpackage.module.foo()"
798 module1 renamed as name1, if supplied.
799from module import name1 [as othername1] [, name2]*
800 -- imports names from module module in current namespace.
801 "from sys import argv; print argv"
802 "from package1 import module; module.foo()"
803 "from package1.module import foo; foo()"
804 name1 renamed as othername1, if supplied.
805from module import *
806 -- imports all names in module, except those starting with "_";
807 *to be used sparsely, beware of name clashes* :
808 "from sys import *; print argv"
809 "from package.module import *; print x'
810 NB: "from package import *" only imports the symbols defined
811 in the package's __init__.py file, not those in the
812 template modules!
813global name1 [, name2]*
814 -- names are from global scope (usually meaning from module)
815 rather than local (usually meaning only in function).
816 -- E.g. in fct without "global" statements, assuming
817 "a" is name that hasn't been used in fct or module
818 so far:
819 -Try to read from "a" -> NameError
820 -Try to write to "a" -> creates "a" local to fcn
821 -If "a" not defined in fct, but is in module, then
822 -Try to read from "a", gets value from module
823 -Try to write to "a", creates "a" local to fct
824 But note "a[0]=3" starts with search for "a",
825 will use to global "a" if no local "a".
826
827Function Definition
828
829def func_id ([param_list]): suite
830 -- Creates a function object & binds it to name func_id.
831
832 param_list ::= [id [, id]*]
833 id ::= value | id = value | *id | **id
834 [Args are passed by value.Thus only args representing a mutable object
835 can be modified (are inout parameters). Use a tuple to return more than
836 one value]
837
838Example:
839 def test (p1, p2 = 1+1, *rest, **keywords):
840 -- Parameters with "=" have default value (v is
841 evaluated when function defined).
842 If list has "*id" then id is assigned a tuple of
843 all remaining args passed to function (like C vararg)
844 If list has "**id" then id is assigned a dictionary of
845 all extra arguments passed as keywords.
846
847Class Definition
848
849class <class_id> [(<super_class1> [,<super_class2>]*)]: <suite>
850 -- Creates a class object and assigns it name <class_id>
851 <suite> may contain local "defs" of class methods and
852 assignments to class attributes.
853Example:
854 class my_class (class1, class_list[3]): ...
855 Creates a class object inheriting from both "class1" and whatever
856 class object "class_list[3]" evaluates to. Assigns new
857 class object to name "my_class".
858 - First arg to class methods is always instance object, called 'self'
859 by convention.
860 - Special method __init__() is called when instance is created.
861 - Special method __del__() called when no more reference to object.
862 - Create instance by "calling" class object, possibly with arg
863 (thus instance=apply(aClassObject, args...) creates an instance!)
864 - In current implementation, can't subclass off built-in
865 classes. But can "wrap" them, see UserDict & UserList modules,
866 and see __getattr__() below.
867Example:
868 class c (c_parent):
869 def __init__(self, name): self.name = name
870 def print_name(self): print "I'm", self.name
871 def call_parent(self): c_parent.print_name(self)
872 instance = c('tom')
873 print instance.name
874 'tom'
875 instance.print_name()
876 "I'm tom"
877 Call parent's super class by accessing parent's method
878 directly and passing "self" explicitly (see "call_parent"
879 in example above).
880 Many other special methods available for implementing
881 arithmetic operators, sequence, mapping indexing, etc.
882
883Documentation Strings
884
885Modules, classes and functions may be documented by placing a string literal by
886itself as the first statement in the suite. The documentation can be retrieved
887by getting the '__doc__' attribute from the module, class or function.
888Example:
889 class C:
890 "A description of C"
891 def __init__(self):
892 "A description of the constructor"
893 # etc.
894Then c.__doc__ == "A description of C".
895Then c.__init__.__doc__ == "A description of the constructor".
896
897Others
898
899lambda [param_list]: returnedExpr
900 -- Creates an anonymous function. returnedExpr must be
901 an expression, not a statement (e.g., not "if xx:...",
902 "print xxx", etc.) and thus can't contain newlines.
Guido van Rossum0919a1a2006-08-26 20:49:04 +0000903 Used mostly for filter(), map() functions, and GUI callbacks..
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000904List comprehensions
905result = [expression for item1 in sequence1 [if condition1]
906 [for item2 in sequence2 ... for itemN in sequenceN]
907 ]
908is equivalent to:
909result = []
910for item1 in sequence1:
911 for item2 in sequence2:
912 ...
913 for itemN in sequenceN:
914 if (condition1) and furthur conditions:
915 result.append(expression)
916
917
918
919Built-In Functions
920
921 Built-In Functions
922 Function Result
923__import__(name[, Imports module within the given context (see lib ref for
924globals[, locals[, more details)
925fromlist]]])
926abs(x) Return the absolute value of number x.
Raymond Hettingere685f942003-01-26 03:29:15 +0000927bool(x) Returns True when the argument x is true and False otherwise.
928buffer(obj) Creates a buffer reference to an object.
929callable(x) Returns True if x callable, else False.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000930chr(i) Returns one-character string whose ASCII code isinteger i
Raymond Hettingere685f942003-01-26 03:29:15 +0000931classmethod(f) Converts a function f, into a method with the class as the
932 first argument. Useful for creating alternative constructors.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000933cmp(x,y) Returns negative, 0, positive if x <, ==, > to y
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000934compile(string, from which the code was read, or eg. '<string>'if not read
935filename, kind) from file.kind can be 'eval' if string is a single stmt, or
936 'single' which prints the output of expression statements
937 thatevaluate to something else than None, or be 'exec'.
938complex(real[, Builds a complex object (can also be done using J or j
939image]) suffix,e.g. 1+3J)
940delattr(obj, name) deletes attribute named name of object obj <=> del obj.name
941 If no args, returns the list of names in current
Raymond Hettingere685f942003-01-26 03:29:15 +0000942dict([items]) Create a new dictionary from the specified item list.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000943dir([object]) localsymbol table. With a module, class or class
944 instanceobject as arg, returns list of names in its attr.
945 dict.
946divmod(a,b) Returns tuple of (a/b, a%b)
Raymond Hettingere685f942003-01-26 03:29:15 +0000947enumerate(seq) Return a iterator giving: (0, seq[0]), (1, seq[1]), ...
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000948eval(s[, globals[, Eval string s in (optional) globals, locals contexts.s must
949locals]]) have no NUL's or newlines. s can also be acode object.
950 Example: x = 1; incr_x = eval('x + 1')
951execfile(file[, Executes a file without creating a new module, unlike
952globals[, locals]]) import.
Raymond Hettingere685f942003-01-26 03:29:15 +0000953file() Synonym for open().
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000954filter(function, Constructs a list from those elements of sequence for which
955sequence) function returns true. function takes one parameter.
956float(x) Converts a number or a string to floating point.
957getattr(object, [<default> arg added in 1.5.2]Gets attribute called name
958name[, default])) from object,e.g. getattr(x, 'f') <=> x.f). If not found,
959 raisesAttributeError or returns default if specified.
960globals() Returns a dictionary containing current global variables.
961hasattr(object, Returns true if object has attr called name.
962name)
963hash(object) Returns the hash value of the object (if it has one)
Raymond Hettingere685f942003-01-26 03:29:15 +0000964help(f) Display documentation on object f.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000965hex(x) Converts a number x to a hexadecimal string.
966id(object) Returns a unique 'identity' integer for an object.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000967int(x[, base]) base paramenter specifies base from which to convert string
968 values.
969intern(aString) Enters aString in the table of "interned strings"
970 andreturns the string. Interned strings are 'immortals'.
971isinstance(obj, returns true if obj is an instance of class. Ifissubclass
972class) (A,B) then isinstance(x,A) => isinstance(x,B)
973issubclass(class1, returns true if class1 is derived from class2
974class2)
975 Returns the length (the number of items) of an object
Raymond Hettingere685f942003-01-26 03:29:15 +0000976iter(collection) Returns an iterator over the collection.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +0000977len(obj) (sequence, dictionary, or instance of class implementing
978 __len__).
979list(sequence) Converts sequence into a list. If already a list,returns a
980 copy of it.
981locals() Returns a dictionary containing current local variables.
982 Converts a number or a string to a long integer. Optional
983long(x[, base]) base paramenter specifies base from which to convert string
984 values.
985 Applies function to every item of list and returns a listof
986map(function, list, the results. If additional arguments are passed,function
987...) must take that many arguments and it is givento function on
988 each call.
989max(seq) Returns the largest item of the non-empty sequence seq.
990min(seq) Returns the smallest item of a non-empty sequence seq.
991oct(x) Converts a number to an octal string.
992open(filename [, Returns a new file object. First two args are same asthose
993mode='r', [bufsize= for C's "stdio open" function. bufsize is 0for unbuffered,
994implementation 1 for line-buffered, negative forsys-default, all else, of
995dependent]]) (about) given size.
996ord(c) Returns integer ASCII value of c (a string of len 1). Works
997 with Unicode char.
Raymond Hettingere685f942003-01-26 03:29:15 +0000998object() Create a base type. Used as a superclass for new-style objects.
999open(name Open a file.
1000 [, mode
1001 [, buffering]])
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001002pow(x, y [, z]) Returns x to power y [modulo z]. See also ** operator.
Raymond Hettingere685f942003-01-26 03:29:15 +00001003property() Created a property with access controlled by functions.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001004range(start [,end Returns list of ints from >= start and < end.With 1 arg,
1005[, step]]) list from 0..arg-1With 2 args, list from start..end-1With 3
1006 args, list from start up to end by step
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001007reload(module) after fixing it. If module was syntacticallycorrect but had
1008 an error in initialization, mustimport it one more time
1009 before calling reload().
1010 Returns a string containing a printable and if possible
Neal Norwitz3bd844e2006-08-29 04:39:12 +00001011repr(object) evaluable representation of an object.
1012 Class redefinable (__repr__). See also str().
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001013round(x, n=0) Returns the floating point value x rounded to n digitsafter
1014 the decimal point.
1015setattr(object, This is the counterpart of getattr().setattr(o, 'foobar',
1016name, value) 3) <=> o.foobar = 3Creates attribute if it doesn't exist!
1017slice([start,] stop Returns a slice object representing a range, with R/
1018[, step]) Oattributes: start, stop, step.
1019 Returns a string containing a nicely
Raymond Hettingere685f942003-01-26 03:29:15 +00001020staticmethod() Convert a function to method with no self or class
1021 argument. Useful for methods associated with a class that
1022 do not need access to an object's internal state.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001023str(object) printablerepresentation of an object. Class overridable
1024 (__str__).See also repr().
Raymond Hettingere685f942003-01-26 03:29:15 +00001025super(type) Create an unbound super object. Used to call cooperative
1026 superclass methods.
Raymond Hettingerca60cac2003-07-12 23:55:57 +00001027sum(sequence, Add the values in the sequence and return the sum.
1028 [start])
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001029tuple(sequence) Creates a tuple with same elements as sequence. If already
1030 a tuple, return itself (not a copy).
1031 Returns a type object [see module types] representing
1032 thetype of obj. Example: import typesif type(x) ==
1033type(obj) types.StringType: print 'It is a string'NB: it is
1034 recommanded to use the following form:if isinstance(x,
1035 types.StringType): etc...
1036unichr(code) code.
1037unicode(string[, Creates a Unicode string from a 8-bit string, using
1038encoding[, error thegiven encoding name and error treatment ('strict',
1039]]]) 'ignore',or 'replace'}.
1040 Without arguments, returns a dictionary correspondingto the
1041 current local symbol table. With a module,class or class
1042vars([object]) instance object as argumentreturns a dictionary
1043 corresponding to the object'ssymbol table. Useful with "%"
1044 formatting operator.
1045xrange(start [, end Like range(), but doesn't actually store entire listall at
1046[, step]]) once. Good to use in "for" loops when there is abig range
1047 and little memory.
1048zip(seq1[, seq2, Returns a list of tuples where each tuple contains the nth
1049...]) element of each of the argument sequences.
1050
1051
1052
1053
1054Built-In Exceptions
1055
1056Exception>
1057 Root class for all exceptions
1058 SystemExit
1059 On 'sys.exit()'
Raymond Hettingere685f942003-01-26 03:29:15 +00001060 StopIteration
1061 Signal the end from iterator.next()
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001062 StandardError
1063 Base class for all built-in exceptions; derived from Exception
1064 root class.
1065 ArithmeticError
1066 Base class for OverflowError, ZeroDivisionError,
1067 FloatingPointError
1068 FloatingPointError
1069 When a floating point operation fails.
1070 OverflowError
1071 On excessively large arithmetic operation
1072 ZeroDivisionError
1073 On division or modulo operation with 0 as 2nd arg
1074 AssertionError
1075 When an assert statement fails.
1076 AttributeError
1077 On attribute reference or assignment failure
1078 EnvironmentError [new in 1.5.2]
1079 On error outside Python; error arg tuple is (errno, errMsg...)
1080 IOError [changed in 1.5.2]
1081 I/O-related operation failure
1082 OSError [new in 1.5.2]
1083 used by the os module's os.error exception.
1084 EOFError
1085 Immediate end-of-file hit by input() or raw_input()
1086 ImportError
1087 On failure of `import' to find module or name
1088 KeyboardInterrupt
1089 On user entry of the interrupt key (often `Control-C')
1090 LookupError
1091 base class for IndexError, KeyError
1092 IndexError
1093 On out-of-range sequence subscript
1094 KeyError
1095 On reference to a non-existent mapping (dict) key
1096 MemoryError
1097 On recoverable memory exhaustion
1098 NameError
1099 On failure to find a local or global (unqualified) name
1100 RuntimeError
1101 Obsolete catch-all; define a suitable error instead
1102 NotImplementedError [new in 1.5.2]
1103 On method not implemented
1104 SyntaxError
1105 On parser encountering a syntax error
1106 IndentationError
1107 On parser encountering an indentation syntax error
1108 TabError
1109 On parser encountering an indentation syntax error
1110 SystemError
1111 On non-fatal interpreter error - bug - report it
1112 TypeError
1113 On passing inappropriate type to built-in op or func
1114 ValueError
1115 On arg error not covered by TypeError or more precise
Raymond Hettingere685f942003-01-26 03:29:15 +00001116 Warning
1117 UserWarning
1118 DeprecationWarning
1119 PendingDeprecationWarning
1120 SyntaxWarning
Raymond Hettingere685f942003-01-26 03:29:15 +00001121 RuntimeWarning
1122 FutureWarning
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001123
1124
1125
1126Standard methods & operators redefinition in classes
1127
1128Standard methods & operators map to special '__methods__' and thus may be
1129 redefined (mostly in in user-defined classes), e.g.:
1130 class x:
1131 def __init__(self, v): self.value = v
1132 def __add__(self, r): return self.value + r
1133 a = x(3) # sort of like calling x.__init__(a, 3)
1134 a + 4 # is equivalent to a.__add__(4)
1135
1136Special methods for any class
1137
1138(s: self, o: other)
1139 __init__(s, args) instance initialization (on construction)
1140 __del__(s) called on object demise (refcount becomes 0)
1141 __repr__(s) repr() and `...` conversions
1142 __str__(s) str() and 'print' statement
1143 __cmp__(s, o) Compares s to o and returns <0, 0, or >0.
1144 Implements >, <, == etc...
1145 __hash__(s) Compute a 32 bit hash code; hash() and dictionary ops
Jack Diederich62971282006-11-30 20:50:23 +00001146 __bool__(s) Returns False or True for truth value testing
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001147 __getattr__(s, name) called when attr lookup doesn't find <name>
1148 __setattr__(s, name, val) called when setting an attr
1149 (inside, don't use "self.name = value"
1150 use "self.__dict__[name] = val")
1151 __delattr__(s, name) called to delete attr <name>
1152 __call__(self, *args) called when an instance is called as function.
1153
1154Operators
1155
1156 See list in the operator module. Operator function names are provided with
1157 2 variants, with or without
1158 ading & trailing '__' (eg. __add__ or add).
1159
1160 Numeric operations special methods
1161 (s: self, o: other)
1162
1163 s+o = __add__(s,o) s-o = __sub__(s,o)
1164 s*o = __mul__(s,o) s/o = __div__(s,o)
1165 s%o = __mod__(s,o) divmod(s,o) = __divmod__(s,o)
1166 s**o = __pow__(s,o)
1167 s&o = __and__(s,o)
1168 s^o = __xor__(s,o) s|o = __or__(s,o)
1169 s<<o = __lshift__(s,o) s>>o = __rshift__(s,o)
Jack Diederich62971282006-11-30 20:50:23 +00001170 bool(s) = __bool__(s) (used in boolean testing)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001171 -s = __neg__(s) +s = __pos__(s)
1172 abs(s) = __abs__(s) ~s = __invert__(s) (bitwise)
1173 s+=o = __iadd__(s,o) s-=o = __isub__(s,o)
1174 s*=o = __imul__(s,o) s/=o = __idiv__(s,o)
1175 s%=o = __imod__(s,o)
1176 s**=o = __ipow__(s,o)
1177 s&=o = __iand__(s,o)
1178 s^=o = __ixor__(s,o) s|=o = __ior__(s,o)
1179 s<<=o = __ilshift__(s,o) s>>=o = __irshift__(s,o)
1180 Conversions
1181 int(s) = __int__(s) long(s) = __long__(s)
1182 float(s) = __float__(s) complex(s) = __complex__(s)
1183 oct(s) = __oct__(s) hex(s) = __hex__(s)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001184 Right-hand-side equivalents for all binary operators exist;
1185 are called when class instance is on r-h-s of operator:
1186 a + 3 calls __add__(a, 3)
1187 3 + a calls __radd__(a, 3)
1188
1189 All seqs and maps, general operations plus:
1190 (s: self, i: index or key)
1191
1192 len(s) = __len__(s) length of object, >= 0. Length 0 == false
1193 s[i] = __getitem__(s,i) Element at index/key i, origin 0
1194
1195 Sequences, general methods, plus:
1196 s[i]=v = __setitem__(s,i,v)
1197 del s[i] = __delitem__(s,i)
1198 s[i:j] = __getslice__(s,i,j)
1199 s[i:j]=seq = __setslice__(s,i,j,seq)
1200 del s[i:j] = __delslice__(s,i,j) == s[i:j] = []
1201 seq * n = __repeat__(seq, n)
1202 s1 + s2 = __concat__(s1, s2)
1203 i in s = __contains__(s, i)
1204 Mappings, general methods, plus
1205 hash(s) = __hash__(s) - hash value for dictionary references
1206 s[k]=v = __setitem__(s,k,v)
1207 del s[k] = __delitem__(s,k)
1208
1209Special informative state attributes for some types:
1210
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001211 Modules:
1212 __doc__ (string/None, R/O): doc string (<=> __dict__['__doc__'])
1213 __name__(string, R/O): module name (also in __dict__['__name__'])
1214 __dict__ (dict, R/O): module's name space
1215 __file__(string/undefined, R/O): pathname of .pyc, .pyo or .pyd (undef for
1216 modules statically linked to the interpreter)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001217
1218 Classes: [in bold: writable since 1.5.2]
1219 __doc__ (string/None, R/W): doc string (<=> __dict__['__doc__'])
Raymond Hettingere685f942003-01-26 03:29:15 +00001220 __module__ is the module name in which the class was defined
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001221 __name__(string, R/W): class name (also in __dict__['__name__'])
1222 __bases__ (tuple, R/W): parent classes
1223 __dict__ (dict, R/W): attributes (class name space)
1224
1225 Instances:
1226 __class__ (class, R/W): instance's class
1227 __dict__ (dict, R/W): attributes
Raymond Hettingere685f942003-01-26 03:29:15 +00001228
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001229 User-defined functions: [bold: writable since 1.5.2]
1230 __doc__ (string/None, R/W): doc string
1231 __name__(string, R/O): function name
1232 func_doc (R/W): same as __doc__
1233 func_name (R/O): same as __name__
1234 func_defaults (tuple/None, R/W): default args values if any
1235 func_code (code, R/W): code object representing the compiled function body
1236 func_globals (dict, R/O): ref to dictionary of func global variables
Raymond Hettingere685f942003-01-26 03:29:15 +00001237 func_dict (dict, R/W): same as __dict__ contains the namespace supporting
1238 arbitrary function attributes
1239 func_closure (R/O): None or a tuple of cells that contain bindings
1240 for the function's free variables.
1241
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001242
1243 User-defined Methods:
1244 __doc__ (string/None, R/O): doc string
1245 __name__(string, R/O): method name (same as im_func.__name__)
1246 im_class (class, R/O): class defining the method (may be a base class)
1247 im_self (instance/None, R/O): target instance object (None if unbound)
1248 im_func (function, R/O): function object
Raymond Hettingere685f942003-01-26 03:29:15 +00001249
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001250 Built-in Functions & methods:
1251 __doc__ (string/None, R/O): doc string
1252 __name__ (string, R/O): function name
1253 __self__ : [methods only] target object
Raymond Hettingere685f942003-01-26 03:29:15 +00001254
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001255 Codes:
1256 co_name (string, R/O): function name
1257 co_argcount (int, R/0): number of positional args
1258 co_nlocals (int, R/O): number of local vars (including args)
1259 co_varnames (tuple, R/O): names of local vars (starting with args)
Raymond Hettingere685f942003-01-26 03:29:15 +00001260 co_cellvars (tuple, R/O)) the names of local variables referenced by
1261 nested functions
1262 co_freevars (tuple, R/O)) names of free variables
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001263 co_code (string, R/O): sequence of bytecode instructions
1264 co_consts (tuple, R/O): litterals used by the bytecode, 1st one is
1265 fct doc (or None)
1266 co_names (tuple, R/O): names used by the bytecode
1267 co_filename (string, R/O): filename from which the code was compiled
1268 co_firstlineno (int, R/O): first line number of the function
1269 co_lnotab (string, R/O): string encoding bytecode offsets to line numbers.
1270 co_stacksize (int, R/O): required stack size (including local vars)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001271 co_flags (int, R/O): flags for the interpreter
1272 bit 2 set if fct uses "*arg" syntax
1273 bit 3 set if fct uses '**keywords' syntax
1274 Frames:
1275 f_back (frame/None, R/O): previous stack frame (toward the caller)
1276 f_code (code, R/O): code object being executed in this frame
1277 f_locals (dict, R/O): local vars
1278 f_globals (dict, R/O): global vars
1279 f_builtins (dict, R/O): built-in (intrinsic) names
1280 f_restricted (int, R/O): flag indicating whether fct is executed in
1281 restricted mode
1282 f_lineno (int, R/O): current line number
1283 f_lasti (int, R/O): precise instruction (index into bytecode)
1284 f_trace (function/None, R/W): debug hook called at start of each source line
1285 f_exc_type (Type/None, R/W): Most recent exception type
1286 f_exc_value (any, R/W): Most recent exception value
1287 f_exc_traceback (traceback/None, R/W): Most recent exception traceback
1288 Tracebacks:
1289 tb_next (frame/None, R/O): next level in stack trace (toward the frame where
1290 the exception occurred)
1291 tb_frame (frame, R/O): execution frame of the current level
Fred Drakedb390c12005-10-28 14:39:47 +00001292 tb_lineno (int, R/O): line number where the exception occurred
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001293 tb_lasti (int, R/O): precise instruction (index into bytecode)
1294
1295 Slices:
1296 start (any/None, R/O): lowerbound
1297 stop (any/None, R/O): upperbound
1298 step (any/None, R/O): step value
1299
1300 Complex numbers:
1301 real (float, R/O): real part
1302 imag (float, R/O): imaginary part
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001303
1304
1305Important Modules
1306
1307 sys
1308
1309 Some sys variables
1310 Variable Content
1311argv The list of command line arguments passed to aPython
1312 script. sys.argv[0] is the script name.
1313builtin_module_names A list of strings giving the names of all moduleswritten
1314 in C that are linked into this interpreter.
1315check_interval How often to check for thread switches or signals(measured
1316 in number of virtual machine instructions)
1317exc_type, exc_value, Deprecated since release 1.5. Use exc_info() instead.
1318exc_traceback
1319exitfunc User can set to a parameterless fcn. It will getcalled
1320 before interpreter exits.
1321last_type, Set only when an exception not handled andinterpreter
1322last_value, prints an error. Used by debuggers.
1323last_traceback
1324maxint maximum positive value for integers
1325modules Dictionary of modules that have already been loaded.
1326path Search path for external modules. Can be modifiedby
1327 program. sys.path[0] == dir of script executing
1328platform The current platform, e.g. "sunos5", "win32"
1329ps1, ps2 prompts to use in interactive mode.
1330 File objects used for I/O. One can redirect byassigning a
1331stdin, stdout, new file object to them (or any object:.with a method
1332stderr write(string) for stdout/stderr,.with a method readline()
1333 for stdin)
1334version string containing version info about Python interpreter.
1335 (and also: copyright, dllhandle, exec_prefix, prefix)
1336version_info tuple containing Python version info - (major, minor,
1337 micro, level, serial).
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001338
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001339 Some sys functions
1340 Function Result
1341exit(n) Exits with status n. Raises SystemExit exception.(Hence can
1342 be caught and ignored by program)
Raymond Hettingere685f942003-01-26 03:29:15 +00001343getrefcount(object Returns the reference count of the object. Generally one
1344) higher than you might expect, because of object arg temp
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001345 reference.
1346setcheckinterval( Sets the interpreter's thread switching interval (in number
Skip Montanaroeec26f92003-07-02 21:38:34 +00001347interval) of virtual code instructions, default:100).
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001348settrace(func) Sets a trace function: called before each line ofcode is
1349 exited.
1350setprofile(func) Sets a profile function for performance profiling.
1351 Info on exception currently being handled; this is atuple
1352 (exc_type, exc_value, exc_traceback).Warning: assigning the
1353exc_info() traceback return value to a loca variable in a
Raymond Hettingere685f942003-01-26 03:29:15 +00001354 function handling an exception will cause a circular
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001355 reference.
1356setdefaultencoding Change default Unicode encoding - defaults to 7-bit ASCII.
1357(encoding)
1358getrecursionlimit Retrieve maximum recursion depth.
1359()
1360setrecursionlimit Set maximum recursion depth. (Defaults to 1000.)
1361()
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001362
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001363
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001364
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001365 os
1366"synonym" for whatever O/S-specific module is proper for current environment.
1367this module uses posix whenever possible.
1368(see also M.A. Lemburg's utility http://www.lemburg.com/files/python/
1369platform.py)
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001370
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001371 Some os variables
1372 Variable Meaning
1373name name of O/S-specific module (e.g. "posix", "mac", "nt")
1374path O/S-specific module for path manipulations.
1375 On Unix, os.path.split() <=> posixpath.split()
1376curdir string used to represent current directory ('.')
1377pardir string used to represent parent directory ('..')
1378sep string used to separate directories ('/' or '\'). Tip: use
1379 os.path.join() to build portable paths.
1380altsep Alternate sep
1381if applicable (None
1382otherwise)
1383pathsep character used to separate search path components (as in
1384 $PATH), eg. ';' for windows.
1385linesep line separator as used in binary files, ie '\n' on Unix, '\
1386 r\n' on Dos/Win, '\r'
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001387
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001388 Some os functions
1389 Function Result
1390makedirs(path[, Recursive directory creation (create required intermediary
1391mode=0777]) dirs); os.error if fails.
1392removedirs(path) Recursive directory delete (delete intermediary empty
1393 dirs); if fails.
1394renames(old, new) Recursive directory or file renaming; os.error if fails.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001395
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001396
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001397
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001398 posix
1399don't import this module directly, import os instead !
1400(see also module: shutil for file copy & remove fcts)
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001401
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001402 posix Variables
1403Variable Meaning
1404environ dictionary of environment variables, e.g.posix.environ['HOME'].
1405error exception raised on POSIX-related error.
1406 Corresponding value is tuple of errno code and perror() string.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001407
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001408 Some posix functions
1409 Function Result
1410chdir(path) Changes current directory to path.
1411chmod(path, Changes the mode of path to the numeric mode
1412mode)
1413close(fd) Closes file descriptor fd opened with posix.open.
1414_exit(n) Immediate exit, with no cleanups, no SystemExit,etc. Should use
1415 this to exit a child process.
1416execv(p, args) "Become" executable p with args args
1417getcwd() Returns a string representing the current working directory
1418getpid() Returns the current process id
1419fork() Like C's fork(). Returns 0 to child, child pid to parent.[Not
1420 on Windows]
1421kill(pid, Like C's kill [Not on Windows]
1422signal)
1423listdir(path) Lists (base)names of entries in directory path, excluding '.'
1424 and '..'
1425lseek(fd, pos, Sets current position in file fd to position pos, expressedas
1426how) an offset relative to beginning of file (how=0), tocurrent
1427 position (how=1), or to end of file (how=2)
1428mkdir(path[, Creates a directory named path with numeric mode (default 0777)
1429mode])
1430open(file, Like C's open(). Returns file descriptor. Use file object
1431flags, mode) fctsrather than this low level ones.
1432pipe() Creates a pipe. Returns pair of file descriptors (r, w) [Not on
1433 Windows].
1434popen(command, Opens a pipe to or from command. Result is a file object to
1435mode='r', read to orwrite from, as indicated by mode being 'r' or 'w'.
1436bufSize=0) Use it to catch acommand output ('r' mode) or to feed it ('w'
1437 mode).
1438remove(path) See unlink.
1439rename(src, dst Renames/moves the file or directory src to dst. [error iftarget
1440) name already exists]
1441rmdir(path) Removes the empty directory path
1442read(fd, n) Reads n bytes from file descriptor fd and return as string.
1443 Returns st_mode, st_ino, st_dev, st_nlink, st_uid,st_gid,
1444stat(path) st_size, st_atime, st_mtime, st_ctime.[st_ino, st_uid, st_gid
1445 are dummy on Windows]
1446system(command) Executes string command in a subshell. Returns exitstatus of
1447 subshell (usually 0 means OK).
1448 Returns accumulated CPU times in sec (user, system, children's
1449times() user,children's sys, elapsed real time). [3 last not on
1450 Windows]
1451unlink(path) Unlinks ("deletes") the file (not dir!) path. same as: remove
1452utime(path, ( Sets the access & modified time of the file to the given tuple
1453aTime, mTime)) of values.
1454wait() Waits for child process completion. Returns tuple ofpid,
1455 exit_status [Not on Windows]
1456waitpid(pid, Waits for process pid to complete. Returns tuple ofpid,
1457options) exit_status [Not on Windows]
1458write(fd, str) Writes str to file fd. Returns nb of bytes written.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001459
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001460
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001461
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001462 posixpath
1463Do not import this module directly, import os instead and refer to this module
1464as os.path. (e.g. os.path.exists(p)) !
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001465
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001466 Some posixpath functions
1467 Function Result
1468abspath(p) Returns absolute path for path p, taking current working dir in
1469 account.
1470dirname/
1471basename(p directory and name parts of the path p. See also split.
1472)
1473exists(p) True if string p is an existing path (file or directory)
1474expanduser Returns string that is (a copy of) p with "~" expansion done.
1475(p)
1476expandvars Returns string that is (a copy of) p with environment vars expanded.
1477(p) [Windows: case significant; must use Unix: $var notation, not %var%]
1478getsize( return the size in bytes of filename. raise os.error.
1479filename)
1480getmtime( return last modification time of filename (integer nb of seconds
1481filename) since epoch).
1482getatime( return last access time of filename (integer nb of seconds since
1483filename) epoch).
1484isabs(p) True if string p is an absolute path.
1485isdir(p) True if string p is a directory.
1486islink(p) True if string p is a symbolic link.
1487ismount(p) True if string p is a mount point [true for all dirs on Windows].
1488join(p[,q Joins one or more path components intelligently.
1489[,...]])
1490 Splits p into (head, tail) where tail is lastpathname component and
1491split(p) <head> is everything leadingup to that. <=> (dirname(p), basename
1492 (p))
1493splitdrive Splits path p in a pair ('drive:', tail) [Windows]
1494(p)
1495splitext(p Splits into (root, ext) where last comp of root contains no periods
1496) and ext is empty or startswith a period.
1497 Calls the function visit with arguments(arg, dirname, names) for
1498 each directory recursively inthe directory tree rooted at p
1499walk(p, (including p itself if it's a dir)The argument dirname specifies the
1500visit, arg visited directory, the argumentnames lists the files in the
1501) directory. The visit function maymodify names to influence the set
1502 of directories visited belowdirname, e.g., to avoid visiting certain
1503 parts of the tree.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001504
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001505
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001506
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001507 shutil
1508high-level file operations (copying, deleting).
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001509
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001510 Main shutil functions
1511 Function Result
1512copy(src, dst) Copies the contents of file src to file dst, retaining file
1513 permissions.
1514copytree(src, dst Recursively copies an entire directory tree rooted at src
1515[, symlinks]) into dst (which should not already exist). If symlinks is
1516 true, links insrc are kept as such in dst.
1517rmtree(path[, Deletes an entire directory tree, ignoring errors if
1518ignore_errors[, ignore_errors true,or calling onerror(func, path,
1519onerror]]) sys.exc_info()) if supplied with
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001520
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001521(and also: copyfile, copymode, copystat, copy2)
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001522
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001523time
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001524
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001525 Variables
1526Variable Meaning
1527altzone signed offset of local DST timezone in sec west of the 0th meridian.
1528daylight nonzero if a DST timezone is specified
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001529
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001530 Functions
1531 Function Result
1532time() return a float representing UTC time in seconds since the epoch.
1533gmtime(secs), return a tuple representing time : (year aaaa, month(1-12),day
1534localtime( (1-31), hour(0-23), minute(0-59), second(0-59), weekday(0-6, 0 is
1535secs) monday), Julian day(1-366), daylight flag(-1,0 or 1))
1536asctime(
1537timeTuple),
1538strftime(
1539format, return a formated string representing time.
1540timeTuple)
1541mktime(tuple) inverse of localtime(). Return a float.
1542strptime( parse a formated string representing time, return tuple as in
1543string[, gmtime().
1544format])
1545sleep(secs) Suspend execution for <secs> seconds. <secs> can be a float.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001546
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001547and also: clock, ctime.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001548
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001549 string
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001550
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001551As of Python 2.0, much (though not all) of the functionality provided by the
1552string module have been superseded by built-in string methods - see Operations
1553on strings for details.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001554
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001555 Some string variables
1556 Variable Meaning
1557digits The string '0123456789'
1558hexdigits, octdigits legal hexadecimal & octal digits
1559letters, uppercase, lowercase, Strings containing the appropriate
1560whitespace characters
1561index_error Exception raised by index() if substr not
1562 found.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001563
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001564 Some string functions
1565 Function Result
1566expandtabs(s, returns a copy of string <s> with tabs expanded.
1567tabSize)
1568find/rfind(s, sub Return the lowest/highest index in <s> where the substring
1569[, start=0[, end= <sub> is found such that <sub> is wholly contained ins
15700]) [start:end]. Return -1 if <sub> not found.
1571ljust/rjust/center Return a copy of string <s> left/right justified/centerd in
1572(s, width) afield of given width, padded with spaces. <s> is
1573 nevertruncated.
1574lower/upper(s) Return a string that is (a copy of) <s> in lowercase/
1575 uppercase
1576split(s[, sep= Return a list containing the words of the string <s>,using
1577whitespace[, the string <sep> as a separator.
1578maxsplit=0]])
1579join(words[, sep=' Concatenate a list or tuple of words with
1580']) interveningseparators; inverse of split.
Fred Drakedb390c12005-10-28 14:39:47 +00001581replace(s, old, Returns a copy of string <s> with all occurrences of
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001582new[, maxsplit=0] substring<old> replaced by <new>. Limits to <maxsplit>
1583 firstsubstitutions if specified.
1584strip(s) Return a string that is (a copy of) <s> without leadingand
1585 trailing whitespace. see also lstrip, rstrip.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001586
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001587
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001588
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001589 re (sre)
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001590
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001591Handles Unicode strings. Implemented in new module sre, re now a mere front-end
1592for compatibility.
1593Patterns are specified as strings. Tip: Use raw strings (e.g. r'\w*') to
1594litteralize backslashes.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001595
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001596
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001597 Regular expression syntax
1598 Form Description
1599. matches any character (including newline if DOTALL flag specified)
1600^ matches start of the string (of every line in MULTILINE mode)
1601$ matches end of the string (of every line in MULTILINE mode)
1602* 0 or more of preceding regular expression (as many as possible)
1603+ 1 or more of preceding regular expression (as many as possible)
Fred Drakedb390c12005-10-28 14:39:47 +00001604? 0 or 1 occurrence of preceding regular expression
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001605*?, +?, ?? Same as *, + and ? but matches as few characters as possible
1606{m,n} matches from m to n repetitions of preceding RE
1607{m,n}? idem, attempting to match as few repetitions as possible
1608[ ] defines character set: e.g. '[a-zA-Z]' to match all letters(see also
1609 \w \S)
1610[^ ] defines complemented character set: matches if char is NOT in set
1611 escapes special chars '*?+&$|()' and introduces special sequences
1612\ (see below). Due to Python string rules, write as '\\' orr'\' in the
1613 pattern string.
1614\\ matches a litteral '\'; due to Python string rules, write as '\\\\
1615 'in pattern string, or better using raw string: r'\\'.
1616| specifies alternative: 'foo|bar' matches 'foo' or 'bar'
1617(...) matches any RE inside (), and delimits a group.
1618(?:...) idem but doesn't delimit a group.
1619 matches if ... matches next, but doesn't consume any of the string
1620(?=...) e.g. 'Isaac (?=Asimov)' matches 'Isaac' only if followed by
1621 'Asimov'.
1622(?!...) matches if ... doesn't match next. Negative of (?=...)
1623(?P<name matches any RE inside (), and delimits a named group. (e.g. r'(?P
1624>...) <id>[a-zA-Z_]\w*)' defines a group named id)
1625(?P=name) matches whatever text was matched by the earlier group named name.
1626(?#...) A comment; ignored.
1627(?letter) letter is one of 'i','L', 'm', 's', 'x'. Set the corresponding flags
1628 (re.I, re.L, re.M, re.S, re.X) for the entire RE.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001629
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001630 Special sequences
1631Sequence Description
1632number matches content of the group of the same number; groups are numbered
1633 starting from 1
1634\A matches only at the start of the string
1635\b empty str at beg or end of word: '\bis\b' matches 'is', but not 'his'
1636\B empty str NOT at beginning or end of word
1637\d any decimal digit (<=> [0-9])
1638\D any non-decimal digit char (<=> [^O-9])
1639\s any whitespace char (<=> [ \t\n\r\f\v])
1640\S any non-whitespace char (<=> [^ \t\n\r\f\v])
1641\w any alphaNumeric char (depends on LOCALE flag)
1642\W any non-alphaNumeric char (depends on LOCALE flag)
1643\Z matches only at the end of the string
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001644
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001645 Variables
1646Variable Meaning
1647error Exception when pattern string isn't a valid regexp.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001648
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001649 Functions
1650 Function Result
1651 Compile a RE pattern string into a regular expression object.
1652 Flags (combinable by |):
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001653
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001654 I or IGNORECASE or (?i)
1655 case insensitive matching
1656compile( L or LOCALE or (?L)
1657pattern[, make \w, \W, \b, \B dependent on thecurrent locale
1658flags=0]) M or MULTILINE or (?m)
1659 matches every new line and not onlystart/end of the whole
1660 string
1661 S or DOTALL or (?s)
1662 '.' matches ALL chars, including newline
1663 X or VERBOSE or (?x)
1664 Ignores whitespace outside character sets
1665escape(string) return (a copy of) string with all non-alphanumerics
1666 backslashed.
1667match(pattern, if 0 or more chars at beginning of <string> match the RE pattern
1668string[, flags string,return a corresponding MatchObject instance, or None if
1669]) no match.
1670search(pattern scan thru <string> for a location matching <pattern>, return
1671, string[, acorresponding MatchObject instance, or None if no match.
1672flags])
1673split(pattern, split <string> by occurrences of <pattern>. If capturing () are
1674string[, used inpattern, then occurrences of patterns or subpatterns are
1675maxsplit=0]) also returned.
1676findall( return a list of non-overlapping matches in <pattern>, either a
1677pattern, list ofgroups or a list of tuples if the pattern has more than 1
1678string) group.
1679 return string obtained by replacing the (<count> first) lefmost
1680sub(pattern, non-overlapping occurrences of <pattern> (a string or a RE
1681repl, string[, object) in <string>by <repl>; <repl> can be a string or a fct
1682count=0]) called with a single MatchObj arg, which must return the
1683 replacement string.
1684subn(pattern,
1685repl, string[, same as sub(), but returns a tuple (newString, numberOfSubsMade)
1686count=0])
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001687
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001688Regular Expression Objects
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001689
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001690
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001691(RE objects are returned by the compile fct)
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001692
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001693 re object attributes
1694Attribute Descrition
1695flags flags arg used when RE obj was compiled, or 0 if none provided
1696groupindex dictionary of {group name: group number} in pattern
1697pattern pattern string from which RE obj was compiled
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001698
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001699 re object methods
1700 Method Result
1701 If zero or more characters at the beginning of string match this
1702 regular expression, return a corresponding MatchObject instance.
1703 Return None if the string does not match the pattern; note that
1704 this is different from a zero-length match.
1705 The optional second parameter pos gives an index in the string
1706match( where the search is to start; it defaults to 0. This is not
1707string[, completely equivalent to slicing the string; the '' pattern
1708pos][, character matches at the real beginning of the string and at
1709endpos]) positions just after a newline, but not necessarily at the index
1710 where the search is to start.
1711 The optional parameter endpos limits how far the string will be
1712 searched; it will be as if the string is endpos characters long, so
1713 only the characters from pos to endpos will be searched for a
1714 match.
1715 Scan through string looking for a location where this regular
1716search( expression produces a match, and return a corresponding MatchObject
1717string[, instance. Return None if no position in the string matches the
1718pos][, pattern; note that this is different from finding a zero-length
1719endpos]) match at some point in the string.
1720 The optional pos and endpos parameters have the same meaning as for
1721 the match() method.
1722split(
1723string[, Identical to the split() function, using the compiled pattern.
1724maxsplit=
17250])
1726findall( Identical to the findall() function, using the compiled pattern.
1727string)
1728sub(repl,
1729string[, Identical to the sub() function, using the compiled pattern.
1730count=0])
1731subn(repl,
1732string[, Identical to the subn() function, using the compiled pattern.
1733count=0])
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001734
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001735Match Objects
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001736
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001737
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001738(Match objects are returned by the match & search functions)
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001739
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001740 Match object attributes
1741Attribute Description
1742pos value of pos passed to search or match functions; index intostring at
1743 which RE engine started search.
1744endpos value of endpos passed to search or match functions; index intostring
1745 beyond which RE engine won't go.
1746re RE object whose match or search fct produced this MatchObj instance
1747string string passed to match() or search()
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001748
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001749 Match object functions
1750Function Result
1751 returns one or more groups of the match. If one arg, result is a
1752group([g1 string;if multiple args, result is a tuple with one item per arg. If
1753, g2, gi is 0,return value is entire matching string; if 1 <= gi <= 99,
1754...]) returnstring matching group #gi (or None if no such group); gi may
1755 also bea group name.
1756 returns a tuple of all groups of the match; groups not
1757groups() participatingto the match have a value of None. Returns a string
1758 instead of tupleif len(tuple)=1
1759start(
1760group), returns indices of start & end of substring matched by group (or
1761end(group Noneif group exists but doesn't contribute to the match)
1762)
1763span( returns the 2-tuple (start(group), end(group)); can be (None, None)if
1764group) group didn't contibute to the match.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001765
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001766
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001767
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001768 math
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001769
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001770Variables:
1771pi
1772e
1773Functions (see ordinary C man pages for info):
1774acos(x)
1775asin(x)
1776atan(x)
1777atan2(x, y)
1778ceil(x)
1779cos(x)
1780cosh(x)
Raymond Hettingere685f942003-01-26 03:29:15 +00001781degrees(x)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001782exp(x)
1783fabs(x)
1784floor(x)
1785fmod(x, y)
1786frexp(x) -- Unlike C: (float, int) = frexp(float)
1787ldexp(x, y)
Raymond Hettingere685f942003-01-26 03:29:15 +00001788log(x [,base])
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001789log10(x)
1790modf(x) -- Unlike C: (float, float) = modf(float)
1791pow(x, y)
Raymond Hettingere685f942003-01-26 03:29:15 +00001792radians(x)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001793sin(x)
1794sinh(x)
1795sqrt(x)
1796tan(x)
1797tanh(x)
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001798
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001799 getopt
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001800
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001801Functions:
1802getopt(list, optstr) -- Similar to C. <optstr> is option
1803 letters to look for. Put ':' after letter
1804 if option takes arg. E.g.
1805 # invocation was "python test.py -c hi -a arg1 arg2"
1806 opts, args = getopt.getopt(sys.argv[1:], 'ab:c:')
1807 # opts would be
1808 [('-c', 'hi'), ('-a', '')]
1809 # args would be
1810 ['arg1', 'arg2']
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001811
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001812
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001813List of modules and packages in base distribution
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001814
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001815(built-ins and content of python Lib directory)
1816(Python NT distribution, may be slightly different in other distributions)
Guido van Rossumc8180cc1994-08-05 15:57:31 +00001817
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001818 Standard library modules
1819 Operation Result
1820aifc Stuff to parse AIFF-C and AIFF files.
1821anydbm Generic interface to all dbm clones. (dbhash, gdbm,
1822 dbm,dumbdbm)
1823asynchat Support for 'chat' style protocols
1824asyncore Asynchronous File I/O (in select style)
1825atexit Register functions to be called at exit of Python interpreter.
1826audiodev Audio support for a few platforms.
1827base64 Conversions to/from base64 RFC-MIME transport encoding .
1828BaseHTTPServer Base class forhttp services.
1829Bastion "Bastionification" utility (control access to instance vars)
1830bdb A generic Python debugger base class.
1831binhex Macintosh binhex compression/decompression.
1832bisect List bisection algorithms.
Raymond Hettingere685f942003-01-26 03:29:15 +00001833bz2 Support for bz2 compression/decompression.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001834calendar Calendar printing functions.
1835cgi Wraps the WWW Forms Common Gateway Interface (CGI).
Raymond Hettingere685f942003-01-26 03:29:15 +00001836cgitb Utility for handling CGI tracebacks.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001837CGIHTTPServer CGI http services.
1838cmd A generic class to build line-oriented command interpreters.
Raymond Hettingere685f942003-01-26 03:29:15 +00001839datetime Basic date and time types.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001840code Utilities needed to emulate Python's interactive interpreter
1841codecs Lookup existing Unicode encodings and register new ones.
1842colorsys Conversion functions between RGB and other color systems.
1843commands Tools for executing UNIX commands .
1844compileall Force "compilation" of all .py files in a directory.
1845ConfigParser Configuration file parser (much like windows .ini files)
1846copy Generic shallow and deep copying operations.
1847copy_reg Helper to provide extensibility for pickle/cPickle.
Raymond Hettingerca60cac2003-07-12 23:55:57 +00001848csv Read and write files with comma separated values.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001849dbhash (g)dbm-compatible interface to bsdhash.hashopen.
1850dircache Sorted list of files in a dir, using a cache.
1851[DEL:dircmp:DEL] [DEL:Defines a class to build directory diff tools on.:DEL]
Raymond Hettingere685f942003-01-26 03:29:15 +00001852difflib Tool for creating delta between sequences.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001853dis Bytecode disassembler.
1854distutils Package installation system.
Raymond Hettingere685f942003-01-26 03:29:15 +00001855doctest Tool for running and verifying tests inside doc strings.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001856dospath Common operations on DOS pathnames.
1857dumbdbm A dumb and slow but simple dbm clone.
1858[DEL:dump:DEL] [DEL:Print python code that reconstructs a variable.:DEL]
Raymond Hettingere685f942003-01-26 03:29:15 +00001859email Comprehensive support for internet email.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001860exceptions Class based built-in exception hierarchy.
1861filecmp File comparison.
1862fileinput Helper class to quickly write a loop over all standard input
1863 files.
1864[DEL:find:DEL] [DEL:Find files directory hierarchy matching a pattern.:DEL]
1865fnmatch Filename matching with shell patterns.
1866formatter A test formatter.
1867fpformat General floating point formatting functions.
1868ftplib An FTP client class. Based on RFC 959.
1869gc Perform garbacge collection, obtain GC debug stats, and tune
1870 GC parameters.
1871getopt Standard command line processing. See also ftp://
1872 www.pauahtun.org/pub/getargspy.zip
1873getpass Utilities to get a password and/or the current user name.
1874glob filename globbing.
1875gopherlib Gopher protocol client interface.
1876[DEL:grep:DEL] [DEL:'grep' utilities.:DEL]
1877gzip Read & write gzipped files.
Raymond Hettingere685f942003-01-26 03:29:15 +00001878heapq Priority queue implemented using lists organized as heaps.
1879HMAC Keyed-Hashing for Message Authentication -- RFC 2104.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001880htmlentitydefs Proposed entity definitions for HTML.
1881htmllib HTML parsing utilities.
Raymond Hettingere685f942003-01-26 03:29:15 +00001882HTMLParser A parser for HTML and XHTML.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001883httplib HTTP client class.
1884ihooks Hooks into the "import" mechanism.
1885imaplib IMAP4 client.Based on RFC 2060.
1886imghdr Recognizing image files based on their first few bytes.
1887imputil Privides a way of writing customised import hooks.
Raymond Hettingere685f942003-01-26 03:29:15 +00001888inspect Tool for probing live Python objects.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001889keyword List of Python keywords.
1890knee A Python re-implementation of hierarchical module import.
1891linecache Cache lines from files.
1892linuxaudiodev Lunix /dev/audio support.
1893locale Support for number formatting using the current locale
1894 settings.
Raymond Hettingere685f942003-01-26 03:29:15 +00001895logging Python logging facility.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001896macpath Pathname (or related) operations for the Macintosh.
1897macurl2path Mac specific module for conversion between pathnames and URLs.
1898mailbox A class to handle a unix-style or mmdf-style mailbox.
1899mailcap Mailcap file handling (RFC 1524).
1900mhlib MH (mailbox) interface.
1901mimetools Various tools used by MIME-reading or MIME-writing programs.
1902mimetypes Guess the MIME type of a file.
1903MimeWriter Generic MIME writer.
1904mimify Mimification and unmimification of mail messages.
1905mmap Interface to memory-mapped files - they behave like mutable
1906 strings./font>
1907multifile Class to make multi-file messages easier to handle.
1908mutex Mutual exclusion -- for use with module sched.
1909netrc
1910nntplib An NNTP client class. Based on RFC 977.
1911ntpath Common operations on DOS pathnames.
1912nturl2path Mac specific module for conversion between pathnames and URLs.
Raymond Hettingere685f942003-01-26 03:29:15 +00001913optparse A comprehensive tool for processing command line options.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001914os Either mac, dos or posix depending system.
1915[DEL:packmail: [DEL:Create a self-unpacking shell archive.:DEL]
1916DEL]
1917pdb A Python debugger.
1918pickle Pickling (save and restore) of Python objects (a faster
1919 Cimplementation exists in built-in module: cPickle).
1920pipes Conversion pipeline templates.
Raymond Hettingere685f942003-01-26 03:29:15 +00001921pkgunil Utilities for working with Python packages.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001922popen2 variations on pipe open.
1923poplib A POP3 client class. Based on the J. Myers POP3 draft.
1924posixfile Extended (posix) file operations.
1925posixpath Common operations on POSIX pathnames.
1926pprint Support to pretty-print lists, tuples, & dictionaries
1927 recursively.
1928profile Class for profiling python code.
1929pstats Class for printing reports on profiled python code.
Raymond Hettingere685f942003-01-26 03:29:15 +00001930pydoc Utility for generating documentation from source files.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001931pty Pseudo terminal utilities.
1932pyexpat Interface to the Expay XML parser.
1933py_compile Routine to "compile" a .py file to a .pyc file.
1934pyclbr Parse a Python file and retrieve classes and methods.
1935Queue A multi-producer, multi-consumer queue.
1936quopri Conversions to/from quoted-printable transport encoding.
1937rand Don't use unless you want compatibility with C's rand().
Raymond Hettinger5a772d32003-01-25 22:35:42 +00001938random Random variable generators
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001939re Regular Expressions.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001940repr Redo repr() but with limits on most sizes.
1941rexec Restricted execution facilities ("safe" exec, eval, etc).
1942rfc822 RFC-822 message manipulation class.
1943rlcompleter Word completion for GNU readline 2.0.
Raymond Hettinger2d95f1a2004-03-13 20:27:23 +00001944robotparser Parse robots.txt files, useful for web spiders.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001945sched A generally useful event scheduler class.
Raymond Hettingere685f942003-01-26 03:29:15 +00001946sets Module for a set datatype.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001947sgmllib A parser for SGML.
1948shelve Manage shelves of pickled objects.
1949shlex Lexical analyzer class for simple shell-like syntaxes.
1950shutil Utility functions usable in a shell-like program.
1951SimpleHTTPServer Simple extension to base http class
1952site Append module search paths for third-party packages to
1953 sys.path.
1954smtplib SMTP Client class (RFC 821)
1955sndhdr Several routines that help recognizing sound.
1956SocketServer Generic socket server classes.
1957stat Constants and functions for interpreting stat/lstat struct.
1958statcache Maintain a cache of file stats.
1959statvfs Constants for interpreting statvfs struct as returned by
1960 os.statvfs()and os.fstatvfs() (if they exist).
1961string A collection of string operations.
1962StringIO File-like objects that read/write a string buffer (a fasterC
1963 implementation exists in built-in module: cStringIO).
1964sunau Stuff to parse Sun and NeXT audio files.
1965sunaudio Interpret sun audio headers.
1966symbol Non-terminal symbols of Python grammar (from "graminit.h").
1967tabnanny,/font> Check Python source for ambiguous indentation.
Raymond Hettingere685f942003-01-26 03:29:15 +00001968tarfile Facility for reading and writing to the *nix tarfile format.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001969telnetlib TELNET client class. Based on RFC 854.
1970tempfile Temporary file name allocation.
Raymond Hettingere685f942003-01-26 03:29:15 +00001971textwrap Object for wrapping and filling text.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001972threading Proposed new higher-level threading interfaces
1973threading_api (doc of the threading module)
1974toaiff Convert "arbitrary" sound files to AIFF files .
1975token Tokens (from "token.h").
1976tokenize Compiles a regular expression that recognizes Python tokens.
1977traceback Format and print Python stack traces.
1978tty Terminal utilities.
1979turtle LogoMation-like turtle graphics
1980types Define names for all type symbols in the std interpreter.
1981tzparse Parse a timezone specification.
1982unicodedata Interface to unicode properties.
1983urllib Open an arbitrary URL.
1984urlparse Parse URLs according to latest draft of standard.
1985user Hook to allow user-specified customization code to run.
1986UserDict A wrapper to allow subclassing of built-in dict class.
1987UserList A wrapper to allow subclassing of built-in list class.
1988UserString A wrapper to allow subclassing of built-in string class.
1989[DEL:util:DEL] [DEL:some useful functions that don't fit elsewhere !!:DEL]
1990uu UUencode/UUdecode.
Raymond Hettingere685f942003-01-26 03:29:15 +00001991unittest Utilities for implementing unit testing.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001992wave Stuff to parse WAVE files.
Raymond Hettingere685f942003-01-26 03:29:15 +00001993weakref Tools for creating and managing weakly referenced objects.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001994webbrowser Platform independent URL launcher.
1995[DEL:whatsound: [DEL:Several routines that help recognizing sound files.:DEL]
1996DEL]
1997whichdb Guess which db package to use to open a db file.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00001998xdrlib Implements (a subset of) Sun XDR (eXternal Data
1999 Representation)
2000xmllib A parser for XML, using the derived class as static DTD.
2001xml.dom Classes for processing XML using the Document Object Model.
2002xml.sax Classes for processing XML using the SAX API.
Raymond Hettingere685f942003-01-26 03:29:15 +00002003xmlrpclib Support for remote procedure calls using XML.
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002004zipfile Read & write PK zipped files.
2005[DEL:zmod:DEL] [DEL:Demonstration of abstruse mathematical concepts.:DEL]
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002006
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002007
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002008
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002009* Built-ins *
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002010
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002011 sys Interpreter state vars and functions
2012 __built-in__ Access to all built-in python identifiers
2013 __main__ Scope of the interpreters main program, script or stdin
2014 array Obj efficiently representing arrays of basic values
2015 math Math functions of C standard
Raymond Hettingere685f942003-01-26 03:29:15 +00002016 time Time-related functions (also the newer datetime module)
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002017 marshal Read and write some python values in binary format
2018 struct Convert between python values and C structs
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002019
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002020* Standard *
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002021
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002022 getopt Parse cmd line args in sys.argv. A la UNIX 'getopt'.
2023 os A more portable interface to OS dependent functionality
2024 re Functions useful for working with regular expressions
2025 string Useful string and characters functions and exceptions
Raymond Hettingere685f942003-01-26 03:29:15 +00002026 random Mersenne Twister pseudo-random number generator
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002027 thread Low-level primitives for working with process threads
2028 threading idem, new recommanded interface.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002029
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002030* Unix/Posix *
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002031
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002032 dbm Interface to Unix ndbm database library
2033 grp Interface to Unix group database
2034 posix OS functionality standardized by C and POSIX standards
2035 posixpath POSIX pathname functions
2036 pwd Access to the Unix password database
2037 select Access to Unix select multiplex file synchronization
2038 socket Access to BSD socket interface
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002039
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002040* Tk User-interface Toolkit *
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002041
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002042 tkinter Main interface to Tk
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002043
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002044* Multimedia *
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002045
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002046 audioop Useful operations on sound fragments
2047 imageop Useful operations on images
2048 jpeg Access to jpeg image compressor and decompressor
2049 rgbimg Access SGI imglib image files
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002050
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002051* Cryptographic Extensions *
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002052
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002053 md5 Interface to RSA's MD5 message digest algorithm
Andrew M. Kuchling5a9618e2004-08-31 13:43:19 +00002054 sha Interface to the SHA message digest algorithm
Raymond Hettingere685f942003-01-26 03:29:15 +00002055 HMAC Keyed-Hashing for Message Authentication -- RFC 2104.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002056
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002057* Stdwin * Standard Window System
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002058
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002059 stdwin Standard Window System interface
2060 stdwinevents Stdwin event, command, and selection constants
2061 rect Rectangle manipulation operations
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002062
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002063* SGI IRIX * (4 & 5)
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002064
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002065 al SGI audio facilities
2066 AL al constants
2067 fl Interface to FORMS library
2068 FL fl constants
2069 flp Functions for form designer
2070 fm Access to font manager library
2071 gl Access to graphics library
2072 GL Constants for gl
2073 DEVICE More constants for gl
2074 imgfile Imglib image file interface
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002075
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002076* Suns *
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002077
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002078 sunaudiodev Access to sun audio interface
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002079
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002080
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002081Workspace exploration and idiom hints
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002082
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002083 dir(<module>) list functions, variables in <module>
2084 dir() get object keys, defaults to local name space
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002085 if __name__ == '__main__': main() invoke main if running as script
2086 map(None, lst1, lst2, ...) merge lists
2087 b = a[:] create copy of seq structure
2088 _ in interactive mode, is last value printed
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002089
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002090
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002091
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002092
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002093
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002094
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002095
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002096Python Mode for Emacs
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002097
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002098(Not revised, possibly not up to date)
2099Type C-c ? when in python-mode for extensive help.
2100INDENTATION
2101Primarily for entering new code:
2102 TAB indent line appropriately
2103 LFD insert newline, then indent
2104 DEL reduce indentation, or delete single character
2105Primarily for reindenting existing code:
2106 C-c : guess py-indent-offset from file content; change locally
2107 C-u C-c : ditto, but change globally
2108 C-c TAB reindent region to match its context
2109 C-c < shift region left by py-indent-offset
2110 C-c > shift region right by py-indent-offset
2111MARKING & MANIPULATING REGIONS OF CODE
2112C-c C-b mark block of lines
2113M-C-h mark smallest enclosing def
2114C-u M-C-h mark smallest enclosing class
2115C-c # comment out region of code
2116C-u C-c # uncomment region of code
2117MOVING POINT
2118C-c C-p move to statement preceding point
2119C-c C-n move to statement following point
2120C-c C-u move up to start of current block
2121M-C-a move to start of def
2122C-u M-C-a move to start of class
2123M-C-e move to end of def
2124C-u M-C-e move to end of class
2125EXECUTING PYTHON CODE
2126C-c C-c sends the entire buffer to the Python interpreter
2127C-c | sends the current region
2128C-c ! starts a Python interpreter window; this will be used by
2129 subsequent C-c C-c or C-c | commands
Raymond Hettingere685f942003-01-26 03:29:15 +00002130C-c C-w runs PyChecker
2131
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002132VARIABLES
2133py-indent-offset indentation increment
2134py-block-comment-prefix comment string used by py-comment-region
2135py-python-command shell command to invoke Python interpreter
2136py-scroll-process-buffer t means always scroll Python process buffer
2137py-temp-directory directory used for temp files (if needed)
2138py-beep-if-tab-change ring the bell if tab-width is changed
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002139
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002140
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002141The Python Debugger
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002142
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002143(Not revised, possibly not up to date, see 1.5.2 Library Ref section 9.1; in 1.5.2, you may also use debugger integrated in IDLE)
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002144
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002145Accessing
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002146
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002147import pdb (it's a module written in Python)
2148 -- defines functions :
2149 run(statement[,globals[, locals]])
2150 -- execute statement string under debugger control, with optional
2151 global & local environment.
2152 runeval(expression[,globals[, locals]])
2153 -- same as run, but evaluate expression and return value.
2154 runcall(function[, argument, ...])
2155 -- run function object with given arg(s)
2156 pm() -- run postmortem on last exception (like debugging a core file)
2157 post_mortem(t)
2158 -- run postmortem on traceback object <t>
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002159
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002160 -- defines class Pdb :
2161 use Pdb to create reusable debugger objects. Object
2162 preserves state (i.e. break points) between calls.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002163
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002164 runs until a breakpoint hit, exception, or end of program
2165 If exception, variable '__exception__' holds (exception,value).
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002166
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002167Commands
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002168
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002169h, help
2170 brief reminder of commands
2171b, break [<arg>]
2172 if <arg> numeric, break at line <arg> in current file
2173 if <arg> is function object, break on entry to fcn <arg>
2174 if no arg, list breakpoints
2175cl, clear [<arg>]
2176 if <arg> numeric, clear breakpoint at <arg> in current file
2177 if no arg, clear all breakpoints after confirmation
2178w, where
2179 print current call stack
2180u, up
2181 move up one stack frame (to top-level caller)
2182d, down
2183 move down one stack frame
2184s, step
2185 advance one line in the program, stepping into calls
2186n, next
2187 advance one line, stepping over calls
2188r, return
2189 continue execution until current function returns
2190 (return value is saved in variable "__return__", which
2191 can be printed or manipulated from debugger)
2192c, continue
2193 continue until next breakpoint
Raymond Hettingere685f942003-01-26 03:29:15 +00002194j, jump lineno
2195 Set the next line that will be executed
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002196a, args
2197 print args to current function
2198rv, retval
2199 prints return value from last function that returned
2200p, print <arg>
2201 prints value of <arg> in current stack frame
2202l, list [<first> [, <last>]]
2203 List source code for the current file.
2204 Without arguments, list 11 lines around the current line
2205 or continue the previous listing.
2206 With one argument, list 11 lines starting at that line.
2207 With two arguments, list the given range;
2208 if the second argument is less than the first, it is a count.
2209whatis <arg>
2210 prints type of <arg>
2211!
2212 executes rest of line as a Python statement in the current stack frame
2213q quit
2214 immediately stop execution and leave debugger
2215<return>
2216 executes last command again
2217Any input debugger doesn't recognize as a command is assumed to be a
2218Python statement to execute in the current stack frame, the same way
2219the exclamation mark ("!") command does.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002220
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002221Example
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002222
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002223(1394) python
2224Python 1.0.3 (Sep 26 1994)
2225Copyright 1991-1994 Stichting Mathematisch Centrum, Amsterdam
2226>>> import rm
2227>>> rm.run()
2228Traceback (innermost last):
2229 File "<stdin>", line 1
2230 File "./rm.py", line 7
2231 x = div(3)
2232 File "./rm.py", line 2
2233 return a / r
2234ZeroDivisionError: integer division or modulo
2235>>> import pdb
2236>>> pdb.pm()
2237> ./rm.py(2)div: return a / r
2238(Pdb) list
2239 1 def div(a):
2240 2 -> return a / r
2241 3
2242 4 def run():
2243 5 global r
2244 6 r = 0
2245 7 x = div(3)
2246 8 print x
2247[EOF]
2248(Pdb) print r
22490
2250(Pdb) q
2251>>> pdb.runcall(rm.run)
2252etc.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002253
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002254Quirks
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002255
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002256Breakpoints are stored as filename, line number tuples. If a module is reloaded
2257after editing, any remembered breakpoints are likely to be wrong.
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002258
Andrew M. Kuchling13423f32001-08-06 17:43:49 +00002259Always single-steps through top-most stack frame. That is, "c" acts like "n".
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002260
Guido van Rossumc8180cc1994-08-05 15:57:31 +00002261