> **Источник:** https://python-all.ru/3.10/library/queue.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # [`queue`](https://python-all.ru/3.10/library/queue.html#module-queue) – синхронизированный класс очереди **Исходный код:** [Lib/queue.py](https://python-all.ru/src/3.10/Lib/queue.py) --- Модуль [`queue`](https://python-all.ru/3.10/library/queue.html#module-queue) реализует очереди с несколькими производителями и несколькими потребителями. Особенно полезно в многопоточном программировании, когда нужно безопасно обмениваться данными между несколькими потоками. Класс [`Queue`](https://python-all.ru/3.10/library/queue.html#queue.Queue) в этом модуле реализует всю необходимую семантику блокировок. Модуль реализует три типа очередей, различающихся только порядком извлечения элементов. В очереди FIFO первые добавленные задачи извлекаются первыми. В очереди LIFO последний добавленный элемент извлекается первым (работает как стек). В очереди с приоритетом элементы хранятся отсортированными (с помощью модуля [`heapq`](https://python-all.ru/3.10/library/heapq.html#module-heapq)), и элемент с наименьшим значением извлекается первым. Внутри этих трёх типов очередей для временной блокировки конкурирующих потоков используются блокировки; однако они не рассчитаны на реентерабельность в пределах одного потока. Кроме того, модуль реализует «простой» тип очереди FIFO, [`SimpleQueue`](https://python-all.ru/3.10/library/queue.html#queue.SimpleQueue), чья реализация предоставляет дополнительные гарантии ценой меньшей функциональности. Модуль [`queue`](https://python-all.ru/3.10/library/queue.html#module-queue) определяет следующие классы и исключения: #### `class queue.Queue(maxsize=0)` Конструктор для очереди FIFO. *maxsize* – целое число, задающее верхний предел количества элементов, которые можно поместить в очередь. Вставка будет блокироваться, когда этот размер достигнут, пока элементы очереди не будут потреблены. Если *maxsize* меньше или равно нулю, размер очереди бесконечен. #### `class queue.LifoQueue(maxsize=0)` Конструктор для очереди LIFO. *maxsize* – целое число, задающее верхний предел количества элементов, которые можно поместить в очередь. Вставка будет блокироваться, когда этот размер достигнут, пока элементы очереди не будут потреблены. Если *maxsize* меньше или равно нулю, размер очереди бесконечен. #### `class queue.PriorityQueue(maxsize=0)` Конструктор для очереди с приоритетом. *maxsize* – целое число, задающее верхний предел количества элементов, которые можно поместить в очередь. Вставка будет блокироваться, когда этот размер достигнут, пока элементы очереди не будут потреблены. Если *maxsize* меньше или равно нулю, размер очереди бесконечен. Элементы с наименьшим значением извлекаются первыми (элемент с наименьшим значением – это тот, который вернула бы функция `min(entries)`). Обычно элементы представлены кортежем вида: `(priority_number, data)`. Если элементы *data* несравнимы, данные можно обернуть в класс, который игнорирует элемент данных и сравнивает только номер приоритета: ```python from dataclasses import dataclass, field from typing import Any @dataclass(order=True) class PrioritizedItem: priority: int item: Any=field(compare=False) ``` #### `class queue.SimpleQueue` Конструктор для неограниченной очереди FIFO. Простые очереди лишены расширенной функциональности, такой как отслеживание задач. Добавлено в версии 3.7. #### `exception queue.Empty` Исключение, возбуждаемое при вызове неблокирующего [`get()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.get) (или [`get_nowait()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.get_nowait)) на пустом объекте [`Queue`](https://python-all.ru/3.10/library/queue.html#queue.Queue). #### `exception queue.Full` Исключение, возбуждаемое при вызове неблокирующего [`put()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.put) (или [`put_nowait()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.put_nowait)) на полном объекте [`Queue`](https://python-all.ru/3.10/library/queue.html#queue.Queue). ## Объекты очередей Объекты очередей ([`Queue`](https://python-all.ru/3.10/library/queue.html#queue.Queue), [`LifoQueue`](https://python-all.ru/3.10/library/queue.html#queue.LifoQueue) или [`PriorityQueue`](https://python-all.ru/3.10/library/queue.html#queue.PriorityQueue)) предоставляют описанные ниже открытые методы. #### `Queue.qsize()` Возвращает приблизительный размер очереди. Обратите внимание: qsize() \> 0 не гарантирует, что последующий вызов get() не заблокируется, равно как qsize() \< maxsize не гарантирует, что put() не заблокируется. #### `Queue.empty()` Возвращает `True`, если очередь пуста, и `False` в противном случае. Если empty() возвращает `True`, это не гарантирует, что последующий вызов put() не заблокируется. Аналогично, если empty() возвращает `False`, это не гарантирует, что последующий вызов get() не заблокируется. #### `Queue.full()` Возвращает `True`, если очередь заполнена, и `False` в противном случае. Если full() возвращает `True`, это не гарантирует, что последующий вызов get() не заблокируется. Аналогично, если full() возвращает `False`, это не гарантирует, что последующий вызов put() не заблокируется. #### `Queue.put(item, block=True, timeout=None)` Помещает *элемент* в очередь. Если необязательный аргумент *block* истинен и *timeout* равен `None` (по умолчанию), блокируется при необходимости до освобождения места. Если *timeout* – положительное число, блокируется не более чем на *timeout* секунд и возбуждает исключение [`Full`](https://python-all.ru/3.10/library/queue.html#queue.Full), если за это время место не освободилось. В противном случае (*block* ложен), помещает элемент в очередь, если место свободно немедленно, иначе возбуждает исключение [`Full`](https://python-all.ru/3.10/library/queue.html#queue.Full) (в этом случае *timeout* игнорируется). #### `Queue.put_nowait(item)` Эквивалентно `put(item, block=False)`. #### `Queue.get(block=True, timeout=None)` Удаляет элемент из очереди и возвращает его. Если необязательный аргумент *block* равен true, а *timeout* равен `None` (по умолчанию), при необходимости блокирует выполнение, пока элемент не станет доступен. Если *timeout* – положительное число, блокирует выполнение не более чем на *timeout* секунд и вызывает исключение [`Empty`](https://python-all.ru/3.10/library/queue.html#queue.Empty), если за это время элемент не появился. В противном случае (*block* равен false) возвращает элемент, если он доступен немедленно, иначе вызывает исключение [`Empty`](https://python-all.ru/3.10/library/queue.html#queue.Empty) (*timeout* в этом случае игнорируется). До версии 3.0 в системах POSIX и во всех версиях Windows, если *block* истинен и *timeout* равен `None`, эта операция переходит в непрерываемое ожидание на базовой блокировке. Это означает, что никакие исключения не могут возникнуть, и, в частности, SIGINT не вызовет [`KeyboardInterrupt`](https://python-all.ru/3.10/library/exceptions.html#KeyboardInterrupt). #### `Queue.get_nowait()` Эквивалентно `get(False)`. Предлагаются два метода для отслеживания того, были ли задачи, поставленные в очередь, полностью обработаны потоками-потребителями-демонами. #### `Queue.task_done()` Указывает, что ранее поставленная в очередь задача завершена. Используется потоками-потребителями очереди. Для каждого вызова [`get()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.get), использованного для получения задачи, последующий вызов [`task_done()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.task_done) сообщает очереди, что обработка задачи завершена. Если [`join()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.join) в данный момент заблокирован, он возобновит работу, когда все элементы будут обработаны (то есть для каждого элемента, который был [`put()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.put) в очередь, был получен вызов [`task_done()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.task_done)). Возбуждает [`ValueError`](https://python-all.ru/3.10/library/exceptions.html#ValueError), если вызывается больше раз, чем было помещено элементов в очередь. #### `Queue.join()` Блокируется до тех пор, пока все элементы в очереди не будут получены и обработаны. Счётчик незавершённых задач увеличивается каждый раз, когда элемент добавляется в очередь. Счётчик уменьшается, когда поток-потребитель вызывает [`task_done()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.task_done), чтобы указать, что элемент был получен и вся работа с ним завершена. Когда счетчик незавершённых задач падает до нуля, [`join()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.join) разблокируется. Пример ожидания завершения поставленных в очередь задач: ```python import threading import queue q = queue.Queue() def worker(): while True: item = q.get() print(f'Working on {item}') print(f'Finished {item}') q.task_done() # Запустить рабочий поток. threading.Thread(target=worker, daemon=True).start() # Отправить рабочему тридцать запросов задач. for item in range(30): q.put(item) # Ожидать завершения всех задач. q.join() print('All work completed') ``` ## Объекты SimpleQueue Объекты [`SimpleQueue`](https://python-all.ru/3.10/library/queue.html#queue.SimpleQueue) предоставляют описанные ниже публичные методы. #### `SimpleQueue.qsize()` Возвращает приблизительный размер очереди. Обратите внимание, qsize() \> 0 не гарантирует, что последующий вызов get() не заблокируется. #### `SimpleQueue.empty()` Возвращает `True`, если очередь пуста, и `False` в противном случае. Если empty() возвращает `False`, это не гарантирует, что последующий вызов get() не заблокируется. #### `SimpleQueue.put(item, block=True, timeout=None)` Помещает *элемент* в очередь. Метод никогда не блокируется и всегда выполняется успешно (за исключением возможных низкоуровневых ошибок, например, сбоя выделения памяти). Необязательные аргументы *block* и *timeout* игнорируются и предоставлены только для совместимости с [`Queue.put()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.put). **Особенность реализации CPython:** Этот метод имеет реализацию на C, которая является реентерабельной. То есть вызов `put()` или `get()` может быть прерван другим вызовом `put()` в том же потоке без взаимоблокировки или повреждения внутреннего состояния очереди. Это делает его подходящим для использования в деструкторах, таких как методы `__del__` или колбэки [`weakref`](https://python-all.ru/3.10/library/weakref.html#module-weakref). #### `SimpleQueue.put_nowait(item)` Эквивалентно `put(item, block=False)`, предусмотрено для совместимости с [`Queue.put_nowait()`](https://python-all.ru/3.10/library/queue.html#queue.Queue.put_nowait). #### `SimpleQueue.get(block=True, timeout=None)` Удаляет элемент из очереди и возвращает его. Если необязательный аргумент *block* равен true, а *timeout* равен `None` (по умолчанию), при необходимости блокирует выполнение, пока элемент не станет доступен. Если *timeout* – положительное число, блокирует выполнение не более чем на *timeout* секунд и вызывает исключение [`Empty`](https://python-all.ru/3.10/library/queue.html#queue.Empty), если за это время элемент не появился. В противном случае (*block* равен false) возвращает элемент, если он доступен немедленно, иначе вызывает исключение [`Empty`](https://python-all.ru/3.10/library/queue.html#queue.Empty) (*timeout* в этом случае игнорируется). #### `SimpleQueue.get_nowait()` Эквивалентно `get(False)`. > **См. также** > > **Класс [`multiprocessing.Queue`](https://python-all.ru/3.10/library/multiprocessing.html#multiprocessing.Queue)** > > Класс очереди для использования в контексте многопроцессорной обработки (а не многопоточности). > > [`collections.deque`](https://python-all.ru/3.10/library/collections.html#collections.deque) – это альтернативная реализация неограниченных очередей с быстрыми атомарными операциями [`append()`](https://python-all.ru/3.10/library/collections.html#collections.deque.append) и [`popleft()`](https://python-all.ru/3.10/library/collections.html#collections.deque.popleft), которые не требуют блокировок и также поддерживают индексирование.