Python Built-in Exceptions

Every exception in Python must be an instance of a class deriving from BaseExceptionThe attempt statement's except clause also deals with any exception classes descended from the class specified in the clause (but not exception classes from which it is derived). Even if they share the same name, two exception classes that are not connected through subclassing are never equal.

The interpreter or built-in functions can produce any of the built-in exceptions described below. They have an "associated value" that, unless otherwise stated, details the error's precise source.This content may take the form of a group or pair (e.g., an error code and a string explaining the code). The constructor of the exception class typically receives the associated value as an argument.

User code has the ability to generate built-in errors. This can be used to evaluate an exception handling mechanism or to report an error condition that is "exactly" the same as the circumstance in which the interpreter produces the same exception, even though there is nothing to prevent user code from generating an incorrect error.

It is recommended that programmers avoid using BaseException and instead create new exceptions from the Exception class or one of its variants.

To define new exceptions, subclasses of the built-in exception classes can be created.

Context for exception

The new exception's __context__ property is instantly set to the handled exception when it is raised while another exception is already being handled. When an except, finally, or with expression is used, an exception may be managed.

By using from with raise, this implied exception context can be strengthened with a specific justification: raise the initial exc to the new etc.

The expression that comes next must be either a None or an exceptionIt will be listed as the __cause__ of the exception. Because of this, when using raise new exc from None, the old exception is changed to the new one for display reasons (such as converting KeyError to AttributeError), but the old exception is still accessible in __context__. This is because setting __cause__ also implicitly sets the __to suppress context__ attribute to True.

Along with the traceback for the specific exception, the standard traceback display code also displays these linked exceptions. When it exists, an explicitly referenced exception in __cause__ is always displayed. Only if __cause__ is None and __suppress context__ is set to false will a tangentially related exception in __context__ be displayed.

The exception itself is always displayed following any chained exceptions, ensuring that the latest exception raised is always displayed on the traceback's final line.

Inheriting from built-in exceptions

Subclasses that descended from an exception type can be made by user-written code. To prevent any potential disputes between how the bases manage the args property and because of potential memory structure issues, it is recommended to only subclass one exception type at a time.

Implementation specifics for CPython: For efficiency, the majority of built-in exceptions are implemented in C; see Objects/exceptions.c. It is hard to design a subclass that inherits numerous exception types because some have unique memory layouts. A type's memory layout is an implementation feature that may vary between Python versions and cause future issues. It is advised to completely refrain from subclassing various exception types.

Base classes

The exceptions listed below serve mostly as basic classes for further exceptions.

exception BaseException

all built-in exceptions' base class. It is not intended for user-defined classes to directly inherit from it (for that, use Exception). When calling str() on a component of this class, the representation of the argument(s) to the instance is returned, or the empty text if there were none.

args

the tuple of inputs passed to the constructor of the exception. Some built-in exceptions, such as OSError, need a specific number of arguments and give the elements of this tuple a special significance, although others are typically called just with a single string that contains the error message.

with traceback(tb)

This function updates tb to the updated traceback for the exception and returns the exception object. It was used more commonly prior to the introduction of PEP 3134's exception chaining functionality. The example that follows shows how to keep the traceback while converting a SomeException instance into an OtherException instance. Once raised, the current frame is added to the OtherException's traceback, just as it would have done to the original SomeException's traceback had we allowed it to reach the caller.

try:
    ...
Except for SomeException:
    tb = sys.exc_info()[2]
    raise OtherException(...).with_traceback(tb)

Append the string note to the exception's notes, which follow the exception string in the normal traceback. Note not being a string causes a TypeError to be triggered.

Updated for version 3.11.

__notes__

a list of the notes that were added to this exception using add note (). When add a note() is called, this attribute is created.

Updated for version 3.11.

exclusion Exclusion

This class is the root of all built-in exceptions that don't cause the system to quit. It is recommended that all user-defined exceptions originate from this class.

exception ArithmeticError

The foundation class for the built-in exceptions OverflowError, ZeroDivisionError, and FloatingPointError is raised for different arithmetic problems.

exception BufferError

When a buffer-related operation fails, this flag is raised.

exception LookupError

The fundamental classes for exceptions raised when a key or index used in a mapping or series is incorrect are IndexError and KeyError. This can be immediately raised by codecs.

lookup().

specific exceptions

The exceptions that are frequently raised are listed below.

exception AssertionError

when a to assert statement fails raised.

exception AttributeError

raised whenever an assignment or attribute reference (see Attribute references) fails. (TypeError is generated when an object does not accept attribute references or attribute assignments at all.)

By providing the constructor with keyword-only arguments, the name and obj attributes can be changed. They stand in for the name of the attempted-to-be-accessed attribute and the object for the said attribute when set, respectively.

Version 3.10 was modified by the addition of the name and obj attributes.

EOFError exception

When the input() method encounters the EOF situation (end-of-file) without reading any data, this value is raised. (Note: When they reach EOF, the io.IOBase.read() and io.IOBase.readline() functions return an empty string.)

exception FloatingPointError

Not in use right now.

exception GeneratorExit

A raised number is given when a generator or coroutine ends; see generator. close() and coroutine. close (). It immediately descends from BaseException rather than Exception because it isn't a mistake.

exception ImportError

raised whenever an import statement attempts to load a module but fails. The issue is also brought up when a name in the "from list" in the from... import cannot be located.

By providing the constructor with keyword-only arguments, the name and path attributes can be changed. When set, they stand for the attempted import attempt's name of the module and the location of the file that caused the exception, respectively.

The name and path attributes were added in version 3.3.

exception ModuleNotFoundError

a subclass of ImportError that import throws when a module can't be found. Moreover, it is raised if None is seen in sys. modules.

updated to version 3.6.

exception IndexError

when a sequence subscript is out of bounds, raised. If a slice index is not an integer, a TypeError is raised (slice indices are discreetly shortened to fall within the permitted range).

exception KeyError

raised when the collection of available keys does not contain a mapping (dictionary) key.

exception when a user hits the interrupt key, raised keyboard alert (normally Control-C or Delete). While the software is running, regular interruption tests are carried out. The exception derives from BaseException so that it won't be accidentally captured by code that captures an Exception and keeps the interpreter from stopping.

Note KeyboardInterrupts must be caught with extra care. It may occasionally leave the running application in an inconsistent state because it can be raised at random intervals. The program should typically be terminated as soon as feasible by allowing KeyboardInterrupt to do so, or it should not be raised at all. (See Note on Exceptions and Signal Handlers.)

exception MemoryError

raised when memory is exhausted during an operation but a rescue is still possible (by deleting some objects). A string identifying the type of (internal) operation that ran out of memory is the related value. The processor may not always be able to fully recover from this situation due to the underlying memory management design (C's malloc() function), but it still raises an exception so that a stack traceback can be shown in case a runaway program was to blame.

exception NameError

when a local or global name cannot be located. It only applies to names that are not qualified. A message with an error and the name that couldn't be located in the related value.

exception NotImplementedError

RuntimeError is the ancestor of this exception. When derived classes must modify an abstract method or while the class is still being constructed, the abstract method in the user-defined parent class should trigger this exception to signal that the actual implementation must be added.

Note Never use it to indicate that a method or operator isn't meant to be enabled at all; in that case, keep the method or operator undefined or, if it's a subclass, assign it to None.

Note Despite having identical names and objectives, NotImplementedError and NotImplemented cannot be used interchangeably. Information on when to use it is provided in NotImplemented.

exception OSError([arg])

exception OSError(errno, strerror[, filename[, winerror[, filename2]]]) (errno, strerror[, filename[, winerror[, filename2]]])

This exception is triggered whenever a system function returns a system-related mistake, such as an I/O failure like "file not found" or "disk full" (not for illegal argument types or other incidental errors).

The related properties, which are explained below, are set by the constructor's second iteration. If not given, the characteristics default to NoneFor backward compatibility, if three inputs are provided, the args property only includes a 2-tuple of the first two constructor arguments.

In reality, the constructor frequently produces a subclass of OSError, as discussed in the section below on OS exceptions. The final errno value determines which subclass to use. This behavior is not inherited when subclassing; it only manifests itself when OSError is constructed directly or through an alias.

errno

an error number from the errno variable in C.

filename \sfilename2

When a file system path exception occurs (such as when using open() or os. unlink()), Filename is the file name that was passed to the method. Filename2 is the second file name that is supplied to functions that use two file system paths (like os. rename()).

EnvironmentError, IOError, WindowsError, socket. error, select. error, and map. error have all been combined into OSError in version 3.3, and the constructor now has the option of returning a subclass.

The initial file name provided to the procedure is now the filename property rather than the name encoded to or decoded from the filesystem encoding and error handler. Moreover, the constructor parameter and attribute for filename2 were introduced. In error

This provides you with the standard Windows error code. The errno attribute then roughly translates that native error code into POSIX terminology.

If the win error constructor input is an integer, Windows uses the win error code to calculate the errno property and skips the errno parameter. On other systems, neither the win error argument nor the winerror property exists.

strerror

The associated error message that the operating system provides. On POSIX and Windows, it is formatted by the C methods error () and FormatMessage(), respectively.

exception OverflowError

The number is increased when the result of an arithmetic action is too big to be represented. With numbers, this is not feasible (which would rather raise MemoryError than give up). OverflowError is, however, occasionally raised for integers that are outside of a specified range due to historical factors. The majority of floating point operations in C are not verified due to the absence of standards in floating point exception handling.

exception RecursionError

RuntimeError is the ancestor of this exception. When the maximum recursion depth (see sys. getrecursionlimit()) is exceeded, the interpreter raises this error.

A plain RuntimeError was previously raised. This is new in version 3.5.

reference error exception

This mistake happens when a weak reference proxy created by the weaker is used to reach a referent's property. after the referent has been trash collected, use the proxy() method. See the weakref module for additional details on weak references.

exception RuntimeError

raised whenever a mistake that doesn't fit into one of the other categories is discovered. The associated value is a string that details the specific error.

exception StopIteration

It is raised by the iterator's __next__() method and the built-in function next() to indicate that no more items will be created by the iterator.

While creating the exception, a single attribute value is provided as an argument, and by default, it is None.

When a generator or coroutine function completes, a new StopIteration instance is raised, and the constructor of the exception receives the value returned by the function as the value argument.

If a generator code raises StopIteration directly or indirectly, the StopIteration is kept as the new exception's cause and the RuntimeError is created instead.

Generator functions can now use the value functionality to output values thanks to its introduction in version 3.3.

Changes in version 3.5: The RuntimeError change first appeared in PEP 479, which added the __future__ import generator stop.

Version 3.7 introduced a change that enabled PEP 479 by default for all code, turning a StopIteration error that occurred in a generator into a RuntimeError.

exception StopAsyncIteration

To halt iteration, an asynchronous iterator object's __anext__() method must raise the appropriate exception.

Updated in version 3.5.

exception SyntaxError(message, details) (message, details)

triggered when the parser finds a grammar mistake. This might occur when the built-in methods compile(), exec(), or eval() are called, when reading the original script or standard input, or when using an import line (also interactively).

Just the error message is returned by the exception instance's str() method. A tuple called Details has members that are also available as individual attributes.

filename

the name of the file that had the syntax mistake.

linen

which line in the file contained the problem. This is 1-indexed, and the file's first line has a line value of 1.

offset

the line's column containing the error. The first character on the line has an offset of 1, making this 1-indexed.

text

The text in the source code that caused the mistake.

end lineno

which line in the file the issue happened on is at the end. This is 1-indexed, and the file's first line has a lineno value of 1.

end offset

The final line's final column is where the mistake happened. This is 1-indexed since the first letter on the line has a shift of 1.

The offsets are offsets in a text that is generated from the substitute formula for mistakes in f-string fields, and the message is preceded with "f-string:"

For instance, when the I’d a b field is compiled, the following args attribute is produced: ('f-string:...', (", 1, 2, '(a b)n', 1, 5)).

Version 3.10 changes: end lineno and end offset characteristics were added.

exception IndentationError

base class for syntax mistakes brought caused by improper indentation. This is a SyntaxError subclass.

exception TabError

raised when tabs and spaces are used erratically in indentation. This is an IndentationError subclass.

exception SystemError

raised when the interpreter discovers an internal mistake, but the circumstance does not seem dire enough to make it give up on finding a solution. The associated value is a string that describes the error (in low-level terms).

You should tell this to the person who created or maintains your Python program. Include the full error message (the exception's related value), the Python interpreter version (sys. version; this information is also displayed at the beginning of a live Python session), and, if it's possible, the name of the program that malfunctioned.

exception SystemExit

The sys. exit() function causes this exception to be thrown. It inherits from BaseException rather than Exception to prevent being unintentionally caught by code that catches Exception. This makes it possible for the exception to rise properly and cause the parser to shut down. If it is not managed, the Python program exits without displaying a stack traceback. Exactly the same additional argument as sys is accepted by the constructor ().

If the value is None, the exit status is zero. If it belongs to another class (such as a string), the object's value will appear. If not, the exit status is one. The system departure state is specified (and provided to the exit() function in C) if the number is an integer.

So that fresh handlers (the end sections of try commands) can be executed and a debugger can execute a script without fretting about losing control, a call to sys. exit() is converted into an exception.

The os. exit() method can be used if an immediate exit is definitely, certainly needed, such as in the child process following a request to os. fork().

Code

The constructor is given the exit status or error message. (Standard value: None.)

exception TypeError

raised when an improperly suited item is subjected to an operation or function. A string containing information about the type mismatch is the associated value.

This exception may be thrown by user programs to signal that an operation being attempted on an object is neither supported nor meant to be. NotImplementedError should be triggered if an object is intended to allow a specific action but has not yet provided an implementation.

In contrast to passing arguments with the incorrect value, such as a number outside of expected limits, passing arguments of the incorrect type, such as giving a list when an int is intended, should result in a TypeError.

exception UnboundLocalError

Raised whenever a local variable is referred to in a function or procedure without having a value yet. This is a subtype of NameError.

exception UnicodeError

raised whenever an encoding or decoding mistake involving Unicode happens. It belongs to the ValueError subclass.

The encoding or decoding error is described via characteristics of the UnicodeError class. err. object[err. start:err. end], for instance, displays the specific incorrect input that the codec failed on.

encoding

the identification of the offending encoding.

reason

a string that details the particular codec fault.

object

whatever it was that the codec was trying to encode or decode.

start

the object's first incorrect data index.

end

the index following the object's most recent incorrect data.

exception UnicodeEncodeError

raised when an encoding issue involving Unicode happens. It belongs to the UnicodeError subclass.

exception UnicodeDecodeError

raised whenever a decoding error involving Unicode happens. It belongs to the UnicodeError subclass.

exception UnicodeTranslateError

raised whenever a translation error involving Unicode happens. It belongs to the UnicodeError subclass.

exception ValueError

When an action or function gets an input with the correct type but the incorrect value and no other exception, such as IndexError, better explains the circumstance, this exception is raised.

exception ZeroDivisionError

raised if a division or modulo operation's second parameter is zero. A string identifying the type of the operands and the operation is the related value.

The following exceptions, which are aliases of OSError as of Python 3.3, are kept around for backward compatibility.

exception EnvironmentError \sexception IOError \sexception Only available on Windows, WindowsError.

OS deviations

The following exceptions are OSError subclasses and are raised by the system error code.

exception BlockingIOError

Raised if an operation on an object (such as a socket) designated for the non-blocking operation would cause it to block. is equivalent to the errno values EAGAIN, EALREADY, EWOULDBLOCK, and IN PROGRESS.

BlockingIOError can have one extra attribute in addition to the ones of OSError:

characters written

An integer is used to indicate how many characters were posted to the stream prior to it stopping. This property is available when using the buffered I/O classes from the io package.

exception ChildProcessError

raised after an unsuccessful operation on a child process. coincides with errno ECHILD.

ConnectionError is an exception

a foundational class for problems with connections.

BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError, and ConnectionResetError are examples of subclasses.

exception BrokenPipeError

When attempting to write on a pipe with the other end closed or a socket that has been disabled for writing, a subclass of ConnectionError is raised. matches the errno values EPIPE and ESHUTDOWN.

exception ConnectionAbortedError

When a peer cancels a connection attempt, a subclass of ConnectionError is raised. equal to the ECONNABORTED error number.

exception ConnectionRefusedError

A subtype of ConnectionError is raised when a peer declines to accept a connection request. in the same league as the mistake number ECONNREFUSED.

a ConnectionResetError exception

A subtype of ConnectionError is triggered when a connection is reset by the peer. corresponds to the error number ECONNRESET. When trying to make a directory or file that already exists, FileExistsError is thrown. responds to the EEXIST warning number.

exception FileNotFoundError

raised when a directory or file is sought after but is not found. is equivalent to errno ENOENT.

exception InterruptedError

raised if an incoming signal causes a system call to be halted. matches the error code EINTR.

Version 3.5 changes: When a signal interrupts a system call, Python now attempts the system call again, unless the signal handler throws an exception (see PEP 475 for the explanation), in which case it issues InterruptedError.

exception If a directory is the target of a file action (like os. remove()), IsADirectoryError is triggered. corresponds to the error number EISDIR.

exception NotADirectoryError

raised if an object that isn't a directory is asked to perform a directory operation, such as os. listdir(). It may also be raised if an operation tries to access or traverse a non-directory file as if it were a directory on the majority of POSIX platforms. in agreement with errno ENOTDIR.

exception PermissionError

raised while attempting to operate without having the proper access privileges, such as filesystem permissions. in accord with EACCES's errno.

Version 3.11.1 of WASI now maps the ENOTCAPABLE exception to PermissionError. exception ProcessLookupError

alerted if a particular procedure is not present. corresponds to errno ESRCH.

exception When a system procedure at the system level ran out of time, a TimeoutError was reported.

. replies to the error code ETIMEDOUT.

All of the aforementioned OSError subclasses were added in version 3.3.

PEP 3151 deals with restructuring the OS and IO exception structures.

Warnings

The following cases are used as caution categories; for more details, see the documentation for warning categories.

exception Category base class for warnings.

exception UserWarning User code-generated warnings' base class.

exception DeprecationWarning

Basic class for deprecated feature warnings when those warnings are directed at other Python programmers.

except in the __main__ module, not taken into account by the default warning filters (PEP 565). This warning appears when the Python Development Mode is enabled.

PEP 387 provides information on the deprecation policy.

PendingDeprecationWarning Base class for alerts about features that are no longer required, are slated to be discontinued but have not yet done so.

Because DeprecationWarning is favored for already live deprecations and issuing a warning about a possible upcoming deprecation is unusual, this class is infrequently used.

ignored by the built-in alert filters. This warning appears when the Python Development Mode is enabled.

PEP 387 provides information on the deprecation policy.

warning SyntaxException

Basic class for syntax-related alerts.

exception RuntimeWarning

Basic class for alerts regarding questionable runtime behavior.

exception FutureWarning Basic class for deprecated feature warnings when those warnings are directed to users of Python-coded programs.

warning ImportException

Basic class for alerts regarding potential errors in module imports.

ignored by the built-in alert filters. This warning appears when the Python Development Mode is enabled.

warnings about Unicode are contained in the base class UnicodeWarning. exception

Basic class for warnings about encodings, EncodingWarning

For information, see Opt-in EncodingWarning.

brand-new in 3.10

exception BytesWarning

Basic class for bytes and bytearray-related warnings.

exception ResourceWarning Resource usage-related warnings' base class.

ignored by the built-in alert filters. This warning appears when the Python Development Mode is enabled.

updated to version 3.2.

Exceptional teams

When it's required to raise several unrelated exceptions, the following are employed. They can be handled with the exceptions just like any other exceptions because they are a member of the exception hierarchy. Moreover, except*, which matches their subgroups based on the kinds of the included exceptions, recognizes them.

exception ExceptionGroup(msg, excs) (msg, excs)
exception BaseExceptionGroup(msg, excs) (msg, excs)

The exceptions in the sequence excs are wrapped by both of these exception types. Strings are required for the msg parameter. In contrast to ExceptionGroup, which extends Exception and can only encompass instances of that class, BaseExceptionGroup extends BaseException and can wrap any exception. The distinction between the two groups is as follows.

This architecture allows Exception to receive an ExceptionGroup but not a BaseExceptionGroup.

If all enclosed exceptions are Exception instances, the BaseExceptionGroup constructor produces an ExceptionGroup rather than a BaseExceptionGroup, allowing the selection to be automated. On the other hand, if any of the exceptions stored in it are not an Exception subtype, the ExceptionGroup constructor generates a TypeError.

message

The constructor's message argument This attribute can only be read.

exceptions A list of each exception in the constructor's excs sequence, represented as a tuple. This characteristic can only be read.

If the outcome is empty, Subgroup(condition) returns None; otherwise, it returns an exception group that only contains the exceptions from the current group that fit condition.

The condition could be a function that accepts an exception and returns true for those that come under the subgroup, or it could be an exception type or tuple of exception types that are used to check for a match using the same check as an except clause.

The current exception's nesting structure and the contents of its message, __traceback__, __cause__, __context__, and __notes__ fields are both retained in the result. Nests of empty groups.

All exceptions in the inner exception group as well as the top-level and any subordinate exception groups are checked.

Such an exception group is fully included in the result if the criteria is met.

split(condition)

Like subgroup(), but yields the pair (match, rest), where match is the remaining portion of the subgroup's non-matching component (condition).

derive(excs) yields an exception group with the same message but with the exceptions wrapped in excs.

Subgroup() and Split both employ this technique (). For subgroup() and split() to return instances of the subclass rather than ExceptionGroup, a subclass must override it.

The __traceback__, __cause__, __context__, and __notes__ fields from the original exception group are copied by subgroup() and split() to the exception group returned by derive ().

class MyGroup(ExceptionGroup):
    def derive(self, exc):
        return MyGroup(self.message, exc)
e = MyGroup("eg", [ValueError(1), TypeError(2)])
e.add_note("a note")
e.__context__ = Exception("context")
e.__cause__ = Exception("cause")
try:
   raise e
except Exception as e:
   exc = e
match, rest = exc.split(ValueError)
exc, exc.__context__, exc.__cause__, exc.__notes__
(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
match, match.__context__, match.__cause__, match.__notes__
(MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), ['a note'])
rest, rest.__context__, rest.__cause__, rest.__notes__
(MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
exc.__traceback__ is match.__traceback__ is rest.__traceback__
True