Feature request: Allow us to offset a set number of rows/columns in GoogleSheets append_to_sheet

anzelpwj commented 2 months ago

Detailed Description

Hi everyone! I'm putting in this request to allow users to set a number of offset rows and columns for GoogleSheets.append_to_sheet. For example, if I wanted my data block to start at C3, I'd give 2 skip rows and 2 skip columns.

Context

I'm a volunteer with Tech for Campaigns, and I'd love to be able to use this tool to automate a process we have to download donation data from ActBlue and put it into a standardized spreadsheet that TFC uses for every campaigns. However, our sheets are organized in a fashion such that our data would need to start being added at position D6 (or a lower row, if I'm just updating donations after a given day).

Possible Implementation

I'd suggest a method call something like:

GoogleSheets.append_to_sheet(spreadsheet_id, table, worksheet=0, user_entered_value=False, skip_rows=0, skip_cols=0, **kwargs)

If skip_rows and skip_cols are both 0, the logic we have in lines 275-286 (https://github.com/move-coop/parsons/blob/3fc05e75d572a107f8c6b5af0609df0cc52564eb/parsons/google/google_sheets.py#L275) can proceed as normal. But if non-default values are provided, we simply drop the data in at skip_rows + 1, skip_cols + 1 in the spreadsheet.

Alternately, if it makes more sense to have something like start_row=1, start_col=1 that would be fine as well.

Priority

Medium - would simplify some grunt work for TFC, but it's not a hair-on-fire situation.

anzelpwj commented 2 months ago

Actually just looked at the Pandas to_excel API (https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_excel.html) and they use startrow=0, startcol=0, so probably best to match that functionality.

matthewkrausse commented 2 months ago

Just a suggestion for an immediate workaround. Drop the data into a new sheet and then use a reference to that sheet like this in C3: ={DataFromParsons!A:C}.

But we'll look into this.

anzelpwj commented 2 months ago

I'm happy to take on this PR and do the coding work, but would appreciate advice on how I should design the API to fit in best with the rest of the library.

Will probably want to add another parameter to the method call that lets you decide whether or not you want to include the header row.

shaunagm commented 2 months ago

Hi @anzelpwj! Thanks for the feature request and for the offer to make a PR.

This short guide has some general advice for how to write code for Parsons. Some advice that's more specific to your situation:

Try to use the underlying terminology wherever possible. If the Google Sheets client (or API endpoint) uses a specific variable name, use the same variable name, etc.
Your addition should not change the default behavior. You're already doing that by having the defaults for your proposed new parameters lead to the existing behavior.
Make sure to update the docstrings and tests to reflect the new parameter.

Let me know if you run into any issues or have more questions. Always happy to help, including a pair programming session if you'd like. :)

move-coop / parsons