Skip to content

Queue

py_ds.datastructures.queue.Queue 

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

Bases: Generic[T]

A simple FIFO (first-in, first-out) queue.

Backed by a Python list, providing O(1) enqueue and O(1) dequeue operations.

Initialize the queue.

Parameters:

Name Type Description Default
items Iterable[T] | None

Optional iterable of initial items. The first item of the iterable becomes the front of the queue.

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

    Args:
        items: Optional iterable of initial items.
               The first item of the iterable becomes the front of the queue.
    """
    self._items = list(items) if items else []

Functions

enqueue 

enqueue(item: T) -> None

Add an item to the back of the queue.

Parameters:

Name Type Description Default
item T

The item to add to the queue.

 required

Time complexity: O(1).

Source code in src/py_ds/datastructures/queue.py 
28
29
30
31
32
33
34
35
36
def enqueue(self, item: T) -> None:
    """Add an item to the back of the queue.

    Args:
        item: The item to add to the queue.

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

dequeue 

dequeue() -> T

Remove and return the front item of the queue.

Returns:

Type Description
T

The item that was at the front of the queue.

Raises:

Type Description
IndexError

If the queue is empty.

Time complexity: O(1).

Source code in src/py_ds/datastructures/queue.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def dequeue(self) -> T:
    """Remove and return the front item of the queue.

    Returns:
        The item that was at the front of the queue.

    Raises:
        IndexError: If the queue is empty.

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

peek 

peek() -> T

Return the front item without removing it.

Returns:

Type Description
T

The item at the front of the queue.

Raises:

Type Description
IndexError

If the queue is empty.

Time complexity: O(1).

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

    Returns:
        The item at the front of the queue.

    Raises:
        IndexError: If the queue is empty.

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

is_empty 

is_empty() -> bool

Check if the queue is empty.

Returns:

Type Description
bool

True if the queue contains no items, False otherwise.

Time complexity: O(1).

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

    Returns:
        True if the queue contains no items, False otherwise.

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

extend 

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

Enqueue multiple items in the order provided.

The first item of the iterable becomes the next after the current back.

Parameters:

Name Type Description Default
items Iterable[T]

An iterable of items to enqueue.

 required

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

Source code in src/py_ds/datastructures/queue.py 
82
83
84
85
86
87
88
89
90
91
92
93
def extend(self, items: Iterable[T]) -> None:
    """Enqueue multiple items in the order provided.

    The first item of the iterable becomes the next after the current back.

    Args:
        items: An iterable of items to enqueue.

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

clear 

clear() -> None

Remove all items from the queue.

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

Time complexity: O(1).

Source code in src/py_ds/datastructures/queue.py 
 95
 96
 97
 98
 99
100
101
102
def clear(self) -> None:
    """Remove all items from the queue.

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

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

to_list 

to_list() -> list[T]

Convert the queue to a Python list.

Returns:

Type Description
list[T]

A shallow copy of the queue contents as a list, ordered from
list[T]

front to back.

Time complexity: O(n).

Source code in src/py_ds/datastructures/queue.py 
104
105
106
107
108
109
110
111
112
113
def to_list(self) -> list[T]:
    """Convert the queue to a Python list.

    Returns:
        A shallow copy of the queue contents as a list, ordered from
        front to back.

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

__len__ 

__len__() -> int

Return the number of items in the queue.

Returns:

Type Description
int

The number of items in the queue.

Time complexity: O(1).

Source code in src/py_ds/datastructures/queue.py 
119
120
121
122
123
124
125
126
127
def __len__(self) -> int:
    """Return the number of items in the queue.

    Returns:
        The number of items in the queue.

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

__bool__ 

__bool__() -> bool

Return the truthiness of the queue.

Returns:

Type Description
bool

False if the queue is empty, True otherwise.

Enables: if queue: ...

Source code in src/py_ds/datastructures/queue.py 
129
130
131
132
133
134
135
136
137
def __bool__(self) -> bool:
    """Return the truthiness of the queue.

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

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

__iter__ 

__iter__() -> Iterator[T]

Iterate over the items in the queue from front to back.

Yields:

Type Description
T

Each item in the queue, starting from the front.
Example

q = Queue([1, 2, 3]) list(q) # [1, 2, 3] (front to back)

Source code in src/py_ds/datastructures/queue.py 
139
140
141
142
143
144
145
146
147
148
149
def __iter__(self) -> Iterator[T]:
    """Iterate over the items in the queue from front to back.

    Yields:
        Each item in the queue, starting from the front.

    Example:
        q = Queue([1, 2, 3])
        list(q)  # [1, 2, 3]  (front to back)
    """
    return iter(self._items)

__repr__ 

__repr__() -> str

Return a string representation of the queue.

Returns:

Type Description
str

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

Queue([1, 2, 3])

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

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

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