From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 18 Jan 2019 06:02:07 +0000 (-0500)
Subject: Feature mysqlclient
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=97f260e1ba60a210c3353368d0bad0e554f98792;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Feature mysqlclient

MySQL-Python hasn't been released in about five years and there
is no reason that it should be listed as a viable DBAPI;
all MySQL / MariaDB users should be using mysqlclient or PyMySQL today.

Change-Id: I2f12babe6e60bc7393398400a125d0592e86dbb8
(cherry picked from commit 894acf7b8eaa166a6ec231d0a139c699239b5008)
---

diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst
index e029531e75..a22b7f22b3 100644
--- a/doc/build/core/engines.rst
+++ b/doc/build/core/engines.rst
@@ -77,7 +77,7 @@ of a URL that includes the password ``"kx%jj5/g"``::
 
   postgresql+pg8000://dbuser:kx%25jj5%2Fg@pghost10/appdb
 
-The encoding for the password can be generated using ``urllib``::
+The encoding for the above password can be generated using ``urllib``::
 
   >>> import urllib.parse
   >>> urllib.parse.quote_plus("kx%jj5/g")
@@ -113,14 +113,11 @@ MySQL DBAPIs available, including MySQL-connector-python and OurSQL::
     # default
     engine = create_engine('mysql://scott:tiger@localhost/foo')
 
-    # mysql-python
+    # mysqlclient (a maintained fork of MySQL-Python)
     engine = create_engine('mysql+mysqldb://scott:tiger@localhost/foo')
 
-    # MySQL-connector-python
-    engine = create_engine('mysql+mysqlconnector://scott:tiger@localhost/foo')
-
-    # OurSQL
-    engine = create_engine('mysql+oursql://scott:tiger@localhost/foo')
+    # PyMySQL
+    engine = create_engine('mysql+pymysql://scott:tiger@localhost/foo')
 
 More notes on connecting to MySQL at :ref:`mysql_toplevel`.
 
@@ -165,11 +162,13 @@ For a relative file path, this requires three slashes::
 
 And for an absolute file path, the three slashes are followed by the absolute path::
 
-    #Unix/Mac - 4 initial slashes in total
+    # Unix/Mac - 4 initial slashes in total
     engine = create_engine('sqlite:////absolute/path/to/foo.db')
-    #Windows
+
+    # Windows
     engine = create_engine('sqlite:///C:\\path\\to\\foo.db')
-    #Windows alternative using raw string
+
+    # Windows alternative using raw string
     engine = create_engine(r'sqlite:///C:\path\to\foo.db')
 
 To use a SQLite ``:memory:`` database, specify an empty URL::
diff --git a/doc/build/dialects/mysql.rst b/doc/build/dialects/mysql.rst
index ebfc8a31cc..d64a9dd160 100644
--- a/doc/build/dialects/mysql.rst
+++ b/doc/build/dialects/mysql.rst
@@ -157,12 +157,12 @@ construction arguments, are as follows:
     :members: __init__
 
 
-MySQL-Python
-------------
+mysqlclient (fork of MySQL-Python)
+----------------------------------
 
 .. automodule:: sqlalchemy.dialects.mysql.mysqldb
 
-pymysql
+PyMySQL
 -------
 
 .. automodule:: sqlalchemy.dialects.mysql.pymysql
diff --git a/lib/sqlalchemy/dialects/mysql/mysqldb.py b/lib/sqlalchemy/dialects/mysql/mysqldb.py
index 73ef278ed7..82a686e703 100644
--- a/lib/sqlalchemy/dialects/mysql/mysqldb.py
+++ b/lib/sqlalchemy/dialects/mysql/mysqldb.py
@@ -8,10 +8,20 @@
 """
 
 .. dialect:: mysql+mysqldb
-    :name: MySQL-Python
+    :name: mysqlclient (maintained fork of MySQL-Python)
     :dbapi: mysqldb
     :connectstring: mysql+mysqldb://<user>:<password>@<host>[:<port>]/<dbname>
-    :url: http://sourceforge.net/projects/mysql-python
+    :url: https://pypi.org/project/mysqlclient/
+
+Driver Status
+-------------
+
+The mysqlclient DBAPI is a maintained fork of the
+`MySQL-Python <http://sourceforge.net/projects/mysql-python>`_ DBAPI
+that is no longer maintained.  `mysqlclient`_ supports Python 2 and Python 3
+and is very stable.
+
+.. _mysqlclient: https://github.com/PyMySQL/mysqlclient-python
 
 .. _mysqldb_unicode:
 
@@ -21,14 +31,6 @@ Unicode
 Please see :ref:`mysql_unicode` for current recommendations on unicode
 handling.
 
-Py3K Support
-------------
-
-Currently, MySQLdb only runs on Python 2 and development has been stopped.
-`mysqlclient`_ is fork of MySQLdb and provides Python 3 support as well
-as some bugfixes.
-
-.. _mysqlclient: https://github.com/PyMySQL/mysqlclient-python
 
 Using MySQLdb with Google Cloud SQL
 -----------------------------------