Note DBAPIs and dialects that we don't support

Since we have strong CI for the DBAPIs and dialects that are actively
supported, this indicates that those DBAPIs that aren't in CI are
continuing to fall behind in support, to the point where we can
not address issues that may arise. As such, the Sybase and Firebird
dialects overall are moving into an explicit "not supported" zone
where we would like to eventually remove them.   Additionally,
a pass is made through legacy MySQL and PostgreSQL DBAPI dialects
as well as those which we aren't able to include in CI to note
that these DBAPIs aren't actively supported by the project.

Change-Id: I61f1515b97b741b7534b54e434e3e47065df7b5d
(cherry picked from commit 4bd4bae5c1132e1ca41425f742402d06026a918a)

diff --git a/doc/build/dialects/index.rst b/doc/build/dialects/index.rst
index b8a443ec3f62c7427a275655cf5a80755e72deac..0d5a904aa813ab823fec82eca4f9129eef862520 100644 (file)
--- a/doc/build/dialects/index.rst
+++ b/doc/build/dialects/index.rst
@@ -21,6 +21,18 @@ Included Dialects
     sqlite
     oracle
     mssql
+
+Included, but not currently supported dialects
+----------------------------------------------
+
+The following dialects have implementations wtihin SQLAlchemy however are not
+part of continuous integration testing nor are they actively developed.
+These dialects may be removed in future major releases.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
     firebird
     sybase
 

diff --git a/lib/sqlalchemy/dialects/firebird/base.py b/lib/sqlalchemy/dialects/firebird/base.py
index 7ae198f6c91acbf4bdaf8e0ba1ce265ad3e10c91..2e3ecba5d9465e67f42659a2c4683919f9b0cf30 100644 (file)
--- a/lib/sqlalchemy/dialects/firebird/base.py
+++ b/lib/sqlalchemy/dialects/firebird/base.py
@@ -10,6 +10,12 @@ r"""
 .. dialect:: firebird
     :name: Firebird
 
+.. note::
+
+    The Firebird dialect within SQLAlchemy **is not currently supported**. The
+    dialect is not tested within continuous integration and is likely to have
+    many issues and caveats not currently handled.
+
 Firebird Dialects
 -----------------
 

diff --git a/lib/sqlalchemy/dialects/mssql/adodbapi.py b/lib/sqlalchemy/dialects/mssql/adodbapi.py
index 0b8cc01dcb22475a3c4398ba668e165d411a51e2..38b4a764f84414fc05d07003d12ed352bb3eb8c2 100644 (file)
--- a/lib/sqlalchemy/dialects/mssql/adodbapi.py
+++ b/lib/sqlalchemy/dialects/mssql/adodbapi.py
@@ -14,7 +14,7 @@
 
 .. note::
 
-    The adodbapi dialect is not implemented SQLAlchemy versions 0.6 and
+    The adodbapi dialect is not implemented in SQLAlchemy versions 0.6 and
     above at this time.
 
 """

diff --git a/lib/sqlalchemy/dialects/mysql/cymysql.py b/lib/sqlalchemy/dialects/mysql/cymysql.py
index 47bdbbc99448d037599e951e705221921babaa23..ed9582477edf2837a9b0f87162ef520e9ee5f1d2 100644 (file)
--- a/lib/sqlalchemy/dialects/mysql/cymysql.py
+++ b/lib/sqlalchemy/dialects/mysql/cymysql.py
@@ -12,6 +12,12 @@ r"""
     :connectstring: mysql+cymysql://<username>:<password>@<host>/<dbname>[?<options>]
     :url: https://github.com/nakagami/CyMySQL
 
+.. note::
+
+    The CyMySQL dialect is **not tested as part of SQLAlchemy's continuous
+    integration** and may have unresolved issues.  The recommended MySQL
+    dialects are mysqlclient and PyMySQL.
+
 """  # noqa
 
 from .base import BIT

diff --git a/lib/sqlalchemy/dialects/mysql/mysqlconnector.py b/lib/sqlalchemy/dialects/mysql/mysqlconnector.py
index e4027351defd6b42c2ed7f48299b4cfca4a67966..90c7db2cd6e2b7514dc2955d291e1bcd4970acaf 100644 (file)
--- a/lib/sqlalchemy/dialects/mysql/mysqlconnector.py
+++ b/lib/sqlalchemy/dialects/mysql/mysqlconnector.py
@@ -12,6 +12,12 @@ r"""
     :connectstring: mysql+mysqlconnector://<user>:<password>@<host>[:<port>]/<dbname>
     :url: https://pypi.org/project/mysql-connector-python/
 
+.. note::
+
+    The MySQL Connector/Python DBAPI has had many issues since its release,
+    some of which may remain unresolved, and the mysqlconnector dialect is
+    **not tested as part of SQLAlchemy's continuous integration**.
+    The recommended MySQL dialects are mysqlclient and PyMySQL.
 
 """  # noqa
 

diff --git a/lib/sqlalchemy/dialects/mysql/oursql.py b/lib/sqlalchemy/dialects/mysql/oursql.py
index 80313a2fc9847a7c8137760ae3e4865ecbe45c7c..483c24221b4649db54a1dbd5ba5d3659db11aa25 100644 (file)
--- a/lib/sqlalchemy/dialects/mysql/oursql.py
+++ b/lib/sqlalchemy/dialects/mysql/oursql.py
@@ -13,6 +13,12 @@
     :connectstring: mysql+oursql://<user>:<password>@<host>[:<port>]/<dbname>
     :url: http://packages.python.org/oursql/
 
+.. note::
+
+    The OurSQL MySQL dialect is legacy and is no longer supported upstream,
+    and is **not tested as part of SQLAlchemy's continuous integration**.
+    The recommended MySQL dialects are mysqlclient and PyMySQL.
+
 Unicode
 -------
 

diff --git a/lib/sqlalchemy/dialects/postgresql/pg8000.py b/lib/sqlalchemy/dialects/postgresql/pg8000.py
index e4fc0a970c7f22461b7c27447925ef5883cce05d..05327f81e484cdf852fea42ca015dc822b88b9f5 100644 (file)
--- a/lib/sqlalchemy/dialects/postgresql/pg8000.py
+++ b/lib/sqlalchemy/dialects/postgresql/pg8000.py
@@ -11,6 +11,11 @@ r"""
     :connectstring: postgresql+pg8000://user:password@host:port/dbname[?key=value&key=value...]
     :url: https://pythonhosted.org/pg8000/
 
+.. note::
+
+    The pg8000 dialect is **not tested as part of SQLAlchemy's continuous
+    integration** and may have unresolved issues.  The recommended PostgreSQL
+    dialect is psycopg2.
 
 .. _pg8000_unicode:
 

diff --git a/lib/sqlalchemy/dialects/postgresql/pygresql.py b/lib/sqlalchemy/dialects/postgresql/pygresql.py
index 6df77a2978670162d79a90e77adf01bb12cc8d8f..efeea26f114ba17e82c48677cbc0037524cd5197 100644 (file)
--- a/lib/sqlalchemy/dialects/postgresql/pygresql.py
+++ b/lib/sqlalchemy/dialects/postgresql/pygresql.py
@@ -10,6 +10,13 @@
     :dbapi: pgdb
     :connectstring: postgresql+pygresql://user:password@host:port/dbname[?key=value&key=value...]
     :url: http://www.pygresql.org/
+
+.. note::
+
+    The pygresql dialect is **not tested as part of SQLAlchemy's continuous
+    integration** and may have unresolved issues.  The recommended PostgreSQL
+    dialect is psycopg2.
+
 """  # noqa
 
 import decimal

diff --git a/lib/sqlalchemy/dialects/postgresql/pypostgresql.py b/lib/sqlalchemy/dialects/postgresql/pypostgresql.py
index fdb66f29cb47da5814bd471c7c83c5d4ece00348..17a80cf025087ade4818410f6a9b125169b09f85 100644 (file)
--- a/lib/sqlalchemy/dialects/postgresql/pypostgresql.py
+++ b/lib/sqlalchemy/dialects/postgresql/pypostgresql.py
@@ -11,6 +11,12 @@
     :connectstring: postgresql+pypostgresql://user:password@host:port/dbname[?key=value&key=value...]
     :url: http://python.projects.pgfoundry.org/
 
+.. note::
+
+    The pypostgresql dialect is **not tested as part of SQLAlchemy's continuous
+    integration** and may have unresolved issues.  The recommended PostgreSQL
+    driver is psycopg2.
+
 
 """  # noqa
 

diff --git a/lib/sqlalchemy/dialects/sybase/base.py b/lib/sqlalchemy/dialects/sybase/base.py
index 31efed0ab2ebe81b349c4fcd50c773dfc38dc037..71ff629768484d0d12a4522cf4174f39397c9dc1 100644 (file)
--- a/lib/sqlalchemy/dialects/sybase/base.py
+++ b/lib/sqlalchemy/dialects/sybase/base.py
@@ -16,9 +16,9 @@
 
 .. note::
 
-    The Sybase dialect functions on current SQLAlchemy versions
-    but is not regularly tested, and may have many issues and
-    caveats not currently handled.
+    The Sybase dialect within SQLAlchemy **is not currently supported**.   The
+    dialect is not tested within continuous integration and is likely to have
+    many issues and caveats not currently handled.
 
 """