Quick answer: A Python lookup table is usually a dictionary that maps a stable key to a value or callable. It replaces repetitive branching with data, but production code still needs key validation, a deliberate missing-key policy, and tests for duplicate or unexpected inputs.
A Python lookup table maps known keys to known results. In most Python programs, a dictionary is the right structure for that job because it gives direct key-based access, readable syntax, and simple fallback handling.
Lookup tables are useful when code has a fixed set of choices: plan names to prices, status codes to labels, file extensions to parsers, or command names to functions. They often replace long if/elif chains with a single mapping.
The official Python documentation covers dictionary mapping behavior.
Use a lookup table when the mapping is data, not control flow. If each branch only returns a value or calls a known handler, a dictionary usually reads better. If each branch has complex steps, a normal function or class may be clearer. The dictionary lookup pattern scales into a structured ZIP-code lookup workflow in uszipcode Python ZIP Code Lookup Guide.
A good lookup table is small enough to scan and explicit enough to review. Keep keys consistent, keep values in one format, and give the table a name that describes the decision being made. That makes future edits safer because new entries follow the existing pattern.
Lookup tables are also easy to test. A test can check that required keys exist, that all values have the expected type, and that unknown input follows the intended fallback path. Those checks are simpler than testing many separate conditional branches.
Basic Dictionary Lookup
The simplest lookup table is a dictionary with fixed keys and values.
prices = {
"free": 0,
"starter": 12,
"pro": 29,
}
plan = "pro"
print(prices[plan])
Square brackets are best when a missing key should be treated as an error.
This makes mistakes visible. If the code asks for a plan that does not exist, Python raises KeyError, which is often better than silently returning the wrong price.
Use bracket lookup for required configuration, permission names, and other cases where accepting an unknown key would create bad output. The error points directly to the missing key.
Use dict.get For A Fallback
Use dict.get() when a missing key has a safe default.
labels = {
200: "OK",
404: "Not Found",
500: "Server Error",
}
status = 403
message = labels.get(status, "Unknown status")
print(message)
The second argument to get() is returned when the key is not present.
Fallbacks should be intentional. A generic default is helpful for display text, but it may hide bad input in billing, permissions, or data migration code. Use bracket lookup when a missing key should stop the program early.
Replace Repeated Conditions
A dictionary can replace repeated equality checks when each option maps to a simple result.
extensions = {
".csv": "comma-separated values",
".json": "JSON document",
".txt": "plain text",
}
suffix = ".json"
kind = extensions.get(suffix, "unsupported file")
print(kind)
This is easier to scan than several elif branches that only return labels.
It is also easier to update. Adding a new file suffix means adding one dictionary entry, not changing the structure of the control flow.
This style works best when every branch has the same shape. If one option needs validation, another writes files, and another calls a service, split that work into named functions and use a dispatch table instead.
Use A Dispatch Table For Functions
A lookup table can map command names to functions. This is often called a dispatch table.
def start():
return "starting"
def stop():
return "stopping"
commands = {
"start": start,
"stop": stop,
}
action = "start"
handler = commands.get(action)
if handler:
print(handler())
else:
print("unknown command")
The dictionary stores function objects, and the selected handler is called after lookup.
Keep dispatch functions small and consistent. If some handlers need different arguments or side effects, consider wrapping them so the call shape stays the same.
Use Nested Dictionaries
Nested dictionaries work well when a lookup depends on two keys.
shipping = {
"US": {"standard": 5, "express": 15},
"CA": {"standard": 7, "express": 18},
}
country = "US"
speed = "express"
cost = shipping[country][speed]
print(cost)
This keeps related choices grouped together.
Nested lookup tables are readable for two levels. If the table becomes deeper than that, consider a tuple key such as ("US", "express") or move the data into a small configuration file.
Create A Reverse Lookup
If values are unique, build a second dictionary that maps values back to keys.
country_codes = {
"United States": "US",
"Canada": "CA",
"India": "IN",
}
code_to_country = {code: country for country, code in country_codes.items()}
print(code_to_country["IN"])
A reverse lookup is only safe when each value appears once.
If two countries shared the same code in this example, the later item would overwrite the earlier item in the reversed dictionary. For non-unique values, map each value to a list or set of keys instead.
When a lookup table grows large, consider loading it from JSON, TOML, YAML, a database, or another configuration source. The Python access pattern can stay the same after the data is loaded into a dictionary.
In practice, choose bracket lookup when missing keys are errors, get() when a fallback is valid, dispatch tables when names map to functions, and nested dictionaries when multiple keys select one result. That gives you clear lookup behavior without long conditional chains.
Use A Dictionary For Direct Mapping
A dictionary makes the relationship between key and result visible and gives average constant-time lookup for normal hash-table usage. Keep keys and values simple where possible, and use a function value when a mapping must select behavior rather than static data.
Choose Missing-Key Semantics
Use table[key] when absence is a programming error that should be visible, get(key, default) when a fallback is valid, or an explicit membership check when the caller must distinguish a missing key from a stored None. Do not let a convenient default hide malformed input.
Use defaultdict For Collection Building
defaultdict(list) or defaultdict(set) is useful when every missing key should create a new collection. It can also create entries during a read, so use get() or membership checks when observing the table must not mutate it.
Keep Keys Stable And Hashable
Strings, numbers, tuples of hashable values, and Enum members make predictable keys. Lists and dictionaries are mutable and unhashable. Convert external input into a normalized immutable key before lookup, and validate its type at the boundary.
Test The Table As Data
Test every supported key, the missing-key path, default values, malformed external keys, and callable values if used. Check that adding a new mapping does not shadow an existing key and that the table’s output contract remains stable.
Python’s dict documentation covers mapping operations and key behavior. The defaultdict reference explains automatic defaults. Related guidance includes callable values and mapping tests.
For related mapping design, compare dictionary operations, ordered mappings, and mapping tests when deciding how a lookup table should behave.
Frequently Asked Questions
What is a lookup table in Python?
It is usually a dictionary that maps a key to a value so code can retrieve a result directly instead of using a long chain of conditions.
How do I avoid a KeyError in a lookup table?
Use get() when a default is valid, check membership when absence matters, or handle KeyError at the boundary where the missing key is meaningful.
When should I use defaultdict?
Use defaultdict when every missing key should create the same kind of default value, such as a new list for grouping.
Can lookup-table keys be lists?
No. Dictionary keys must be hashable; use an immutable tuple or another stable representation when a compound key is needed.
