All 71 names Python gives you for free. Grouped by the job they do, with every parameter explained and several ways to call each one.
These names live in the builtins module, which Python loads into every scope before your first line runs. No import needed, ever. This page is a working reference. Each entry gives the signature, what each parameter means, three or four real call forms, and the trap that catches people.
int, list, str, type and friends are types. You call them and get an instance. The docs list them here because you use them exactly like functions. A trailing / in a signature means the parameters before it are positional only. You cannot pass them by name.If you learn nothing else, learn these. They cover almost every line of real Python.
sum(xs), max(xs) and any(...) beat the hand-written loop on speed and on readability. Reach for the built-in first.Seven functions. Arithmetic that is common enough to not need import math.
Distance from zero. Drops the minus sign.
x — an int, float, Decimal, Fraction, or complex. Any object with an __abs__ method works.abs(-5) # 5
abs(-2.5) # 2.5
abs(3 + 4j) # 5.0 the magnitude, not a part
sorted(xs, key=abs) # sort by size, ignoring sign
Trap. abs(-2**63) is fine in Python. Ints have no fixed width, so there is no overflow.
Floor division and remainder in one call. Returns a 2-tuple.
a — the number being divided.b — the divisor. Must not be zero.divmod(7, 2) # (3, 1) same as (7 // 2, 7 % 2)
divmod(-7, 2) # (-4, 1) floor, so it rounds down
hours, mins = divmod(135, 60) # (2, 15)
divmod(7.5, 2) # (3.0, 1.5) floats work too
Use it for. Time splits, base conversion, and grid coordinates from a flat index.
The largest item. Two call forms: one iterable, or several separate values.
iterable — any iterable. Ties go to the first item seen.key — a one-argument function. Compares key(item) but returns the original item.default — what to return if the iterable is empty. Without it, an empty input raises ValueError.max([3, 9, 1]) # 9
max(3, 9, 1) # 9 separate args
max(words, key=len) # longest word
max(people, key=lambda p: p.age) # oldest person object
max([], default=0) # 0 no exception
max(counts, key=counts.get) # key with the biggest value
Trap. key and default are keyword only. max(xs, len) is a silent bug: it compares the list to the function.
The smallest item. Same rules as max in every way.
iterable, key, default — identical to max.min([3, 9, 1]) # 1
min(a, b) # clamp lower bound
min(points, key=lambda p: p[0]**2 + p[1]**2) # closest to origin
min(intervals, key=lambda iv: iv[1]) # earliest end time
Idiom. max(low, min(high, x)) clamps x into a range.
Raise to a power. With three arguments it does fast modular exponentiation.
base — the number to raise.exp — the exponent. May be negative or a float.mod — optional modulus. All three must be ints, and exp must be non-negative unless base has an inverse.pow(2, 10) # 1024 same as 2 ** 10
pow(2, -1) # 0.5 negative exponent gives a float
pow(2, 100, 1000) # 376 fast, never builds the huge number
pow(3, -1, 7) # 5 modular inverse, Python 3.8+
Why three args. 2**100 % 1000 builds a 31-digit number first. pow(2, 100, 1000) never does. This is the crypto and hashing path.
Round to a given number of decimal places.
number — the value to round.ndigits — places after the point. Negative rounds to tens, hundreds and so on. Omit it and you get an int.round(3.567) # 4 an int, not a float
round(3.567, 2) # 3.57
round(1234, -2) # 1200 round to the nearest hundred
round(2.5) # 2 banker's rounding, see below
round(0.5) # 0
Trap. Python rounds halves to the even number. So round(2.5) is 2 and round(3.5) is 4. This is deliberate and reduces bias. For money, use decimal.Decimal with ROUND_HALF_UP.
Add up the items, left to right.
iterable — numbers, or anything that supports +.start — the value to begin from. Also the result for an empty input.sum([1, 2, 3]) # 6
sum([1, 2, 3], 100) # 106
sum(x*x for x in nums) # generator, no temp list
sum(1 for x in nums if x > 0) # count matches
sum([[1], [2]], []) # [1, 2] works, but O(n^2). Use itertools.chain
Trap. sum refuses strings on purpose. Use "".join(parts). For floats needing precision, use math.fsum.
Seven functions. Convert between number types, and between an int and its text form in another base.
A whole number. Truncates floats toward zero, or parses text.
x — a number, or a string / bytes holding digits.base — 2 to 36, or 0. Only allowed when x is text. Base 0 reads the prefix and decides for itself.int('42') # 42
int(3.99) # 3 truncates, never rounds
int(-3.99) # -3 toward zero, not down
int('ff', 16) # 255
int('1010', 2) # 10
int('0x1f', 0) # 31 base guessed from the prefix
int(' 7 ') # 7 surrounding spaces are fine
Trap. int('3.5') raises ValueError. Go through float first: int(float('3.5')).
A 64-bit decimal number.
x — a number, or a string. Accepts 'nan', 'inf', '-inf' and scientific notation.float('3.5') # 3.5
float(7) # 7.0
float('1e-3') # 0.001
float('inf') # inf handy as a starting "worst" value
float('nan') == float('nan') # False. Use math.isnan
Trap. 0.1 + 0.2 != 0.3. That is binary floating point, not a Python bug. Compare with math.isclose.
A number with a real and an imaginary part.
real — the real part, or a whole string like '1+2j'.imag — the imaginary part. Not allowed when the first argument is a string.complex(1, 2) # (1+2j)
complex('1+2j') # (1+2j) note: no spaces allowed inside
z = 3 + 4j
z.real, z.imag # (3.0, 4.0)
abs(z) # 5.0
Handy for. 2D grid problems. One complex number holds x and y, and adding does the move.
True or False. Applies Python's truthiness rules.
x — anything. Empty containers, zero, None and '' are false. Everything else is true.bool([]) # False
bool([0]) # True non-empty list, contents ignored
bool('False') # True any non-empty string is true
bool(0.0) # False
True + True # 2 bool is a subclass of int
sum(flags) # counts the True values
Style. Write if items: not if len(items) > 0:. Both work; the first is idiomatic.
The binary text form of an int, with a 0b prefix.
x — an int, or an object with __index__.bin(10) # '0b1010'
bin(10)[2:] # '1010' drop the prefix
format(10, '08b') # '00001010' padded, no prefix
bin(-5) # '-0b101' sign, not two's complement
bin(x).count('1') # popcount. Or x.bit_count() in 3.10+
The hexadecimal text form of an int, with a 0x prefix.
x — an int, or an object with __index__.hex(255) # '0xff'
hex(255)[2:] # 'ff'
format(255, '04X') # '00FF' padded and upper case
int(hex(255), 16) # 255 round trip
bytes([255, 0]).hex() # 'ff00' for byte strings
The octal text form of an int, with a 0o prefix.
x — an int, or an object with __index__.oct(8) # '0o10'
oct(0o755) # '0o755'
os.chmod(path, 0o644) # the one place you still meet octal
int('755', 8) # 493
Eight functions. Make text, show text, and move between a character and its code point.
Text. The friendly form of a value, meant for humans.
object — anything. Calls its __str__, and falls back to __repr__.encoding — only for bytes input. Usually 'utf-8'.errors — what to do with bad bytes: 'strict', 'ignore', 'replace'.str(42) # '42'
str([1, 2]) # '[1, 2]'
str(b'hi', 'utf-8') # 'hi' same as b'hi'.decode()
str(b'\xff', 'utf-8', 'replace') # a placeholder char, no crash
f'{value}' # calls str() under the hood
The unambiguous form of a value, meant for developers. Should look like valid Python.
obj — anything. Calls its __repr__.repr('a') # "'a'" quotes are visible
str('a') # 'a' quotes are not
repr('a\nb') # "'a\\nb'" escapes show up
print(f'{name!r}') # !r means "use repr here"
Use it when. Debugging whitespace or type confusion. repr shows the difference between 1 and '1'; str hides it.
Like repr, but escapes every non-ASCII character.
obj — anything.ascii('café') # "'caf\\xe9'"
repr('café') # "'café'"
ascii('日本') # "'\\u65e5\\u672c'"
Use it when. A log file or terminal cannot handle Unicode, or you need to see exactly which code points are in a string.
Apply one format spec to one value. The engine behind f-strings.
value — the thing to format.format_spec — the mini-language: [fill][align][sign][width][,][.precision][type].format(3.14159, '.2f') # '3.14'
format(1234567, ',') # '1,234,567'
format(0.256, '.1%') # '25.6%'
format('hi', '>10') # ' hi' right aligned
format(255, '#06x') # '0x00ff'
f'{3.14159:.2f}' # same thing, preferred in normal code
When to call it directly. When the spec itself is a variable: format(x, spec).
The character for a Unicode code point.
i — an int from 0 to 1114111 (0x10FFFF).chr(65) # 'A'
chr(97) # 'a'
chr(ord('a') + 1) # 'b' next letter
[chr(ord('a') + i) for i in range(26)] # the alphabet
The code point for one character. The inverse of chr.
c — a string of length exactly one.ord('A') # 65
ord('a') - ord('A') # 32 case gap
counts[ord(ch) - ord('a')] += 1 # 26-slot array instead of a dict
Trap. ord('ab') raises TypeError. One character only.
Write values to a stream, with separators.
*objects — any number of values. Each is passed through str.sep — text placed between the values. Default one space.end — text placed after the last value. Default a newline.file — any object with a write method. Default sys.stdout.flush — force the buffer out now. Needed for live progress output.print('a', 'b') # a b
print('a', 'b', sep='-') # a-b
print('loading', end='') # no newline
print(*my_list, sep='\n') # one item per line
print('error', file=sys.stderr) # to the error stream
print(f'{pct}%', end='\r', flush=True) # a live-updating line
Read one line from standard input. Always returns a string.
prompt — text shown before reading. Written without a newline.name = input('Name: ') # always a str
age = int(input('Age: ')) # convert yourself
n, m = map(int, input().split()) # two ints on one line
Trap. The trailing newline is stripped, but other whitespace is not. And input() raises EOFError at end of file, so guard it in scripts that read piped input.
Ten functions. Every core data structure, plus the two lazy ones.
An ordered sequence you can change.
iterable — any iterable. Omit it for an empty list.list() # []
list('abc') # ['a', 'b', 'c']
list(range(3)) # [0, 1, 2]
list({'a': 1}) # ['a'] dicts iterate over keys
list(zip(xs, ys)) # drain an iterator into memory
copy = list(original) # a shallow copy
Trap. list(gen) drains the generator. A second call gives [].
An ordered sequence you cannot change. Hashable if its items are.
iterable — any iterable.tuple([1, 2]) # (1, 2)
tuple('ab') # ('a', 'b')
(1,) # a 1-tuple. The comma makes it, not the brackets
seen.add(tuple(row)) # lists cannot go in a set. Tuples can
cache[(x, y)] = value # tuples make fine dict keys
A key to value map. Keeps insertion order since Python 3.7.
mapping — another dict to copy.pairs — an iterable of two-item pairs.**kwargs — keyword arguments become string keys.dict(a=1, b=2) # {'a': 1, 'b': 2}
dict([('a', 1), ('b', 2)]) # same
dict(zip(keys, values)) # the pairing idiom
dict.fromkeys('abc', 0) # {'a': 0, 'b': 0, 'c': 0}
{**base, **overrides} # merge, right side wins
Trap. Keys must be hashable, so no lists. And dict(a=1) cannot make a key with a space or a dash in it.
An unordered bag of unique, hashable items. O(1) membership tests.
iterable — any iterable. Duplicates are dropped.set([1, 1, 2]) # {1, 2}
set() # the empty set. {} is an empty DICT
set('hello') # {'h', 'e', 'l', 'o'}
a | b, a & b, a - b # union, intersection, difference
len(set(xs)) != len(xs) # "has duplicates" in one line
Why it matters. Swapping x in a_list for x in a_set is the single most common way to turn O(n²) into O(n).
A set you cannot change. Because it is immutable, it is hashable.
iterable — any iterable of hashable items.frozenset([1, 1, 2]) # frozenset({1, 2})
groups = {frozenset({'a','b'}): 1} # a set used as a dict key
seen.add(frozenset(members)) # dedupe unordered groups
Use it for. Anagram grouping, graph edge sets, and any cache key where order should not matter.
A fixed sequence of integers from 0 to 255. Raw binary data.
source — an int (that many zero bytes), an iterable of ints, or a string.encoding — required when source is a string.errors — how to handle characters that will not encode.bytes([65, 66]) # b'AB'
bytes(3) # b'\x00\x00\x00'
bytes('hi', 'utf-8') # b'hi' same as 'hi'.encode()
b'AB'[0] # 65 indexing gives an INT
b'AB'[0:1] # b'A' slicing gives bytes
Trap. Indexing a bytes object gives an int, not a one-byte string. Slice instead if you want bytes back.
The same as bytes, but you can change it in place.
source, encoding, errors — identical to bytes.buf = bytearray(b'hi')
buf[0] = 72 # bytearray(b'Hi')
buf.extend(b' there') # grows in place, no copy
buf += b'!'
bytes(buf) # freeze it back
Use it for. Building a binary message piece by piece. Repeated bytes + bytes is O(n²); a bytearray is amortised O(1).
A window onto another object's bytes. Slicing it copies nothing.
object — anything supporting the buffer protocol: bytes, bytearray, array.array, a NumPy array.mv = memoryview(b'abcdef')
mv[0] # 97
bytes(mv[1:3]) # b'bc' the slice itself was free
data = bytearray(1_000_000)
chunk = memoryview(data)[500:600] # no 1 MB copy
chunk[0] = 65 # writes straight into `data`
Use it for. Parsing large buffers without copying. data[500:600] on a bytearray copies; the memoryview version does not.
A lazy sequence of evenly spaced ints. Stores only three numbers.
start — first value. Defaults to 0.stop — one past the last value. Never included.step — the gap. May be negative. Must not be 0.range(3) # 0, 1, 2
range(2, 5) # 2, 3, 4
range(0, 10, 2) # 0, 2, 4, 6, 8
range(5, 0, -1) # 5, 4, 3, 2, 1
len(range(10**18)) # instant. Nothing is built
10**17 in range(10**18) # also instant. It does the maths
Not a generator. A range is re-iterable, supports len, indexing and slicing, and never runs out. It is a real sequence.
A reusable slice object. What a[1:5:2] builds behind the scenes.
start, stop, step — the same three numbers as slice syntax. None means "the default".FIRST_NAME = slice(0, 10) # name the columns once
record[FIRST_NAME] # readable at every use site
[1,2,3,4][slice(None, None, 2)] # [1, 3] same as [::2]
s.indices(len(seq)) # (start, stop, step) clamped to the length
Use it for. Fixed-width record parsing, and inside __getitem__ when you handle both ints and slices.
Thirteen functions. The largest group, and the one that shapes how Python code reads.
How many items. O(1) for every built-in type.
s — a sequence or collection with a __len__ method.len('hello') # 5
len({'a': 1}) # 1 pairs, not keys plus values
len(range(10**9)) # instant
len(x for x in xs) # TypeError. Generators have no length
Trap. No length on generators, files or map objects. Convert with list() first, or use sum(1 for _ in it).
Get an iterator. The second form calls a function until it returns a stop value.
object — anything with __iter__, or a sequence with __getitem__.callable — a zero-argument function, called once per step.sentinel — when callable() returns this value, iteration stops.it = iter([1, 2, 3])
next(it) # 1
for chunk in iter(lambda: f.read(4096), b''):
process(chunk) # read a file in blocks
for line in iter(input, 'quit'):
handle(line) # read until the user types quit
The pairing idiom. it = iter(xs); list(zip(it, it)) chunks a flat list into pairs.
Pull the next item. With a default, an exhausted iterator returns that instead of raising.
iterator — an iterator, not just any iterable. A plain list will not work.default — returned when the iterator is empty. Without it you get StopIteration.next(iter([7])) # 7
next(it, None) # safe: None when empty
first_even = next((x for x in xs if x % 2 == 0), None) # find-first, lazy
next(iter(a_set)) # peek at any one set item
Why the generator form is good. next(gen, None) stops at the first match. A list comprehension scans everything.
The async version of iter. Python 3.10+.
async_iterable — an object with __aiter__.async def consume(stream):
ait = aiter(stream) # what `async for` calls for you
async for item in stream: # the normal way to consume one
handle(item)
The async version of next. Returns an awaitable. Python 3.10+.
async_iterator — an object with __anext__.default — returned instead of raising StopAsyncIteration.async def peek(ait):
first = await anext(ait) # raises StopAsyncIteration when empty
safe = await anext(ait, None) # None instead of an error
return first, safe
Trap. You must await it. Forgetting gives you a coroutine object, not a value.
Pair each item with a running count. Lazy.
iterable — any iterable.start — the first index. Use 1 for human-facing numbering.list(enumerate('ab')) # [(0, 'a'), (1, 'b')]
list(enumerate('ab', 1)) # [(1, 'a'), (2, 'b')]
for i, ch in enumerate(s):
...
for i, (a, b) in enumerate(pairs): # nested unpacking works
...
Style. Never write for i in range(len(xs)). Use enumerate. Reviewers notice.
Walk several iterables together, yielding tuples. Lazy.
*iterables — two or more iterables. Zero gives an empty result.strict — Python 3.10+. Raise ValueError if the lengths differ.list(zip([1,2], 'ab')) # [(1,'a'), (2,'b')]
list(zip([1,2,3], 'ab')) # [(1,'a'), (2,'b')] silently short
list(zip(xs, ys, strict=True)) # raises on a length mismatch
dict(zip(keys, values)) # build a dict from two lists
list(zip(*matrix)) # transpose rows and columns
zip(xs, xs[1:]) # every neighbouring pair
Trap. Without strict=True, zip stops at the shortest input. That hides bugs. Use itertools.zip_longest when you want padding instead.
Apply a function to every item. Lazy: nothing runs until you consume it.
function — takes as many arguments as there are iterables.*iterables — one or more. With several, it stops at the shortest.list(map(str, [1, 2])) # ['1', '2']
n, m = map(int, input().split()) # parse a line of numbers
list(map(pow, [2,3], [3,2])) # [8, 9] two iterables
max(map(len, words)) # no temp list built
Style. map(f, xs) beats a comprehension only when f already exists. map(lambda x: x*2, xs) is slower and uglier than [x*2 for x in xs].
Keep items where the test is true. Lazy.
function — a one-argument test. Pass None to keep whatever is truthy.iterable — any iterable.list(filter(None, [0, 1, '', 2])) # [1, 2] drops falsy values
list(filter(str.isdigit, chars)) # only digits
list(filter(lambda x: x > 0, nums)) # prefer [x for x in nums if x > 0]
next(filter(pred, xs), None) # find first match, lazily
Worth knowing. filter(None, xs) is the compact way to strip empties. Everything else reads better as a comprehension.
A new sorted list. Timsort: O(n log n), stable, and O(n) on nearly sorted input.
iterable — any iterable. Always returns a list, whatever went in.key — a one-argument function called once per item. Sorts by its result.reverse — descending order. Keeps stability, unlike reversing afterwards.sorted([3, 1]) # [1, 3]
sorted(words, key=len) # by length
sorted(words, key=str.lower) # case insensitive
sorted(people, key=lambda p: (-p.age, p.name)) # age desc, then name asc
sorted(counts.items(), key=lambda kv: kv[1], reverse=True)
sorted(d, key=d.get) # keys, ordered by value
Stable means. Equal items keep their original order. So you can sort twice: least important key first, most important key last.
A lazy iterator walking a sequence backwards.
seq — a sequence with __len__ and __getitem__, or an object with __reversed__.list(reversed([1, 2])) # [2, 1]
for i in reversed(range(n)): # count down, no list built
...
''.join(reversed(s)) # same as s[::-1], but lazy
reversed(my_dict) # keys, newest first. Python 3.8+
Trap. Generators and set have no order, so reversed rejects them. xs[::-1] copies; reversed(xs) does not.
True when every item is truthy. Stops at the first false one.
iterable — any iterable. An empty one gives True.all([1, 2, 0]) # False
all([]) # True "no counter-example found"
all(x > 0 for x in nums) # short-circuits on the first failure
all(isinstance(x, int) for x in xs)
Trap. Pass a generator, not a list comprehension. all([f(x) for x in xs]) evaluates every item before checking any of them.
True when at least one item is truthy. Stops at the first true one.
iterable — any iterable. An empty one gives False.any([0, 0, 3]) # True
any([]) # False
any(word in text for word in banned) # exits early on a hit
if not any(errors): ship() # "none of them" reads as `not any`
Thirteen functions. Ask an object what it is and what it holds.
One argument reads a class. Three arguments create one.
object — the value whose class you want.name — the new class name, as a string.bases — a tuple of parent classes.dict — the class body: methods and attributes.type(1) # <class 'int'>
type(x).__name__ # 'int' just the name
type(x) is list # exact type, no subclasses
Point = type('Point', (), {'x': 0}) # a class made at runtime
Style. For a type check, use isinstance. Use type(x) is C only when a subclass must not pass.
Is this value of that type, or a subclass of it?
object — the value to test.classinfo — a class, a tuple of classes, or a | union in 3.10+.isinstance(1, int) # True
isinstance(True, int) # True. bool subclasses int
isinstance(x, (int, float)) # either one
isinstance(x, int | str) # 3.10+ syntax
isinstance(x, collections.abc.Iterable) # "does it behave like one"
Trap. isinstance(True, int) is True. If you must reject booleans, test type(x) is int.
Does one class inherit from another? Both arguments must be classes.
class — the candidate subclass.classinfo — a class, or a tuple of classes.issubclass(bool, int) # True
issubclass(int, int) # True. A class is its own subclass
issubclass(int, object) # True. Everything is
issubclass(1, int) # TypeError. 1 is not a class
Can you put brackets after it? True for functions, classes and objects with __call__.
object — anything.callable(len) # True
callable(int) # True. Classes are callable
callable(42) # False
callable(lambda: 1) # True
Note. True is not a guarantee. Calling it can still raise TypeError on the arguments.
Read an attribute whose name is a string.
object — the object to read from.name — the attribute name, as a string.default — returned when the attribute is missing. Without it you get AttributeError.getattr(obj, 'x') # same as obj.x
getattr(obj, 'x', 0) # 0 when missing
getattr(obj, field_name) # the whole point: a dynamic name
handler = getattr(self, f'do_{cmd}', self.unknown) # dispatch table
Use it for. Command dispatch and config-driven code. Avoid it when the name is a literal; obj.x is clearer and faster.
Write an attribute whose name is a string.
object — the target.name — the attribute name, as a string.value — what to store.setattr(obj, 'x', 5) # same as obj.x = 5
for k, v in config.items():
setattr(self, k, v) # bulk-assign from a dict
Trap. Fails on classes using __slots__ if the name is not declared there.
Remove an attribute whose name is a string.
object — the target.name — the attribute name, as a string.delattr(obj, 'cache') # same as del obj.cache
if hasattr(obj, 'tmp'):
delattr(obj, 'tmp') # guard first, or catch AttributeError
Does this attribute exist? Implemented as a getattr with the error caught.
object — the object to test.name — the attribute name, as a string.hasattr([], 'append') # True
hasattr(obj, 'read') # duck typing: "is it file-like"
Trap. If the attribute is a property that raises, hasattr reports False. Prefer getattr(obj, name, sentinel) when that matters.
A sorted list of the names an object exposes. No argument gives the current scope.
object — anything. Omit it to list names in the current local scope.dir() # names defined right here
dir(str) # every string method
[m for m in dir(x) if not m.startswith('_')] # the public surface
'append' in dir(obj)
Note. This is for humans exploring in a REPL. It can be customised by __dir__, so do not build logic on it.
The __dict__ of an object. No argument acts like locals().
object — a module, class or instance that has a __dict__.vars(obj) # {'x': 5}
vars() # same as locals()
json.dumps(vars(obj)) # quick serialise of a simple object
vars(obj)['x'] = 9 # writes through. It is the real dict
Trap. Raises TypeError on objects with __slots__, and on ints and strings.
A unique int for the object, for as long as it lives. In CPython, its memory address.
object — anything.id(x) == id(y) # same object. Prefer `x is y`
a = [1]; b = a
id(a) == id(b) # True. Two names, one list
Trap. Ids are reused after an object is freed. Never store one as a long-lived key.
An int fingerprint. Equal objects must hash equal. Used by dicts and sets.
object — must be hashable. Lists, dicts and sets are not.hash('a') # some int
hash(1) == hash(1.0) # True. Equal values hash equal
hash([1]) # TypeError: unhashable
Note. String hashes are randomised per process for security. Never persist one to disk. Use hashlib for a stable digest.
The root of every class. Calling it gives a bare instance with no attributes.
MISSING = object() # a unique sentinel value
def f(x=MISSING):
if x is MISSING: ... # distinguishes "not passed" from None
class C(object): ... # Python 2 habit. Just write class C:
The real use. A sentinel. Nothing else in the program can ever equal it, so None stays free to be a valid value.
Four functions. Three are used as decorators; the fourth reaches upward.
A method that receives the class, not the instance. Call it on the class or an instance.
function — the method. Its first parameter is cls by convention.class Point:
def __init__(self, x, y):
self.x, self.y = x, y
@classmethod
def from_string(cls, text): # an alternative constructor
x, y = map(int, text.split(','))
return cls(x, y) # cls, so subclasses work too
Point.from_string('1,2')
Main use. Factory methods. Using cls(...) instead of Point(...) means a subclass gets its own type back.
A plain function that lives inside a class. Gets neither self nor cls.
function — the method. No implicit first parameter.class Temp:
@staticmethod
def c_to_f(c): # no self needed
return c * 9 / 5 + 32
Temp.c_to_f(100) # 212
Temp().c_to_f(100) # works on an instance too
When to use. A helper that belongs with the class for readability but touches no state. Since 3.10 these are callable as plain functions too.
Make a method look like an attribute. Lets you add validation without changing callers.
fget — the getter, called on read.fset — the setter, called on assignment.fdel — called on del.doc — the docstring. Taken from fget if omitted.class Circle:
def __init__(self, r):
self._r = r
@property
def area(self): # read as circle.area, no brackets
return 3.14159 * self._r ** 2
@property
def r(self):
return self._r
@r.setter
def r(self, value): # validation on write
if value < 0:
raise ValueError('radius must be non-negative')
self._r = value
Related. functools.cached_property computes once and stores the result on the instance.
A proxy to the next class in the method resolution order. Usually the parent.
type — the class to start searching after.object_or_type — the instance or class supplying the MRO.class Base:
def greet(self): return 'hi'
class Child(Base):
def __init__(self, extra):
super().__init__() # run the parent's setup
self.extra = extra
def greet(self):
return super().greet() + '!' # extend, do not replace
Child.__mro__ # the exact search order
Trap. "Next in the MRO" is not always the direct parent. With multiple inheritance it can be a sibling class. That is the feature, not a bug.
Two functions. Useful for debugging and templating, risky for logic.
The module-level namespace, as a real dict. Writing to it creates a global.
globals()['__name__'] # '__main__'
globals()['dynamic'] = 5 # really does create a global
fn = globals()['handler_' + name] # look up a function by name
Better option. A plain dict of handlers is clearer than name lookups in globals(), and a linter can check it.
The local namespace as a dict. At module level it is the same as globals().
def f(a, b):
c = a + b
print(locals()) # {'a': 1, 'b': 2, 'c': 3}
'Hello {name}'.format(**locals()) # quick templating
Trap. Inside a function this is a snapshot copy. Assigning into it does not change the variable. Python 3.13 makes that explicit.
Four functions. Powerful, and the usual source of remote code execution bugs.
eval, exec or compile. There is no safe sandbox; passing empty globals does not help. For data, use json.loads. For a literal Python value, use ast.literal_eval, which handles only strings, numbers, tuples, lists, dicts, sets and booleans.Run one expression and return its value. Statements are not allowed.
expression — a string, or a code object from compile.globals — a dict of global names. Defaults to the caller's.locals — a mapping of local names. Defaults to the caller's.eval('2 + 3') # 5
eval('x * 2', {'x': 4}) # 8
eval('x = 1') # SyntaxError. That is a statement
ast.literal_eval('[1, 2]') # the safe choice for data
Run a block of statements. Always returns None.
object — a string, or a code object.globals, locals — the namespaces to run in. Results land here.ns = {}
exec('def double(x): return x * 2', ns)
ns['double'](5) # 10
Legitimate use. Code generation inside libraries. dataclasses and namedtuple both build methods with exec.
Turn source text into a code object you can run more than once.
source — a string, bytes, or an AST object.filename — the name shown in tracebacks. Use '<string>' if there is no file.mode — 'exec' for a module, 'eval' for one expression, 'single' for one interactive statement.flags / dont_inherit — control __future__ features and AST-only output.optimize — -1 uses the interpreter setting, 0 keeps asserts, 1 strips them, 2 also strips docstrings.code = compile('x + 1', '<expr>', 'eval')
eval(code, {'x': 1}) # 2. Reuse the code, skip re-parsing
tree = compile(src, 'f.py', 'exec', ast.PyCF_ONLY_AST) # get the AST
Use it for. Static analysis via the AST, or a template engine that compiles once and runs many times.
The low-level hook behind the import statement.
name — the module name, as a string.globals — used to work out the package for relative imports.locals — ignored in practice.fromlist — names to import from inside. Changes what gets returned.level — 0 for absolute, higher numbers for relative imports.__import__('math').pi # 3.14159...
__import__('os.path') # returns `os`, not `os.path`
__import__('os.path', fromlist=['path']) # returns os.path
importlib.import_module('os.path') # do this instead
Do not use it. The return value rule is confusing. importlib.import_module does the same job correctly.
One function, and it carries eight parameters.
Open a file and return a file object.
file — a path string, a Path, or an open file descriptor int.mode — 'r' read, 'w' truncate and write, 'a' append, 'x' create-or-fail. Add 'b' for binary and '+' for read and write.buffering — -1 for the default, 0 for unbuffered binary, 1 for line buffered text, or a byte size.encoding — text mode only. Always pass 'utf-8'. The default is platform dependent.errors — 'strict', 'ignore', 'replace', 'surrogateescape'.newline — None translates line endings, '' leaves them alone. Use '' for the csv module.closefd — keep the descriptor open after closing. Only valid with an int file.opener — a custom function returning a file descriptor.with open('f.txt', encoding='utf-8') as f:
for line in f: # lazy. Never f.read() a big file
process(line)
with open('out.txt', 'w', encoding='utf-8') as f:
f.write('hi')
with open('img.png', 'rb') as f: # binary: no encoding allowed
data = f.read()
with open('log.txt', 'a', encoding='utf-8') as f: # append, keeps content
f.write('line\n')
Always use with. It closes the file even when an exception fires. And 'w' wipes an existing file the moment it opens, before you write a byte.
Two functions. Both are for you, not for production code.
Print the docs for an object. No argument starts an interactive help session.
request — an object, or a string naming a module or topic.help(len) # the signature and docstring
help(str.split) # one method
help('modules') # every installed module
help(my_function) # your own docstring shows here
Related. obj.__doc__ gets the raw docstring string, without the formatting.
Drop into the debugger at this line. Python 3.7+.
*args, **kws — passed through to whatever hook is configured.def f(x):
breakpoint() # pdb opens here
return x * 2
Two things worth knowing. Set PYTHONBREAKPOINT=0 to disable every breakpoint without editing code. Set PYTHONBREAKPOINT=ipdb.set_trace to swap in a nicer debugger.
| Pair | The difference |
|---|---|
| str vs repr | str is for users, repr is for developers. repr shows the quotes. |
| sorted vs .sort() | sorted returns a new list from any iterable. .sort() changes a list in place and returns None. |
| reversed vs [::-1] | reversed is a lazy iterator. The slice builds a full copy. |
| type vs isinstance | type(x) is C rejects subclasses. isinstance accepts them. Use isinstance. |
| == vs is | == compares values. is compares identity, the same thing id() reports. |
| int() vs round() | int truncates toward zero. round goes to the nearest, ties to even. |
| iter vs next | iter makes the walker. next takes one step with it. |
| list vs tuple | Lists change and are unhashable. Tuples are fixed and can be dict keys. |
| set() vs {} | {} is an empty dict. The empty set only has one spelling: set(). |
| vars vs dir | vars gives the instance data. dir gives every name, methods included. |
These feel like built-ins but need an import, or left the language entirely.
| Name | Where it lives now |
|---|---|
| reduce | functools.reduce. Moved out in Python 3 on purpose. |
| sqrt, floor, ceil, gcd, log | math. Only abs, pow, round, divmod are built in. |
| accumulate, chain, product, combinations | itertools. |
| Counter, defaultdict, deque, namedtuple | collections. |
| partial, lru_cache, cache | functools. |
| reload | importlib.reload. |
| raw_input, xrange, unicode, long, cmp, execfile, apply | Gone in Python 3. Use input, range, str, int. |
builtins module also holds True, False, None, NotImplemented, Ellipsis (...), __debug__, and every exception class from Exception down. Run len(dir(__builtins__)) to see the whole set for your version.sum, max, any over a hand-written loop.key= on sorted, max and min removes most custom comparison code.zip stops at the shortest input unless you pass strict=True.eval, exec or compile.encoding='utf-8' to open, and always use with.