warnings — 경고 제어¶
소스 코드: Lib/warnings.py
경고 메시지는 일반적으로 프로그램에서 사용자에게 (일반적으로) 예외를 발생시키거나 프로그램을 종료하는 것을 보증하지 않는 특정 조건에 대해 경고하는 것이 유용한 상황 상황에서 발행됩니다. 예를 들어, 프로그램이 더는 사용되지 않는 모듈을 사용할 때 경고를 발행하려고 할 수 있습니다.
파이썬 프로그래머는 이 모듈에 정의된 warn() 함수를 호출하여 경고를 발행합니다. (C 프로그래머는 PyErr_WarnEx()를 사용합니다; 자세한 내용은 예외 처리를 참조하십시오).
경고 메시지는 일반적으로 sys.stderr에 기록되지만, 모든 경고를 무시하는 것에서 예외로 변경하는 것에 이르기까지 배치를 유연하게 변경할 수 있습니다. 경고의 처리는 경고 범주, 경고 메시지의 텍스트 및 발행된 소스 위치에 따라 달라질 수 있습니다. 같은 소스 위치에 대한 특정 경고의 반복은 일반적으로 억제됩니다.
경고 제어에는 두 가지 단계가 있습니다; 첫째, 경고가 발행될 때마다, 메시지를 발행할지를 결정합니다; 다음으로, 메시지가 발행된다면, 사용자 설정 가능한 훅을 사용하여 포맷되고 인쇄됩니다.
경고 메시지를 발행할지는 경고 필터에 의해 제어되며, 이는 일치 규칙과 조치의 시퀀스입니다. filterwarnings()를 호출하여 규칙을 필터에 추가하고 resetwarnings()를 호출하여 기본 상태로 재설정할 수 있습니다.
경고 메시지의 인쇄는 showwarning()을 호출하여 수행되며, 이는 재정의될 수 있습니다; 이 함수의 기본 구현은 formatwarning()을 호출하여 메시지를 포맷하며, 사용자 정의 구현에서도 사용할 수 있습니다.
더 보기
logging.captureWarnings()를 사용하면 표준 로깅 인프라로 모든 경고를 처리할 수 있습니다.
경고 범주¶
경고 범주를 나타내는 여러 가지 내장 예외가 있습니다. 이 범주화는 경고 그룹을 필터링하는 데 유용합니다.
이들은 기술적으로 내장 예외이지만, 개념적으로 경고 메커니즘에 속하기 때문에 여기에서 설명합니다.
사용자 코드는 표준 경고 범주 중 하나를 서브 클래싱 하여 추가 경고 범주를 정의할 수 있습니다. 경고 범주는 항상 Warning 클래스의 서브 클래스여야 합니다.
다음과 같은 경고 범주 클래스가 현재 정의되어 있습니다:
클래스 |
설명 |
|---|---|
이것은 모든 경고 범주 클래스의 베이스 클래스입니다. |
|
|
|
폐지된 기능에 대한 경고의 베이스 범주, 경고가 다른 파이썬 개발자를 대상으로 할 때 ( |
|
의심스러운 구문 기능에 대한 경의 베이스 범주(일반적으로 파이썬 소스 코드를 컴파일할 때 발생하며, 따라서 런타임 필터로 억제되지 않을 수 있습니다) |
|
모호한 런타임 기능에 대한 경고의 베이스 범주. |
|
폐지된 기능에 대한 경고의 베이스 범주, 경고가 파이썬으로 작성된 응용 프로그램의 최종 사용자를 대상으로 할 때. |
|
향후 폐지될 기능에 대한 경고의 베이스 범주 (기본적으로 무시됩니다). |
|
모듈을 임포트 하는 과정에서 트리거 되는 경고의 베이스 범주 (기본적으로 무시됩니다). |
|
유니코드와 관련된 경고의 베이스 범주. |
|
자원 사용과 관련된 경고의 베이스 범주 (기본적으로 무시됩니다). |
버전 3.7에서 변경: 이전에는 DeprecationWarning과 FutureWarning은 기능이 완전히 제거되었는지 또는 동작을 변경하는지에 따라 구별되었습니다. 이제 의도한 대상과 기본 경고 필터에서 처리하는 방식에 따라 구별됩니다.
경고 필터¶
경고 필터는 경고를 무시, 표시 또는 에러로 전환(예외 발생)할지를 제어합니다.
개념적으로, 경고 필터는 필터 명세의 순서 있는 목록을 유지합니다; 일치가 발견될 때까지 목록의 각 필터 명세에 대해 특정 경고를 일치시킵니다; 필터는 일치의 처리를 결정합니다. 각 항목은 (action, message, category, module, lineno) 형식의 튜플입니다, 여기서:
action은 다음 문자열 중 하나입니다:
값
처리
"default"경고가 발행된 각 위치(모듈 + 줄 번호)에 대해 일치하는 경고의 첫 번째 발생을 인쇄합니다
"error"일치하는 경고를 예외로 바꿉니다
"ignore"일치하는 경고를 인쇄하지 않습니다
"always"일치하는 경고를 항상 인쇄합니다
"all"“always”의 별칭
"module"경고가 발행된 모듈마다 (줄 번호와 관계없이) 일치하는 경고의 첫 번째 발생을 인쇄합니다
"once"위치와 관계없이 일치하는 경고의 첫 번째 발생만 인쇄합니다
message 는 경고 메시지의 시작 부분이 대소문자 구분 없이 일치해야 하는 정규식을 포함하는 문자열입니다.
-W및PYTHONWARNINGS에서, message 가 슬래시(/)로 시작하고 끝나면 위와 같은 정규식을 지정하며, 그렇지 않으면 경고 메시지의 시작 부분과 일치해야 하는 리터럴 문자열을 의미합니다(이 경우 message 의 시작이나 끝에 있는 공백은 무시되며 대소문자를 구분하지 않습니다).category는 클래스(
Warning의 서브 클래스)이며, 일치하는 경고 범주는 이것의 서브 클래스여야 합니다.module 은 완전히 정규화된 모듈 이름의 시작 부분이 대소문자를 구분하여 일치해야 하는 정규식을 포함하는 문자열입니다.
-W및PYTHONWARNINGS에서, module 이 슬래시(/)로 시작하고 끝나면 위와 같은 정규식을 지정하며, 그렇지 않으면 완전히 정규화된 모듈 이름과 일치해야 하는 리터럴 문자열을 의미합니다(이 경우 module 의 시작이나 끝에 있는 공백은 무시되며 대소문자를 구분합니다).lineno는 경고가 발생한 줄 번호가 일치해야 하는 정수이거나, 모든 줄 번호와 일치하려면
0입니다.
Warning 클래스는 내장 Exception 클래스에서 파생되므로, 경고를 에러로 바꾸려면 단순히 category(message)를 raise 합니다.
경고가 보고되고 등록된 필터와 일치하지 않으면 “default” 조치가 적용됩니다 (그래서 그런 이름을 갖고 있습니다).
중복 경고 억제 기준¶
중복 경고를 억제하는 필터는 경고가 중복된 것으로 간주되는지 판단하기 위해 다음 기준을 적용합니다:
"default": (message, category, module, lineno)가 모두 동일할 경우에만 경고가 중복된 것으로 간주됩니다."module": 줄 번호를 무시하고 (message, category, module)이 동일한 경우 경고가 중복된 것으로 간주됩니다."once": 모듈과 줄 번호를 무시하고 (message, category)가 동일한 경우 경고가 중복된 것으로 간수됩니다.
경고 필터 설명¶
경고 필터는 파이썬 인터프리터 명령 줄에 전달된 -W 옵션과 PYTHONWARNINGS 환경 변수로 초기화됩니다. 인터프리터는 모든 제공된 항목의 인자를 해석 없이 sys.warnoptions 에 저장하며, warnings 모듈이 처음 임포트될 때 이를 구문 분석합니다(유효하지 않은 옵션은 메시지를 sys.stderr 에 출력한 후 무시됩니다).
개별 경고 필터는 콜론으로 구분된 필드의 시퀀스로 지정됩니다:
action:message:category:module:line
이러한 각 필드의 의미는 경고 필터에 설명된 대로입니다. 한 줄에 여러 필터를 나열할 때 (PYTHONWARNINGS와 같이), 개별 필터는 쉼표로 구분되고 나중에 나열된 필터가 그 앞에 나열된 필터보다 우선합니다 (왼쪽에서 오른쪽으로 적용되고, 가장 최근에 적용된 필터가 앞서 나온 필터에 우선하기 때문입니다).
일반적으로 사용되는 경고 필터는 모든 경고, 특정 범주의 경고 또는 특정 모듈이나 패키지에서 발생하는 경고에 적용됩니다. 몇 가지 예:
default # 모든 경고를 표시합니다 (설사 기본적으로 무시되더라도)
ignore # 모든 경고를 무시합니다
error # 모든 경고를 에러로 변환합니다
error::ResourceWarning # ResourceWarning 메시지를 에러로 취급합니다
default::DeprecationWarning # DeprecationWarning 메시지를 표시합니다
ignore,default:::mymodule # "mymodule"이 트리거 한 경고만 보고합니다
error:::mymodule # "mymodule"에서 경고를 에러로 변환합니다
기본 경고 필터¶
기본적으로, 파이썬은 -W 명령 줄 옵션, PYTHONWARNINGS 환경 변수 및 filterwarnings() 호출로 재정의할 수 있는 몇 가지 경고 필터를 설치합니다.
정규 릴리스 빌드에서, 기본 경고 필터에는 다음과 같은 항목이 있습니다 (우선순위 순서로):
default::DeprecationWarning:__main__
ignore::DeprecationWarning
ignore::PendingDeprecationWarning
ignore::ImportWarning
ignore::ResourceWarning
디버그 빌드에서, 기본 경고 필터 목록은 비어 있습니다.
버전 3.2에서 변경: DeprecationWarning은 이제 PendingDeprecationWarning 에 더해 기본적으로 무시됩니다.
버전 3.7에서 변경: DeprecationWarning은 __main__의 코드에 의해 직접 트리거 될 때 기본적으로 다시 한번 표시됩니다.
버전 3.7에서 변경: BytesWarning은 더는 기본 필터 목록에 나타나지 않으며 대신 -b가 두 번 지정되면 sys.warnoptions를 통해 구성됩니다.
기본 필터 재정의¶
파이썬으로 작성된 응용 프로그램 개발자는 기본적으로 사용자에게 모든 파이썬 수준 경고를 숨기고, 테스트를 실행하거나 달리 응용 프로그램에 대해 작업할 때만 표시하고 싶을 수 있습니다. 필터 구성을 인터프리터에 전달하는 데 사용되는 sys.warnoptions 어트리뷰트는 경고를 비활성화해야 하는지를 나타내는 마커로 사용할 수 있습니다:
import sys
if not sys.warnoptions:
import warnings
warnings.simplefilter("ignore")
파이썬 코드용 테스트 실행기 개발자는 대신 다음과 같은 코드를 사용하여 테스트 대상 코드에 대해 기본적으로 모든 경고가 표시되도록 하는 것이 좋습니다:
import sys
if not sys.warnoptions:
import os, warnings
warnings.simplefilter("default") # 이 프로세스의 필터를 변경합니다
os.environ["PYTHONWARNINGS"] = "default" # 서브 프로세스에도 영향을 줍니다
마지막으로, __main__ 이외의 이름 공간에서 사용자 코드를 실행하는 대화식 셸 개발자는 다음과 같은 코드를 사용하여 DeprecationWarning 메시지가 기본적으로 표시되도록 하는 것이 좋습니다 (여기서 user_ns는 대화식으로 입력된 코드를 실행하는 데 사용되는 모듈입니다):
import warnings
warnings.filterwarnings("default", category=DeprecationWarning,
module=user_ns.get("__name__"))
일시적인 경고 억제¶
폐지된 함수처럼, 경고를 발생시킬 것을 알고 있는 코드를 사용하고 있지만, 경고를 보고 싶지 않으면 (명령 줄을 통해 경고가 명시적으로 구성된 경우조차), catch_warnings 컨텍스트 관리자를 사용하여 경고를 억제할 수 있습니다:
import warnings
def fxn():
warnings.warn("deprecated", DeprecationWarning)
with warnings.catch_warnings():
warnings.simplefilter("ignore")
fxn()
컨텍스트 매니저 내에서는 모든 경고가 무시됩니다. 이를 통해 다른 코드가 폐지된 기능을 사용하는 것을 알지 못해 발생하는 경고를 억제하지 않으면서, 알려진 폐기된 코드를 사용할 때 경고를 보지 않을 수 있습니다.
참고
멀티 스레드 또는 비동기 함수를 사용하는 프로그램에서 사용되는
catch_warnings컨텍스트 매니저의 동시성 안전성에 대한 자세한 내용은 컨텍스트 관리자의 동시성 안전성 를 참조하십시오.
경고 테스트¶
코드가 발생시키는 경고를 테스트하려면, catch_warnings 컨텍스트 관리자를 사용하십시오. 이를 통해 쉽게 테스트할 수 있도록 경고 필터를 일시적으로 변경할 수 있습니다. 예를 들어, 검사할 모든 경고를 캡처하려면 다음을 수행하십시오:
import warnings
def fxn():
warnings.warn("deprecated", DeprecationWarning)
with warnings.catch_warnings(record=True) as w:
# Cause all warnings to always be triggered.
warnings.simplefilter("always")
# Trigger a warning.
fxn()
# Verify some things
assert len(w) == 1
assert issubclass(w[-1].category, DeprecationWarning)
assert "deprecated" in str(w[-1].message)
always 대신 error를 사용하여 모든 경고를 예외로 만들 수도 있습니다. 한 가지 알아야 할 것은 once / default 규칙으로 인해 경고가 이미 발생했으면, 어떤 필터가 설정되어 있더라도 경고와 관련된 경고 레지스트리가 지워지지 않으면 경고가 다시 표시되지 않는다는 것입니다.
컨텍스트 매니저를 나가면 경고 필터가 컨텍스트에 진입할 당시의 상태로 복구됩니다. 이를 통해 테스트 사이에서 경고 필터가 예기치 못한 방식으로 변경되어 시험 결과가 불분명해지는 것을 방지합니다.
참고
멀티 스레드 또는 비동기 함수를 사용하는 프로그램에서 사용되는
catch_warnings컨텍스트 매니저의 동시성 안전성에 대한 자세한 내용은 컨텍스트 관리자의 동시성 안전성 를 참조하십시오.
같은 종류의 경고를 발생시키는 여러 작업을 테스트할 때, 각 작업이 새로운 경고를 발생시키는지 확인하는 방식으로 테스트하는 것이 중요합니다 (예를 들어 경고가 예외를 발생시키도록 설정하고 작업이 예외를 일으키는지 확인합니다, 각 작업 후에 경고 목록의 길이가 계속 증가하는지 확인합니다, 또는 각 새 작업 전에 경고 목록에서 이전 항목을 삭제합니다).
새 버전의 종속성에 대한 코드 갱신¶
(파이썬으로 작성된 응용 프로그램의 최종 사용자가 아닌) 파이썬 개발자가 주로 관심을 두는 경고 범주는 기본적으로 무시됩니다.
특히, 이 “기본적으로 무시됨” 목록에는 DeprecationWarning(__main__을 제외한 모든 모듈에서)가 포함되어 있습니다. 이는 개발자가 (표준 라이브러리와 제삼자 패키지 모두에서) 호환성을 깨는 향후 API 변경에 대한 시기적절한 알림을 받기 위해 일반적으로 무시되는 경고를 가시화해서 코드를 테스트해야 한다는 것을 의미합니다.
이상적인 경우, 코드에 적절한 테스트 스위트가 있고, 테스트 실행기는 테스트를 실행할 때 모든 경고를 묵시적으로 활성화합니다 (unittest 모듈에서 제공하는 테스트 실행기가 이렇게 합니다).
덜 이상적인 경우, -Wd 를 파이썬 인터프리터에 전달하거나 (-W default의 줄임 표현입니다), 환경에 PYTHONWARNINGS=default를 설정하여 응용프로그램이 폐지된 인터페이스를 사용하는지를 확인할 수 있습니다. 이를 통해 기본적으로 무시되는 경고를 포함한 모든 경고에 대한 default 처리가 가능합니다. 발생한 경고에 대해 수행할 조치를 변경하려면 -W로 전달되는 인자를 변경할 수 있습니다 (예를 들어 -W error). 어떤 것이 가능한지에 대한 자세한 내용은 -W 플래그를 참조하십시오.
사용 가능한 함수¶
- warnings.warn(message, category=None, stacklevel=1, source=None, *, skip_file_prefixes=())¶
경고를 발행하거나, 무시하거나 예외를 발생시킵니다. 주어지면 category 인자는 경고 범주 클래스여야 합니다; 기본값은
UserWarning입니다. 또는, message가Warning인스턴스일 수 있으며, 이 경우 category는 무시되고message.__class__가 사용됩니다. 이 경우, 메시지 텍스트는str(message)입니다. 이 함수는 발행된 특정 경고가 경고 필터에 의해 에러로 변경되면 예외를 발생시킵니다. stacklevel 인자는 다음과 같이 파이썬으로 작성된 래퍼 함수에서 사용할 수 있습니다:def deprecated_api(message): warnings.warn(message, DeprecationWarning, stacklevel=2)
이것은 경고가
deprecated_api자체의 소스가 아닌deprecated_api의 호출자를 참조하게 합니다 (전자는 경고 메시지의 목적을 무효로 하기 때문입니다).skip_file_prefixes 키워드 인자는 스택 수준을 계산할 때 어떤 스택 프레임을 무시할지 지정하는 데 사용될 수 있습니다. 고정된 stacklevel 이 모든 호출 경로에 적합하지 않거나 유지하기 어려운 경우, 패키지 외부의 호출 지점에서 항상 경고가 나타나게 하고 싶을 때 유용합니다. 이 인자를 제공할 때는 문자열 튜플이어야 합니다. 프리픽스가 제공되면 stacklevel은 내부적으로
max(2, stacklevel)으로 대체됩니다. 현재 패키지 외부의 호출자에게 경고를 할당하려면 다음과 같이 작성할 수 있습니다:# example/lower.py _warn_skips = (os.path.dirname(__file__),) def one_way(r_luxury_yacht=None, t_wobbler_mangrove=None): if r_luxury_yacht: warnings.warn("Please migrate to t_wobbler_mangrove=.", skip_file_prefixes=_warn_skips) # example/higher.py from . import lower def another_way(**kw): lower.one_way(**kw)
이 설정을 통해
`example`패키지 외부의 호출 코드에서만example.lower.one_way()``와 ``example.higher.another_way()호출 지점 모두에 대한 경고를 참조하게 됩니다.제공되면, source는
ResourceWarning을 방출한 파괴된 객체입니다.버전 3.6에서 변경: source 매개 변수를 추가했습니다.
버전 3.12에서 변경: skip_file_prefixes 가 추가되었습니다.
- warnings.warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)¶
이것은 메시지, 범주, 파일명 및 줄 번호와 선택적으로 다른 인자들을 명시적으로 전달하는
warn()기능에 대한 저수렁 인터페이스입니다. message 는 문자열이어야 하며 category 는Warning의 서브클래스여야 합니다. 또는 message 가Warning인스턴스일 수 있으며, 이 경우 category 는 무시됩니다.module 가 제공되는 경우 모듈 이름이어야 합니다. 모듈이 전달되지 않으면 warnings filter 의 모듈 정규식은 모든 상위 디렉터리부터 시작하는 경로 구성 요소로부터 생성된 모듈 이름(
/__init__.py,.py및 Windows의 경우.pyw가 제거됨)과.py가 제거된 파일 이름에 대해 테스트됩니다. 예를 들어 파일명이'/path/to/package/module.py'인 경우,'path.to.package.module','to.package.module','package.module','module', 및'/path/to/package/module'에 대해 테스트됩니다.registry 가 제공되는 경우 모듈의
__warningregistry__딕셔너리여야 합니다. 레지스트리가 전달되지 않으면 각 경고는 첫 번째 발생으로 취급되며, 즉 필터 동작"default","module"및"once"가"always"로 처리됩니다.제공되면, module_globals는 경고가 발행되는 코드에서 사용 중인 전역 이름 공간이어야 합니다. (이 인자는 zip 파일이나 다른 파일 시스템이 아닌 임포트 소스에서 찾은 모듈의 소스 표시를 지원하는 데 사용됩니다).
제공되면, source는
ResourceWarning을 방출한 파괴된 객체입니다.버전 3.6에서 변경: source 매개 변수를 추가합니다.
버전 3.15에서 변경: 모듈이 전달되지 않으면 필터 정규식을 경로 자체뿐만 아니라 해당 경로에서 생성된 모듈 이름에 대해서도 테스트합니다.
- warnings.showwarning(message, category, filename, lineno, file=None, line=None)¶
파일에 경고를 기록합니다. 기본 구현은
formatwarning(message, category, filename, lineno, line)를 호출하고 결과 문자열을 file에 씁니다, file의 기본값은sys.stderr입니다.warnings.showwarning에 대입하여 이 함수를 임의의 콜러블로 대체할 수 있습니다. line은 경고 메시지에 포함될 소스 코드 줄입니다; line이 제공되지 않으면,showwarning()은 filename과 lineno로 지정된 줄을 읽으려고 시도합니다.
- warnings.formatwarning(message, category, filename, lineno, line=None)¶
표준 방식으로 경고를 포맷합니다. 내장된 개행 문자를 포함하고 개행 문자로 끝날 수 있는 문자열을 반환합니다. line은 경고 메시지에 포함될 소스 코드 줄입니다; line이 제공되지 않으면,
formatwarning()은 filename과 lineno로 지정된 줄을 읽으려고 시도합니다.
- warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)¶
경고 필터 명세 목록에 항목을 삽입합니다. 항목은 기본적으로 앞에 삽입됩니다; append가 참이면, 끝에 삽입됩니다. 인자의 형을 확인하고, message와 module 정규식을 컴파일한 후 경고 필터 목록에 튜플로 삽입합니다. 둘 다 특정 경고와 일치하면, 목록 앞쪽에 더 가까운 항목이 목록의 뒷부분에 있는 항목보다 우선합니다. 생략된 인자의 기본값은 모든 것과 일치하는 값입니다.
- warnings.simplefilter(action, category=Warning, lineno=0, append=False)¶
경고 필터 명세 목록에 간단한 항목을 삽입합니다. 함수 매개 변수의 의미는
filterwarnings()와 같지만, 범주와 줄 번호가 일치하는 한 삽입 된 필터가 항상 모든 모듈의 메시지와 일치하기 때문에 정규식이 필요하지 않습니다.
- warnings.resetwarnings()¶
경고 필터를 재설정합니다. 이는
-W명령 줄 옵션과simplefilter()에 대한 호출을 포함하여filterwarnings()에 대한 모든 이전 호출의 영향을 되돌립니다.
- @warnings.deprecated(msg, *, category=DeprecationWarning, stacklevel=1)¶
클래스, 함수 또는 오버로드가 폐지되었음을 나타내는 데코레이터입니다.
이 데코레이터를 객체에 적용하면, 해당 객체를 사용할 때 런타임에서 폐지 경고가 발생할 수 있습니다. 또한 정적 형 검사기 도 폐지된 객체의 사용 시 진단 메시지를 생성합니다.
사용법:
from warnings import deprecated from typing import overload @deprecated("Use B instead") class A: pass @deprecated("Use g instead") def f(): pass @overload @deprecated("int support is deprecated") def g(x: int) -> int: ... @overload def g(x: str) -> int: ...
category*에 지정된 경고는 폐지된 객체를 사용할 때 런타임에 발생합니다. 함수의 경우 호출 시에, 클래스의 경우 인스턴스화 및 하위 클래스 생성 시에 발생합니다. *category*가 ``None``인 경우 런타임에 경고가 발생하지 않습니다. *stacklevel*은 경고가 발생하는 위치를 결정합니다. 이 값이 ``1``(기본값)이면 폐지된 객체의 직접 호출자에서 경고가 발생하고, 그보다 높으면 스택 상위에서 발생합니다. 정적 형 검사기의 동작은 *category 및 stacklevel 인수에 영향을 받지 않습니다.
데코레이터에 전달된 폐지 메시지는 데코레이션된 객체의
__deprecated__어트리뷰트에 저장됩니다. 오버로드에 적용하는 경우,typing.get_overloads()가 반환하는 오버로드에 해당 어트리뷰트가 존재하려면 데코레이터가@~typing.overload데코레이터 뒤에 위치해야 합니다.Added in version 3.13: PEP 702 을(를) 참조하십시오.
사용 가능한 컨텍스트 관리자¶
- class warnings.catch_warnings(*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)¶
경고 필터와
showwarning()함수를 복사하고 종료 시 복원하는 컨텍스트 관리자입니다. record 인자가False(기본값)인 경우, 컨텍스트 관리자는 진입 시에None을 반환합니다. record 가True인 경우, 커스텀showwarning()함수(sys.stderr로의 출력도 억제함)에서 확인되는 객체들로 채워지는 리스트를 반환합니다. 리스트의 각 객체는 다음 어트리뷰트들을 포함하는 것이 보장됩니다.버전 3.6에서 변경:
source어트리뷰트가 추가되었습니다.버전 3.15에서 변경:
module어트리뷰트가 추가되었습니다.이 객체들의 타입은 명시되지 않았으며 변경될 수 있습니다. 이러한 어트리뷰트들이 존재하는 것만 보장됩니다.
module 인자는 필터가 보호되는
warnings`를 임포트할 때 반환되는 모듈 대신 사용될 모듈을 받습니다. 이 인자는 주로 :mod:!warnings` 모듈 자체를 테스트하기 위해 존재합니다.action 인자가
None이 아닌 경우, 나머지 인자들은 컨텍스트에 진입할 때 즉시 호출되는 것처럼simplefilter()로 전달됩니다.category 및 lineno 매개변수의 의미는 경고 필터 를 참조하십시오.
참고
멀티 스레드 또는 비동기 함수를 사용하는 프로그램에서 사용되는
catch_warnings컨텍스트 매니저의 동시성 안전성에 대한 자세한 내용은 컨텍스트 관리자의 동시성 안전성 를 참조하십시오.버전 3.11에서 변경: action, category, lineno 및 append 매개변수가 추가되었습니다.
컨텍스트 관리자의 동시성 안전성¶
catch_warnings 컨텍스트 관리자의 동작은 sys.flags.context_aware_warnings 플래그에 따라 달라집니다. 플래그가 참(True)인 경우, 컨텍스트 관리자는 동시성 안전한 방식으로 작동하며 그렇지 않은 경우 동시성 안전하지 않습니다. 동시성 안전하다는 것은 스레드 안전(thread-safe)할 뿐만 아니라 asyncio 코루틴 및 태스크 내에서도 안전하게 사용할 수 있음을 의미합니다. 이 플래그의 기본값은 free-threaded 빌드에서는 참이며 그 외에는 거짓입니다.
context_aware_warnings 플래그가 거짓인 경우, catch_warnings`는 :mod:!warnings` 모듈의 전역 어트리뷰트를 수정합니다. 이는 동시성 프로그램(다중 스레드 또는 asyncio 코루틴 사용)에서 안전하지 않습니다. 예를 들어, 두 개 이상의 스레드가 동시에 catch_warnings 클래스를 사용하는 경우 동작이 정의되지 않습니다.
플래그가 참인 경우, catch_warnings 는 전역 어트리뷰트를 수정하지 않고 대신 새로 설정된 경고 필터링 상태를 저장하기 위해 ContextVar 을(를) 사용합니다. 컨텍스트 변수는 스레드 로컬 저장 공간을 제공하며, 이를 통해 catch_warnings 의 사용이 스레드 안전해집니다.
컨텍스트 핸들러의 record 매개변수 또한 플래그 값에 따라 다르게 동작합니다. record 가 참이고 플래그가 거짓인 경우, 컨텍스트 관리자는 모듈의 showwarning() 함수를 교체한 후 나중에 복원하는 방식으로 작동하며 이는 동시성 안전하지 않습니다.
record 가 참이고 플래그가 참인 경우, showwarning() 함수는 교체되지 않습니다. 대신 컨텍스트 변수의 내부 속성에 의해 기록 상태가 표시됩니다. 이 경우 컨텍스트 핸들러를 종료할 때 showwarning() 함수가 복원되지 않습니다.
context_aware_warnings 플래그는 -X context_aware_warnings 명령줄 옵션이나 PYTHON_CONTEXT_AWARE_WARNINGS 환경 변수를 통해 설정할 수 있습니다.
참고
warnings 모듈의 스레드 안전한 동작을 원하는 대부분의 프로그램은
thread_inherit_context플래그도 참으로 설정하기를 원할 것입니다. 해당 플래그가 활성화되면threading.Thread로 생성된 스레드가 이를 시작한 스레드의 컨텍스트 변수 복사본을 가지고 시작됩니다. 이 값이 참이면, 한 스레드에서catch_warnings로 설정된 컨텍스트가 해당 스레드에 의해 시작된 새 스레드에도 적용됩니다. 만약 거짓이라면, 새 스레드는 빈 경고 컨텍스트 변수와 함께 시작되며 이는catch_warnings컨텍스트 관리자에 의해 설정된 모든 필터링이 더 이상 활성화되지 않음을 의미합니다.
버전 3.14에서 변경: sys.flags.context_aware_warnings 플래그와 플래그가 참인 경우 catch_warnings 를 위한 컨텍스트 변수 사용이 추가되었습니다. 이전 버전의 파이썬은 이 플래그가 항상 거짓으로 설정된 것처럼 동작했습니다.