autodrive.gsheet

Module Contents

Classes

GSheet

Provides a connection to a single Google Sheet and access to its properties
class autodrive.gsheet.GSheet(gsheet_id, title=None, *, tabs=None, auth_config=None, sheets_conn=None, autoconnect=True)

Provides a connection to a single Google Sheet and access to its properties and Tabs.

Parameters

  • gsheet_id (str) – The id string of the target Google Sheet; can be found in the link to the Google Sheet.

  • title (str, optional) – The name of the Google Sheet, defaults to None.

  • tabs (List[Tab], optional) – A list of Tabs attached to the Google Sheet. You should probably manage Tabs with GSheet.fetch () or by getting the GSheet directly from a Drive, rather than using this parameter, defaults to None.

  • auth_config (AuthConfig, optional) – Optional custom AuthConfig object, defaults to None.

  • sheets_conn (SheetsConnection, optional) – Optional manually created SheetsConnection, defaults to None.

  • autoconnect (bool, optional) – If you want to instantiate a GSheet without immediately checking your authentication credentials and connecting to the Google Sheets api, set this to False, defaults to True.

property requests: List[Dict[str, Any]]

List of accumulated (uncommitted) requests on this GSheet.

Returns

List of update request dictionaries that have been created for this GSheet.

Return type

List[Dict[str, Any]]

property tabs: Dict[str, autodrive.tab.Tab]

Dictionary of fetched Tabs on this GSheet by title.

Returns

Tab titles as keys and corresponding Tabs as values.

Return type

Dict[str, Tab]

property title: Optional[str]

The name of the GSheet.

Returns

The name of the GSheet, or None if its name hasn’t been fetched.

Return type

Optional[str]

fetch()

Gets the latest metadata from the API for this GSheet. Populates title and tab properties.

Note

This method will cause a request to be posted to the relevant Google API immediately.

Returns

This GSheet

Return type

GSheet

add_tab(tab)

Adds a Tab to the GSheet.

Parameters

tab (Tab) – The Tab instance you want to add.

Returns

This Gsheet.

Return type

GSheet

Raises

ValueError – If the GSheet already has a Tab with that title.

gen_range(rng, tab=None)

Convenience method for generating a new Range object from a Tab in this GSheet.

Parameters

  • rng (FullRange) – The desired FullRange of the new Range object.

  • tab (str | int, optional) – The name of the Tab to generate from, or its index. Defaults to None, which will generate a range from the first Tab.

Returns

The newly generated Range object.

Return type

Range

write_values(data, to_tab=None, rng=None, mode='write')

Adds a request to write data. GSheet.commit () to commit the requests.

Parameters

  • data (Sequence[Sequence[Any] | Dict[str, Any]]) – The data to write. Each sequence or dictionary in the passed data is a row, with each value in that sub-iterable being a column. Dictionary keys will be used as a header row in the written data.

  • to_tab (str, optional) – The name of the tab to write to, defaults to None, which will write to whatever tab is first in the Sheet.

  • rng (FullRange | str, optional) – The range to which the data will be written, starting with the top-left-most cell in the range, defaults to None, which will write to the top-left-most cell in the passed tab, or the first tab.

  • mode (Literal, optional) – Whether to append the data after any populated rows already present in the tab or to write to the passed rng. Overrides rng if specified. Defaults to “write”.

Returns

This GSheet.

Return type

GSheet

Raises

KeyError – If the passed tab name (to_tab) isn’t present in the GSheet’s current tabs property.

get_data(tab=None, rng=None, value_type=EffectiveVal)

Gets the data from the cells of the GSheet. GSheet.fetch() will be called automatically if the GSheet’s tabs are not populated.

Note

This method will cause a request to be posted to the relevant Google API immediately.

Parameters

  • tab (str | int, optional) – The name of the tab, or its (0-based) index (from left to right), defaults to None, which will collect data from the first tab in the Sheet.

  • rng (FullRange | str, optional) – The specific range to fetch data from, defaults to None, for all data in the target tab.

  • value_type (GoogleValueType, optional) – Allows you to toggle the type of the values returned by the Google Sheets API. See the dtypes documentation for more info on the different GoogleValueTypes.

Returns

This GSheet.

Return type

GSheet

Raises

  • KeyError – If the passed tab name is not found in this GSheet’s tabs.

  • TypeError – If anything other than the displayed types is passed for the tab parameter.

keys()

Gets the keys (tab titles) for the fetched tabs on this GSheet.

Returns

The tab titles on this GSheet.

Return type

KeysView[str]

values()

Gets the values (Tabs) for the fetched tabs on this GSheet.

Returns

The Tabs on this GSheet.

Return type

ValuesView[Tab]

get_tab_index_by_title(tab_title)
Parameters

tab_title (str) –

Return type

Optional[int]

to_csv(root_path, filename_overrides=None, **tabs_and_headers)

Convenience method for calling .to_csv() on some or all of the GSheet’s tabs.

Parameters

  • root_path (str) – The root directory path to save tab files to.

  • filename_overrides (Dict[str, str], optional) – By default, this method will name each file after the corresponding tab’s title. To override some or all of the resulting filenames, pass a dictionary with keys equal to the names of the tab you want to override and the values equal to the name of the filename you want. Defaults to None, for all tabs being treated with default behavior.

  • tabs_and_headers (Sequence[Any] | None) – (Sequence[Any], optional): If you want to only output the data for some of the tabs, you can pass the names of the desired tabs as kwargs. If you wish, you can also pass a header row for those tabs, which will be inserted as the first row of the file. If you don’t want to pass a header row, simply pass tabname=None for that tab.

Raises

ValueError – If root_path does not lead to a directory.

Return type

None

to_json(root_path, filename_overrides=None, **tabs_and_headers)

Convenience method for calling .to_json() on some or all of the GSheet’s tabs.

Parameters

  • root_path (str) – The root directory path to save tab files to.

  • filename_overrides (Dict[str, str], optional) – By default, this method will name each file after the corresponding tab’s title. To override some or all of the resulting filenames, pass a dictionary with keys equal to the names of the tab you want to override and the values equal to the name of the filename you want. Defaults to None, for all tabs being treated with default behavior.

  • tabs_and_headers (Sequence[str] | int) – (Sequence[str] | int, optional): If you want to only output the data for some of the tabs, you can pass the names of the desired tabs as kwargs. You must also indicate what keys should be used when creating the jsons for those tabs. For each header value, you may either pass a row index to pull for the keys, or a list of keys.

Raises

ValueError – If root_path does not lead to a directory.

Return type

None