utils: deprecate InsertFromSelect properly

This is provided out-of-box by SQLAlchemy versions >= 1.0.0. We've
had this class deprecated in docs for some time now, now do it
properly by the means of debtcollector and a release note.

Closes-Bug: #1439092

Change-Id: I562c35c265014c6b19a81961f236a7a0ca438765

oslo_db/sqlalchemy/utils.py

@@ -22,6 +22,7 @@ import itertools
 import logging
 import re
 
+import debtcollector
 from oslo_utils import timeutils
 import six
 import sqlalchemy
@@ -415,13 +416,14 @@ def get_table(engine, name):
     return Table(name, metadata, autoload=True)
 
 
+@debtcollector.removals.removed_class(
+    'InsertFromSelect',
+    replacement='sqlalchemy.sql.expression.Insert.from_select',
+    message='this functionality is provided out-of-box by SQLAlchemy >= 1.0.0'
+)
 class InsertFromSelect(object):
     """Form the base for `INSERT INTO table (SELECT ... )` statement.
 
-    DEPRECATED: this class is deprecated and will be removed from oslo_db
-    in a few releases. Use default SQLAlchemy insert from select implementation
-    instead
-
     :param table: table to insert records
     :param select: select query
     :param cols: list of columns to specify in insert clause

releasenotes/notes/deprecate-insert-from-select-ea831381ebd7e7cf.yaml

@@ -0,0 +1,6 @@
+---
+deprecations:
+  - class ``InsertFromSelect`` from module ``oslo_db.sqlalchemy.utils`` is
+    deprecated in favor of ``sqlalchemy.sql.expression.Insert.from_select()``
+    method of Insert expression, that is available in SQLAlchemy versions
+    1.0.0 and newer