Data structures¶

A data structure stores several values in one variable. Python has three you need: the list, the tuple, and the dictionary.

Each one uses a different bracket:

list1 = [1, 2]                   # square brackets
tuple1 = (1, 2)                  # curved brackets
dict1 = {"one": 1, "two": 2}     # curly brackets

Structure	Brackets	Can you change it after creation?
List	`[ ]`	Yes
Tuple	`( )`	No
Dictionary	`{ }`	Yes

Lists¶

A list holds multiple values, of the same or different types, in order.

list1 = []                # an empty list
list2 = ["one", 2, 3.0]   # types can be mixed

Indexing¶

Every element has a position number called an index.

Indexing starts at 0

The first item is index 0, the second is index 1, and so on. A negative index counts backwards from the end.

list1 = [1, 2, 3]

print(list1[0])     # 1, the first item
print(list1[-1])    # 3, the last item
print(list1[0:2])   # [1, 2], a slice from index 0 up to but not including 2

list1[0] = 9        # list1 is now [9, 2, 3]

Common list methods¶

list1 = [1, 2]

list1.append(3)       # add to the end -> [1, 2, 3]
list1.extend([4])     # add every item of another list -> [1, 2, 3, 4]
list1.insert(1, 1.5)  # insert at an index -> [1, 1.5, 2, 3, 4]
list1.remove(1.5)     # remove the first matching value -> [1, 2, 3, 4]
list1.pop(2)          # remove by index and return it -> returns 3
list1.index(2)        # returns the index of the value 2 -> 1
list1.count(4)        # how many times 4 appears -> 1
list1.reverse()       # reverse the order in place
list1.sort()          # sort in place, smallest first
list1.copy()          # returns a copy of the list
list1.clear()         # empties the list -> []

len(list1) gives the number of items.

Full documentation: https://docs.python.org/3/tutorial/datastructures.html

Tuples¶

A tuple is almost the same as a list, but it is immutable: once created, it cannot be changed.

tuple1 = (1, 2)

print(tuple1[1])        # 2
print(tuple1.count(2))  # 1
print(tuple1.index(1))  # 0

tuple1[0] = 2   # error, tuples cannot be modified

Use a tuple instead of a list when the data must not change after it is created. In MARLIN code, PID gains are written as tuples for exactly that reason:

pid={"M1": (0.8, 0.1, 0.0)}

Dictionaries¶

A dictionary stores key–value pairs. Instead of looking a value up by position, you look it up by its key.

dict1 = {"one": 1, "two": 2}

Here "one" is a key, 1 is its value, and the : separates them.

dict1 = {"one": 1, "two": 2}

print(dict1["one"])           # 1
print(dict1.get("two"))       # 2, returns None instead of an error if missing

dict1.update({"three": 3})    # add or overwrite -> {"one": 1, "two": 2, "three": 3}
dict1.pop("one")              # remove by key and return its value -> 1
dict1.popitem()               # remove and return the last pair -> ("three", 3)
del dict1["two"]              # remove by key

print(dict1.keys())           # all keys
print(dict1.values())         # all values
dict1.clear()                 # empties the dictionary -> {}

Dictionaries are mutable, so you can add, change, and remove pairs after creating them.

Full documentation: https://docs.python.org/3/tutorial/datastructures.html#dictionaries

You already use dictionaries in MARLIN

Hardware configuration is a dictionary. The port is the key and the hardware class is the value:

robot.configure(
    sensors={"S1": IMU},
    effectors={"M1": Thruster, "M2": Servo},
)

See Hardware configuration.

What to read next¶

Control flow: how to make decisions and repeat work.