From ad97d2740201f6b7687dfccebd85cc348e8bfbe3 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 16 May 2014 11:25:39 +0200 Subject: [PATCH] SQL: update some signatures and docstrings: - remove meta kwarg from read_sql_table (see discussion in #6300) - remove flavor kwarg from read_sql (not necessary + not there in 0.13, so would have been API change) - update docstring of to_sql in generic with latest changes - enhance docstring of get_schema --- pandas/core/generic.py | 5 ++-- pandas/io/sql.py | 49 +++++++++++++++++++------------------ pandas/io/tests/test_sql.py | 2 +- 3 files changed, 29 insertions(+), 27 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 04ab4fb14d512..0e5ca6afdb56b 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -928,10 +928,11 @@ def to_sql(self, name, con, flavor='sqlite', if_exists='fail', index=True, con : SQLAlchemy engine or DBAPI2 connection (legacy mode) Using SQLAlchemy makes it possible to use any DB supported by that library. - If a DBAPI2 object is given, a supported SQL flavor must also be provided + If a DBAPI2 object, only sqlite3 is supported. flavor : {'sqlite', 'mysql'}, default 'sqlite' The flavor of SQL to use. Ignored when using SQLAlchemy engine. - Required when using DBAPI2 connection. + 'mysql' is deprecated and will be removed in future versions, but it + will be further supported through SQLAlchemy engines. if_exists : {'fail', 'replace', 'append'}, default 'fail' - fail: If table exists, do nothing. - replace: If table exists, drop it, recreate it, and insert data. diff --git a/pandas/io/sql.py b/pandas/io/sql.py index 347370eaee92f..aa08c95c4f1c3 100644 --- a/pandas/io/sql.py +++ b/pandas/io/sql.py @@ -221,8 +221,8 @@ def uquery(sql, con=None, cur=None, retry=True, params=None): #------------------------------------------------------------------------------ #--- Read and write to DataFrames -def read_sql_table(table_name, con, meta=None, index_col=None, - coerce_float=True, parse_dates=None, columns=None): +def read_sql_table(table_name, con, index_col=None, coerce_float=True, + parse_dates=None, columns=None): """Read SQL database table into a DataFrame. Given a table name and an SQLAlchemy engine, returns a DataFrame. @@ -234,8 +234,6 @@ def read_sql_table(table_name, con, meta=None, index_col=None, Name of SQL table in database con : SQLAlchemy engine Sqlite DBAPI conncection mode not supported - meta : SQLAlchemy meta, optional - If omitted MetaData is reflected from engine index_col : string, optional Column to set as index coerce_float : boolean, default True @@ -264,7 +262,7 @@ def read_sql_table(table_name, con, meta=None, index_col=None, """ - pandas_sql = PandasSQLAlchemy(con, meta=meta) + pandas_sql = PandasSQLAlchemy(con) table = pandas_sql.read_table( table_name, index_col=index_col, coerce_float=coerce_float, parse_dates=parse_dates, columns=columns) @@ -292,11 +290,10 @@ def read_sql_query(sql, con, index_col=None, coerce_float=True, params=None, library. If a DBAPI2 object, only sqlite3 is supported. index_col : string, optional - column name to use for the returned DataFrame object. + Column name to use as index for the returned DataFrame object. coerce_float : boolean, default True Attempt to convert values to non-string, non-numeric objects (like decimal.Decimal) to floating point, useful for SQL result sets - cur : depreciated, cursor is obtained from connection params : list, tuple or dict, optional List of parameters to pass to execute method. parse_dates : list or dict @@ -325,8 +322,8 @@ def read_sql_query(sql, con, index_col=None, coerce_float=True, params=None, parse_dates=parse_dates) -def read_sql(sql, con, index_col=None, flavor='sqlite', coerce_float=True, - params=None, parse_dates=None, columns=None): +def read_sql(sql, con, index_col=None, coerce_float=True, params=None, + parse_dates=None, columns=None): """ Read SQL query or database table into a DataFrame. @@ -339,15 +336,10 @@ def read_sql(sql, con, index_col=None, flavor='sqlite', coerce_float=True, library. If a DBAPI2 object, only sqlite3 is supported. index_col : string, optional - column name to use for the returned DataFrame object. - flavor : string, {'sqlite', 'mysql'} - The flavor of SQL to use. Ignored when using - SQLAlchemy engine. Required when using DBAPI2 connection. - 'mysql' is still supported, but will be removed in future versions. + column name to use as index for the returned DataFrame object. coerce_float : boolean, default True Attempt to convert values to non-string, non-numeric objects (like decimal.Decimal) to floating point, useful for SQL result sets - cur : depreciated, cursor is obtained from connection params : list, tuple or dict, optional List of parameters to pass to execute method. parse_dates : list or dict @@ -360,7 +352,8 @@ def read_sql(sql, con, index_col=None, flavor='sqlite', coerce_float=True, Especially useful with databases without native Datetime support, such as SQLite columns : list - List of column names to select from sql table + List of column names to select from sql table (only used when reading + a table). Returns ------- @@ -379,7 +372,7 @@ def read_sql(sql, con, index_col=None, flavor='sqlite', coerce_float=True, read_sql_query : Read SQL query into a DataFrame """ - pandas_sql = pandasSQL_builder(con, flavor=flavor) + pandas_sql = pandasSQL_builder(con) if 'select' in sql.lower(): try: @@ -419,8 +412,8 @@ def to_sql(frame, name, con, flavor='sqlite', if_exists='fail', index=True, If a DBAPI2 object, only sqlite3 is supported. flavor : {'sqlite', 'mysql'}, default 'sqlite' The flavor of SQL to use. Ignored when using SQLAlchemy engine. - Required when using DBAPI2 connection. - 'mysql' is still supported, but will be removed in future versions. + 'mysql' is deprecated and will be removed in future versions, but it + will be further supported through SQLAlchemy engines. if_exists : {'fail', 'replace', 'append'}, default 'fail' - fail: If table exists, do nothing. - replace: If table exists, drop it, recreate it, and insert data. @@ -461,8 +454,8 @@ def has_table(table_name, con, flavor='sqlite'): If a DBAPI2 object, only sqlite3 is supported. flavor: {'sqlite', 'mysql'}, default 'sqlite' The flavor of SQL to use. Ignored when using SQLAlchemy engine. - Required when using DBAPI2 connection. - 'mysql' is still supported, but will be removed in future versions. + 'mysql' is deprecated and will be removed in future versions, but it + will be further supported through SQLAlchemy engines. Returns ------- @@ -1090,15 +1083,23 @@ def _create_sql_schema(self, frame, table_name): def get_schema(frame, name, flavor='sqlite', keys=None, con=None): """ - Get the SQL db table schema for the given frame + Get the SQL db table schema for the given frame. Parameters ---------- frame : DataFrame - name : name of SQL table + name : string + name of SQL table flavor : {'sqlite', 'mysql'}, default 'sqlite' - keys : columns to use a primary key + The flavor of SQL to use. Ignored when using SQLAlchemy engine. + 'mysql' is deprecated and will be removed in future versions, but it + will be further supported through SQLAlchemy engines. + keys : string or sequence + columns to use a primary key con: an open SQL database connection object or an SQLAlchemy engine + Using SQLAlchemy makes it possible to use any DB supported by that + library. + If a DBAPI2 object, only sqlite3 is supported. """ diff --git a/pandas/io/tests/test_sql.py b/pandas/io/tests/test_sql.py index 6058c0923e3c1..a47feceb7f233 100644 --- a/pandas/io/tests/test_sql.py +++ b/pandas/io/tests/test_sql.py @@ -340,7 +340,7 @@ def test_read_sql_iris(self): def test_legacy_read_frame(self): with tm.assert_produces_warning(FutureWarning): iris_frame = sql.read_frame( - "SELECT * FROM iris", self.conn, flavor='sqlite') + "SELECT * FROM iris", self.conn) self._check_iris_loaded_frame(iris_frame) def test_to_sql(self):