`BlockingIOError`

BlockingIOError is a built-in exception that occurs when an input/output (I/O) operation would block on an object set to non-blocking mode. This exception is typically raised when a non-blocking operation is requested, but it can’t be completed immediately.

The BlockingIOError exception is part of the OSError family and is specific to I/O operations, such as reading from or writing to a file or a socket.

Unlike other OSError subclasses, BlockingIOError can carry a .characters_written attribute, which holds the number of bytes written to the stream before it blocked. This attribute is available when using the buffered I/O classes from the io module.

You should keep this exception in mind when working with non-blocking I/O, especially in network programming and asynchronous applications.

`BlockingIOError` Occurs When

Performing non-blocking I/O operations on files or sockets
Doing network programming where non-blocking sockets are used

`BlockingIOError` Can Be Used When

Writing asynchronous applications where you want to avoid blocking the main thread

`BlockingIOError` Examples

An example of when the exception appears:

>>> import os

>>> read, write = os.pipe()
>>> os.set_blocking(read, False)

>>> os.read(read, 1024)
Traceback (most recent call last):
    ...
BlockingIOError: [Errno 35] Resource temporarily unavailable

The errno value is platform-dependent. EAGAIN is errno 35 on macOS and other BSD systems but errno 11 on Linux, where the same snippet reports [Errno 11] Resource temporarily unavailable.

An example of how to handle the exception:

>>> import os

>>> read, write = os.pipe()
>>> os.set_blocking(read, False)

>>> try:
...     os.read(read, 1024)
... except BlockingIOError as e:
...     print(f"Caught BlockingIOError: {e}")
... finally:  # Clean up
...     os.close(read)
...     os.close(write)
...
Caught BlockingIOError: [Errno 35] Resource temporarily unavailable

Raising BlockingIOError manually isn’t a common practice because it’s automatically raised by the system when a non-blocking I/O operation can’t be completed immediately.

Tutorial

Python's Built-in Exceptions: A Walkthrough With Examples

In this tutorial, you'll get to know some of the most commonly used built-in exceptions in Python. You'll learn when these exceptions can appear in your code and how to handle them. Finally, you'll learn how to raise some of these exceptions in your code.

intermediate python

For additional information on related topics, take a look at the following resources: