list

Create an empty list or a new list from a source you can loop through, such as a string, list or generator. Items keep their order; nested collections are shared with the source.

list()
list(iterable, /)

numbers = list()
numbers.append(2)
numbers.append(3)

copied = list(numbers)

Create a list by writing its items between square brackets.

[1, 2, 3]

numbers = [2, 0, 3]
first = numbers[0]       # returns 2

Build a list from values produced by expr while looping through a source. Use if to keep only matching items; multiple for/if clauses are allowed. Loop variables stay inside this expression.

[expr for target in iterable if condition]

values = [1, 2, 3, 4]
evens = [x for x in values if x % 2 == 0]

Create a new integer list for loops, counters, and numeric ranges.

range(stop, /) | range(start, stop, step=1, /)

numbers = range(5)         # returns [0, 1, 2, 3, 4]
evens = range(0, 10, 2)   # returns [0, 2, 4, 6, 8]

Count how many items are in the list.

len(list, /)

numbers = range(3, 8)     # returns [3, 4, 5, 6, 7]
count = len(numbers)      # returns 5

Read one item by position: 0 is first, -1 is last, and other negative indexes count from the end.

list[index]

numbers = range(10, 15)   # returns [10, 11, 12, 13, 14]
first = numbers[0]        # returns 10
third = numbers[2]        # returns 12
last = numbers[-1]        # returns 14

Return a new list from start up to, but not including, end. Negative indexes count from the end. Omitted bounds select the whole list in the step direction; nested collections remain shared.

list[start:end[:step]]

numbers = [0, 1, 2, 3, 4]
middle = numbers[1:4]     # returns [1, 2, 3]
tail = numbers[-2:]       # returns [3, 4]
reverse = numbers[::-1]   # returns [4, 3, 2, 1, 0]

Replace one existing item by index. Negative indexes count from the end. The index must already be inside the list.

list[index] = value

numbers = [12, 12, 21, 3, 2, 1]
numbers[4] = 3            # numbers becomes [12, 12, 21, 3, 3, 1]

Assign list items to variables from left to right. The number of variables must match the number of items or an error is raised. Groups of variables can be nested; *rest is not supported.

a, b = list

point = [500, 900]
x, y = point

Add one new item to the end of the list.

list.append(value, /)

numbers = [2, 0]
numbers.append(3)
last = numbers[-1]        # returns 3

Add each item from a source you can loop through to the end of this list, preserving source order.

list.extend(iterable, /)

numbers = [1]
numbers.extend([2, 3])
count = len(numbers)      # returns 3

Insert an item before the given position. Positions start at 0; negative indexes count from the end. An index before the list inserts at the beginning; one past the list inserts at the end.

list.insert(index, value, /)

numbers = [1, 3]
numbers.insert(1, 2)      # numbers becomes [1, 2, 3]

Remove the first item whose value matches the given value.

list.remove(value, /)

numbers = [1, 2, 2, 3]
numbers.remove(2)         # numbers becomes [1, 2, 3]

Remove one item from the list and return it. Omitting the index removes the last item.

list.pop(index=-1, /)

numbers = [2, 0, 3]
removed = numbers.pop()   # returns 3
first = numbers.pop(0)    # returns 2

Remove every item from the list.

list.clear()

numbers = [2, 0, 3]
numbers.clear()
text(str(len(numbers)))   # returns 0

Return the first index whose item equals value within the optional start and stop bounds.

list.index(value, start=0, stop=len(list), /)

numbers = [1, 2, 1, 3]
first_one = numbers.index(1)       # returns 0
later_one = numbers.index(1, 1)    # returns 2

Count how many items equal the given value.

list.count(value, /)

numbers = [1, 2, 1, 3]
ones = numbers.count(1)   # returns 2

Reorder this list from smallest to largest. Equal comparison values keep their original order. Values must be comparable: numbers and booleans, strings, or lists/tuples of the same kind with comparable items; mixing incompatible kinds raises an error.

list.sort(*, key=None, reverse=False)

numbers = [3, 1, 2]
numbers.sort()
text(str(numbers))        # returns [1, 2, 3]

Reverse the list in place.

list.reverse()

numbers = [1, 2, 3]
numbers.reverse()         # numbers becomes [3, 2, 1]

Return a new list with the same items. Adding, removing or replacing items in the copy does not change the original; nested collections are still shared.

list.copy()

numbers = [1, 2]
copied = numbers.copy()
copied.append(3)
count = len(numbers)      # returns 2

Loop through items in order from left to right.

for item in list:

steps = range(1, 4)      # returns [1, 2, 3]
for step in steps:
    wait(step * 100)      # returns None

Check whether the list has at least one item. An empty list is treated as false.

if list | if not list

numbers = range(0)        # returns []
if not numbers:
    text("No items")      # returns None