1   Why Do We Need Dictionaries?

Suppose you are writing a program to track data about a spaceship. Using a list, you might write:

ship = ["Persephone", 12, 87.5, "operational"]

This works — but it is fragile. To get the fuel level, you have to remember that it is at index 2. Reorder the list and every piece of code that reads it breaks. Add a new field in the middle and all subsequent indices shift.

A dictionary solves this by giving each value a name:

ship = {
    "name":   "Persephone",
    "crew":   12,
    "fuel":   87.5,
    "status": "operational"
}

Now ship["fuel"] always means fuel level — no matter what order the fields are in, no matter how many new fields you add.

2   Creating a Dictionary

A dictionary is written with curly braces { }. Each entry is a key–value pair written as key: value, with pairs separated by commas.

ship = {
    "name":        "Persephone",
    "class":       "Firefly-class transport",
    "crew":        12,
    "fuel":        87.5,
    "operational": True
}

2.1   The Vocabulary of Dictionaries

2.2   Keys Must Be Unique

A dictionary cannot have two entries with the same key. If you define the same key twice, the second value silently overwrites the first — no error is raised:

ship = {
    "fuel": 87.5,
    "fuel": 42.0     # overwrites the first entry
}
print(ship["fuel"])  # 42.0

3   Accessing Values

3.1   Square Bracket Notation

Access a value by putting its key in square brackets, just like a list index — except you use a key name instead of a number:

ship = {
    "name":  "Persephone",
    "crew":  12,
    "fuel":  87.5
}

print(ship["name"])    # Persephone
print(ship["crew"])    # 12
print(ship["fuel"])    # 87.5

3.2   The Safe Way: .get()

.get(key) returns the value for a key if it exists, or None if it does not — without raising an error. You can also provide a custom default value as a second argument:

ship = {"name": "Persephone", "crew": 12, "fuel": 87.5}

print(ship.get("crew"))              # 12  — key exists
print(ship.get("weapons"))           # None — key missing, no error
print(ship.get("weapons", "none"))   # none — custom default

4   Adding and Modifying Entries

Dictionaries are mutable — you can add new key–value pairs and change existing values after creation. The syntax for both is the same: assignment using square brackets.

4.1   Modifying an Existing Value

ship = {"name": "Persephone", "fuel": 87.5, "crew": 12}

ship["fuel"] = 62.0          # fuel has dropped after a jump
ship["crew"] = 11            # one crew member disembarked
print(ship)
# {'name': 'Persephone', 'fuel': 62.0, 'crew': 11}

4.2   Adding a New Key–Value Pair

If the key does not already exist, assignment creates it:

ship["shields"] = 95
ship["location"] = "Sector 7-G"
print(ship)
# {'name': 'Persephone', 'fuel': 62.0, 'crew': 11, 'shields': 95, 'location': 'Sector 7-G'}

4.3   Updating Multiple Values: .update()

.update() merges another dictionary into the current one. Existing keys are updated; new keys are added:

ship = {"name": "Persephone", "fuel": 62.0, "crew": 11}

ship.update({"fuel": 100.0, "shields": 95, "location": "Starbase Omega"})
print(ship)
# {'name': 'Persephone', 'fuel': 100.0, 'crew': 11, 'shields': 95, 'location': 'Starbase Omega'}

5   Removing Entries

ship = {
    "name":     "Persephone",
    "fuel":     100.0,
    "shields":  95,
    "location": "Starbase Omega"
}

del ship["location"]                         # no longer tracking location
print(ship)

old_shields = ship.pop("shields")            # remove and capture the old value
print("Removed shields rating:", old_shields)

removed = ship.pop("weapons", "not fitted")  # safe remove — key may not exist
print("Weapons:", removed)

6   Testing for Membership

The in operator checks whether a key exists in a dictionary — the same operator you used for strings and lists in earlier articles. It always tests keys, never values.

ship = {"name": "Persephone", "fuel": 87.5, "crew": 12}

print("fuel" in ship)        # True  — the key "fuel" exists
print("weapons" in ship)     # False — no such key
print("not" in ship)         # False
print("fuel" not in ship)    # False

This is the correct way to guard against a KeyError before accessing a key you are not sure about:

if "shields" in ship:
    print("Shield strength:", ship["shields"])
else:
    print("No shield data available.")

7   Iterating Through a Dictionary

Python gives you three views of a dictionary for iteration. Each is a live view of the dictionary's contents — not a copy — and each lets you loop over a different aspect of the data.

7.1   Iterating Over Keys

ship = {
    "name":    "Persephone",
    "class":   "Firefly",
    "crew":    12,
    "fuel":    87.5,
    "shields": 95
}

for key in ship.keys():
    print(key)

Output:

name
class
crew
fuel
shields

7.2   Iterating Over Values

for value in ship.values():
    print(value)

Output:

Persephone
Firefly
12
87.5
95

7.3   Iterating Over Key–Value Pairs

This is the most useful form. .items() gives you both the key and the value together, which you unpack into two variables:

for key, value in ship.items():
    print(f"  {key:<10} : {value}")

Output:

  name       : Persephone
  class      : Firefly
  crew       : 12
  fuel       : 87.5
  shields    : 95

7.4   Practical Iteration — Building a Status Report

fleet = [
    {"name": "Persephone", "crew": 12, "fuel": 87.5, "shields": 95},
    {"name": "Icarus IV",  "crew": 8,  "fuel": 43.0, "shields": 60},
    {"name": "Calypso",    "crew": 20, "fuel": 91.0, "shields": 88},
]

print("=== Fleet Status ===")
for ship in fleet:
    status = "⚠ LOW FUEL" if ship["fuel"] < 50 else "OK"
    print(f"  {ship['name']:<15} crew: {ship['crew']:<4} "
          f"fuel: {ship['fuel']:<6} shields: {ship['shields']}  {status}")

Output:

=== Fleet Status ===
  Persephone      crew: 12   fuel: 87.5  shields: 95  OK
  Icarus IV       crew: 8    fuel: 43.0  shields: 60  ⚠ LOW FUEL
  Calypso         crew: 20   fuel: 91.0  shields: 88  OK

8   Other Useful Dictionary Methods

8.1   Copying a Dictionary

Just like lists, assigning a dictionary to a new variable does not create a copy — both variables point to the same object:

original = {"name": "Persephone", "fuel": 87.5}
alias = original                # NOT a copy

alias["fuel"] = 0.0
print(original["fuel"])         # 0.0 — the original was changed too!

Use .copy() to get a true independent copy:

original = {"name": "Persephone", "fuel": 87.5}
backup = original.copy()

backup["fuel"] = 0.0
print(original["fuel"])         # 87.5 — untouched

9   Richer Data: Dictionaries Containing Lists

Values in a dictionary can be any type — including lists. This is how you naturally represent an object with multiple items in one of its fields:

ship = {
    "name":      "Persephone",
    "crew":      12,
    "fuel":      87.5,
    "cargo":     ["food supplies", "medical kits", "engine parts"],
    "visited":   ["Proxima Station", "New Shanghai", "Titan Outpost"],
}

# Access the whole list
print(ship["cargo"])
# ['food supplies', 'medical kits', 'engine parts']

# Access one item from the list
print(ship["cargo"][0])
# food supplies

# Add to the list
ship["cargo"].append("spare hull plating")
print(len(ship["cargo"]))       # 4

# Check for an item in the list
if "medical kits" in ship["cargo"]:
    print("Medical supplies confirmed aboard.")

The notation ship["cargo"][0] reads left to right: first retrieve the value stored under "cargo" (which is a list), then access index 0 of that list.

10   Putting It All Together: The Fleet Management System

Here is a complete program that uses almost everything from this article. The data is a fleet of ships stored as a list of dictionaries. Read it carefully and trace a few of the function calls before running it.

FUEL_WARNING = 50.0         # global constant — low fuel threshold
SHIELD_WARNING = 70         # global constant — low shield threshold

# ── Fleet data ────────────────────────────────────────────────────
fleet = [
    {
        "name":    "Persephone",
        "class":   "Firefly",
        "crew":    12,
        "fuel":    87.5,
        "shields": 95,
        "cargo":   ["food supplies", "medical kits", "engine parts"],
    },
    {
        "name":    "Icarus IV",
        "class":   "Dreadnought",
        "crew":    8,
        "fuel":    43.0,
        "shields": 60,
        "cargo":   ["weapons cache", "fuel cells"],
    },
    {
        "name":    "Calypso",
        "class":   "Science Vessel",
        "crew":    20,
        "fuel":    91.0,
        "shields": 88,
        "cargo":   ["research equipment", "specimens", "data drives"],
    },
]


# ── Functions ─────────────────────────────────────────────────────

def get_warnings(ship):
    """Returns a list of warning strings for a given ship dict."""
    warnings = []
    if ship["fuel"] < FUEL_WARNING:
        warnings.append(f"LOW FUEL ({ship['fuel']}%)")
    if ship["shields"] < SHIELD_WARNING:
        warnings.append(f"LOW SHIELDS ({ship['shields']}%)")
    return warnings


def print_ship_summary(ship):
    """Prints a one-line summary for a ship."""
    warnings = get_warnings(ship)
    flag = "  ⚠ " + ", ".join(warnings) if warnings else ""
    print(f"  {ship['name']:<16} [{ship['class']}]  "
          f"crew: {ship['crew']:<4} "
          f"fuel: {ship['fuel']:<6} "
          f"shields: {ship['shields']}{flag}")


def find_ship(fleet, name):
    """Returns the ship dict with the given name, or None if not found."""
    for ship in fleet:
        if ship["name"].lower() == name.lower():
            return ship
    return None


def refuel(ship, amount):
    """Adds fuel to a ship, capped at 100.0. Returns the amount actually added."""
    space = 100.0 - ship["fuel"]
    added = min(amount, space)
    ship["fuel"] = round(ship["fuel"] + added, 1)
    return added


def fleet_cargo_contains(fleet, item):
    """Returns a list of ship names whose cargo contains the given item."""
    carrying = []
    for ship in fleet:
        if item in ship["cargo"]:
            carrying.append(ship["name"])
    return carrying


# ── Main program ──────────────────────────────────────────────────

print("╔══════════════════════════════╗")
print("║   STARFLEET OPERATIONS HQ   ║")
print("╚══════════════════════════════╝\n")

# Fleet overview
print("── Fleet Status ─────────────────────────────")
for ship in fleet:
    print_ship_summary(ship)

# Find and refuel a specific ship
print("\n── Refuelling Operation ─────────────────────")
target = find_ship(fleet, "Icarus IV")
if target:
    added = refuel(target, 70.0)
    print(f"  Transferred {added}% fuel to {target['name']}.")
    print(f"  New fuel level: {target['fuel']}%")

# Check cargo across the fleet
print("\n── Cargo Search ─────────────────────────────")
search_item = "medical kits"
ships_with_item = fleet_cargo_contains(fleet, search_item)
if ships_with_item:
    print(f"  '{search_item}' found aboard: {', '.join(ships_with_item)}")
else:
    print(f"  '{search_item}' not found in any ship's cargo.")

# Print all fields of one ship using .items()
print("\n── Detailed Report: Calypso ─────────────────")
calypso = find_ship(fleet, "Calypso")
for key, value in calypso.items():
    print(f"  {key:<10} : {value}")

Things to notice:

• get_warnings() iterates over nothing — it just accesses specific keys directly, using in and comparisons.
• find_ship() loops over the fleet list, checking ship["name"] for each dictionary.
• fleet_cargo_contains() checks item in ship["cargo"] — the in operator working on a list that is itself a dictionary value.
• The final loop uses .items() to print every key–value pair of one ship's dictionary — a useful debugging technique.

11   Final Check: The Big Picture

12   Quick-Reference Summary