Ngoại lệ tích hợp

Trong Python, tất cả các ngoại lệ phải là phiên bản của một lớp bắt nguồn từ BaseException. Trong câu lệnh try có mệnh đề except đề cập đến một lớp cụ thể, mệnh đề đó cũng xử lý mọi lớp ngoại lệ bắt nguồn từ lớp đó (nhưng không xử lý các lớp ngoại lệ mà it bắt nguồn). Hai lớp ngoại lệ không liên quan thông qua phân lớp con sẽ không bao giờ tương đương nhau, ngay cả khi chúng có cùng tên.

Các ngoại lệ tích hợp được liệt kê trong chương này có thể được tạo ra bởi trình thông dịch hoặc các hàm tích hợp. Trừ khi được đề cập, chúng có "giá trị liên quan" cho biết nguyên nhân chi tiết của lỗi. Đây có thể là một chuỗi hoặc một bộ gồm nhiều mục thông tin (ví dụ: mã lỗi và chuỗi giải thích mã). Giá trị liên quan thường được truyền dưới dạng đối số cho hàm tạo của lớp ngoại lệ.

Mã người dùng có thể đưa ra các ngoại lệ tích hợp. Điều này có thể được sử dụng để kiểm tra trình xử lý ngoại lệ hoặc để báo cáo tình trạng lỗi "giống như" tình huống mà trình thông dịch đưa ra cùng một ngoại lệ; nhưng hãy lưu ý rằng không có gì ngăn cản mã người dùng gây ra lỗi không phù hợp.

Các lớp ngoại lệ tích hợp có thể được phân lớp để xác định các ngoại lệ mới; các lập trình viên được khuyến khích rút ra các ngoại lệ mới từ lớp Exception hoặc một trong các lớp con của nó chứ không phải từ BaseException. Thông tin thêm về cách xác định ngoại lệ có sẵn trong Hướng dẫn Python trong Ngoại lệ do người dùng xác định.

Bối cảnh ngoại lệ

Ba thuộc tính trên các đối tượng ngoại lệ cung cấp thông tin về bối cảnh trong đó ngoại lệ được nêu ra:

BaseException.__context__

BaseException.__cause__

BaseException.__suppress_context__

Khi đưa ra một ngoại lệ mới trong khi một ngoại lệ khác đang được xử lý, thuộc tính __context__ của ngoại lệ mới sẽ tự động được đặt thành ngoại lệ đã được xử lý. Một ngoại lệ có thể được xử lý khi sử dụng mệnh đề except hoặc finally hoặc câu lệnh with.

Bối cảnh ngoại lệ tiềm ẩn này có thể được bổ sung bằng một nguyên nhân rõ ràng bằng cách sử dụng from với raise:

tăng new_exc từ original_exc

Biểu thức theo sau from phải là một ngoại lệ hoặc None. Nó sẽ được đặt là __cause__ trên ngoại lệ được nêu ra. Việc đặt __cause__ cũng ngầm đặt thuộc tính __suppress_context__ thành True, sao cho việc sử dụng raise new_exc from None sẽ thay thế ngoại lệ cũ bằng ngoại lệ mới một cách hiệu quả cho mục đích hiển thị (ví dụ: chuyển đổi KeyError thành AttributeError), trong khi vẫn giữ nguyên ngoại lệ cũ trong __context__ để xem xét nội tâm khi gỡ lỗi.

Mã hiển thị truy nguyên mặc định hiển thị các ngoại lệ theo chuỗi này ngoài dấu vết cho chính ngoại lệ đó. Một ngoại lệ được xâu chuỗi rõ ràng trong __cause__ luôn được hiển thị khi có mặt. Một ngoại lệ được xâu chuỗi ngầm trong __context__ chỉ được hiển thị nếu __cause__ là None và __suppress_context__ là sai.

Trong cả hai trường hợp, ngoại lệ luôn được hiển thị sau bất kỳ ngoại lệ theo chuỗi nào để dòng cuối cùng của truy nguyên luôn hiển thị ngoại lệ cuối cùng được nêu ra.

Kế thừa từ các ngoại lệ tích hợp

Mã người dùng có thể tạo các lớp con kế thừa từ một loại ngoại lệ. Bạn chỉ nên phân lớp một loại ngoại lệ tại một thời điểm để tránh mọi xung đột có thể xảy ra giữa cách các cơ sở xử lý thuộc tính args, cũng như do khả năng không tương thích về bố cục bộ nhớ.

Hầu hết các ngoại lệ tích hợp đều được triển khai trong C để đạt hiệu quả, xem: Objects/exceptions.c. Một số có bố cục bộ nhớ tùy chỉnh khiến không thể tạo lớp con kế thừa từ nhiều loại ngoại lệ. Bố cục bộ nhớ của một loại là một chi tiết triển khai và có thể thay đổi giữa các phiên bản Python, dẫn đến những xung đột mới trong tương lai. Do đó, nên tránh phân lớp hoàn toàn nhiều loại ngoại lệ.

Lớp cơ sở

Các ngoại lệ sau đây được sử dụng chủ yếu làm lớp cơ sở cho các ngoại lệ khác.

exception BaseException

Lớp cơ sở cho tất cả các ngoại lệ tích hợp. Nó không có nghĩa là được kế thừa trực tiếp bởi các lớp do người dùng định nghĩa (để làm được điều đó, hãy sử dụng Exception). Nếu str() được gọi trên một phiên bản của lớp này, thì việc biểu diễn (các) đối số cho phiên bản đó sẽ được trả về hoặc chuỗi trống khi không có đối số.

args

Bộ đối số được cung cấp cho hàm tạo ngoại lệ. Một số ngoại lệ tích hợp (như OSError) mong đợi một số lượng đối số nhất định và gán ý nghĩa đặc biệt cho các thành phần của bộ dữ liệu này, trong khi những ngoại lệ khác thường chỉ được gọi bằng một chuỗi duy nhất đưa ra thông báo lỗi.

with_traceback(tb)

Phương thức này đặt tb làm truy nguyên mới cho ngoại lệ và trả về đối tượng ngoại lệ. Nó được sử dụng phổ biến hơn trước khi các tính năng chuỗi ngoại lệ của PEP 3134 có sẵn. Ví dụ sau đây cho thấy cách chúng ta có thể chuyển đổi một phiên bản của SomeException thành một phiên bản của OtherException trong khi vẫn duy trì dấu vết. Sau khi được nâng lên, khung hiện tại sẽ được đẩy lên truy nguyên của OtherException, giống như điều sẽ xảy ra với truy nguyên của SomeException ban đầu nếu chúng tôi cho phép nó truyền tới người gọi.

thử:
    ...
ngoại trừ một số ngoại lệ:
    tb = sys.Exception().__traceback__
    nâng cao OtherException(...).with_traceback(tb)

__traceback__

Trường có thể ghi chứa traceback object được liên kết với ngoại lệ này. Xem thêm: Tuyên bố raise.

add_note(note)

Thêm chuỗi note vào ghi chú của ngoại lệ xuất hiện trong truy nguyên tiêu chuẩn sau chuỗi ngoại lệ. Một TypeError được nâng lên nếu note không phải là một chuỗi.

Added in version 3.11.

__notes__

Danh sách các ghi chú của ngoại lệ này, đã được thêm bằng add_note(). Thuộc tính này được tạo khi add_note() được gọi.

Added in version 3.11.

exception Exception

Tất cả các ngoại lệ tích hợp sẵn, không thoát khỏi hệ thống đều bắt nguồn từ lớp này. Tất cả các ngoại lệ do người dùng định nghĩa cũng phải được bắt nguồn từ lớp này.

exception ArithmeticError

Lớp cơ sở dành cho các ngoại lệ tích hợp được đưa ra để khắc phục các lỗi số học khác nhau: OverflowError, ZeroDivisionError, FloatingPointError.

exception BufferError

Xảy ra khi không thể thực hiện thao tác liên quan đến buffer.

exception LookupError

Lớp cơ sở dành cho các ngoại lệ được nêu ra khi khóa hoặc chỉ mục được sử dụng trên ánh xạ hoặc chuỗi không hợp lệ: IndexError, KeyError. Điều này có thể được nêu trực tiếp bởi codecs.lookup().

Ngoại lệ cụ thể

Các ngoại lệ sau đây là những ngoại lệ thường được nêu ra.

exception AssertionError

Xảy ra khi câu lệnh assert không thành công.

exception AttributeError

Xảy ra khi tham chiếu thuộc tính (xem Tham chiếu thuộc tính) hoặc gán không thành công. (Khi một đối tượng hoàn toàn không hỗ trợ tham chiếu thuộc tính hoặc gán thuộc tính, TypeError sẽ được nâng lên.)

Các đối số chỉ từ khóa name và obj tùy chọn sẽ đặt các thuộc tính tương ứng:

name

Tên của thuộc tính đã được cố gắng truy cập.

obj

Đối tượng được truy cập cho thuộc tính được đặt tên.

Thay đổi trong phiên bản 3.10: Đã thêm thuộc tính name và obj.

exception EOFError

Xảy ra khi hàm input() gặp phải điều kiện cuối tệp (EOF) mà không đọc bất kỳ dữ liệu nào. (Lưu ý: phương thức io.TextIOBase.read() và io.IOBase.readline() trả về một chuỗi trống khi chúng chạm vào EOF.)

exception FloatingPointError

Hiện tại không được sử dụng.

exception GeneratorExit

Tăng lên khi đóng generator hoặc coroutine; xem generator.close() và coroutine.close(). Nó kế thừa trực tiếp từ BaseException thay vì Exception vì về mặt kỹ thuật đây không phải là lỗi.

exception ImportError

Xảy ra khi câu lệnh import gặp sự cố khi tải mô-đun. Cũng được nêu ra khi "từ danh sách" trong from ... import có tên không thể tìm thấy.

Các đối số chỉ từ khóa name và path tùy chọn sẽ đặt các thuộc tính tương ứng:

name

Tên của mô-đun đã được cố gắng nhập.

path

Đường dẫn đến bất kỳ tệp nào đã kích hoạt ngoại lệ.

Thay đổi trong phiên bản 3.3: Đã thêm thuộc tính name và path.

exception ModuleNotFoundError

Một lớp con của ImportError được import nâng lên khi không thể định vị được mô-đun. Nó cũng được nâng lên khi tìm thấy None trong sys.modules.

Added in version 3.6.

exception IndexError

Xảy ra khi chỉ số thứ tự nằm ngoài phạm vi. (Chỉ số lát cắt được cắt bớt một cách âm thầm để rơi vào phạm vi cho phép; nếu chỉ mục không phải là số nguyên, TypeError sẽ được nâng lên.)

exception KeyError

Xảy ra khi không tìm thấy khóa ánh xạ (từ điển) trong bộ khóa hiện có.

exception KeyboardInterrupt

Tăng lên khi người dùng nhấn phím ngắt (thông thường là Control-C hoặc Delete). Trong quá trình thực hiện, việc kiểm tra các ngắt được thực hiện thường xuyên. Ngoại lệ kế thừa từ BaseException để không vô tình bị bắt bởi mã bắt Exception và do đó ngăn trình thông dịch thoát ra.

Ghi chú

Việc bắt được một con KeyboardInterrupt cần phải được cân nhắc đặc biệt. Vì nó có thể được nâng lên ở những điểm không thể đoán trước nên trong một số trường hợp, nó có thể khiến chương trình đang chạy ở trạng thái không nhất quán. Nói chung, tốt nhất là cho phép KeyboardInterrupt kết thúc chương trình càng nhanh càng tốt hoặc tránh nâng cấp nó hoàn toàn. (Xem Lưu ý về Trình xử lý tín hiệu và ngoại lệ.)

exception MemoryError

Xảy ra khi một thao tác hết bộ nhớ nhưng tình huống đó vẫn có thể được giải quyết (bằng cách xóa một số đối tượng). Giá trị liên quan là một chuỗi cho biết loại hoạt động (nội bộ) nào đã hết bộ nhớ. Lưu ý rằng do kiến ​​trúc quản lý bộ nhớ cơ bản (hàm malloc() của C), không phải lúc nào trình thông dịch cũng có thể khôi phục hoàn toàn sau tình huống này; tuy nhiên, nó đưa ra một ngoại lệ để có thể in truy nguyên ngăn xếp, trong trường hợp nguyên nhân là do một chương trình chạy xa.

exception NameError

Xảy ra khi không tìm thấy tên địa phương hoặc tên chung. Điều này chỉ áp dụng cho những tên không đủ tiêu chuẩn. Giá trị liên quan là thông báo lỗi bao gồm tên không thể tìm thấy.

Đối số chỉ từ khóa name tùy chọn đặt thuộc tính:

name

Tên của biến đã được cố gắng truy cập.

Thay đổi trong phiên bản 3.10: Đã thêm thuộc tính name.

exception NotImplementedError

Ngoại lệ này có nguồn gốc từ RuntimeError. Trong các lớp cơ sở do người dùng định nghĩa, các phương thức trừu tượng sẽ đưa ra ngoại lệ này khi chúng yêu cầu các lớp dẫn xuất ghi đè phương thức hoặc trong khi lớp đang được phát triển để chỉ ra rằng việc triển khai thực sự vẫn cần được thêm vào.

Ghi chú

Nó không nên được sử dụng để chỉ ra rằng một toán tử hoặc phương thức hoàn toàn không được hỗ trợ -- trong trường hợp đó, hãy để toán tử / phương thức đó không được xác định hoặc, nếu là một lớp con, hãy đặt nó thành None.

Cảnh báo

NotImplementedError và NotImplemented không thể thay thế cho nhau. Ngoại lệ này chỉ nên được sử dụng như mô tả ở trên; xem NotImplemented để biết chi tiết về cách sử dụng đúng hằng số tích hợp.

exception OSError([arg])

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

Ngoại lệ này xuất hiện khi một hàm hệ thống trả về lỗi liên quan đến hệ thống, bao gồm cả lỗi I/O như "không tìm thấy tệp" hoặc "đĩa đầy" (không dành cho các loại đối số bất hợp pháp hoặc các lỗi ngẫu nhiên khác).

Dạng thứ hai của hàm tạo đặt các thuộc tính tương ứng, được mô tả bên dưới. Các thuộc tính mặc định là None nếu không được chỉ định. Để tương thích ngược, nếu ba đối số được truyền, thuộc tính args chỉ chứa 2 bộ trong số hai đối số hàm tạo đầu tiên.

Hàm tạo thường thực sự trả về một lớp con của OSError, như được mô tả trong OS exceptions bên dưới. Lớp con cụ thể phụ thuộc vào giá trị errno cuối cùng. Hành vi này chỉ xảy ra khi xây dựng OSError trực tiếp hoặc thông qua bí danh và không được kế thừa khi phân lớp.

errno

Mã lỗi số từ biến C errno.

winerror

Trong Windows, điều này cung cấp cho bạn mã lỗi gốc của Windows. Khi đó, thuộc tính errno là bản dịch gần đúng, theo thuật ngữ POSIX, của mã lỗi gốc đó.

Trong Windows, nếu đối số hàm tạo winerror là số nguyên thì thuộc tính errno được xác định từ mã lỗi Windows và đối số errno bị bỏ qua. Trên các nền tảng khác, đối số winerror bị bỏ qua và thuộc tính winerror không tồn tại.

strerror

Thông báo lỗi tương ứng do hệ điều hành cung cấp. Nó được định dạng bằng các hàm C perror() trong POSIX và FormatMessage() trong Windows.

filename

filename2

Đối với các trường hợp ngoại lệ liên quan đến đường dẫn hệ thống tệp (chẳng hạn như open() hoặc os.unlink()), filename là tên tệp được truyền cho hàm. Đối với các hàm liên quan đến hai đường dẫn hệ thống tệp (chẳng hạn như os.rename()), filename2 tương ứng với tên tệp thứ hai được truyền cho hàm.

Thay đổi trong phiên bản 3.3: EnvironmentError, IOError, WindowsError, socket.error, select.error và mmap.error đã được hợp nhất thành OSError và hàm tạo có thể trả về một lớp con.

Thay đổi trong phiên bản 3.4: Thuộc tính filename hiện là tên tệp gốc được truyền cho hàm, thay vì tên được mã hóa hoặc giải mã từ filesystem encoding and error handler. Ngoài ra, đối số và thuộc tính của hàm tạo filename2 đã được thêm vào.

exception OverflowError

Xảy ra khi kết quả của phép tính số học quá lớn không thể biểu diễn được. Điều này không thể xảy ra đối với các số nguyên (thà tăng MemoryError hơn là bỏ cuộc). Tuy nhiên, vì lý do lịch sử, OverflowError đôi khi được nâng lên đối với các số nguyên nằm ngoài phạm vi bắt buộc. Do thiếu tiêu chuẩn hóa việc xử lý ngoại lệ dấu phẩy động trong C nên hầu hết các thao tác dấu phẩy động đều không được kiểm tra.

exception PythonFinalizationError

Ngoại lệ này có nguồn gốc từ RuntimeError. Nó xuất hiện khi một thao tác bị chặn trong quá trình tắt trình thông dịch, còn được gọi là Python finalization.

Ví dụ về các hoạt động có thể bị chặn bằng PythonFinalizationError trong quá trình hoàn thiện Python:

• Tạo một luồng Python mới.

• Joining một chuỗi daemon đang chạy.

• os.fork().

Xem thêm chức năng sys.is_finalizing().

Added in version 3.13: Trước đây, một RuntimeError đơn giản đã được đưa ra.

Thay đổi trong phiên bản 3.14: threading.Thread.join() hiện có thể đưa ra ngoại lệ này.

exception RecursionError

Ngoại lệ này có nguồn gốc từ RuntimeError. Nó được nâng lên khi trình thông dịch phát hiện thấy độ sâu đệ quy tối đa (xem sys.getrecursionlimit()) bị vượt quá.

Added in version 3.5: Trước đây, một RuntimeError đơn giản đã được đưa ra.

exception ReferenceError

Ngoại lệ này xuất hiện khi một proxy tham chiếu yếu, được tạo bởi hàm weakref.proxy(), được sử dụng để truy cập thuộc tính của tham chiếu sau khi nó được thu thập rác. Để biết thêm thông tin về các tài liệu tham khảo yếu, hãy xem mô-đun weakref.

exception RuntimeError

Xảy ra khi phát hiện thấy lỗi không thuộc bất kỳ danh mục nào khác. Giá trị liên quan là một chuỗi cho biết chính xác điều gì đã xảy ra.

exception StopIteration

Được tăng lên bởi hàm next() tích hợp sẵn và phương thức __next__() của iterator để báo hiệu rằng không có mục nào khác được trình vòng lặp tạo ra.

value

Đối tượng ngoại lệ có một thuộc tính duy nhất value, được đưa ra làm đối số khi xây dựng ngoại lệ và mặc định là None.

Khi hàm generator hoặc coroutine trả về, một phiên bản StopIteration mới sẽ được tạo ra và giá trị mà hàm trả về sẽ được sử dụng làm tham số value cho hàm tạo của ngoại lệ.

Nếu mã trình tạo trực tiếp hoặc gián tiếp tăng StopIteration thì mã đó sẽ được chuyển đổi thành RuntimeError (giữ lại StopIteration làm nguyên nhân của ngoại lệ mới).

Thay đổi trong phiên bản 3.3: Đã thêm thuộc tính value và khả năng các hàm tạo sử dụng nó để trả về một giá trị.

Thay đổi trong phiên bản 3.5: Đã giới thiệu phép chuyển đổi RuntimeError thông qua from __future__ import generator_stop, xem PEP 479.

Thay đổi trong phiên bản 3.7: Bật PEP 479 cho tất cả mã theo mặc định: lỗi StopIteration xuất hiện trong trình tạo sẽ được chuyển thành RuntimeError.

exception StopAsyncIteration

Phải được nâng lên bằng phương thức __anext__() của đối tượng asynchronous iterator để dừng việc lặp lại.

Added in version 3.5.

exception SyntaxError(message, details)

Xảy ra khi trình phân tích cú pháp gặp lỗi cú pháp. Điều này có thể xảy ra trong câu lệnh import, trong lệnh gọi các hàm dựng sẵn compile(), exec() hoặc eval() hoặc khi đọc tập lệnh ban đầu hoặc đầu vào tiêu chuẩn (cũng có tính tương tác).

str() của phiên bản ngoại lệ chỉ trả về thông báo lỗi. Chi tiết là một bộ mà các thành viên của nó cũng có sẵn dưới dạng các thuộc tính riêng biệt.

filename

Tên của tệp xảy ra lỗi cú pháp.

lineno

Đã xảy ra lỗi ở dòng nào trong tệp. Đây là số 1 được lập chỉ mục: dòng đầu tiên trong tệp có lineno là 1.

offset

Cột trong dòng xảy ra lỗi. Đây là chỉ mục 1: ký tự đầu tiên trong dòng có offset là 1.

text

Văn bản mã nguồn liên quan đến lỗi.

end_lineno

Lỗi xảy ra ở dòng nào trong tệp. Đây là số 1 được lập chỉ mục: dòng đầu tiên trong tệp có lineno là 1.

end_offset

Cột ở dòng cuối nơi xảy ra lỗi kết thúc. Đây là chỉ mục 1: ký tự đầu tiên trong dòng có offset là 1.

Đối với các lỗi trong trường chuỗi f, thông báo có tiền tố là "f-string: " và phần bù là phần bù trong văn bản được tạo từ biểu thức thay thế. Ví dụ: biên dịch trường f'Bad {a b}' dẫn đến thuộc tính args này: ('f-string: ...', ('', 1, 2, '(a b)n', 1, 5)).

Thay đổi trong phiên bản 3.10: Đã thêm thuộc tính end_lineno và end_offset.

exception IndentationError

Lớp cơ sở cho các lỗi cú pháp liên quan đến việc thụt lề không chính xác. Đây là một lớp con của SyntaxError.

exception TabError

Xảy ra khi thụt lề có cách sử dụng tab và dấu cách không nhất quán. Đây là một lớp con của IndentationError.

exception SystemError

Xảy ra khi trình thông dịch tìm thấy một lỗi nội bộ, nhưng tình huống đó có vẻ không nghiêm trọng đến mức khiến nó mất hết hy vọng. Giá trị liên quan là một chuỗi cho biết điều gì đã xảy ra (theo thuật ngữ cấp thấp). Trong CPython, điều này có thể xảy ra do sử dụng sai C API của Python, chẳng hạn như trả về giá trị NULL mà không đặt ngoại lệ.

Nếu bạn tin chắc rằng ngoại lệ này không phải lỗi của bạn hoặc lỗi của gói bạn đang sử dụng, bạn nên báo cáo điều này với tác giả hoặc người bảo trì trình thông dịch Python của bạn. Hãy nhớ báo cáo phiên bản của trình thông dịch Python (sys.version; nó cũng được in khi bắt đầu phiên Python tương tác), thông báo lỗi chính xác (giá trị liên quan của ngoại lệ) và nếu có thể, nguồn của chương trình đã gây ra lỗi.

exception SystemExit

Ngoại lệ này được đưa ra bởi hàm sys.exit(). Nó kế thừa từ BaseException thay vì Exception để không vô tình bị bắt bởi mã bắt Exception. Điều này cho phép ngoại lệ lan truyền đúng cách và khiến trình thông dịch thoát ra. Khi nó không được xử lý, trình thông dịch Python sẽ thoát; không có dấu vết ngăn xếp nào được in. Hàm tạo chấp nhận đối số tùy chọn tương tự được truyền cho sys.exit(). Nếu giá trị là số nguyên, nó chỉ định trạng thái thoát hệ thống (được chuyển tới hàm exit() của C); nếu là None, trạng thái thoát bằng 0; nếu nó có loại khác (chẳng hạn như một chuỗi), giá trị của đối tượng sẽ được in và trạng thái thoát là một.

Lệnh gọi tới sys.exit() được dịch thành một ngoại lệ để các trình xử lý dọn dẹp (mệnh đề finally của câu lệnh try) có thể được thực thi và để trình gỡ lỗi có thể thực thi tập lệnh mà không gặp nguy cơ mất quyền kiểm soát. Chức năng os._exit() có thể được sử dụng nếu thực sự cần thiết phải thoát ra ngay lập tức (ví dụ: trong tiến trình con sau lệnh gọi tới os.fork()).

code

Trạng thái thoát hoặc thông báo lỗi được chuyển đến hàm tạo. (Mặc định là None.)

exception TypeError

Xảy ra khi một thao tác hoặc chức năng được áp dụng cho một đối tượng thuộc loại không phù hợp. Giá trị liên quan là một chuỗi cung cấp thông tin chi tiết về loại không khớp.

Ngoại lệ này có thể được mã người dùng đưa ra để chỉ ra rằng một thao tác đã thử trên một đối tượng không được hỗ trợ và không có nghĩa là như vậy. Nếu một đối tượng nhằm hỗ trợ một hoạt động nhất định nhưng chưa cung cấp cách triển khai thì NotImplementedError là ngoại lệ thích hợp để nêu ra.

Việc truyền đối số sai loại (ví dụ: truyền list khi dự kiến ​​sẽ có int) sẽ dẫn đến TypeError, nhưng truyền đối số có giá trị sai (ví dụ: một số nằm ngoài ranh giới dự kiến) sẽ dẫn đến ValueError.

exception UnboundLocalError

Xảy ra khi một tham chiếu được tạo tới một biến cục bộ trong một hàm hoặc phương thức, nhưng không có giá trị nào được liên kết với biến đó. Đây là một lớp con của NameError.

exception UnicodeError

Xảy ra khi xảy ra lỗi mã hóa hoặc giải mã liên quan đến Unicode. Nó là một lớp con của ValueError.

UnicodeError có các thuộc tính mô tả lỗi mã hóa hoặc giải mã. Ví dụ: err.object[err.start:err.end] cung cấp đầu vào không hợp lệ cụ thể mà codec không hoạt động được.

encoding

Tên của mã hóa gây ra lỗi.

reason

Một chuỗi mô tả lỗi codec cụ thể.

object

Đối tượng mà codec đang cố gắng mã hóa hoặc giải mã.

start

Chỉ mục đầu tiên của dữ liệu không hợp lệ trong object.

Giá trị này không được âm vì nó được hiểu là giá trị bù tuyệt đối nhưng ràng buộc này không được thực thi trong thời gian chạy.

end

Chỉ mục sau dữ liệu không hợp lệ cuối cùng trong object.

Giá trị này không được âm vì nó được hiểu là giá trị bù tuyệt đối nhưng ràng buộc này không được thực thi trong thời gian chạy.

exception UnicodeEncodeError

Xảy ra khi xảy ra lỗi liên quan đến Unicode trong quá trình mã hóa. Nó là một lớp con của UnicodeError.

exception UnicodeDecodeError

Xảy ra khi xảy ra lỗi liên quan đến Unicode trong quá trình giải mã. Nó là một lớp con của UnicodeError.

exception UnicodeTranslateError

Xảy ra khi xảy ra lỗi liên quan đến Unicode trong quá trình dịch. Nó là một lớp con của UnicodeError.

exception ValueError

Xảy ra khi một thao tác hoặc hàm nhận được một đối số có đúng loại nhưng có giá trị không phù hợp và tình huống không được mô tả bằng một ngoại lệ chính xác hơn, chẳng hạn như IndexError.

exception ZeroDivisionError

Xảy ra khi đối số thứ hai của phép chia hoặc phép toán modulo bằng 0. Giá trị liên quan là một chuỗi cho biết loại toán hạng và phép toán.

Các ngoại lệ sau được giữ lại để tương thích với các phiên bản trước; bắt đầu từ Python 3.3, chúng là bí danh của OSError.

exception EnvironmentError

exception IOError

exception WindowsError

Chỉ có sẵn trên Windows.

Ngoại lệ hệ điều hành

Các trường hợp ngoại lệ sau đây là các lớp con của OSError, chúng được nâng lên tùy thuộc vào mã lỗi hệ thống.

exception BlockingIOError

Xảy ra khi một thao tác chặn trên một đối tượng (ví dụ: ổ cắm) được đặt thành thao tác không chặn. Tương ứng với errno EAGAIN, EALREADY, EWOULDBLOCK và EINPROGRESS.

Ngoài các thuộc tính của OSError, BlockingIOError có thể có thêm một thuộc tính:

characters_written

Một số nguyên chứa số bytes được ghi vào luồng trước khi nó bị chặn. Thuộc tính này khả dụng khi sử dụng các lớp I/O được đệm từ mô-đun io.

exception ChildProcessError

Xảy ra khi một thao tác trên tiến trình con không thành công. Tương ứng với errno ECHILD.

exception ConnectionError

Một lớp cơ sở cho các vấn đề liên quan đến kết nối.

Các lớp con là BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError và ConnectionResetError.

exception BrokenPipeError

Một lớp con của ConnectionError, được nâng lên khi cố gắng ghi trên một đường ống trong khi đầu kia đã bị đóng hoặc cố gắng ghi trên một ổ cắm đã bị tắt để ghi. Tương ứng với errno EPIPE và ESHUTDOWN.

exception ConnectionAbortedError

Một lớp con của ConnectionError, được tạo ra khi nỗ lực kết nối bị hủy bỏ bởi thiết bị ngang hàng. Tương ứng với errno ECONNABORTED.

exception ConnectionRefusedError

Một lớp con của ConnectionError, được tạo ra khi một nỗ lực kết nối bị từ chối bởi thiết bị ngang hàng. Tương ứng với errno ECONNREFUSED.

exception ConnectionResetError

Một lớp con của ConnectionError, được nâng lên khi kết nối được thiết lập lại bởi thiết bị ngang hàng. Tương ứng với errno ECONNRESET.

exception FileExistsError

Xảy ra khi cố gắng tạo một tập tin hoặc thư mục đã tồn tại. Tương ứng với errno EEXIST.

exception FileNotFoundError

Xảy ra khi một tập tin hoặc thư mục được yêu cầu nhưng không tồn tại. Tương ứng với errno ENOENT.

exception InterruptedError

Xảy ra khi cuộc gọi hệ thống bị gián đoạn bởi tín hiệu đến. Tương ứng với errno EINTR.

Thay đổi trong phiên bản 3.5: Python bây giờ thử lại các cuộc gọi hệ thống khi một tòa nhà cao tầng bị gián đoạn bởi một tín hiệu, ngoại trừ nếu trình xử lý tín hiệu đưa ra một ngoại lệ (xem PEP 475 để biết lý do), thay vì tăng InterruptedError.

exception IsADirectoryError

Xảy ra khi một thao tác tệp (chẳng hạn như os.remove()) được yêu cầu trên một thư mục. Tương ứng với errno EISDIR.

exception NotADirectoryError

Xảy ra khi một thao tác thư mục (chẳng hạn như os.listdir()) được yêu cầu trên một thứ không phải là thư mục. Trên hầu hết các nền tảng POSIX, nó cũng có thể được nâng lên nếu một thao tác cố gắng mở hoặc duyệt qua một tệp không phải thư mục như thể nó là một thư mục. Tương ứng với errno ENOTDIR.

exception PermissionError

Xảy ra khi cố gắng chạy một thao tác mà không có đủ quyền truy cập - ví dụ như quyền hệ thống tệp. Tương ứng với errno EACCES, EPERM và ENOTCAPABLE.

Thay đổi trong phiên bản 3.11.1: ENOTCAPABLE của WASI hiện được ánh xạ tới PermissionError.

exception ProcessLookupError

Xảy ra khi một quy trình nhất định không tồn tại. Tương ứng với errno ESRCH.

exception TimeoutError

Xảy ra khi một chức năng hệ thống hết thời gian chờ ở cấp hệ thống. Tương ứng với errno ETIMEDOUT.

Added in version 3.3: Tất cả các lớp con OSError ở trên đã được thêm vào.

Xem thêm

PEP 3151 - Làm lại hệ thống phân cấp ngoại lệ của hệ điều hành và IO

Cảnh báo

Các trường hợp ngoại lệ sau đây được sử dụng làm danh mục cảnh báo; xem tài liệu Danh mục cảnh báo để biết thêm chi tiết.

exception Warning

Lớp cơ sở cho các danh mục cảnh báo.

exception UserWarning

Lớp cơ sở cho các cảnh báo do mã người dùng tạo ra.

exception DeprecationWarning

Lớp cơ sở để cảnh báo về các tính năng không được dùng nữa khi những cảnh báo đó dành cho các nhà phát triển Python khác.

Bị bỏ qua bởi các bộ lọc cảnh báo mặc định, ngoại trừ trong mô-đun __main__ (PEP 565). Kích hoạt Python Development Mode sẽ hiển thị cảnh báo này.

Chính sách ngừng sử dụng được mô tả trong PEP 387.

exception PendingDeprecationWarning

Lớp cơ sở để cảnh báo về các tính năng đã lỗi thời và dự kiến sẽ không được dùng nữa trong tương lai nhưng hiện tại không được dùng nữa.

Lớp này hiếm khi được sử dụng vì việc đưa ra cảnh báo về khả năng ngừng sử dụng sắp tới là điều không bình thường và DeprecationWarning được ưu tiên cho các lần ngừng sử dụng đã hoạt động.

Bị bỏ qua bởi các bộ lọc cảnh báo mặc định. Kích hoạt Python Development Mode sẽ hiển thị cảnh báo này.

Chính sách ngừng sử dụng được mô tả trong PEP 387.

exception SyntaxWarning

Lớp cơ sở để cảnh báo về cú pháp không rõ ràng.

Cảnh báo này thường được đưa ra khi biên dịch mã nguồn Python và thường không được báo cáo khi chạy mã đã được biên dịch.

exception RuntimeWarning

Lớp cơ sở để cảnh báo về hành vi thời gian chạy đáng ngờ.

exception FutureWarning

Lớp cơ sở để cảnh báo về các tính năng không được dùng nữa khi những cảnh báo đó dành cho người dùng cuối của các ứng dụng được viết bằng Python.

exception ImportWarning

Lớp cơ sở để cảnh báo về những lỗi có thể xảy ra khi nhập mô-đun.

Bị bỏ qua bởi các bộ lọc cảnh báo mặc định. Kích hoạt Python Development Mode sẽ hiển thị cảnh báo này.

exception UnicodeWarning

Lớp cơ sở cho các cảnh báo liên quan đến Unicode.

exception EncodingWarning

Lớp cơ sở cho các cảnh báo liên quan đến mã hóa.

Xem Cảnh báo mã hóa chọn tham gia để biết chi tiết.

Added in version 3.10.

exception BytesWarning

Lớp cơ sở cho các cảnh báo liên quan đến bytes và bytearray.

exception ResourceWarning

Lớp cơ sở cho các cảnh báo liên quan đến việc sử dụng tài nguyên.

Bị bỏ qua bởi các bộ lọc cảnh báo mặc định. Kích hoạt Python Development Mode sẽ hiển thị cảnh báo này.

Added in version 3.2.

Nhóm ngoại lệ

Những điều sau đây được sử dụng khi cần đưa ra nhiều ngoại lệ không liên quan. Chúng là một phần của hệ thống phân cấp ngoại lệ nên chúng có thể được xử lý bằng except giống như tất cả các ngoại lệ khác. Ngoài ra, chúng được except* công nhận, phù hợp với các nhóm con của chúng dựa trên các loại ngoại lệ có trong đó.

exception ExceptionGroup(msg, excs)

exception BaseExceptionGroup(msg, excs)

Cả hai loại ngoại lệ này đều bao bọc các ngoại lệ trong chuỗi excs. Tham số msg phải là một chuỗi. Sự khác biệt giữa hai lớp là BaseExceptionGroup mở rộng BaseException và nó có thể bao bọc bất kỳ ngoại lệ nào, trong khi ExceptionGroup mở rộng Exception và nó chỉ có thể bao bọc các lớp con của Exception. Thiết kế này để except Exception bắt được ExceptionGroup chứ không phải BaseExceptionGroup.

Hàm tạo BaseExceptionGroup trả về ExceptionGroup thay vì BaseExceptionGroup nếu tất cả các ngoại lệ được chứa đều là các phiên bản Exception, vì vậy nó có thể được sử dụng để thực hiện lựa chọn tự động. Mặt khác, hàm tạo ExceptionGroup sẽ tăng TypeError nếu có bất kỳ ngoại lệ nào không phải là lớp con Exception.

Tham số excs có thể là bất kỳ chuỗi nào, nhưng ở đây danh sách và bộ dữ liệu được xử lý cụ thể hiệu quả hơn. Để có hiệu suất tối ưu, hãy chuyển một bộ dữ liệu dưới dạng excs.

message

Đối số msg cho hàm tạo. Đây là thuộc tính chỉ đọc.

exceptions

Một bộ ngoại lệ trong chuỗi excs được cung cấp cho hàm tạo. Đây là thuộc tính chỉ đọc.

subgroup(condition)

Trả về một nhóm ngoại lệ chỉ chứa các ngoại lệ từ nhóm hiện tại khớp với condition hoặc None nếu kết quả trống.

Điều kiện có thể là một loại ngoại lệ hoặc một bộ các loại ngoại lệ, trong trường hợp đó, mỗi ngoại lệ được kiểm tra xem có khớp hay không bằng cách sử dụng cùng một kiểm tra được sử dụng trong mệnh đề except. Điều kiện cũng có thể là một đối tượng có thể gọi được (không phải là đối tượng kiểu) chấp nhận một ngoại lệ làm đối số duy nhất của nó và trả về true cho các ngoại lệ phải nằm trong nhóm con.

Cấu trúc lồng nhau của ngoại lệ hiện tại được giữ nguyên trong kết quả, cũng như các giá trị của các trường message, __traceback__, __cause__, __context__ và __notes__. Các nhóm lồng nhau trống sẽ bị loại bỏ khỏi kết quả.

Điều kiện được kiểm tra đối với tất cả các ngoại lệ trong nhóm ngoại lệ lồng nhau, bao gồm cả nhóm ngoại lệ cấp cao nhất và bất kỳ nhóm ngoại lệ lồng nhau nào. Nếu điều kiện đúng cho một nhóm ngoại lệ như vậy thì nó sẽ được đưa vào kết quả đầy đủ.

Added in version 3.13: condition có thể là bất kỳ lệnh gọi nào không phải là đối tượng kiểu.

split(condition)

Giống như subgroup(), nhưng trả về cặp (match, rest) trong đó match là subgroup(condition) và rest là phần không khớp còn lại.

derive(excs)

Trả về một nhóm ngoại lệ có cùng message nhưng bao gồm các ngoại lệ trong excs.

Phương pháp này được subgroup() và split() sử dụng, được sử dụng trong nhiều ngữ cảnh khác nhau để chia nhỏ một nhóm ngoại lệ. Một lớp con cần ghi đè lên nó để tạo ra các phiên bản trả về của subgroup() và split() của lớp con thay vì ExceptionGroup.

subgroup() và split() sao chép các trường __traceback__, __cause__, __context__ và __notes__ từ nhóm ngoại lệ ban đầu sang nhóm được trả về bởi derive(), vì vậy các trường này không cần phải được derive() cập nhật.

>>> lớp MyGroup(ExceptionGroup):
... def lấy được(self, exes):
... trả về MyGroup(self.message, exes)
...
>>> e = MyGroup("eg", [ValueError(1), TypeError(2)])
>>> e.add_note("ghi chú")
>>> e.__context__ = Ngoại lệ("bối cảnh")
>>> e.__ Cause__ = Ngoại lệ("nguyên nhân")
>>> thử:
... nâng cao e
... ngoại trừ Ngoại lệ là e:
...exc = e
...
>>> khớp, nghỉ = exc.split(ValueError)
>>> exc, ex.__context__, ex.__nguyên nhân__, ex.__notes__
(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), Exception('nguyên nhân'), ['a note'])
>>> khớp, khớp.__context__, khớp.__nguyên nhân__, khớp.__notes__
(MyGroup('ví dụ', [ValueError(1)]), Ngoại lệ('bối cảnh'), Ngoại lệ('nguyên nhân'), ['ghi chú'])
>>> nghỉ ngơi, nghỉ ngơi.__bối cảnh__, nghỉ ngơi.__vì__, nghỉ ngơi.__notes__
(MyGroup('ví dụ', [TypeError(2)]), Ngoại lệ('bối cảnh'), Ngoại lệ('nguyên nhân'), ['ghi chú'])
>>> ex.__traceback__ là khớp.__traceback__ là phần còn lại.__traceback__
đúng

Lưu ý rằng BaseExceptionGroup định nghĩa __new__(), vì vậy các lớp con cần chữ ký hàm tạo khác cần ghi đè lên chữ ký đó thay vì __init__(). Ví dụ: phần sau đây định nghĩa một lớp con của nhóm ngoại lệ chấp nhận exit_code và xây dựng thông báo của nhóm từ đó.

lỗi lớp (Nhóm ngoại lệ):
   def __new__(cls, error, exit_code):
      self = super().__new__(Lỗi, f"mã thoát: {exit_code}", lỗi)
      self.exit_code = exit_code
      tự trở về

   def lấy được (tự, exes):
      trả về lỗi(excs, self.exit_code)

Giống như ExceptionGroup, bất kỳ lớp con nào của BaseExceptionGroup cũng là lớp con của Exception chỉ có thể bao bọc các phiên bản của Exception.

Added in version 3.11.

Phân cấp ngoại lệ

Hệ thống phân cấp lớp cho các ngoại lệ tích hợp là:

Ngoại lệ cơ sở
 ├── BaseExceptionGroup
 ├── Máy phát điệnThoát
 ├── Bàn phímNgắt
 ├── Thoát khỏi hệ thống
 └── Ngoại lệ
      ├──Lỗi Số Học
      │ ├── Lỗi dấu phẩy động
      │ ├── Lỗi tràn
      │ └── ZeroDivisionError
      ├── Lỗi xác nhận
      ├── Lỗi thuộc tính
      ├── Lỗi bộ đệm
      ├── EOFLỗi
      ├── Nhóm ngoại lệ [BaseExceptionGroup]
      ├── Lỗi nhập
      │ └── Lỗi mô-đun không tìm thấy
      ├── Tra cứuLỗi
      │ ├── Lỗi chỉ mục
      │ └── Lỗi phím
      ├── Lỗi bộ nhớ
      ├── TênLỗi
      │ └── UnboundLocalError
      ├── OSLỗi
      │ ├── BlockingIOError
      │ ├── ChildProcessError
      │ ├── Lỗi kết nối
      │ │ ├── BrokenPipeError
      │ │ ├── Lỗi kết nối bị hủy bỏ
      │ │ ├── Lỗi kết nối bị từ chối
      │ │ └── Lỗi kết nối lại
      │ ├── FileExistsError
      │ ├── Lỗi Không Tìm Thấy Tệp
      │ ├── Bị gián đoạnLỗi
      │ ├── IsADirectoryError
      │ ├── NotADirectoryError
      │ ├── Lỗi cấp phép
      │ ├── Lỗi tra cứu quy trình
      │ └── Lỗi hết thời gian chờ
      ├── Lỗi tham khảo
      ├── Lỗi thời gian chạy
      │ ├── Lỗi chưa được thực hiện
      │ ├── Lỗi hoàn thiện Python
      │ └── Lỗi đệ quy
      ├── DừngAsyncIteration
      ├── Dừng lại
      ├── Lỗi Cú pháp
      │ └── Lỗi thụt đầu dòng
      │ └── TabLỗi
      ├── Lỗi hệ thống
      ├── LoạiLỗi
      ├── Giá trịLỗi
      │ └── Lỗi Unicode
      │ ├── Lỗi UnicodeDecode
      │ ├── Lỗi UnicodeEncode
      │ └── UnicodeTranslateError
      └── Cảnh báo
           ├── ByteCảnh báo
           ├── Ngừng sử dụngCảnh báo
           ├── Cảnh báo mã hóa
           ├── Cảnh báo tương lai
           ├── Cảnh báo nhập khẩu
           ├── Đang chờ ngừng sử dụngCảnh báo
           ├── Tài nguyênCảnh báo
           ├── Cảnh báo thời gian chạy
           ├── Cú phápCảnh báo
           ├── UnicodeCảnh báo
           └── Cảnh báo người dùng