`warnings` --- Kiểm soát cảnh báo¶

Source code: Lib/warnings.py

Thông báo cảnh báo thường được đưa ra trong các tình huống hữu ích khi cảnh báo người dùng về một số điều kiện trong chương trình, trong đó điều kiện đó (thông thường) không đảm bảo đưa ra một ngoại lệ và chấm dứt chương trình. Ví dụ: người ta có thể muốn đưa ra cảnh báo khi chương trình sử dụng mô-đun lỗi thời.

Các lập trình viên Python đưa ra cảnh báo bằng cách gọi hàm warn() được xác định trong mô-đun này. (Lập trình viên C sử dụng PyErr_WarnEx(); xem Xử lý ngoại lệ để biết chi tiết).

Thông báo cảnh báo thường được ghi vào sys.stderr, nhưng cách xử lý của chúng có thể được thay đổi linh hoạt, từ bỏ qua mọi cảnh báo đến biến chúng thành ngoại lệ. Việc xử lý các cảnh báo có thể khác nhau dựa trên warning category, nội dung của thông báo cảnh báo và vị trí nguồn nơi cảnh báo được đưa ra. Việc lặp lại một cảnh báo cụ thể cho cùng một vị trí nguồn thường bị chặn.

Có hai giai đoạn trong quá trình kiểm soát cảnh báo: thứ nhất, mỗi lần cảnh báo được đưa ra, sẽ đưa ra quyết định xem có nên đưa ra thông báo hay không; tiếp theo, nếu một thông báo được phát đi, nó sẽ được định dạng và in bằng cách sử dụng hook do người dùng cài đặt.

Việc xác định xem có đưa ra thông báo cảnh báo hay không được kiểm soát bởi warning filter, đây là một chuỗi các quy tắc và hành động phù hợp. Các quy tắc có thể được thêm vào bộ lọc bằng cách gọi filterwarnings() và đặt lại về trạng thái mặc định bằng cách gọi resetwarnings().

Việc in các thông báo cảnh báo được thực hiện bằng cách gọi showwarning(), có thể bị ghi đè; việc triển khai mặc định của hàm này sẽ định dạng thông báo bằng cách gọi formatwarning(), tính năng này cũng có sẵn để các triển khai tùy chỉnh sử dụng.

Xem thêm

logging.captureWarnings() cho phép bạn xử lý tất cả các cảnh báo bằng cơ sở hạ tầng ghi nhật ký tiêu chuẩn.

Danh mục cảnh báo¶

Có một số trường hợp ngoại lệ tích hợp đại diện cho các danh mục cảnh báo. Việc phân loại này rất hữu ích để có thể lọc ra các nhóm cảnh báo.

Mặc dù về mặt kỹ thuật đây là built-in exceptions nhưng chúng được ghi lại ở đây vì về mặt khái niệm chúng thuộc về cơ chế cảnh báo.

Mã người dùng có thể xác định các danh mục cảnh báo bổ sung bằng cách phân lớp một trong các danh mục cảnh báo tiêu chuẩn. Danh mục cảnh báo phải luôn là lớp con của lớp Warning.

Các lớp danh mục cảnh báo sau đây hiện được xác định:

lớp học	Mô tả
`Warning`	Đây là lớp cơ sở của tất cả các lớp danh mục cảnh báo. Nó là một lớp con của `Exception`.
`UserWarning`	Danh mục mặc định cho `warn()`.
`DeprecationWarning`	Danh mục cơ sở dành cho các 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 theo mặc định, trừ khi được kích hoạt bởi mã trong `__main__`).
`SyntaxWarning`	Danh mục cơ sở để cảnh báo về các tính năng cú pháp đáng ngờ (thường được phát ra khi biên dịch mã nguồn Python và do đó có thể không bị các bộ lọc thời gian chạy chặn)
`RuntimeWarning`	Danh mục cơ sở để cảnh báo về các tính năng thời gian chạy đáng ngờ.
`FutureWarning`	Danh mục cơ sở dành cho các 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.
`PendingDeprecationWarning`	Danh mục cơ sở để cảnh báo về các tính năng sẽ không được dùng nữa trong tương lai (bị bỏ qua theo mặc định).
`ImportWarning`	Danh mục cơ sở cho các cảnh báo được kích hoạt trong quá trình nhập mô-đun (bị bỏ qua theo mặc định).
`UnicodeWarning`	Danh mục cơ sở cho các cảnh báo liên quan đến Unicode.
`BytesWarning`	Danh mục cơ sở cho các cảnh báo liên quan đến `bytes` và `bytearray`.
`ResourceWarning`	Danh mục cơ sở cho các cảnh báo liên quan đến việc sử dụng tài nguyên (mặc định bị bỏ qua).

Thay đổi trong phiên bản 3.7: Trước đây DeprecationWarning và FutureWarning được phân biệt dựa trên việc một tính năng đang bị xóa hoàn toàn hay đang thay đổi hành vi của nó. Giờ đây chúng được phân biệt dựa trên đối tượng mục tiêu và cách chúng được xử lý bởi các bộ lọc cảnh báo mặc định.

Bộ lọc cảnh báo¶

Bộ lọc cảnh báo kiểm soát xem cảnh báo có bị bỏ qua, hiển thị hay biến thành lỗi hay không (đưa ra một ngoại lệ).

Về mặt khái niệm, bộ lọc cảnh báo duy trì một danh sách có thứ tự các thông số kỹ thuật của bộ lọc; mọi cảnh báo cụ thể sẽ được so khớp lần lượt với từng thông số bộ lọc trong danh sách cho đến khi tìm thấy kết quả khớp; bộ lọc xác định cách sắp xếp của trận đấu. Mỗi mục là một bộ dữ liệu có dạng (action, message, category, module, lineno), trong đó:

action là một trong các chuỗi sau:

Giá trị	Bố trí
`"default"`	in lần xuất hiện đầu tiên của các cảnh báo trùng khớp cho từng vị trí (mô-đun + số dòng) nơi cảnh báo được đưa ra
`"error"`	biến cảnh báo phù hợp thành ngoại lệ
`"ignore"`	không bao giờ in cảnh báo phù hợp
`"always"`	luôn in cảnh báo phù hợp
`"all"`	bí danh là "luôn luôn"
`"module"`	in lần xuất hiện đầu tiên của các cảnh báo trùng khớp cho mỗi mô-đun nơi cảnh báo được đưa ra (bất kể số dòng)
`"once"`	chỉ in lần xuất hiện đầu tiên của cảnh báo trùng khớp, bất kể vị trí

message là một chuỗi chứa biểu thức chính quy mà phần đầu của thông báo cảnh báo phải khớp, không phân biệt chữ hoa chữ thường. Trong -W và PYTHONWARNINGS, message là một chuỗi ký tự mà phần đầu của thông báo cảnh báo phải chứa (không phân biệt chữ hoa chữ thường), bỏ qua mọi khoảng trắng ở đầu hoặc cuối message.
category là một lớp (một lớp con của Warning) trong đó danh mục cảnh báo phải là một lớp con để phù hợp.
module là một chuỗi chứa biểu thức chính quy mà phần đầu của tên mô-đun đủ điều kiện phải khớp, phân biệt chữ hoa chữ thường. Trong -W và PYTHONWARNINGS, module là một chuỗi ký tự mà tên mô-đun đủ điều kiện phải bằng (phân biệt chữ hoa chữ thường), bỏ qua mọi khoảng trắng ở đầu hoặc cuối module.
lineno là một số nguyên mà số dòng xảy ra cảnh báo phải khớp hoặc 0 phải khớp với tất cả các số dòng.

Vì lớp Warning có nguồn gốc từ lớp Exception tích hợp sẵn, nên để biến cảnh báo thành lỗi, chúng tôi chỉ cần đưa ra category(message).

Nếu cảnh báo được báo cáo và không khớp với bất kỳ bộ lọc đã đăng ký nào thì hành động "mặc định" sẽ được áp dụng (do đó có tên của nó).

Tiêu chí ngăn chặn cảnh báo lặp lại¶

Các bộ lọc ngăn chặn cảnh báo lặp lại áp dụng các tiêu chí sau để xác định xem cảnh báo có được coi là lặp lại hay không:

"default": Cảnh báo chỉ được coi là lặp lại nếu (message, category, module, lineno) đều giống nhau.
"module": Cảnh báo được coi là lặp lại nếu (message, category, module) giống nhau, bỏ qua số dòng.
"once": Cảnh báo được coi là lặp lại nếu (message, category) giống nhau, bỏ qua mô-đun và số dòng.

Mô tả bộ lọc cảnh báo¶

Bộ lọc cảnh báo được khởi tạo bởi các tùy chọn -W được chuyển đến dòng lệnh trình thông dịch Python và biến môi trường PYTHONWARNINGS. Trình thông dịch lưu các đối số cho tất cả các mục nhập được cung cấp mà không cần giải thích trong sys.warnoptions; mô-đun warnings phân tích các phân tích này khi nó được nhập lần đầu tiên (các tùy chọn không hợp lệ sẽ bị bỏ qua sau khi in thông báo tới sys.stderr).

Các bộ lọc cảnh báo riêng lẻ được chỉ định dưới dạng một chuỗi các trường được phân tách bằng dấu hai chấm

hành động:tin nhắn:danh mục:mô-đun:dòng

Ý nghĩa của từng trường này được mô tả trong Bộ lọc cảnh báo. Khi liệt kê nhiều bộ lọc trên một dòng (như đối với PYTHONWARNINGS), các bộ lọc riêng lẻ được phân tách bằng dấu phẩy và các bộ lọc được liệt kê sau sẽ được ưu tiên hơn các bộ lọc được liệt kê trước chúng (vì chúng được áp dụng từ trái sang phải và các bộ lọc được áp dụng gần đây nhất sẽ được ưu tiên hơn các bộ lọc trước đó).

Các bộ lọc cảnh báo thường được sử dụng áp dụng cho tất cả các cảnh báo, cảnh báo trong một danh mục cụ thể hoặc cảnh báo do các mô-đun hoặc gói cụ thể đưa ra. Một số ví dụ:

mặc định # Show tất cả các cảnh báo (ngay cả những cảnh báo bị bỏ qua theo mặc định)
bỏ qua # Ignore tất cả các cảnh báo
lỗi # Convert tất cả các cảnh báo lỗi
error::ResourceWarning # Treat Thông báo ResourceWarning là lỗi
mặc định::Khấu haoCảnh báo # Show Khấu haoThông báo cảnh báo
bỏ qua,mặc định:::mymodule # Only báo cáo cảnh báo được kích hoạt bởi "mymodule"
error:::mymodule # Convert cảnh báo lỗi trong "mymodule"

Bộ lọc cảnh báo mặc định¶

Theo mặc định, Python cài đặt một số bộ lọc cảnh báo, có thể bị ghi đè bằng tùy chọn dòng lệnh -W, biến môi trường PYTHONWARNINGS và gọi tới filterwarnings().

Trong các bản phát hành thông thường, bộ lọc cảnh báo mặc định có các mục sau (theo thứ tự ưu tiên):

mặc định::Không dùng nữaCảnh báo:__main__
bỏ qua::Khấu haoCảnh báo
bỏ qua::Đang chờ xử lýCảnh báo
bỏ qua::Cảnh báo nhập khẩu
bỏ qua::ResourceWarning

Trong debug build, danh sách các bộ lọc cảnh báo mặc định trống.

Thay đổi trong phiên bản 3.2: DeprecationWarning hiện bị bỏ qua theo mặc định ngoài PendingDeprecationWarning.

Thay đổi trong phiên bản 3.7: DeprecationWarning một lần nữa được hiển thị theo mặc định khi được kích hoạt trực tiếp bằng mã trong __main__.

Thay đổi trong phiên bản 3.7: BytesWarning không còn xuất hiện trong danh sách bộ lọc mặc định và thay vào đó được định cấu hình qua sys.warnoptions khi -b được chỉ định hai lần.

Ghi đè bộ lọc mặc định¶

Theo mặc định, các nhà phát triển ứng dụng viết bằng Python có thể muốn ẩn các cảnh báo cấp độ Python all khỏi người dùng của họ và chỉ hiển thị chúng khi chạy thử nghiệm hoặc làm việc trên ứng dụng. Thuộc tính sys.warnoptions được sử dụng để chuyển cấu hình bộ lọc tới trình thông dịch có thể được sử dụng làm điểm đánh dấu để cho biết có nên tắt cảnh báo hay không

hệ thống nhập khẩu

nếu không phải sys.warnooptions:
    cảnh báo nhập khẩu
    cảnh báo.simplefilter("bỏ qua")

Thay vào đó, các nhà phát triển chương trình chạy thử nghiệm cho mã Python nên đảm bảo rằng các cảnh báo all được hiển thị theo mặc định cho mã đang được thử nghiệm, sử dụng mã như:

hệ thống nhập khẩu

nếu không phải sys.warnooptions:
    nhập hệ điều hành, cảnh báo
    Warning.simplefilter("default") # Change bộ lọc trong quy trình này
    os.environ["PYTHONWARNINGS"] = "default" # Also ảnh hưởng đến các quy trình con

Cuối cùng, các nhà phát triển shell tương tác chạy mã người dùng trong không gian tên khác __main__ nên đảm bảo rằng các thông báo DeprecationWarning được hiển thị theo mặc định, sử dụng mã như sau (trong đó user_ns là mô-đun được sử dụng để thực thi mã được nhập tương tác):

cảnh báo nhập khẩu
cảnh báo.filterwarnings("mặc định", danh mục=Không dùng nữaCảnh báo,
                                   module=user_ns.get("__name__"))

Tạm thời ngăn chặn cảnh báo¶

Nếu bạn đang sử dụng mã mà bạn biết sẽ đưa ra cảnh báo, chẳng hạn như hàm không được dùng nữa nhưng không muốn xem cảnh báo (ngay cả khi cảnh báo đã được định cấu hình rõ ràng qua dòng lệnh), thì bạn có thể chặn cảnh báo bằng cách sử dụng trình quản lý ngữ cảnh catch_warnings:

cảnh báo nhập khẩu

định nghĩa fxn():
    Warning.warn("không dùng nữa", DeprecationWarning)

với cảnh báo.catch_warnings():
    cảnh báo.simplefilter("bỏ qua")
    fxn()

Mặc dù trong trình quản lý bối cảnh, tất cả các cảnh báo sẽ bị bỏ qua. Điều này cho phép bạn sử dụng mã đã biết không còn được dùng nữa mà không cần phải xem cảnh báo trong khi không loại bỏ cảnh báo đối với mã khác có thể không biết về việc sử dụng mã không được dùng nữa.

Ghi chú

Xem Sự an toàn đồng thời của Trình quản lý bối cảnh để biết chi tiết về tính an toàn đồng thời của trình quản lý bối cảnh catch_warnings khi được sử dụng trong các chương trình sử dụng nhiều luồng hoặc hàm không đồng bộ.

Cảnh báo thử nghiệm¶

Để kiểm tra các cảnh báo do mã đưa ra, hãy sử dụng trình quản lý ngữ cảnh catch_warnings. Với nó, bạn có thể tạm thời thay đổi bộ lọc cảnh báo để tạo điều kiện thuận lợi cho việc thử nghiệm của mình. Ví dụ: hãy làm như sau để nắm bắt tất cả các cảnh báo được nêu ra để kiểm tra:

cảnh báo nhập khẩu

định nghĩa fxn():
    Warning.warn("không dùng nữa", DeprecationWarning)

với Warning.catch_warnings(record=True) là w:
    # Cause tất cả các cảnh báo luôn được kích hoạt.
    cảnh báo.simplefilter("luôn luôn")
    # Trigger một cảnh báo.
    fxn()
    # Verify một số thứ
    khẳng định len(w) == 1
    khẳng định issubclass(w[-1].category, DeprecationWarning)
    khẳng định "không được dùng nữa" trong str(w[-1].message)

Người ta cũng có thể khiến tất cả cảnh báo trở thành ngoại lệ bằng cách sử dụng error thay vì always. Một điều cần lưu ý là nếu cảnh báo đã được đưa ra do quy tắc once/default thì bất kể bộ lọc nào được đặt, cảnh báo sẽ không được nhìn thấy lại trừ khi sổ đăng ký cảnh báo liên quan đến cảnh báo đã bị xóa.

Khi trình quản lý bối cảnh thoát, bộ lọc cảnh báo sẽ được khôi phục về trạng thái khi nhập ngữ cảnh. Điều này ngăn cản việc kiểm tra thay đổi bộ lọc cảnh báo theo những cách không mong muốn giữa các lần kiểm tra và dẫn đến kết quả kiểm tra không xác định.

Ghi chú

Xem Sự an toàn đồng thời của Trình quản lý bối cảnh để biết chi tiết về tính an toàn đồng thời của trình quản lý bối cảnh catch_warnings khi được sử dụng trong các chương trình sử dụng nhiều luồng hoặc hàm không đồng bộ.

Khi kiểm tra nhiều thao tác đưa ra cùng một loại cảnh báo, điều quan trọng là phải kiểm tra chúng theo cách xác nhận rằng mỗi thao tác đang đưa ra cảnh báo mới (ví dụ: đặt cảnh báo được đưa ra dưới dạng ngoại lệ và kiểm tra các thao tác đưa ra ngoại lệ, kiểm tra xem độ dài của danh sách cảnh báo có tiếp tục tăng sau mỗi thao tác hay không, nếu không, hãy xóa các mục trước đó khỏi danh sách cảnh báo trước mỗi thao tác mới).

Cập nhật mã cho các phiên bản phụ thuộc mới¶

Các danh mục cảnh báo chủ yếu được các nhà phát triển Python quan tâm (chứ không phải là người dùng cuối của các ứng dụng viết bằng Python) sẽ bị bỏ qua theo mặc định.

Đáng chú ý, danh sách "bị bỏ qua theo mặc định" này bao gồm DeprecationWarning (cho mọi mô-đun ngoại trừ __main__), có nghĩa là các nhà phát triển phải đảm bảo kiểm tra mã của họ với các cảnh báo thường bị bỏ qua được hiển thị để nhận được thông báo kịp thời về các thay đổi API có thể xảy ra trong tương lai (cho dù trong thư viện tiêu chuẩn hay gói của bên thứ ba).

Trong trường hợp lý tưởng, mã sẽ có một bộ thử nghiệm phù hợp và trình chạy thử nghiệm sẽ đảm nhiệm việc ngầm kích hoạt tất cả các cảnh báo khi chạy thử nghiệm (trình chạy thử nghiệm do mô-đun unittest cung cấp thực hiện việc này).

Trong những trường hợp ít lý tưởng hơn, các ứng dụng có thể được kiểm tra việc sử dụng các giao diện không được dùng nữa bằng cách chuyển -Wd tới trình thông dịch Python (đây là cách viết tắt của -W default) hoặc đặt PYTHONWARNINGS=default trong môi trường. Điều này cho phép xử lý mặc định cho tất cả các cảnh báo, bao gồm cả những cảnh báo bị bỏ qua theo mặc định. Để thay đổi hành động nào được thực hiện đối với các cảnh báo gặp phải, bạn có thể thay đổi đối số nào được chuyển tới -W (ví dụ: -W error). Xem cờ -W để biết thêm chi tiết về những gì có thể.

Chức năng có sẵn¶

warnings.warn(message, category=None, stacklevel=1, source=None, *, skip_file_prefixes=())¶

Đưa ra cảnh báo hoặc có thể bỏ qua hoặc đưa ra một ngoại lệ. Đối số category, nếu được đưa ra, phải là warning category class; nó mặc định là UserWarning. Ngoài ra, message có thể là một phiên bản Warning, trong trường hợp đó category sẽ bị bỏ qua và message.__class__ sẽ được sử dụng. Trong trường hợp này, nội dung tin nhắn sẽ là str(message). Hàm này đưa ra một ngoại lệ nếu cảnh báo cụ thể được đưa ra bị warnings filter thay đổi thành lỗi. Đối số stacklevel có thể được sử dụng bởi các hàm bao bọc được viết bằng Python, như thế này

def deprecated_api(tin nhắn):
    Warning.warn(tin nhắn, DeprecationWarning, stacklevel=2)

Điều này làm cho cảnh báo đề cập đến người gọi của deprecated_api, thay vì đến chính nguồn của deprecated_api (vì cái sau sẽ làm mất đi mục đích của thông báo cảnh báo).

Đối số từ khóa skip_file_prefixes có thể được sử dụng để chỉ ra khung ngăn xếp nào bị bỏ qua khi đếm mức ngăn xếp. Điều này có thể hữu ích khi bạn muốn cảnh báo luôn xuất hiện tại các trang web cuộc gọi bên ngoài gói khi stacklevel không đổi không phù hợp với tất cả các đường dẫn cuộc gọi hoặc khó duy trì. Nếu được cung cấp, nó phải là một bộ chuỗi. Khi tiền tố được cung cấp, stacklevel được ghi đè ngầm thành max(2, stacklevel). Để đưa ra cảnh báo cho người gọi từ bên ngoài gói hiện tại, bạn có thể viết:

# example/hạ.py
_warn_skips = (os.path.dirname(__file__),)

def one_way(r_luxury_yacht=Không, t_wobbler_mangrove=Không):
    nếu r_luxury_yacht:
        Warning.warn("Hãy di chuyển tới t_wobbler_mangrove=.",
                      Skip_file_prefixes=_warn_skips)

# example/higher.py
từ . nhập khẩu thấp hơn

def another_way(**kw):
    low.one_way(**kw)

Điều này làm cho cảnh báo chỉ đề cập đến cả hai trang web gọi example.lower.one_way() và example.higher.another_way() từ mã gọi nằm ngoài gói example.

source, nếu được cung cấp, là đối tượng bị phá hủy phát ra ResourceWarning.

Thay đổi trong phiên bản 3.6: Đã thêm tham số source.

Thay đổi trong phiên bản 3.12: Đã thêm skip_file_prefixes.

warnings.warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)¶

Đây là giao diện cấp thấp cho chức năng của warn(), truyền rõ ràng thông báo, danh mục, tên tệp và số dòng cũng như các đối số tùy chọn khác. message phải là một chuỗi và category một lớp con của Warning hoặc message có thể là một phiên bản Warning, trong trường hợp đó category sẽ bị bỏ qua.

module, nếu được cung cấp, phải là tên mô-đun. Nếu không có mô-đun nào được thông qua, tên tệp bị loại bỏ .py sẽ được sử dụng.

registry, nếu được cung cấp, phải là từ điển __warningregistry__ của mô-đun. Nếu không có đăng ký nào được thông qua thì mỗi cảnh báo sẽ được coi là lần xuất hiện đầu tiên, nghĩa là các hành động lọc "default", "module" và "once" được xử lý như "always".

module_globals, nếu được cung cấp, phải là không gian tên chung được sử dụng bởi mã đưa ra cảnh báo. (Đối số này được sử dụng để hỗ trợ hiển thị nguồn cho các mô-đun được tìm thấy trong tệp zip hoặc các nguồn nhập không phải hệ thống tệp khác).

source, nếu được cung cấp, là đối tượng bị phá hủy phát ra ResourceWarning.

Thay đổi trong phiên bản 3.6: Thêm tham số source.

warnings.showwarning(message, category, filename, lineno, file=None, line=None)¶: Viết cảnh báo vào một tập tin. Việc triển khai mặc định gọi formatwarning(message, category, filename, lineno, line) và ghi chuỗi kết quả vào file, mặc định là sys.stderr. Bạn có thể thay thế chức năng này bằng bất kỳ lệnh gọi nào bằng cách gán cho warnings.showwarning. line là dòng mã nguồn được đưa vào thông báo cảnh báo; nếu line không được cung cấp, showwarning() sẽ cố đọc dòng được chỉ định bởi filename và lineno.

warnings.formatwarning(message, category, filename, lineno, line=None)¶: Định dạng cảnh báo theo cách tiêu chuẩn. Điều này trả về một chuỗi có thể chứa các dòng mới được nhúng và kết thúc bằng một dòng mới. line là một dòng mã nguồn được đưa vào thông báo cảnh báo; nếu line không được cung cấp, formatwarning() sẽ cố đọc dòng được chỉ định bởi filename và lineno.

warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)¶: Chèn một mục vào danh sách warnings filter specifications. Mục nhập được chèn ở phía trước theo mặc định; nếu append đúng thì nó sẽ được chèn vào cuối. Thao tác này sẽ kiểm tra các loại đối số, biên dịch các biểu thức chính quy message và module, đồng thời chèn chúng dưới dạng một bộ dữ liệu vào danh sách các bộ lọc cảnh báo. Các mục ở gần đầu danh sách sẽ ghi đè các mục ở sau trong danh sách, nếu cả hai đều khớp với một cảnh báo cụ thể. Các đối số bị bỏ qua mặc định có giá trị khớp với mọi thứ.

warnings.simplefilter(action, category=Warning, lineno=0, append=False)¶: Chèn một mục đơn giản vào danh sách warnings filter specifications. Ý nghĩa của các tham số hàm giống như đối với filterwarnings(), nhưng không cần biểu thức chính quy vì bộ lọc được chèn luôn khớp với bất kỳ thông báo nào trong bất kỳ mô-đun nào miễn là danh mục và số dòng khớp với nhau.

warnings.resetwarnings()¶: Đặt lại bộ lọc cảnh báo. Điều này loại bỏ tác dụng của tất cả các lệnh gọi trước đó tới filterwarnings(), bao gồm cả các tùy chọn dòng lệnh -W và các lệnh gọi tới simplefilter().

@warnings.deprecated(msg, *, category=DeprecationWarning, stacklevel=1)¶

Công cụ trang trí để cho biết rằng một lớp, hàm hoặc tình trạng quá tải không còn được dùng nữa.

Khi trang trí này được áp dụng cho một đối tượng, các cảnh báo không dùng nữa có thể được đưa ra trong thời gian chạy khi đối tượng được sử dụng. static type checkers cũng sẽ tạo chẩn đoán về việc sử dụng đối tượng không được dùng nữa.

Cách sử dụng:

từ cảnh báo nhập không được chấp nhận
từ việc nhập quá tải nhập

@deprecated("Thay vào đó hãy sử dụng B")
lớp A:
    vượt qua

@deprecated("Thay vào đó hãy sử dụng g")
chắc chắn f():
    vượt qua

@overload
@deprecated("hỗ trợ int không được dùng nữa")
def g(x: int) -> int: ...
@overload
def g(x: str) -> int: ...

Cảnh báo do category chỉ định sẽ được phát ra trong thời gian chạy khi sử dụng các đối tượng không được dùng nữa. Đối với các chức năng, điều đó xảy ra trong các cuộc gọi; cho các lớp, về khởi tạo và tạo các lớp con. Nếu category là None thì sẽ không có cảnh báo nào được đưa ra trong thời gian chạy. Zz004zz xác định nơi phát ra cảnh báo. Nếu là 1 (mặc định), cảnh báo sẽ được phát ra ở người gọi trực tiếp đối tượng không được dùng nữa; nếu nó cao hơn, nó sẽ được phát ra xa hơn trong ngăn xếp. Hành vi của trình kiểm tra loại tĩnh không bị ảnh hưởng bởi các đối số category và stacklevel.

Thông báo ngừng sử dụng được chuyển tới trình trang trí sẽ được lưu trong thuộc tính __deprecated__ trên đối tượng được trang trí. Nếu được áp dụng cho tình trạng quá tải, trình trang trí phải ở sau trình trang trí @~typing.overload để thuộc tính tồn tại trong tình trạng quá tải được trả về bởi typing.get_overloads().

Added in version 3.13: Xem PEP 702.

Trình quản lý bối cảnh có sẵn¶

class warnings.catch_warnings(*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)¶

Trình quản lý bối cảnh sao chép và khi thoát sẽ khôi phục bộ lọc cảnh báo và chức năng showwarning(). Nếu đối số record là False (mặc định), trình quản lý bối cảnh sẽ trả về None khi nhập. Nếu record là True, một danh sách sẽ được trả về được điền dần dần các đối tượng mà một hàm showwarning() tùy chỉnh nhìn thấy (cũng ngăn chặn đầu ra thành sys.stdout). Mỗi đối tượng trong danh sách có các thuộc tính có cùng tên với các đối số của showwarning().

Đối số module lấy một mô-đun sẽ được sử dụng thay vì mô-đun được trả về khi bạn nhập warnings có bộ lọc sẽ được bảo vệ. Đối số này tồn tại chủ yếu để kiểm tra chính mô-đun warnings.

Nếu đối số action không phải là None thì các đối số còn lại sẽ được chuyển đến simplefilter() như thể nó được gọi ngay lập tức khi vào ngữ cảnh.

Xem Bộ lọc cảnh báo để biết ý nghĩa của các thông số category và lineno.

Ghi chú

Xem Sự an toàn đồng thời của Trình quản lý bối cảnh để biết chi tiết về tính an toàn đồng thời của trình quản lý bối cảnh catch_warnings khi được sử dụng trong các chương trình sử dụng nhiều luồng hoặc hàm không đồng bộ.

Thay đổi trong phiên bản 3.11: Đã thêm các tham số action, category, lineno và append.

Sự an toàn đồng thời của Trình quản lý bối cảnh¶

Hoạt động của trình quản lý bối cảnh catch_warnings phụ thuộc vào cờ sys.flags.context_aware_warnings. Nếu cờ đúng, trình quản lý bối cảnh sẽ hoạt động theo kiểu an toàn đồng thời còn ngược lại thì không. An toàn đồng thời có nghĩa là nó vừa an toàn theo luồng vừa an toàn khi sử dụng trong asyncio coroutines và các tác vụ. An toàn theo luồng có nghĩa là hành vi có thể dự đoán được trong một chương trình đa luồng. Cờ mặc định là true đối với các bản dựng có luồng tự do và ngược lại là sai.

Nếu cờ context_aware_warnings là sai thì catch_warnings sẽ sửa đổi các thuộc tính chung của mô-đun warnings. Điều này không an toàn nếu được sử dụng trong một chương trình đồng thời (sử dụng nhiều luồng hoặc sử dụng coroutine asyncio). Ví dụ: nếu hai hoặc nhiều luồng sử dụng lớp catch_warnings cùng một lúc thì hành vi đó sẽ không được xác định.

Nếu cờ đúng, catch_warnings sẽ không sửa đổi các thuộc tính chung và thay vào đó sẽ sử dụng ContextVar để lưu trữ trạng thái lọc cảnh báo mới thiết lập. Một biến bối cảnh cung cấp bộ nhớ cục bộ theo luồng và nó làm cho việc sử dụng luồng catch_warnings trở nên an toàn.

Tham số record của trình xử lý ngữ cảnh cũng hoạt động khác nhau tùy thuộc vào giá trị của cờ. Khi record là đúng và cờ là sai, trình quản lý bối cảnh sẽ hoạt động bằng cách thay thế và sau đó khôi phục chức năng showwarning() của mô-đun. Điều đó không an toàn đồng thời.

Khi record đúng và cờ đúng, hàm showwarning() không được thay thế. Thay vào đó, trạng thái ghi được biểu thị bằng thuộc tính nội bộ trong biến ngữ cảnh. Trong trường hợp này, hàm showwarning() sẽ không được khôi phục khi thoát khỏi trình xử lý ngữ cảnh.

Cờ context_aware_warnings có thể được đặt tùy chọn dòng lệnh -X context_aware_warnings hoặc bằng biến môi trường PYTHON_CONTEXT_AWARE_WARNINGS.

Ghi chú

Có khả năng là hầu hết các chương trình mong muốn hoạt động an toàn theo luồng của mô-đun cảnh báo cũng sẽ muốn đặt cờ thread_inherit_context thành true. Cờ đó khiến các luồng được tạo bởi threading.Thread bắt đầu bằng một bản sao của các biến ngữ cảnh từ luồng bắt đầu nó. Khi đúng, ngữ cảnh do catch_warnings thiết lập trong một luồng cũng sẽ áp dụng cho các luồng mới do nó bắt đầu. Nếu sai, các luồng mới sẽ bắt đầu bằng một biến ngữ cảnh cảnh báo trống, nghĩa là mọi bộ lọc do trình quản lý ngữ cảnh catch_warnings thiết lập sẽ không còn hoạt động nữa.

Thay đổi trong phiên bản 3.14: Đã thêm cờ sys.flags.context_aware_warnings và sử dụng biến ngữ cảnh cho catch_warnings nếu cờ đó đúng. Các phiên bản trước của Python hoạt động như thể cờ luôn được đặt thành sai.

`warnings` --- Kiểm soát cảnh báo¶

Danh mục cảnh báo¶

Bộ lọc cảnh báo¶

Tiêu chí ngăn chặn cảnh báo lặp lại¶

Mô tả bộ lọc cảnh báo¶

Bộ lọc cảnh báo mặc định¶

Ghi đè bộ lọc mặc định¶

Tạm thời ngăn chặn cảnh báo¶

Cảnh báo thử nghiệm¶

Cập nhật mã cho các phiên bản phụ thuộc mới¶

Chức năng có sẵn¶

Trình quản lý bối cảnh có sẵn¶

Sự an toàn đồng thời của Trình quản lý bối cảnh¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này

warnings --- Kiểm soát cảnh báo¶

Danh mục cảnh báo¶

Bộ lọc cảnh báo¶

Tiêu chí ngăn chặn cảnh báo lặp lại¶

Mô tả bộ lọc cảnh báo¶

Bộ lọc cảnh báo mặc định¶

Ghi đè bộ lọc mặc định¶

Tạm thời ngăn chặn cảnh báo¶

Cảnh báo thử nghiệm¶

Cập nhật mã cho các phiên bản phụ thuộc mới¶

Chức năng có sẵn¶

Trình quản lý bối cảnh có sẵn¶

Sự an toàn đồng thời của Trình quản lý bối cảnh¶

`warnings` --- Kiểm soát cảnh báo¶