gspread-dataframe

gspread-dataframe

.. image:: https://badge.fury.io/py/gspread-dataframe.svg :target: https://badge.fury.io/py/gspread-dataframe

.. image:: https://app.travis-ci.com/robin900/gspread-dataframe.svg?branch=master :target: https://travis-ci.com/robin900/gspread-dataframe

.. image:: https://img.shields.io/pypi/dm/gspread-dataframe.svg :target: https://pypi.org/project/gspread-dataframe

.. image:: https://readthedocs.org/projects/gspread-dataframe/badge/?version=latest :target: https://gspread-dataframe.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

This package allows easy data flow between a worksheet in a Google spreadsheet and a Pandas DataFrame. Any worksheet you can obtain using the gspread package can be retrieved as a DataFrame with get_as_dataframe; DataFrame objects can be written to a worksheet using set_with_dataframe:

.. code:: python

import pandas as pd
from gspread_dataframe import get_as_dataframe, set_with_dataframe

worksheet = some_worksheet_obtained_from_gspread_client

df = pd.DataFrame.from_records([{'a': i, 'b': i * 2} for i in range(100)])
set_with_dataframe(worksheet, df)

df2 = get_as_dataframe(worksheet)

The get_as_dataframe function supports the keyword arguments that are supported by your Pandas version's text parsing readers, such as pandas.read_csv. Consult your Pandas documentation for a full list of options <https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html>__. Since the 'python' engine in Pandas is used for parsing, only options supported by that engine are acceptable:

.. code:: python

import pandas as pd
from gspread_dataframe import get_as_dataframe

worksheet = some_worksheet_obtained_from_gspread_client

df = get_as_dataframe(worksheet, parse_dates=True, usecols=[0,2], skiprows=1, header=None)

New in version 4.0.0: drop_empty_rows and drop_empty_columns parameters, both True by default, are now accepted by get_as_dataframe. If you created a Google sheet with the default number of columns and rows (20 columns, 1000 rows), but have meaningful values for the DataFrame only in the top left corner of the worksheet, these parameters will cause any empty rows or columns to be discarded automatically.

Formatting Google worksheets for DataFrames

If you install the ``gspread-formatting`` package, you can additionally format a Google worksheet to suit the  
DataFrame data you've just written. See the `package documentation for details <https://github.com/robin900/gspread-formatting#formatting-a-worksheet-using-a-pandas-dataframe>`__, but here's a short example using the default formatter:

.. code:: python

    import pandas as pd
    from gspread_dataframe import get_as_dataframe, set_with_dataframe
    from gspread_formatting.dataframe import format_with_dataframe

    worksheet = some_worksheet_obtained_from_gspread_client

    df = pd.DataFrame.from_records([{'a': i, 'b': i * 2} for i in range(100)])
    set_with_dataframe(worksheet, df)
    format_with_dataframe(worksheet, df, include_column_header=True)

    
Installation
------------

Requirements
~~~~~~~~~~~~

* Python 2.7, 3+
* gspread (>=3.0.0; to use older versions of gspread, use gspread-dataframe releases of 2.1.1 or earlier)
* Pandas >= 0.24.0

From PyPI
~~~~~~~~~

.. code:: sh

    pip install gspread-dataframe

From GitHub
~~~~~~~~~~~

.. code:: sh

    git clone https://github.com/robin900/gspread-dataframe.git
    cd gspread-dataframe
    python setup.py install