"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__" によって引き起こされない限り通常は  |
|                                    | 無視 されます)。                                |
+------------------------------------+-------------------------------------------------+
| "SyntaxWarning"                    | Base category for warnings about dubious        |
|                                    | syntactic features (typically emitted when      |
|                                    | compiling Python source code, and hence may not |
|                                    | be suppressed by runtime filters)               |
+------------------------------------+-------------------------------------------------+
| "RuntimeWarning"                   | そのランタイム機能があいまいであることを示す警  |
|                                    | 告カテゴリの基底クラスで す。                   |
+------------------------------------+-------------------------------------------------+
| "FutureWarning"                    | Python で書かれたアプリケーションのエンドユーザ |
|                                    | ーへ向けて警告を発する ときの、非推奨の機能につ |
|                                    | いての警告の基底カテゴリです。                  |
+------------------------------------+-------------------------------------------------+
| "PendingDeprecationWarning"        | 将来その機能が非推奨になることを示す警告カテゴ  |
|                                    | リの基底クラスです(デフ ォルトでは無視されます) |
|                                    | 。                                              |
+------------------------------------+-------------------------------------------------+
| "ImportWarning"                    | モジュールのインポート処理中に引き起こされる警  |
|                                    | 告カテゴリの基底クラスで す (デフォルトでは無視 |
|                                    | されます)。                                     |
+------------------------------------+-------------------------------------------------+
| "UnicodeWarning"                   | Unicode に関係した警告カテゴリの基底クラスです  |
|                                    | 。                                              |
+------------------------------------+-------------------------------------------------+
| "BytesWarning"                     | "bytes" や "bytearray" に関連した警告カテゴリの |
|                                    | 基底クラスです。                                |
+------------------------------------+-------------------------------------------------+
| "ResourceWarning"                  | リソースの使用に関連した警告カテゴリの基底クラ  |
|                                    | スです (デフォルトでは無 視されます)。          |
+------------------------------------+-------------------------------------------------+

バージョン 3.7 で変更: Previously "DeprecationWarning" and
"FutureWarning" were distinguished based on whether a feature was
being removed entirely or changing its behaviour. They are now
distinguished based on their intended audience and the way they're
handled by the default warnings filters.


警告フィルタ
============

警告フィルタは、ある警告を無視すべきか、表示すべきか、あるいは (例外を
送出する) エラーにするべきかを制御します。

概念的には、警告フィルタは複数のフィルタ仕様からなる順番リストを維持し
ています; 何らかの特定の警告が生じると、一致するものが見つかるまでリス
ト中の各フィルタとの照合が行われます; 一致したフィルタ仕様がその警告の
処理方法を決定します。フィルタの各エントリは (*action*, *message*,
*category*, *module*, *lineno*) からなるタプルです。ここで:

* *action* は以下の文字列のうちの一つです:

  +-----------------+------------------------------------------------+
  | 値              | 処理方法                                       |
  |=================|================================================|
  | ""default""     | print the first occurrence of matching         |
  |                 | warnings for each location (module + line      |
  |                 | number) where the warning is issued            |
  +-----------------+------------------------------------------------+
  | ""error""       | 一致した警告を例外に変えます                   |
  +-----------------+------------------------------------------------+
  | ""ignore""      | 一致した警告を出力しません                     |
  +-----------------+------------------------------------------------+
  | ""always""      | 一致した警告を常に出力します                   |
  +-----------------+------------------------------------------------+
  | ""all""         | alias to "always"                              |
  +-----------------+------------------------------------------------+
  | ""module""      | print the first occurrence of matching         |
  |                 | warnings for each module where the warning is  |
  |                 | issued (regardless of line number)             |
  +-----------------+------------------------------------------------+
  | ""once""        | 一致した警告のうち、警告の原因になった場所にか |
  |                 | かわらず最初の警告のみ 出力します              |
  +-----------------+------------------------------------------------+

* *message* is a string containing a regular expression that the start
  of the warning message must match, case-insensitively.  In "-W" and
  "PYTHONWARNINGS", *message* is a literal string that the start of
  the warning message must contain (case-insensitively), ignoring any
  whitespace at the start or end of *message*.

* *category* はクラス ("Warning" のサブクラス) です。警告クラスはこの
  クラスのサブクラスに一致しなければなりません。

* *module* is a string containing a regular expression that the start
  of the fully qualified module name must match, case-sensitively.  In
  "-W" and "PYTHONWARNINGS", *module* is a literal string that the
  fully qualified module name must be equal to (case-sensitively),
  ignoring any whitespace at the start or end of *module*.

* *lineno* は整数で、警告が発生した場所の行番号に一致しなければなりま
  せん。"0" の場合はすべての行と一致します。

"Warning" クラスは組み込みの "Exception" クラスから派生しているので、
警告をエラーに変換するには単に "category(message)" を "raise" します。

If a warning is reported and doesn't match any registered filter then
the "default" action is applied (hence its name).


Repeated Warning Suppression Criteria
-------------------------------------

The filters that suppress repeated warnings apply the following
criteria to determine if a warning is considered a repeat:

* ""default"": A warning is considered a repeat only if the
  (*message*, *category*, *module*, *lineno*) are all the same.

* ""module"": A warning is considered a repeat if the (*message*,
  *category*, *module*) are the same, ignoring the line number.

* ""once"": A warning is considered a repeat if the (*message*,
  *category*) are the same, ignoring the module and line number.


Describing Warning Filters
--------------------------

The warnings filter is initialized by "-W" options passed to the
Python interpreter command line and the "PYTHONWARNINGS" environment
variable. The interpreter saves the arguments for all supplied entries
without interpretation in "sys.warnoptions"; the "warnings" module
parses these when it is first imported (invalid options are ignored,
after printing a message to "sys.stderr").

Individual warnings filters are specified as a sequence of fields
separated by colons:

   action:message:category:module:line

The meaning of each of these fields is as described in 警告フィルタ.
When listing multiple filters on a single line (as for
"PYTHONWARNINGS"), the individual filters are separated by commas and
the filters listed later take precedence over those listed before them
(as they're applied left-to-right, and the most recently applied
filters take precedence over earlier ones).

Commonly used warning filters apply to either all warnings, warnings
in a particular category, or warnings raised by particular modules or
packages. Some examples:

   default                      # Show all warnings (even those ignored by default)
   ignore                       # Ignore all warnings
   error                        # Convert all warnings to errors
   error::ResourceWarning       # Treat ResourceWarning messages as errors
   default::DeprecationWarning  # Show DeprecationWarning messages
   ignore,default:::mymodule    # Only report warnings triggered by "mymodule"
   error:::mymodule             # Convert warnings to errors in "mymodule"


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

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

In regular release builds, the default warning filter has the
following entries (in order of precedence):

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

In a debug build, the list of default warning filters is empty.

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

バージョン 3.7 で変更: "DeprecationWarning" is once again shown by
default when triggered directly by code in "__main__".

バージョン 3.7 で変更: "BytesWarning" no longer appears in the default
filter list and is instead configured via "sys.warnoptions" when "-b"
is specified twice.


Overriding the default filter
-----------------------------

Developers of applications written in Python may wish to hide *all*
Python level warnings from their users by default, and only display
them when running tests or otherwise working on the application. The
"sys.warnoptions" attribute used to pass filter configurations to the
interpreter can be used as a marker to indicate whether or not
warnings should be disabled:

   import sys

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

Developers of test runners for Python code are advised to instead
ensure that *all* warnings are displayed by default for the code under
test, using code like:

   import sys

   if not sys.warnoptions:
       import os, warnings
       warnings.simplefilter("default") # Change the filter in this process
       os.environ["PYTHONWARNINGS"] = "default" # Also affect subprocesses

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__"))


一時的に警告を抑制する
======================

If you are using code that you know will raise a warning, such as a
deprecated function, but do not want to see the warning (even when
warnings have been explicitly configured via the command line), then
it is possible to suppress the warning using the "catch_warnings"
context manager:

   import warnings

   def fxn():
       warnings.warn("deprecated", DeprecationWarning)

   with warnings.catch_warnings():
       warnings.simplefilter("ignore")
       fxn()

While within the context manager all warnings will simply be ignored.
This allows you to use known-deprecated code without having to see the
warning while not suppressing the warning for other code that might
not be aware of its use of deprecated code.

   注釈:

     See Concurrent safety of Context Managers for details on the
     concurrency-safety of the "catch_warnings" context manager when
     used in programs using multiple threads or async functions.


警告のテスト
============

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

Once the context manager exits, the warnings filter is restored to its
state when the context was entered. This prevents tests from changing
the warnings filter in unexpected ways between tests and leading to
indeterminate test results.

   注釈:

     See Concurrent safety of Context Managers for details on the
     concurrency-safety of the "catch_warnings" context manager when
     used in programs using multiple threads or async functions.

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


Updating Code For New Versions of Dependencies
==============================================

Warning categories that are primarily of interest to Python developers
(rather than end users of applications written in Python) are ignored
by default.

Notably, this "ignored by default" list includes "DeprecationWarning"
(for every module except "__main__"), which means developers should
make sure to test their code with typically ignored warnings made
visible in order to receive timely notifications of future breaking
API changes (whether in the standard library or third party packages).

In the ideal case, the code will have a suitable test suite, and the
test runner will take care of implicitly enabling all warnings when
running tests (the test runner provided by the "unittest" module does
this).

In less ideal cases, applications can be checked for use of deprecated
interfaces by passing "-Wd" to the Python interpreter (this is
shorthand for "-W default") or setting "PYTHONWARNINGS=default" in the
environment. This enables default handling for all warnings, including
those that are ignored by default. To change what action is taken for
encountered warnings you can change what argument is passed to "-W"
(e.g. "-W error"). See the "-W" flag for more details on what is
possible.


利用可能な関数
==============

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)

   This makes the warning refer to "deprecated_api"'s caller, rather
   than to the source of "deprecated_api" itself (since the latter
   would defeat the purpose of the warning message).

   The *skip_file_prefixes* keyword argument can be used to indicate
   which stack frames are ignored when counting stack levels. This can
   be useful when you want the warning to always appear at call sites
   outside of a package when a constant *stacklevel* does not fit all
   call paths or is otherwise challenging to maintain. If supplied, it
   must be a tuple of strings. When prefixes are supplied, stacklevel
   is implicitly overridden to be "max(2, stacklevel)". To cause a
   warning to be attributed to the caller from outside of the current
   package you might write:

      # 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)

   This makes the warning refer to both the "example.lower.one_way()"
   and "example.higher.another_way()" call sites only from calling
   code living outside of "example" package.

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

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

   バージョン 3.12 で変更: Added *skip_file_prefixes*.

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

   This is a low-level interface to the functionality of "warn()",
   passing in explicitly the message, category, filename and line
   number, and optionally other arguments. *message* must be a string
   and *category* a subclass of "Warning" or *message* may be a
   "Warning" instance, in which case *category* will be ignored.

   *module*, if supplied, should be the module name. If no module is
   passed, the filename with ".py" stripped is used.

   *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* 引数を追加しました。

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)

   Decorator to indicate that a class, function or overload is
   deprecated.

   When this decorator is applied to an object, deprecation warnings
   may be emitted at runtime when the object is used. *static type
   checkers* will also generate a diagnostic on usage of the
   deprecated object.

   使い方:

      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: ...

   The warning specified by *category* will be emitted at runtime on
   use of deprecated objects. For functions, that happens on calls;
   for classes, on instantiation and on creation of subclasses. If the
   *category* is "None", no warning is emitted at runtime. The
   *stacklevel* determines where the warning is emitted. If it is "1"
   (the default), the warning is emitted at the direct caller of the
   deprecated object; if it is higher, it is emitted further up the
   stack. Static type checker behavior is not affected by the
   *category* and *stacklevel* arguments.

   The deprecation message passed to the decorator is saved in the
   "__deprecated__" attribute on the decorated object. If applied to
   an overload, the decorator must be after the "@~typing.overload"
   decorator for the attribute to exist on the overload as returned by
   "typing.get_overloads()".

   Added in version 3.13: See **PEP 702**.


利用可能なコンテキストマネージャー
==================================

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

   A context manager that copies and, upon exit, restores the warnings
   filter and the "showwarning()" function. If the *record* argument
   is "False" (the default) the context manager returns "None" on
   entry. If *record* is "True", a list is returned that is
   progressively populated with objects as seen by a custom
   "showwarning()" function (which also suppresses output to
   "sys.stderr"). Each object in the list is guaranteed to have the
   following attributes:

      * "message": the warning message (an instance of "Warning")

      * "category": the warning category (a subclass of "Warning")

      * "filename": the file name where the warning occurred ("str")

      * "lineno": the line number in the file ("int")

      * "file": the file object used for output (if any), or "None"

      * "line": the line of source code (if available), or "None"

      * "source": the original object that generated the warning (if
        available), or "None"

   バージョン 3.6 で変更: The "source" attribute was added.

   The type of these objects is not specified and may change; only the
   presence of these attributes is guaranteed.

   The *module* argument takes a module that will be used instead of
   the module returned when you import "warnings" whose filter will be
   protected. This argument exists primarily for testing the
   "warnings" module itself.

   If the *action* argument is not "None", the remaining arguments are
   passed to "simplefilter()" as if it were called immediately on
   entering the context.

   See 警告フィルタ for the meaning of the *category* and *lineno*
   parameters.

   注釈:

     See Concurrent safety of Context Managers for details on the
     concurrency-safety of the "catch_warnings" context manager when
     used in programs using multiple threads or async functions.

   バージョン 3.11 で変更: Added the *action*, *category*, *lineno*,
   and *append* parameters.


Concurrent safety of Context Managers
=====================================

The behavior of "catch_warnings" context manager depends on the
"sys.flags.context_aware_warnings" flag.  If the flag is true, the
context manager behaves in a concurrent-safe fashion and otherwise
not. Concurrent-safe means that it is both thread-safe and safe to use
within asyncio coroutines and tasks.  Being thread-safe means that
behavior is predictable in a multi-threaded program.  The flag
defaults to true for free-threaded builds and false otherwise.

If the "context_aware_warnings" flag is false, then "catch_warnings"
will modify the global attributes of the "warnings" module.  This is
not safe if used within a concurrent program (using multiple threads
or using asyncio coroutines).  For example, if two or more threads use
the "catch_warnings" class at the same time, the behavior is
undefined.

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.

The *record* parameter of the context handler also behaves differently
depending on the value of the flag.  When *record* is true and the
flag is false, the context manager works by replacing and then later
restoring the module's "showwarning()" function.  That is not
concurrent-safe.

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.

The "context_aware_warnings" flag can be set the "-X
context_aware_warnings" command-line option or by the
"PYTHON_CONTEXT_AWARE_WARNINGS" environment variable.

   注釈:

     It is likely that most programs that desire thread-safe behaviour
     of the warnings module will also want to set the
     "thread_inherit_context" flag to true.  That flag causes threads
     created by "threading.Thread" to start with a copy of the context
     variables from the thread starting it.  When true, the context
     established by "catch_warnings" in one thread will also apply to
     new threads started by it.  If false, new threads will start with
     an empty warnings context variable, meaning that any filtering
     that was established by a "catch_warnings" context manager will
     no longer be active.

バージョン 3.14 で変更: Added the "sys.flags.context_aware_warnings"
flag and the use of a context variable for "catch_warnings" if the
flag is true.  Previous versions of Python acted as if the flag was
always set to false.
