Fixes #12857 Use collections.deque as queue in graphs BFS shortest path - breadth_first_search_shortest_path_2.py

[john-liu2]

Describe your change:

Use collections.deque as queue in graphs BFS shortest path - breadth_first_search_shortest_path_2.py

• Add an algorithm?
• Fix a bug or typo in an existing algorithm?
• Add or change doctests? -- Note: Please avoid changing both code and tests in a single pull request.
• Documentation change?

Checklist:

• I have read CONTRIBUTING.md.
• This pull request is all my own work -- I have not plagiarized.
• I know that pull requests will not be merged if they fail the automated tests.
• This PR only changes one algorithm file. To ease review, please open separate PRs for separate algorithms.
• All new Python files are placed inside an existing directory.
• All filenames are in all lowercase characters with no spaces or dashes.
• All functions and variable names follow Python naming conventions.
• All function parameters and return values are annotated with Python type hints.
• All functions have doctests that pass the automated testing.
• All new algorithms include at least one URL that points to Wikipedia or another similar explanation.
• If this pull request resolves one or more open issues then the description above includes the issue number(s) with a closing keyword: "Fixes Performance Enhancement: Replace list with collections.deque in graph algorithms #12857".

[cclauss]

Why make the proposed change?
Is it faster?
Is it more memory efficient?
Do we really use both ends?

[john-liu2]

Thank you for the quick review. Yes, deque.popleft() is much faster with its O(1) time complexity.

from timeit import timeit
from collections import deque

# Prepare long data
cnt = 100_000
lst = list(range(cnt))
dq = deque(range(cnt))

# Time pop from front
pop_time = timeit(lambda: lst.pop(0), number=cnt)
print("The list.pop(0) time:", pop_time)  # Slow
popleft_time = timeit(lambda: dq.popleft(), number=cnt)
print("The deque.popleft() time:", popleft_time)  # Fast

spd_diff = int(pop_time / popleft_time)
print(f"The deque.popleft() speed is {spd_diff} times the speed of list.pop(0).")

A sample run result of the above code:

The list.pop(0) time: 0.7074825000017881
The deque.popleft() time: 0.0027668749971780926
The deque.popleft() speed is 255 times the speed of list.pop(0).

[adityakaldate21-dev]

from collections import deque

def breadth_first_search(graph, start, target):
visited = set()
queue = deque([(start, [start])]) # queue holds (node, path)

while queue:
    current_node, path = queue.popleft()  # Fast O(1) removal from front
    if current_node == target:
        return path
    if current_node not in visited:
        visited.add(current_node)
        for neighbor in graph.get(current_node, []):
            queue.append((neighbor, path + [neighbor]))

return None  # if no path found

[john-liu2]

from collections import deque

def breadth_first_search(graph, start, target): visited = set() queue = deque([(start, [start])]) # queue holds (node, path)

while queue:
    current_node, path = queue.popleft()  # Fast O(1) removal from front
    if current_node == target:
        return path
    if current_node not in visited:
        visited.add(current_node)
        for neighbor in graph.get(current_node, []):
            queue.append((neighbor, path + [neighbor]))

return None  # if no path found

Thanks for the input. It should be a separate pull request to modify the algorithm logic.

[cclauss]

Why not https://docs.python.org/3/library/queue.html ?

Why not a single file with three implementations -- the original implementation + queue + dequeue -- with a timeit that demonstrates relative performance.

[john-liu2]

Why not https://docs.python.org/3/library/queue.html ?

Why not a single file with three implementations -- the original implementation + queue + dequeue -- with a timeit that demonstrates relative performance.

Thanks for sharing the doc. The queue in the doc is related to multi-threading programming.

The collections.deque.popleft() is the right one to use in the shortest path algorithm. In fact, at the bottom of the doc, we have this statement:

...
collections.deque is an alternative implementation of unbounded queues with fast atomic append() and popleft() operations that do not require locking and also support indexing.

[adityakaldate21-dev]

from collections import deque

def bfs_shortest_path_distance(graph: dict, start, target) -> int:
    """
    Returns the shortest path distance from 'start' to 'target' in an unweighted graph.
    Uses deque for efficient queue operations and includes visited set + distance map.
    """
    if start == target:
        return 0

    queue = deque([start])           #  FIX: Wrap start in a list
    visited = set([start])           #  Prevent revisiting nodes
    dist = {start: 0}                # Track distance of each node

    while queue:
        node = queue.popleft()
        for neighbor in graph.get(node, []):
            if neighbor not in visited:
                visited.add(neighbor)
                dist[neighbor] = dist[node] + 1
                if neighbor == target:
                    return dist[neighbor]
                queue.append(neighbor)

    return -1  # Target not reachable


# Example usage / testing
if __name__ == "__main__":
    graph = {
        'A': ['B', 'C'],
        'B': ['D'],
        'C': [],
        'D': []
    }

    print("Distance A -> D:", bfs_shortest_path_distance(graph, 'A', 'D'))  # Output: 2
    print("Distance A -> A:", bfs_shortest_path_distance(graph, 'A', 'A'))  # Output: 0
    print("Distance A -> Z:", bfs_shortest_path_distance(graph, 'A', 'Z'))  # Output: -1