Skip to content

Stack

py_ds.datastructures.stack.Stack 

Stack(items: Iterable[T] | None = None)

Bases: Generic[T]

A simple LIFO (last-in, first-out) stack.

Backed by a dynamic array (Python list). Provides efficient O(1) operations for push, pop, and peek operations.

Initialize the stack.

Parameters:

Name Type Description Default
items Iterable[T] | None

Optional iterable of initial items. The last item in the iterable should be considered the "top" of the stack.

 None
Example

Stack([1, 2, 3]) # 3 is at the top

Source code in src/py_ds/datastructures/stack.py 
16
17
18
19
20
21
22
23
24
25
26
def __init__(self, items: Iterable[T] | None = None) -> None:
    """Initialize the stack.

    Args:
        items: Optional iterable of initial items. The last item in the
               iterable should be considered the "top" of the stack.

    Example:
        Stack([1, 2, 3])  # 3 is at the top
    """
    self._items = list(items) if items else []

Functions

push 

push(item: T) -> None

Push a single item onto the top of the stack.

Parameters:

Name Type Description Default
item T

The item to push onto the stack.

 required

Time complexity: O(1) amortized.

Source code in src/py_ds/datastructures/stack.py 
30
31
32
33
34
35
36
37
38
def push(self, item: T) -> None:
    """Push a single item onto the top of the stack.

    Args:
        item: The item to push onto the stack.

    Time complexity: O(1) amortized.
    """
    self._items.append(item)

pop 

pop() -> T

Remove and return the top item of the stack.

Returns:

Type Description
T

The item that was at the top of the stack.

Raises:

Type Description
IndexError

If the stack is empty.

Time complexity: O(1).

Source code in src/py_ds/datastructures/stack.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def pop(self) -> T:
    """Remove and return the top item of the stack.

    Returns:
        The item that was at the top of the stack.

    Raises:
        IndexError: If the stack is empty.

    Time complexity: O(1).
    """
    if self.is_empty():
        raise IndexError('pop from empty stack')
    return self._items.pop()

peek 

peek() -> T

Return the top item of the stack without removing it.

Returns:

Type Description
T

The item at the top of the stack.

Raises:

Type Description
IndexError

If the stack is empty.

Time complexity: O(1).

Source code in src/py_ds/datastructures/stack.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def peek(self) -> T:
    """Return the top item of the stack without removing it.

    Returns:
        The item at the top of the stack.

    Raises:
        IndexError: If the stack is empty.

    Time complexity: O(1).
    """
    if self.is_empty():
        raise IndexError('peek from empty stack')
    return self._items[-1]

is_empty 

is_empty() -> bool

Check if the stack is empty.

Returns:

Type Description
bool

True if the stack has no elements, False otherwise.

Time complexity: O(1).

Source code in src/py_ds/datastructures/stack.py 
70
71
72
73
74
75
76
77
78
def is_empty(self) -> bool:
    """Check if the stack is empty.

    Returns:
        True if the stack has no elements, False otherwise.

    Time complexity: O(1).
    """
    return len(self._items) == 0

clear 

clear() -> None

Remove all items from the stack.

After this call, is_empty() returns True and len(stack) == 0.

Time complexity: O(1).

Source code in src/py_ds/datastructures/stack.py 
82
83
84
85
86
87
88
89
def clear(self) -> None:
    """Remove all items from the stack.

    After this call, is_empty() returns True and len(stack) == 0.

    Time complexity: O(1).
    """
    self._items = []

extend 

extend(items: Iterable[T]) -> None

Push multiple items onto the stack, in iteration order.

The last item of items becomes the new top of the stack.

Parameters:

Name Type Description Default
items Iterable[T]

An iterable of items to push onto the stack.

 required
Example

s = Stack([1]) s.extend([2, 3])

now stack top is 3

Time complexity: O(k), where k is the number of items.

Source code in src/py_ds/datastructures/stack.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def extend(self, items: Iterable[T]) -> None:
    """Push multiple items onto the stack, in iteration order.

    The last item of `items` becomes the new top of the stack.

    Args:
        items: An iterable of items to push onto the stack.

    Example:
        s = Stack([1])
        s.extend([2, 3])
        # now stack top is 3

    Time complexity: O(k), where k is the number of items.
    """
    for item in items:
        self.push(item)

to_list 

to_list() -> list[T]

Convert the stack to a Python list.

Returns:

Type Description
list[T]

A shallow copy of the stack contents as a list. The last element
list[T]

of the returned list is the top of the stack.

Time complexity: O(n).

Source code in src/py_ds/datastructures/stack.py 
109
110
111
112
113
114
115
116
117
118
def to_list(self) -> list[T]:
    """Convert the stack to a Python list.

    Returns:
        A shallow copy of the stack contents as a list. The last element
        of the returned list is the top of the stack.

    Time complexity: O(n).
    """
    return self._items[::]

__len__ 

__len__() -> int

Return the number of items in the stack.

Returns:

Type Description
int

The number of items in the stack.

Time complexity: O(1).

Source code in src/py_ds/datastructures/stack.py 
122
123
124
125
126
127
128
129
130
def __len__(self) -> int:
    """Return the number of items in the stack.

    Returns:
        The number of items in the stack.

    Time complexity: O(1).
    """
    return len(self._items)

__bool__ 

__bool__() -> bool

Return the truthiness of the stack.

Returns:

Type Description
bool

False if the stack is empty, True otherwise.

Enables: if stack: ...

Source code in src/py_ds/datastructures/stack.py 
132
133
134
135
136
137
138
139
140
def __bool__(self) -> bool:
    """Return the truthiness of the stack.

    Returns:
        False if the stack is empty, True otherwise.

    Enables: `if stack: ...`
    """
    return len(self._items) > 0

__iter__ 

__iter__() -> Iterator[T]

Iterate over the items in the stack from top to bottom.

Yields:

Type Description
T

Each item in the stack, starting from the top.
Example

s = Stack([1, 2, 3]) list(s) # [3, 2, 1] (top to bottom)

Source code in src/py_ds/datastructures/stack.py 
142
143
144
145
146
147
148
149
150
151
152
def __iter__(self) -> Iterator[T]:
    """Iterate over the items in the stack from top to bottom.

    Yields:
        Each item in the stack, starting from the top.

    Example:
        s = Stack([1, 2, 3])
        list(s)  # [3, 2, 1]  (top to bottom)
    """
    return iter(self._items[::-1])

__repr__ 

__repr__() -> str

Return a string representation of the stack.

Returns:

Type Description
str

A string representation showing the class name and stack contents.
Example

Stack([1, 2, 3])

Source code in src/py_ds/datastructures/stack.py 
154
155
156
157
158
159
160
161
162
163
def __repr__(self) -> str:
    """Return a string representation of the stack.

    Returns:
        A string representation showing the class name and stack contents.

    Example:
        Stack([1, 2, 3])
    """
    return f'Stack({self.to_list()})'