"warnings" --- 警告の制御
*************************

**ソースコード:** Lib/warnings.py

======================================================================

警告メッセージは一般に、ユーザに警告しておいた方がよいような状況下にプ
ログラムが置かれているが、その状況は (通常は) 例外を送出したりそのプロ
グラムを終了させるほどの正当な理由がないといった状況で発されます。例え
ば、プログラムが古いモジュールを使っている場合には警告を発したくなるか
もしれません。

Python プログラマは、このモジュールの "warn()" 関数を使って警告を発す
ることができます。(C 言語のプログラマは "PyErr_WarnEx()" を使います;
詳細は 例外処理 を参照してください)。

警告メッセージは通常 "sys.stderr" に出力されますが、すべての警告を無視
したり、警告を例外にしたりと、その処理を柔軟に変更することができます。
警告の処理は warning category 、警告メッセージのテキスト、警告が発行さ
れたソースの位置に基づいて変化します。 同じソースの位置で特定の警告が
繰り返された場合、通常は抑制されます。

警告制御には 2 つの段階 (stage) があります: 第一に、警告が発されるたび
に、メッセージを出力すべきかどうかの決定が行われます; 次に、メッセージ
を出力するなら、メッセージはユーザによって設定が可能なフックを使って書
式化され印字されます。

警告メッセージを出力するかどうかの決定は、 警告フィルタ によって制御さ
れます。警告フィルタは一致規則 (matching rule)と動作からなるシーケンス
です。 "filterwarnings()" を呼び出して一致規則をフィルタに追加すること
ができ、 "resetwarnings()" を呼び出してフィルタを標準設定の状態にリセ
ットすることができます。

警告メッセージの印字は "showwarning()" を呼び出して行うことができ、こ
の関数は上書きすることができます; この関数の標準の実装では、
"formatwarning()" を呼び出して警告メッセージを書式化しますが、この関数
についても自作の実装を使うことができます。

参考: "logging.captureWarnings()" を使うことで、標準ロギング基盤ですべての
    警告を扱うことができます。


警告カテゴリ
============

警告カテゴリを表現する組み込み例外は数多くあります。このカテゴリ化は警
告をグループごとフィルタする上で便利です。

これらは厳密に言えば 組み込み例外 ですが、概念的には警告メカニズムに属
しているのでここで記述されています。

標準の警告カテゴリをユーザの作成したコード上でサブクラス化することで、
さらに別の警告カテゴリを定義することができます。警告カテゴリは常に
"Warning" クラスのサブクラスでなければなりません。

現在以下の警告カテゴリクラスが定義されています:

+------------------------------------+-------------------------------------------------+
| クラス                             | 説明                                            |
|====================================|=================================================|
| "Warning"                          | 警告カテゴリの基底クラスです。 "Exception" のサ |
|                                    | ブクラスです。                                  |
+------------------------------------+-------------------------------------------------+
| "UserWarning"                      | 利用者のコードが生成する警告の基底クラスです。  |
|                                    | "warn()" のデフォルトの カテゴリです。          |
+------------------------------------+-------------------------------------------------+
| "DeprecationWarning"               | 他の Python 開発者を対象にした、非推奨の機能に  |
|                                    | ついての警告の基底クラス です ("__main__" 内の  |
|                                    | コードが発する場合を除き、デフォルトで無視され  |
|                                    | ま す)。                                        |
+------------------------------------+-------------------------------------------------+
| "PendingDeprecationWarning"        | 将来非推奨になる機能についての警告の基底クラス  |
|                                    | です (デフォルトで無視さ れます)。              |
+------------------------------------+-------------------------------------------------+
| "SyntaxWarning"                    | 疑わしい構文についての警告の基底クラスです (通  |
|                                    | 常は Python ソースコード のコンパイル時に発せら |
|                                    | れるため、実行時のフィルタでは抑制できない場合  |
|                                    | が あります)。                                  |
+------------------------------------+-------------------------------------------------+
| "RuntimeWarning"                   | 疑わしい実行時の動作についての警告の基底クラス  |
|                                    | です。                                          |
+------------------------------------+-------------------------------------------------+
| "FutureWarning"                    | Python で書かれたアプリケーションのエンドユーザ |
|                                    | ーへ向けて警告を発する ときの、廃止予定の機能に |
|                                    | ついての警告の基底クラスです。                  |
+------------------------------------+-------------------------------------------------+
| "ImportWarning"                    | モジュールのインポート中に発せられる警告の基底  |
|                                    | クラスです (デフォルトで 無視されます)。        |
+------------------------------------+-------------------------------------------------+
| "UnicodeWarning"                   | Unicode に関連した警告の基底クラスです。        |
+------------------------------------+-------------------------------------------------+
| "EncodingWarning"                  | エンコーディングに関する警告の基底クラスです。  |
|                                    | 詳しくは EncodingWarning の有効化 を参照してく  |
|                                    | ださい。                                        |
+------------------------------------+-------------------------------------------------+
| "BytesWarning"                     | "bytes" や "bytearray" に関連した警告の基底クラ |
|                                    | スです。                                        |
+------------------------------------+-------------------------------------------------+
| "ResourceWarning"                  | リソースの使用に関する警告の基底クラスです (デ  |
|                                    | フォルトで無視されます) 。                      |
+------------------------------------+-------------------------------------------------+

バージョン 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" のサブクラス) です。 警告が一致するに
  は、その警告カテゴリが *category* のサブクラスでなければなりません。

* *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*) が同じ
  であれば、警告を繰り返しと見なします。


警告フィルタの指定方法
----------------------

警告フィルタは、Python インタープリタのコマンドラインに渡す "-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" の警告をエラーにする


デフォルトの警告フィルタ
------------------------

デフォルトで、 Python はいくつかの警告フィルタをインストールします。こ
れは "-W" コマンドラインオプション、"PYTHONWARNINGS" 環境変数または
"filterwarnings()" の呼び出しでオーバーライドできます。

通常のリリースビルドでは、デフォルトの警告フィルタに次のエントリーが優
先順に含まれています。

   default::DeprecationWarning:__main__
   ignore::DeprecationWarning
   ignore::PendingDeprecationWarning
   ignore::ImportWarning
   ignore::ResourceWarning

デバッグビルド では、デフォルトの警告フィルタのリストは空です。

バージョン 3.2 で変更: "PendingDeprecationWarning" に加えて、
"DeprecationWarning" もデフォルトで無視されるようになりました。

バージョン 3.7 で変更: "__main__" 内のコードが直接発する
"DeprecationWarning" は、再びデフォルトで表示されるようになりました。

バージョン 3.7 で変更: "BytesWarning" がデフォルトのフィルタリストから
除かれ、代わりに "-b" を二回指定したときに "sys.warnoptions" を通じて
設定されるようになりました。


デフォルトのフィルタの上書き
----------------------------

Python で書いたアプリケーションの開発者は、Python レベルの *すべての*
警告をデフォルトでは利用者に表示せず、テストやその他の開発作業のときだ
け表示したい場合があります。 フィルタ設定をインタープリタに渡すための
"sys.warnoptions" 属性を、警告を無効にすべきかどうかの目印に使えます。

   import sys

   if not sys.warnoptions:
       import warnings
       warnings.simplefilter("ignore")

一方、Python コードのテストランナーを開発する場合は、次のようなコード
を使い、テスト対象のコードについてはデフォルトで *すべての* 警告を表示
することを推奨します。

   import sys

   if not sys.warnoptions:
       import os, warnings
       warnings.simplefilter("default") # このプロセス内のフィルタを変更する
       os.environ["PYTHONWARNINGS"] = "default" # 子プロセスにも反映する

Finally, developers of interactive shells that run user code in a
namespace other than "__main__" are advised to ensure that
"DeprecationWarning" messages are made visible by default, using code
like the following (where "user_ns" is the module used to execute code
entered interactively):

   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:
       # すべての警告を常に発生させる。
       warnings.simplefilter("always")
       # 警告を発生させる。
       fxn()
       # いくつかの項目を検証する
       assert len(w) == 1
       assert issubclass(w[-1].category, DeprecationWarning)
       assert "deprecated" in str(w[-1].message)

"always" の代わりに "error" を利用することで、すべての警告で例外を発生
させることができます。1つ気をつけないといけないのは、一度
"once"/"default" ルールによって発生した警告は、フィルタに何をセットし
ているかにかかわらず、警告レジストリをクリアしない限りは 2度と発生しま
せん。

コンテキストマネージャーを抜けると、警告フィルタはコンテキストに入った
ときの状態に戻ります。 これにより、テスト間で警告フィルタが予期せず変
更され、テスト結果が不定になることを防ぎます。

   注釈:

     複数のスレッドや非同期関数を使うプログラムで "catch_warnings" コ
     ンテキストマネージャーを使う際の、並行処理の安全性については コン
     テキストマネージャーの並行処理の安全性 を参照してください。

同じ種類の警告を発生させる複数の操作をテストする場合、各操作が新しい警
告を発生させている事を確認するのは大切な事です (例えば、警告を例外とし
て発生させて各操作が例外を発生させることを確認したり、警告リストの長さ
が各操作で増加していることを確認したり、警告リストを各操作の前に毎回ク
リアする事ができます)。


依存先の新しいバージョンに合わせたコードの更新
==============================================

主に Python 開発者向けの警告カテゴリ (Python で書かれたアプリケーショ
ンのエンドユーザー向けではないもの) は、デフォルトで無視されます。

特に、この「デフォルトで無視する」リストには、"__main__" 以外のすべて
のモジュールの "DeprecationWarning" が含まれます。 そのため開発者は、
通常は無視される警告を表示するようにしてコードをテストする必要がありま
す。 そうすれば、標準ライブラリやサードパーティのパッケージで将来行わ
れる、互換性を損なう API の変更を早めに把握できます。

理想的には、コードに適切なテストスイートが用意されており、テスト実行時
にはテストランナーが暗黙にすべての警告を有効にします ("unittest" モジ
ュールが提供するテストランナーは、このように動作します)。

そうした環境が整っていない場合でも、Python インタープリタに "-Wd" ("-W
default" の省略形) を渡すか、環境変数 "PYTHONWARNINGS=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* 引数は Python で書くラッパー関数で次のように使えます。

      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.lower.one_way()" と
   "example.higher.another_way()" のどちらの呼び出しでも、"example" パ
   ッケージの外にある呼び出し元の箇所を警告が指すようになります。

   *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* を指定する場合は、モジュール名にしてください。 *module* を
   省略した場合、警告フィルタ のモジュールの正規表現は、各親ディレクト
   リから始まるパス要素で構築したモジュール名と、".py" を取り除いたフ
   ァイル名に対して照合されます。 モジュール名の構築では
   "/__init__.py"、".py"、および Windows では ".pyw" を取り除きます。
   例えばファイル名が "'/path/to/package/module.py'" の場合、
   "'path.to.package.module'"、"'to.package.module'"、
   "'package.module'"、"'module'"、"'/path/to/package/module'" に対し
   て照合されます。

   *registry*, if supplied, should be the "__warningregistry__"
   dictionary of the module. If no registry is passed, each warning is
   treated as the first occurrence, that is, filter actions
   ""default"", ""module"" and ""once"" are handled as ""always"".

   *module_globals* は、もし与えられるならば、警告が発せられるコードが
   使っているグローバル名前空間でなければなりません (この引数は
   zipfile やその他の非ファイルシステムのインポート元の中にあるモジュ
   ールのソースを表示することをサポートするためのものです)。

   *source* 引数が与えられた場合、これは "ResourceWarning" を発生させ
   た破壊されたオブジェクトです。

   バージョン 3.6 で変更: *source* 引数を追加しました。

   バージョン 3.15 で変更: *module* が渡されなかった場合、パスそのもの
   だけでなく、パスから作ったモジュール名に対してもフィルタの正規表現
   を照合するようになりました。

warnings.showwarning(message, category, filename, lineno, file=None, line=None)

   警告をファイルに書き込みます。標準の実装では、
   "formatwarning(message, category, filename, lineno, line)" を呼び出
   し、返された文字列を *file* に書き込みます。 *file* は標準では
   "sys.stderr" です。この関数は "warnings.showwarning" に任意の呼び出
   し可能オブジェクトを代入して置き換えることができます。 *line* は警
   告メッセージに含めるソースコードの1行です。 *line* が与えられない場
   合、 "showwarning()" は *filename* と *lineno* から行を取得すること
   を試みます。

warnings.formatwarning(message, category, filename, lineno, line=None)

   警告を通常の方法で書式化します。返される文字列内には改行が埋め込ま
   れている可能性があり、かつ文字列は改行で終端されています。 *line*
   は警告メッセージに含まれるソースコードの1行です。 *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(message, /, *, 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" への出力も抑制
   します)。 リストの各オブジェクトには、次の属性があることが保証され
   ます:

      * "message": 警告メッセージ ("Warning" のインスタンス)

      * "category": 警告カテゴリ ("Warning" のサブクラス)

      * "filename": 警告が発生したファイルの名前 ("str")

      * "lineno": ファイル内の行番号 ("int")

      * "file": 出力に使うファイルオブジェクト (ある場合)、または
        "None"

      * "line": ソースコードの行 (取得できる場合)、または "None"

      * "source": 警告を発生させた元のオブジェクト (取得できる場合)、
        または "None"

      * "module": 警告が発生したモジュールの名前 ("str")、または
        "None"

   バージョン 3.6 で変更: "source" 属性が追加されました。

   バージョン 3.15 で変更: "module" 属性が追加されました。

   これらのオブジェクトの型は規定されておらず、変更される可能性があり
   ます。 保証されるのは、これらの属性が存在することだけです。

   *module* 引数には、"warnings" をインポートしたときに返されるモジュ
   ールの代わりに使い、そのフィルタを保護する対象となるモジュールを指
   定します。 この引数は主に "warnings" モジュール自体のテストのために
   用意されています。

   *action* 引数が "None" でない場合、残りの引数を "simplefilter()" に
   渡し、コンテキストに入った直後に呼び出した場合と同じ処理を行います
   。

   *category* と *lineno* パラメータの意味は 警告フィルタ を参照してく
   ださい。

   注釈:

     複数のスレッドや非同期関数を使うプログラムで "catch_warnings" コ
     ンテキストマネージャーを使う際の、並行処理の安全性については コン
     テキストマネージャーの並行処理の安全性 を参照してください。

   バージョン 3.11 で変更: *action*、*category*、*lineno*、*append* パ
   ラメータが追加されました。


コンテキストマネージャーの並行処理の安全性
==========================================

"catch_warnings" コンテキストマネージャーの動作は、
"sys.flags.context_aware_warnings" フラグに依存します。 このフラグが真
なら並行処理で安全に動作し、偽なら安全ではありません。 並行処理で安全
とは、スレッドセーフであり、asyncio のコルーチン やタスク内でも安全に
使えるという意味です。 スレッドセーフとは、マルチスレッドのプログラム
で動作が予測可能であるという意味です。 このフラグのデフォルト値は、フ
リースレッドビルドでは真、それ以外では偽です。

"context_aware_warnings" フラグが偽の場合、"catch_warnings" は
"warnings" モジュールのグローバル属性を変更します。 そのため、複数のス
レッドや asyncio のコルーチンを使う並行プログラム内で使うのは安全では
ありません。 例えば、二つ以上のスレッドが同時に "catch_warnings" クラ
スを使った場合の動作は未定義です。

If the flag is true, "catch_warnings" will not modify global
attributes and will instead use a "ContextVar" to store the newly
established warning filtering state.  A context variable provides
thread-local storage and it makes the use of "catch_warnings" thread-
safe.

コンテキストマネージャーの *record* パラメータの動作も、フラグの値によ
って異なります。 *record* が真でフラグが偽の場合、コンテキストマネージ
ャーはモジュールの "showwarning()" 関数を置き換え、後で元に戻すことで
動作します。 これは並行処理で安全ではありません。

When *record* is true and the flag is true, the "showwarning()"
function is not replaced.  Instead, the recording status is indicated
by an internal property in the context variable.  In this case, the
"showwarning()" function will not be restored when exiting the context
handler.

"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" はコンテキスト変
数を使います。 以前の Python は、常にこのフラグを偽に設定した場合と同
じ動作をしていました。
