From 51548d6730571cae3b8594711d110e87fc53d652 Mon Sep 17 00:00:00 2001 From: Kurt McKee Date: Thu, 6 Jun 2024 18:20:27 -0500 Subject: [PATCH 1/2] Document how to manage Globus SDK warnings --- ...kee_howto_disable_v4_warnings_sc_29682.rst | 4 + docs/core/exceptions.rst | 4 + docs/testing/index.rst | 1 + docs/testing/warnings.rst | 126 ++++++++++++++++++ 4 files changed, 135 insertions(+) create mode 100644 changelog.d/20240606_181744_kurtmckee_howto_disable_v4_warnings_sc_29682.rst create mode 100644 docs/testing/warnings.rst diff --git a/changelog.d/20240606_181744_kurtmckee_howto_disable_v4_warnings_sc_29682.rst b/changelog.d/20240606_181744_kurtmckee_howto_disable_v4_warnings_sc_29682.rst new file mode 100644 index 000000000..a0534f5ba --- /dev/null +++ b/changelog.d/20240606_181744_kurtmckee_howto_disable_v4_warnings_sc_29682.rst @@ -0,0 +1,4 @@ +Documentation +~~~~~~~~~~~~~ + +- Document how to manage Globus SDK warnings. (:pr:`NUMBER`) diff --git a/docs/core/exceptions.rst b/docs/core/exceptions.rst index b6369225c..49457a74b 100644 --- a/docs/core/exceptions.rst +++ b/docs/core/exceptions.rst @@ -165,6 +165,10 @@ Warnings The following warnings can be emitted by the Globus SDK to indicate a problem which is not necessarily an error. +.. seealso:: + + :ref:`managing-warnings` + .. autoclass:: globus_sdk.RemovedInV4Warning :members: :show-inheritance: diff --git a/docs/testing/index.rst b/docs/testing/index.rst index 9de0abb21..d863842d3 100644 --- a/docs/testing/index.rst +++ b/docs/testing/index.rst @@ -19,4 +19,5 @@ Globus SDK _testing getting_started reference + warnings methods/index diff --git a/docs/testing/warnings.rst b/docs/testing/warnings.rst new file mode 100644 index 000000000..2a7058909 --- /dev/null +++ b/docs/testing/warnings.rst @@ -0,0 +1,126 @@ +.. _managing-warnings: + +Managing warnings +================= + +The Globus SDK issues deprecation warnings to notify developers of upcoming changes. + +By default, Python will not display deprecation warnings to end users, +but testing frameworks like pytest will enable deprecation warnings for developers. + +.. seealso:: + + * `Python's warnings module`_ + * `pytest's warnings documentation`_ + + +Enabling deprecation warnings +----------------------------- + +By default, Python ignores deprecation warnings, +so end users of your application will not see warnings. + +However, you may want to enable deprecation warnings +to help prepare for coming changes in the Globus SDK. +Deprecation warnings can be enabled in several ways: + +#. The ``PYTHONWARNINGS`` environment variable +#. The Python executable ``-W`` argument +#. The Python ``warnings.filterwarnings()`` function + + +.. rubric:: The ``PYTHONWARNINGS`` environment variable + +Deprecation warnings can be enabled using this shell syntax: + +.. code-block:: bash + + # POSIX shell example + export PYTHONWARNINGS="error::DeprecationWarning" + python ... + + # Inline example + PYTHONWARNINGS="error::DeprecationWarning" python ... + +.. code-block:: pwsh + + # Powershell example + $env:PYTHONWARNINGS="error::DeprecationWarning" + python ... + + +.. rubric:: The Python executable ``-W`` argument + +Deprecation warnings can be enabled using this Python executable argument: + +.. code-block:: text + + python -W "error::DeprecationWarning" ... + + +.. rubric:: The Python ``warnings.filterwarnings()`` function + +Deprecation warnings can be enabled in Python code: + +.. code-block:: python + + import warnings + + warnings.filterwarnings("error", category=DeprecationWarning) + + +Disabling deprecation warnings +------------------------------ + +Python testing frameworks like pytest enable deprecation warnings by default. +Deprecation warnings can be disabled in several ways: + +#. The ``PYTHONWARNINGS`` environment variable +#. The pytest executable ``-W`` argument +#. The ``pytest.ini`` (or similar) file + + +.. rubric:: The ``PYTHONWARNINGS`` environment variable + +You can disable deprecation warnings using environment variables: + +.. code-block:: bash + + # POSIX shell example + export PYTHONWARNINGS="ignore::DeprecationWarning" + pytest ... + + # Inline example + PYTHONWARNINGS="ignore::DeprecationWarning" pytest ... + +.. code-block:: pwsh + + # Powershell example + $env:PYTHONWARNINGS="ignore::DeprecationWarning" + pytest ... + + +.. rubric:: The pytest executable ``-W`` argument + +You can disable deprecation warnings using pytest's ``-W`` argument: + +.. code-block:: text + + pytest -W "ignore::DeprecationWarning" ... + + +.. rubric:: The ``pytest.ini`` (or similar) file + +You can disable warnings using a pytest configuration file like ``pytest.ini``: + +.. code-block:: ini + + [pytest] + filterwarnings = + ignore::DeprecationWarning + + +.. Links +.. ----- +.. _Python's warnings module: https://docs.python.org/3/library/warnings.html +.. _pytest's warnings documentation: https://docs.pytest.org/en/latest/how-to/capture-warnings.html From ebb65916dd9ae1a2a467d702130843eb6a291384 Mon Sep 17 00:00:00 2001 From: Kurt McKee Date: Fri, 7 Jun 2024 11:48:10 -0500 Subject: [PATCH 2/2] Feedback: Move warnings content out of `_testing` --- docs/core/exceptions.rst | 14 -------------- docs/core/index.rst | 1 + docs/{testing => core}/warnings.rst | 12 ++++++++---- docs/testing/index.rst | 1 - 4 files changed, 9 insertions(+), 19 deletions(-) rename docs/{testing => core}/warnings.rst (92%) diff --git a/docs/core/exceptions.rst b/docs/core/exceptions.rst index 49457a74b..70837a349 100644 --- a/docs/core/exceptions.rst +++ b/docs/core/exceptions.rst @@ -158,17 +158,3 @@ attributes should be tested before use, as in .. autoclass:: globus_sdk.exc.ConsentRequiredInfo :members: :show-inheritance: - -Warnings --------- - -The following warnings can be emitted by the Globus SDK to indicate a -problem which is not necessarily an error. - -.. seealso:: - - :ref:`managing-warnings` - -.. autoclass:: globus_sdk.RemovedInV4Warning - :members: - :show-inheritance: diff --git a/docs/core/index.rst b/docs/core/index.rst index 6d6ffe1e8..f0ff8e50c 100644 --- a/docs/core/index.rst +++ b/docs/core/index.rst @@ -11,6 +11,7 @@ Underlying components of the Globus SDK. responses paging exceptions + warnings .. toctree:: :hidden: diff --git a/docs/testing/warnings.rst b/docs/core/warnings.rst similarity index 92% rename from docs/testing/warnings.rst rename to docs/core/warnings.rst index 2a7058909..89c33e2d7 100644 --- a/docs/testing/warnings.rst +++ b/docs/core/warnings.rst @@ -1,9 +1,13 @@ -.. _managing-warnings: +Warnings +======== -Managing warnings -================= +The following warnings can be emitted by the Globus SDK to indicate a +problem, or a future change, which is not necessarily an error. + +.. autoclass:: globus_sdk.RemovedInV4Warning + :members: + :show-inheritance: -The Globus SDK issues deprecation warnings to notify developers of upcoming changes. By default, Python will not display deprecation warnings to end users, but testing frameworks like pytest will enable deprecation warnings for developers. diff --git a/docs/testing/index.rst b/docs/testing/index.rst index d863842d3..9de0abb21 100644 --- a/docs/testing/index.rst +++ b/docs/testing/index.rst @@ -19,5 +19,4 @@ Globus SDK _testing getting_started reference - warnings methods/index