An ordered collection you can create, read, loop through, destructure, and update while the script runs.
Syntax
list(iterable=(), /)
Parameters
None
Returns
list
Behavior / side effects
An ordered collection you can create, read, loop through, destructure, and update while the script runs.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Example
numbers = list()
numbers.append(2)
numbers.extend([0, 3])
first = numbers[0] # returns 2
count = len(numbers) # returns 3
for value in numbers:
wait(50) # returns None
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Related APIs
None
Methods
22 methods
list.constructor
Creation Method
Create an empty list or copy the items from one iterable into a new mutable list.
Syntax
list()
list(iterable, /)
Parameters
Name
Description
iterableIterable
Source values to copy into the new list.
Depends on overload · Positional only
Default:()
Returns
list — A new mutable list.
Behavior / side effects
Create an empty list or copy the items from one iterable into a new mutable list.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
list — A new mutable list preserving the literal order.
Behavior / side effects
Create a list literal inline. This is the shortest form when you already know the items.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Loop target for the current item. Starred targets are not supported.
Required · Positional or named
No default
iterableIterable
Source values to loop through.
Required · Positional or named
No default
conditionBoolean
Optional filter checked before appending.
Optional · Positional only
Default:True
Returns
list — A new mutable list with matching items in iteration order.
Behavior / side effects
Build a list by looping through another iterable. Multiple for/if clauses are supported, and loop targets stay local to the comprehension.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Example
values = [1, 2, 3, 4]
evens = [x for x in values if x % 2 == 0]
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Create a new integer list for loops, counters, and numeric ranges.
Syntax
range(stop, /) | range(start, stop, step=1, /)
Parameters
Name
Description
startNumber
Start value (inclusive).
Depends on overload · Positional only
Default:0
stopNumber
End value (exclusive).
Required · Positional only
No default
stepNumber
Increment between items. Cannot be 0.
Depends on overload · Positional only
Default:1
Returns
list[Int] — A new integer list.
Behavior / side effects
Create a new integer list for loops, counters, and numeric ranges.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Any? — The item at that position. Raises IndexError when the index is outside the list.
Behavior / side effects
Read one item by index. Negative indexes count from the end.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Example
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
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Distance between items. Cannot be 0; negative values read backward.
Optional · Positional only
Default:1
Returns
list — A new mutable list slice, clamped to the available range.
Behavior / side effects
Copy part of a list using Python-style slicing. Omitted bounds use the start or end; negative indexes count from the end.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Item index that already exists. Use -1 for the last item.
Required · Positional only
No default
valueAny?
New value to store at that position.
Required · Positional only
No default
Returns
None — No direct return value. The list is updated in place.
Behavior / side effects
Replace one existing item by index. Negative indexes count from the end. The index must already be inside the list.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Unpack list items into matching assignment targets.
Syntax
a, b = list
Parameters
Name
Description
a, bTargets
Assignment targets matching the list item count.
Required · Positional or named
No default
listlist
Source list to unpack.
Required · Positional only
No default
Returns
None — No direct return value. Targets receive list items left to right.
Behavior / side effects
Unpack list items into matching assignment targets. Nested targets are supported, but starred targets such as *rest are not supported.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Example
point = [500, 900]
x, y = point
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
None — No direct return value. The list is updated in place.
Behavior / side effects
Add one new item to the end of the list.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Append every item from another iterable to the end of the current list.
Syntax
list.extend(iterable, /)
Parameters
Name
Description
iterableIterable
Source values whose items will be appended.
Required · Positional only
No default
Returns
None — No direct return value. The list grows in place.
Behavior / side effects
Append every item from another iterable to the end of the current list.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
None — No direct return value. The list is updated in place.
Behavior / side effects
Insert one item before the given index. Negative and oversized indexes are clamped like Python.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Remove the first item whose value matches the given value.
Syntax
list.remove(value, /)
Parameters
Name
Description
valueAny?
Value to find and remove from the list.
Required · Positional only
No default
Returns
None — No direct return value. Raises ValueError when the value is not found.
Behavior / side effects
Remove the first item whose value matches the given value.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Optional index to remove. Negative indexes count from the end.
Optional · Positional only
Default:-1
Returns
Any? — The removed item. Raises IndexError when the list is empty or the index is outside the list.
Behavior / side effects
Remove one item from the list and return it. Omitting the index removes the last item.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
None — No direct return value. The list becomes empty.
Behavior / side effects
Remove every item from the list.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Return the first index whose item equals value within the optional start and stop bounds.
Syntax
list.index(value, start=0, stop=len(list), /)
Parameters
Name
Description
valueAny?
Value to search for.
Required · Positional only
No default
startInt
Optional start bound. Negative values count from the end.
Optional · Positional only
Default:0
stopInt
Optional stop bound. The item at this index is not included.
Optional · Positional only
Default:len(list)
Returns
Int — The matching index. Raises ValueError when the value is not found.
Behavior / side effects
Return the first index whose item equals value within the optional start and stop bounds.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Sort the list in place using the same stable ordering rules as sorted().
Syntax
list.sort(*, key=None, reverse=False)
Parameters
Name
Description
keyCallable?
Optional function that returns the comparison key for each item.
Optional · Keyword only
Default:None
reverseBoolean
When true, sort from largest to smallest.
Optional · Keyword only
Default:False
Returns
None — No direct return value. The list is reordered in place.
Behavior / side effects
Sort the list in place using the same stable ordering rules as sorted().
Execution
Blocking: Conditional
Thread safety: Use separate objects per flow
Parallel execution: Conditional
The operation processes values in the calling flow. A key callable also runs there and may perform waits or side effects; no asynchronous execution is implied.
None — No direct return value. The list order is reversed in place.
Behavior / side effects
Reverse the list in place.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
list — A new mutable list with the same item references.
Behavior / side effects
Create a shallow mutable copy of the list.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
None — No direct return value. The loop runs its body once per item.
Behavior / side effects
Loop through items in order from left to right.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Example
steps = range(1, 4) # returns [1, 2, 3]
for step in steps:
wait(step * 100) # returns None
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Boolean condition — true when the list is not empty, false when it is empty.
Behavior / side effects
Check whether the list has at least one item. An empty list is treated as false.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Value operations execute in the calling flow without an intentional wait for capture, gesture completion, or user input. Create mutable containers/builders separately in each flow; this is isolation, not a shared-object synchronization guarantee.
Example
numbers = range(0) # returns []
if not numbers:
text("No items") # returns None
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
