Fix order of warnings filters

The `warnings.filterwarnings` method inserts entries at the front of the filter list, and entries closer to the front of the list override entries later in the list, if both match a particular warning. (See https://docs.python.org/3/library/warnings.html)

The intended behavior is for all `RemovedIn20Warning` warnings to log and continue, except that specific warnings that match the defined regular expressions should be raised as exceptions. To accomplish this intent, the general filter must be inserted before the regular expression special cases.

The original order would work if `warnings.filterwarnings` for the default case were invoked with `append=True`, but the intent of the documentation is for this set of filters to be determinative (i.e. to override any conflicting pre-existing filters that may exist), so `append=True` should not be used.

diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst
index a5d90839b46f7a5dd0ec89bd5a9e777968604936..79e198d09c4b47a684b9f42dcfc40948f1fcb263 100644 (file)
--- a/doc/build/changelog/migration_20.rst
+++ b/doc/build/changelog/migration_20.rst
@@ -260,7 +260,12 @@ the SQLAlchemy project itself, the approach taken is as follows:
 
         import warnings
         from sqlalchemy import exc
-
+        
+        # for warnings not included in regex-based filter below, just log
+        warnings.filterwarnings(
+          "always", category=exc.RemovedIn20Warning
+        )
+        
         # for warnings related to execute() / scalar(), raise
         for msg in [
             r"The (?:Executable|Engine)\.(?:execute|scalar)\(\) function",
@@ -276,11 +281,6 @@ the SQLAlchemy project itself, the approach taken is as follows:
               "error", message=msg, category=exc.RemovedIn20Warning,
           )
 
-        # for all other warnings, just log
-        warnings.filterwarnings(
-          "always", category=exc.RemovedIn20Warning
-        )
-
 3. As each sub-category of warnings are resolved in the application, new
    warnings that are caught by the "always" filter can be added to the list
    of "errors" to be resolved.