An ordered read-only collection. Use tuple literals when values should stay fixed after creation or when returning grouped values for destructuring.
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
offset = (0, 1)
x = offset[0]
y = offset[1]
if 1 in offset:
text("offset ready")
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Related APIs
None
Methods
9 methods
tuple.constructor
Creation Method
Create an empty tuple or clone another iterable as tuple.
Syntax
tuple()
tuple(iterable, /)
Parameters
Name
Description
iterableIterable
Optional iterable to clone into a tuple.
Depends on overload · Positional only
Default:None
Returns
tuple — A new read-only tuple.
Behavior / side effects
Create an empty tuple or clone another iterable as tuple. Use a tuple literal for multiple inline values.
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
coords = (120, 340)
copy = tuple(coords)
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Create a tuple inline using parentheses and commas.
Syntax
(value1, value2, ...)
Parameters
Name
Description
valueAny?
Each item written inside tuple parentheses.
Required · Positional or named
No default
Returns
tuple — A new tuple preserving literal order.
Behavior / side effects
Create a tuple inline using parentheses and commas.
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.
Example
offset = (0, 1)
count = len(offset) # returns 2
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Any? — tuple item at index, or None when out of range.
Behavior / side effects
Read one tuple 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
pair = (10, 20)
x = pair[0] # returns 10
y = pair[-1] # returns 20
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
tuple — A new tuple slice, clamped to the available range.
Behavior / side effects
Copy part of a tuple 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.
Unpack tuple items into matching assignment targets.
Syntax
x, y = tuple
Parameters
Name
Description
x, yTargets
Assignment targets matching the tuple item count.
Required · Positional or named
No default
tupletuple
Source tuple to unpack.
Required · Positional only
No default
Returns
None — No direct return value. Targets receive tuple items left to right.
Behavior / side effects
Unpack tuple 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
label, (x, y) = ("target", (500, 900))
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Find the first matching item index and fail visibly when absent.
Syntax
tuple.index(value, start=0, stop=len(tuple), /)
Parameters
Name
Description
valueAny?
Value that must exist in the tuple.
Required · Positional only
No default
startInt
Start index for the search.
Optional · Positional only
Default:0
stopInt
Stop index for the search.
Optional · Positional only
Default:len(tuple)
Returns
Int — First matching item index.
Behavior / side effects
Find the first matching item index and fail visibly when absent.
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
pair = ("farm", "pvp")
index = pair.index("pvp")
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
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.
Example
offset = (0, 1)
for item in offset:
text(str(item))
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
