Key-Value Pairs in Python: Absolute Beginners Tutorial

Key-value pairs are the building blocks of Python dictionaries. Understanding them means you can store, look up, and update structured data without reaching for a database or a complicated data structure — just a plain Python dict.

Python's dict type is one of the language's most-used data structures. Under the hood it is a hash map, which means lookups are extremely fast regardless of how many entries the dictionary holds. Before you work with APIs, configuration files, JSON data, or database query results, you will encounter dictionaries — so grasping key-value pairs early pays dividends across every area of Python.

What Is a Key-Value Pair?

A key-value pair is exactly what it sounds like: a label (the key) paired with a piece of data (the value). Think of a physical address book where each name (key) maps to a phone number (value). You look up the name and get the number — you never need to scan every entry to find what you want.

In Python, the dictionary type is the native container for key-value pairs. A dictionary can hold any number of pairs, the values can be any Python object, and the keys must be immutable — meaning they cannot be changed after they are created.

The simplest way to picture the relationship is as a two-column table. The left column holds keys; the right column holds values. Every key is unique within a single dictionary. If you store two entries under the same key, Python keeps only the second one — no error, no warning.

Creating a Dictionary

Python gives you two ways to create a dictionary. The first is a dictionary literal using curly braces. The second is the built-in dict() constructor. Both produce identical objects at runtime.

# Method 1 — dictionary literal
user = {
    "name": "Alice",
    "age": 30,
    "active": True
}

# Method 2 — dict() constructor
user = dict(name="Alice", age=30, active=True)

# Empty dictionary — add pairs later
config = {}
print(type(config))  # <class 'dict'>

Notice that the values in the example above are three different types: a string, an integer, and a boolean. Python imposes no restriction on what types values can be. You can even store a list, another dictionary, or a function as a value.

Accessing values

You retrieve a value by placing its key inside square brackets. If the key does not exist, Python raises a KeyError. To avoid that, use the .get() method, which returns None by default or a value of your choosing.

user = {"name": "Alice", "age": 30}

# Square bracket access — raises KeyError if missing
print(user["name"])    # Alice

# .get() — returns None silently if key is missing
print(user.get("email"))          # None

# .get() with a default fallback value
print(user.get("email", "N/A"))   # N/A

In production code, .get() is usually safer than square bracket access whenever you cannot guarantee a key will be present — for example, when processing API responses or user-supplied data.

Reading, Adding, and Removing Pairs

Once a dictionary exists, you will typically need to read its contents in bulk, add new pairs, update existing ones, or remove entries that are no longer needed. Python provides concise syntax and a set of built-in methods for each of these tasks.

Adding and updating pairs

Both operations use the same assignment syntax. Python checks whether the key already exists: if it does, the value is overwritten; if it does not, a new pair is created.

settings = {"theme": "dark", "font_size": 14}

# Add a new key-value pair
settings["language"] = "en"

# Update an existing value
settings["font_size"] = 16

print(settings)
# {'theme': 'dark', 'font_size': 16, 'language': 'en'}

Removing pairs

Two methods are available: del removes a pair and discards the value. .pop() removes a pair and returns the value, which is convenient when you need to process the data before deletion.

cart = {"apple": 3, "banana": 5, "cherry": 2}

# del — remove and discard
del cart["banana"]

# .pop() — remove and return the value
qty = cart.pop("cherry")
print(qty)     # 2
print(cart)    # {'apple': 3}

Iterating over a dictionary

The three dictionary iteration methods are .keys(), .values(), and .items(). The last one is the most common because it gives you both sides of each pair at once through tuple unpacking.

scores = {"Alice": 92, "Bob": 85, "Carol": 78}

# Iterate over keys only
for name in scores.keys():
    print(name)

# Iterate over values only
for score in scores.values():
    print(score)

# Iterate over key-value pairs together
for name, score in scores.items():
    print(f"{name} scored {score}")

"Dictionaries are Python's most versatile built-in data structure." — Python Documentation

Python Learning Summary Points

1. A key-value pair links a unique, immutable key to a value of any type inside a Python dict. Keys must be hashable; values have no restrictions.
2. Use square bracket access (d["key"]) when you know a key exists, and d.get("key", default) when the key might be absent to avoid KeyError exceptions.
3. Adding, updating, and merging dictionaries all use simple assignment or the .update() method. Removing pairs uses del or .pop(), the latter returning the removed value.
4. Iterating with .items() unpacks each pair into two variables, giving you clean, readable loops. Since Python 3.7, dictionaries guarantee insertion order, so iteration is predictable.
5. Never modify a dictionary's size while looping over it. Iterate over a copy of the keys if you need to remove items during a loop.

Key-value pairs appear everywhere in Python — in JSON parsing, HTTP headers, environment variables, function keyword arguments, and database query results. The dict syntax you have practiced here applies directly to all of those contexts with no additional learning overhead.