> **Источник:** https://python-all.ru/3.14/library/queue.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# `queue` – синхронизированный класс очереди

**Исходный код:** [Lib/queue.py](https://python-all.ru/src/3.14/Lib/queue.py)

---

Модуль `queue` реализует очереди с несколькими производителями и несколькими потребителями. Особенно полезно в многопоточном программировании, когда нужно безопасно обмениваться данными между несколькими потоками. Класс [`Queue`](https://python-all.ru/3.14/library/queue.html#queue.Queue) в этом модуле реализует всю необходимую семантику блокировок.

Модуль реализует три типа очередей, различающихся только порядком извлечения элементов. В очереди FIFO первые добавленные задачи извлекаются первыми. В очереди LIFO последний добавленный элемент извлекается первым (работает как стек). В очереди с приоритетом элементы хранятся отсортированными (с помощью модуля [`heapq`](https://python-all.ru/3.14/library/heapq.html#module-heapq)), и элемент с наименьшим значением извлекается первым.

Внутри этих трёх типов очередей для временной блокировки конкурирующих потоков используются блокировки; однако они не рассчитаны на реентерабельность в пределах одного потока.

Кроме того, модуль реализует «простой» тип очереди FIFO, [`SimpleQueue`](https://python-all.ru/3.14/library/queue.html#queue.SimpleQueue), чья реализация предоставляет дополнительные гарантии ценой меньшей функциональности.

Модуль `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. Простые очереди лишены расширенной функциональности, такой как отслеживание задач.

Простые очереди являются [обобщёнными](https://python-all.ru/3.14/library/typing.html#generics) по типу своих элементов.

Добавлено в версии 3.7.

#### `exception queue.Empty`

Исключение, возбуждаемое при вызове неблокирующего [`get()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.get) (или [`get_nowait()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.get_nowait)) на пустом объекте [`Queue`](https://python-all.ru/3.14/library/queue.html#queue.Queue).

#### `exception queue.Full`

Исключение, возбуждаемое при вызове неблокирующего [`put()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.put) (или [`put_nowait()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.put_nowait)) на полном объекте [`Queue`](https://python-all.ru/3.14/library/queue.html#queue.Queue).

#### `exception queue.ShutDown`

Исключение, возбуждаемое при вызове [`put()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.put) или [`get()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.get) на объекте [`Queue`](https://python-all.ru/3.14/library/queue.html#queue.Queue), который был закрыт.

Добавлено в версии 3.13.

## Объекты очередей

Объекты очередей ([`Queue`](https://python-all.ru/3.14/library/queue.html#queue.Queue), [`LifoQueue`](https://python-all.ru/3.14/library/queue.html#queue.LifoQueue) или [`PriorityQueue`](https://python-all.ru/3.14/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.14/library/queue.html#queue.Full), если за это время место не освободилось. В противном случае (*block* ложен), помещает элемент в очередь, если место свободно немедленно, иначе возбуждает исключение `Full` (в этом случае *timeout* игнорируется).

Вызывает [`ShutDown`](https://python-all.ru/3.14/library/queue.html#queue.ShutDown), если очередь была закрыта.

#### `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.14/library/queue.html#queue.Empty), если за это время элемент не появился. В противном случае (*block* равен false) возвращает элемент, если он доступен немедленно, иначе вызывает исключение `Empty` (*timeout* в этом случае игнорируется).

До версии 3.0 в системах POSIX и во всех версиях Windows, если *block* истинен и *timeout* равен `None`, эта операция переходит в непрерываемое ожидание на базовой блокировке. Это означает, что никакие исключения не могут возникнуть, и, в частности, SIGINT не вызовет [`KeyboardInterrupt`](https://python-all.ru/3.14/library/exceptions.html#KeyboardInterrupt).

Возбуждает [`ShutDown`](https://python-all.ru/3.14/library/queue.html#queue.ShutDown), если очередь была закрыта и пуста, или если очередь была закрыта немедленно.

#### `Queue.get_nowait()`

Эквивалентно `get(False)`.

Предлагаются два метода для отслеживания того, были ли задачи, поставленные в очередь, полностью обработаны потоками-потребителями-демонами.

#### `Queue.task_done()`

Указывает, что ранее поставленная в очередь задача завершена. Используется потоками-потребителями очереди. Для каждого вызова [`get()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.get), использованного для получения задачи, последующий вызов `task_done()` сообщает очереди, что обработка задачи завершена.

Если [`join()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.join) в данный момент заблокирован, он возобновит работу, когда все элементы будут обработаны (то есть для каждого элемента, который был [`put()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.put) в очередь, был получен вызов `task_done()`).

Возбуждает [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError), если вызывается больше раз, чем было помещено элементов в очередь.

#### `Queue.join()`

Блокируется до тех пор, пока все элементы в очереди не будут получены и обработаны.

Счётчик незавершённых задач увеличивается каждый раз, когда элемент добавляется в очередь. Счётчик уменьшается, когда поток-потребитель вызывает [`task_done()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.task_done), чтобы указать, что элемент был получен и вся работа с ним завершена. Когда счетчик незавершённых задач падает до нуля, `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')
```

### Завершение работы очередей

Когда больше не нужны, объекты [`Queue`](https://python-all.ru/3.14/library/queue.html#queue.Queue) можно постепенно завершить до опустошения или немедленно остановить с помощью жёсткого завершения.

#### `Queue.shutdown(immediate=False)`

Переводит экземпляр [`Queue`](https://python-all.ru/3.14/library/queue.html#queue.Queue) в режим завершения работы.

Очередь больше не может расти. Будущие вызовы [`put()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.put) возбуждают [`ShutDown`](https://python-all.ru/3.14/library/queue.html#queue.ShutDown). Текущие заблокированные вызывающие `put()` будут разблокированы и возбудят `ShutDown` в ранее заблокированном потоке.

Если *immediate* равен false (значение по умолчанию), очередь можно завершить нормально с помощью вызовов [`get()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.get) для извлечения задач, которые уже были загружены.

И если [`task_done()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.task_done) вызывается для каждой оставшейся задачи, ожидающий вызов [`join()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.join) будет разблокирован нормально.

Как только очередь опустеет, последующие вызовы [`get()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.get) будут возбуждать исключение [`ShutDown`](https://python-all.ru/3.14/library/queue.html#queue.ShutDown).

Если *immediate* равен true, очередь завершается немедленно. Очередь опустошается полностью, и счётчик незавершённых задач уменьшается на количество извлечённых задач. Если незавершённых задач нет, вызывающие [`join()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.join) разблокируются. Также блокированные вызывающие [`get()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.get) разблокируются и возбудят исключение [`ShutDown`](https://python-all.ru/3.14/library/queue.html#queue.ShutDown), так как очередь пуста.

Соблюдайте осторожность при использовании [`join()`](https://python-all.ru/3.14/library/queue.html#queue.Queue.join) с параметром *immediate*, установленным в true. Это разблокирует join, даже если над задачами не было проделано никакой работы, нарушая обычный инвариант ожидания завершения очереди.

Добавлено в версии 3.13.

## Объекты SimpleQueue

Объекты [`SimpleQueue`](https://python-all.ru/3.14/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.14/library/queue.html#queue.Queue.put).

**Особенность реализации CPython:** Этот метод имеет реализацию на C, которая является реентерабельной. То есть вызов `put()` или `get()` может быть прерван другим вызовом `put()` в том же потоке без взаимоблокировки или повреждения внутреннего состояния очереди. Это делает его подходящим для использования в деструкторах, таких как методы `__del__` или колбэки [`weakref`](https://python-all.ru/3.14/library/weakref.html#module-weakref).

#### `SimpleQueue.put_nowait(item)`

Эквивалентно `put(item, block=False)`, предусмотрено для совместимости с [`Queue.put_nowait()`](https://python-all.ru/3.14/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.14/library/queue.html#queue.Empty), если за это время элемент не появился. В противном случае (*block* равен false) возвращает элемент, если он доступен немедленно, иначе вызывает исключение `Empty` (*timeout* в этом случае игнорируется).

#### `SimpleQueue.get_nowait()`

Эквивалентно `get(False)`.

> **См. также**
>
> **Класс [`multiprocessing.Queue`](https://python-all.ru/3.14/library/multiprocessing.html#multiprocessing.Queue)**
>
> Класс очереди для использования в контексте многопроцессорной обработки (а не многопоточности).
>
> [`collections.deque`](https://python-all.ru/3.14/library/collections.html#collections.deque) – это альтернативная реализация неограниченных очередей с быстрыми атомарными операциями [`append()`](https://python-all.ru/3.14/library/collections.html#collections.deque.append) и [`popleft()`](https://python-all.ru/3.14/library/collections.html#collections.deque.popleft), которые не требуют блокировок и также поддерживают индексирование.