From 18e649670728b09569136c4b52e2d02d6d192939 Mon Sep 17 00:00:00 2001 From: Brett Date: Tue, 10 Jan 2023 13:53:22 -0500 Subject: [PATCH] add AsdfProvisionalAPIWarning This warning should be used for any experimental api changes that should be considered provisional and might experience breaking changes (even in minor releases). --- CHANGES.rst | 3 +++ asdf/exceptions.py | 9 +++++++++ docs/asdf/developer_overview.rst | 6 ++++++ 3 files changed, 18 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index ac36e9c15..af3d73d6f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -5,6 +5,9 @@ The ASDF Standard is at v1.6.0 - Discard cache of lazy-loaded block data when it is no longer referenced by the tree. [#1280] +- Add AsdfProvisionalAPIWarning to warn developers of new features that + may undergo breaking changes but are likely to be included as stable + features (without this warning) in a future version of ASDF [#1295] 2.14.3 (2022-12-15) ------------------- diff --git a/asdf/exceptions.py b/asdf/exceptions.py index 66788b6f4..7afbd8a01 100644 --- a/asdf/exceptions.py +++ b/asdf/exceptions.py @@ -21,3 +21,12 @@ class DelimiterNotFoundError(ValueError): Indicates that a delimiter was not found when reading or seeking through a file. """ + + +class AsdfProvisionalAPIWarning(AsdfWarning, FutureWarning): + """ + Used for provisional features where breaking API changes might be + introduced at any point (including minor releases). These features + are likely to be added in a future ASDF version. However, Use of + provisional features is highly discouraged for production code. + """ diff --git a/docs/asdf/developer_overview.rst b/docs/asdf/developer_overview.rst index 736629e5e..876d0bf71 100644 --- a/docs/asdf/developer_overview.rst +++ b/docs/asdf/developer_overview.rst @@ -72,6 +72,12 @@ Support for ASDF core tags has not yet been moved to the new system. Doing so would be a breaking change for users who subclass that code, so we'll need to wait until asdf 3.0 to do that. +Some features working toward this goal are available for testing but will raise +a ``AsdfProvisionalAPIWarning`` when used. This warning indicates that a feature +may experience breaking API changes (even for minor ASDF releases) and should +not be trusted in a production environment. It is likely that features that +raise this warning will become stable and be added to a future ASDF version. + Some terminology and definitions --------------------------------