Understanding Lists, Tuples, and Dictionaries
Compound data structures nest collections inside one another, such as lists of tuples or dictionaries with tuple keys and list values.
When Structure Is the Problem
A program can have the right information but still fail because that information is organized in the wrong way. A collection might be nested inside another collection, or a value might appear at a different level than the program expects. These structures are called compound data structures because they nest collections within one another.
For example, a list can contain tuples, and a dictionary can have tuple keys and list values. In each case, the outer structure and the inner structures must be considered together. The useful question is not only “What data is present?” but also “What is the shape of that data?”
Reading a Data Shape
The shape of a compound data structure describes several properties at once. First is the type of each container, such as a list, tuple, or dictionary. Second is the size, meaning how much of that structure is present. Third is the composition, meaning the types and arrangement of the elements inside it. Nesting depth also matters because a value can be directly inside a collection or inside a collection within that collection.
| Shape question | What to inspect | Why it matters |
|---|---|---|
| Type | Is the container a list, tuple, or dictionary? | The actual container type may differ from what the code expects. |
| Size | How many elements or entries are present? | The structure may have the wrong number of elements. |
| Composition | What types and arrangements make up the contents? | Elements may not have the consistent structure the code assumes. |
| Nesting depth | How many collection levels must be passed through? | A value may be at a different level from the one the code expects. |
The four shape questions used to inspect nested data
A shape description should be precise enough to answer four questions: What is the container type? How large is it? What kinds of elements does it contain? How deeply are those elements nested?
Tracing a Shape Mismatch
A List with Inconsistent Elements
A program expects a collection whose elements all have the same nested structure. The actual collection contains elements with different structures. How should the mismatch be located?
Describe the expectation: Write down the expected outer container, the expected element type, the expected size if relevant, and the expected nesting depth.
Inspect the outer container: Determine whether the actual outer structure is the expected type and whether it has the expected size.
Inspect elements one level down: Check whether the elements have the expected type and composition. Do not assume that every element has the same structure.
Locate the first difference: The shape error may be in one element rather than in the outer collection. Identify the level where the actual type, size, or composition differs.
Compare before changing the program: Decide whether the data is wrong or whether the program's expectation is wrong. The mismatch itself is the debugging target.
The error is understood by comparing the expected shape with the actual shape at each nesting level, rather than treating the entire compound structure as one undifferentiated value.
In this example, the outer type is not the problem: both expected and actual structures begin with a list. The mismatch appears in the composition of the elements. The expected elements are tuples, but one actual element is a dictionary. This is a shape error even though the outer container is correct.
Comparing Container Shapes
Lists, tuples, and dictionaries are all named as possible container types in the source material. For shape debugging, the most important comparison is not a memorized list of operations. It is the role each type plays in the structure you are inspecting: an outer container, an element inside another container, a dictionary key, or a dictionary value.
| Container type | Shape-focused role | Inspection question |
|---|---|---|
| List | Can be an outer collection or a nested value | Is the list at the level where the program expects it? |
| Tuple | Can be an element in a list or a key in a dictionary | Is this tuple being used in the expected position and composition? |
| Dictionary | Can contain tuple keys and list values | Are the key and value structures the ones the program expects? |
Debugging at Each Level
Debugging a shape error works best as a level-by-level inspection. Start with the complete value, then inspect the outer container, then inspect the elements or entries inside it, and continue into nested collections until the actual structure differs from the expected one.
- State the expected shape before inspecting the data. Include the expected container type, size, composition, and nesting depth.
- Print the data so that you can inspect the actual value instead of relying on an assumption about what a function returned.
- Check types with type() at the outer level and at important nested levels.
- Inspect intermediate values when the structure has more than one level.
- Compare the actual type, size, and composition with the expected shape.
- Correct the data or the program's expectation only after locating the mismatch.
Mistakes Beginners Make
Forgetting what a function returns
The actual result may have a different type, size, or composition from the assumption.
Fix:
Print the returned data and use type() to inspect it before processing nested elements.Assuming that every element has the same structure
The outer collection can look correct while its composition is inconsistent.
Fix:
Inspect elements individually when the data may not be uniform.Confusing nesting levels
The expected nesting depth does not match the actual nesting depth.
Fix:
Trace the structure one level at a time and inspect intermediate values.Using a mutable type where an immutable type is required
The selected type may not satisfy the structural requirement of the place where it is used.
Fix:
Check whether the required position accepts the chosen type, and distinguish the type used from the types nested inside it.
A structure can be correct at one level and incorrect at another. For example, the outer value may be a list as expected, while one nested element has the wrong type. Checking only the outer container would miss that shape error.
Practice the Shape Audit
A program expects a dictionary with tuple keys and list values. Before using the data, describe the checks you would perform to verify that the actual structure matches the expectation.
Hints
- Begin with the outer container type.
- Inspect the types and composition of keys and values separately.
- Check whether the values are lists and whether their sizes or inner composition match what the program expects.
- Use printed data and type() checks at more than one level.
Auditing a Dictionary Shape
The expected structure is a dictionary with tuple keys and list values. What is a complete shape audit?
Check the outer type: Verify that the complete value is a dictionary rather than another container type.
Check the keys: Inspect whether the keys have the expected tuple type and expected composition.
Check the values: Inspect whether the values are lists rather than another type.
Check value size and contents: Compare the sizes and inner composition of the lists with the expectations of the program.
Check consistency: Look for entries whose key or value structure differs from the other entries or from the expected shape.
The audit verifies the outer type, key type, value type, sizes, composition, and consistency of the nested structure.
Reliable Shape Thinking
- Compound data structures nest collections inside one another, such as lists containing tuples or dictionaries with tuple keys and list values.
- A data shape includes its container type, size, composition, and nesting depth.
- A shape error occurs when the actual structure does not match what the code expects.
- Debug shape errors by printing data, checking types with type(), and comparing actual and expected structures at each level.
- Prevent shape errors by stating the expected structure clearly and by checking returned data instead of relying on assumptions.
Key Takeaways
- Compound data structures organize collections inside other collections.
- Lists, tuples, and dictionaries can appear at different levels of one nested structure.
- Shape errors involve a mismatch in type, size, composition, or nesting depth.
- The safest debugging method is to inspect actual data and types level by level.
- Clear expectations about shape make nested data easier to use and debug.