From 3dd17076c566c7ef1606228b571e654e33bd0f62 Mon Sep 17 00:00:00 2001 From: Evan Mattiza Date: Sat, 17 Aug 2019 12:16:08 -0500 Subject: [PATCH 1/2] Added Engine Disposal Documentation Created hyperlink to SQLAlchemy docs for Engine Disposal responsibilities of user. Unified wording of legacy support for sqlite --- doc/source/whatsnew/v0.25.1.rst | 1 + pandas/io/sql.py | 44 +++++++++++++++++++++++---------- 2 files changed, 32 insertions(+), 13 deletions(-) diff --git a/doc/source/whatsnew/v0.25.1.rst b/doc/source/whatsnew/v0.25.1.rst index 34b149a6b8261..97cc16b43057d 100644 --- a/doc/source/whatsnew/v0.25.1.rst +++ b/doc/source/whatsnew/v0.25.1.rst @@ -105,6 +105,7 @@ I/O - Avoid calling ``S3File.s3`` when reading parquet, as this was removed in s3fs version 0.3.0 (:issue:`27756`) - Better error message when a negative header is passed in :func:`pandas.read_csv` (:issue:`27779`) +- Added notes on Engine Disposal and user responsibility to multiple sql related function docstrings (:issue:`23086`) - Plotting diff --git a/pandas/io/sql.py b/pandas/io/sql.py index f1f52a9198d29..f4c0eb6b9f2b6 100644 --- a/pandas/io/sql.py +++ b/pandas/io/sql.py @@ -140,10 +140,14 @@ def execute(sql, con, cur=None, params=None): ---------- sql : string SQL query to be executed. - con : SQLAlchemy connectable(engine/connection) or sqlite3 connection - Using SQLAlchemy makes it possible to use any DB supported by the - library. - If a DBAPI2 object, only sqlite3 is supported. + con : SQLAlchemy connectable (engine/connection) or database string URI + or DBAPI2 connection (fallback mode) + Using SQLAlchemy makes it possible to use any DB supported by that + library. Legacy support is provided for sqlite3.Connection objects. + Note: The user is responsible for engine disposal and connection + closure for the SQLAlchemy connectable. See `EngineDisposal + `_. + cur : deprecated, cursor is obtained from connection, default: None params : list or tuple, optional, default: None List of parameters to pass to execute method. @@ -187,6 +191,9 @@ def read_sql_table( con : SQLAlchemy connectable or str A database URI could be provided as as str. SQLite DBAPI connection mode not supported. + Note: The user is responsible for engine disposal and connection + closure for the SQLAlchemy connectable. See `EngineDisposal + `_. schema : str, default None Name of SQL schema in database to query (if database flavor supports this). Uses default schema if None (default). @@ -279,11 +286,15 @@ def read_sql_query( ---------- sql : string SQL query or SQLAlchemy Selectable (select or text object) SQL query to be executed. - con : SQLAlchemy connectable(engine/connection), database string URI, + con : SQLAlchemy connectable(engine/connection) or database string URI or sqlite3 DBAPI2 connection - Using SQLAlchemy makes it possible to use any DB supported by that - library. - If a DBAPI2 object, only sqlite3 is supported. + Using SQLAlchemy makes it possible to use any DB supported by + that library. Legacy support is provided for sqlite3.Connection + objects. + Note: The user is responsible for engine disposal and connection + closure for the SQLAlchemy connectable. See `EngineDisposal + `_. + index_col : string or list of strings, optional, default: None Column(s) to set as index(MultiIndex). coerce_float : boolean, default True @@ -359,9 +370,12 @@ def read_sql( SQL query to be executed or a table name. con : SQLAlchemy connectable (engine/connection) or database string URI or DBAPI2 connection (fallback mode) - Using SQLAlchemy makes it possible to use any DB supported by that - library. If a DBAPI2 object, only sqlite3 is supported. + library. Legacy support is provided for sqlite3.Connection objects. + Note: The user is responsible for engine disposal and connection + closure for the SQLAlchemy connectable. See `EngineDisposal + `_. + index_col : string or list of strings, optional, default: None Column(s) to set as index(MultiIndex). coerce_float : boolean, default True @@ -459,9 +473,13 @@ def to_sql( Name of SQL table. con : SQLAlchemy connectable(engine/connection) or database string URI or sqlite3 DBAPI2 connection - Using SQLAlchemy makes it possible to use any DB supported by that - library. - If a DBAPI2 object, only sqlite3 is supported. + Using SQLAlchemy makes it possible to use any DB supported by + that library. Legacy support is provided for sqlite3.Connection + objects. + Note: The user is responsible for engine disposal and connection + closure for the SQLAlchemy connectable. See `EngineDisposal + `_. + schema : string, default None Name of SQL schema in database to write to (if database flavor supports this). If None, use default schema (default). From 11f3463bd04dce979da0ec084034d5e0c9663e47 Mon Sep 17 00:00:00 2001 From: vn50dpg Date: Sun, 18 Aug 2019 10:48:12 -0500 Subject: [PATCH 2/2] Added a new line before Note in the parameters. --- pandas/io/sql.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/pandas/io/sql.py b/pandas/io/sql.py index f4c0eb6b9f2b6..b719e355ebf60 100644 --- a/pandas/io/sql.py +++ b/pandas/io/sql.py @@ -144,10 +144,10 @@ def execute(sql, con, cur=None, params=None): or DBAPI2 connection (fallback mode) Using SQLAlchemy makes it possible to use any DB supported by that library. Legacy support is provided for sqlite3.Connection objects. + Note: The user is responsible for engine disposal and connection closure for the SQLAlchemy connectable. See `EngineDisposal `_. - cur : deprecated, cursor is obtained from connection, default: None params : list or tuple, optional, default: None List of parameters to pass to execute method. @@ -191,6 +191,7 @@ def read_sql_table( con : SQLAlchemy connectable or str A database URI could be provided as as str. SQLite DBAPI connection mode not supported. + Note: The user is responsible for engine disposal and connection closure for the SQLAlchemy connectable. See `EngineDisposal `_. @@ -291,10 +292,10 @@ def read_sql_query( Using SQLAlchemy makes it possible to use any DB supported by that library. Legacy support is provided for sqlite3.Connection objects. + Note: The user is responsible for engine disposal and connection closure for the SQLAlchemy connectable. See `EngineDisposal `_. - index_col : string or list of strings, optional, default: None Column(s) to set as index(MultiIndex). coerce_float : boolean, default True @@ -372,10 +373,10 @@ def read_sql( or DBAPI2 connection (fallback mode) Using SQLAlchemy makes it possible to use any DB supported by that library. Legacy support is provided for sqlite3.Connection objects. + Note: The user is responsible for engine disposal and connection closure for the SQLAlchemy connectable. See `EngineDisposal `_. - index_col : string or list of strings, optional, default: None Column(s) to set as index(MultiIndex). coerce_float : boolean, default True @@ -476,10 +477,10 @@ def to_sql( Using SQLAlchemy makes it possible to use any DB supported by that library. Legacy support is provided for sqlite3.Connection objects. + Note: The user is responsible for engine disposal and connection closure for the SQLAlchemy connectable. See `EngineDisposal `_. - schema : string, default None Name of SQL schema in database to write to (if database flavor supports this). If None, use default schema (default).