autodrive.tab

Module Contents

Classes

Tab

Provides a connection to a single Google Sheet Tab, its properties, and its
class autodrive.tab.Tab(gsheet_id, tab_title, tab_idx, tab_id, column_count=26, row_count=1000, *, auth_config=None, sheets_conn=None, autoconnect=True)

Provides a connection to a single Google Sheet Tab, its properties, and its data.

Parameters

  • gsheet_id (str) – The id string of the target Google Sheet that the Tab resides in; can be found in the Google Sheet url.

  • tab_title (str) – The name of the Tab.

  • tab_idx (int) – The index (0-based) of the Tab in the Google Sheet.

  • tab_id (int) – The id of the Tab, can be found in the Google Sheet url (after gid=).

  • column_count (int, optional) – The starting number of columns in the Tab, defaults to 26.

  • row_count (int, optional) – The starting number of rows in the Tab, defaults to 1000.

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

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

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

property tab_id: int

Returns: int: This Tab’s id. Matches the gid of the parent GSheet’s url.

Return type

int

property format_grid: autodrive.formatting.format_tab.TabGridFormatting

Returns: TabGridFormatting: An object with grid formatting methods.

Return type

autodrive.formatting.format_tab.TabGridFormatting

property format_text: autodrive.formatting.format_tab.TabTextFormatting

Returns: TabTextFormatting: An object with text formatting methods.

Return type

autodrive.formatting.format_tab.TabTextFormatting

property format_cell: autodrive.formatting.format_tab.TabCellFormatting

Returns: TabCellFormatting: An object with cell formatting methods.

Return type

autodrive.formatting.format_tab.TabCellFormatting

property title: str

Returns: str: The name of this Tab.

Return type

str

property index: int

Returns: int: The (0-based) index location of this Tab among the other Tabs on the parent GSheet.

Return type

int

property column_count: int

Returns: int: The number of columns in this Tab.

Return type

int

property row_count: int

Returns: int: The number of rows in this Tab.

Return type

int

property range_str: str

The string representation of the range specified by this Component.

Type

str

Return type

str

property range: autodrive.interfaces.FullRange

Returns: FullRange: The FullRange representation of the range specified by this Component.

Return type

autodrive.interfaces.FullRange

property values: List[List[Any]]

Returns: List[List[Any]]: The fetched data values in this Component’s cells.

Return type

List[List[Any]]

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

Returns: List[List[Dict[str, Any]]]: The fetched formatting properties of this Component’s cells.

Return type

List[List[Dict[str, Any]]]

property data_shape: Tuple[int, int]

Returns: Tuple[int, int]: The row length and column width of this Component’s data.

Return type

Tuple[int, int]

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

Returns: List[Dict[str, Any]]: The list of current (uncommitted) requests.

Return type

List[Dict[str, Any]]

property conn: autodrive.connection.SheetsConnection
Returns

The view’s SheetsConnection.

Return type

SheetsConnection

Raises

NoConnectionError – If the view’s connection is null.

property auth: autodrive.interfaces.AuthConfig
Returns

The view’s AuthConfig.

Return type

AuthConfig

Raises

NoConnectionError – If the view’s auth config is null.

property gsheet_id: str

Returns: str: The id of the Google Sheet this view is connected to.

Return type

str

fetch()

Gets the latest metadata from the API for this Tab. Re-populates tab properties like row and column count.

Note

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

Returns

This GSheet

Return type

Tab

classmethod from_properties(gsheet_id, properties, auth_config=None, sheets_conn=None, autoconnect=True)

Generates a Tab assigned to the passed gsheet_id with the passed tab properties dictionary from a SheetsConnection.get_properties call.

Unless you have a special use-case, it is probably more trouble than it’s worth to try to instantiate a Tab with this method, as it is designed for use by other Autodrive objects.

Parameters

  • gsheet_id (str) – The id of the parent GSheet.

  • properties (Dict[str, Any]) – A properties dictionary, which must contain index, SheetId, title, and gridProperties keys. The gridProperties must be a dictionary containing columnCount and rowCount keys.

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

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

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

Returns

A Tab with the values from the passed properties dictionary.

Return type

Tab

full_range()

Generates a FullRange object corresponding to the full range of the Tab.

Returns

A FullRange from A1:the end of the Tab.

Return type

FullRange

get_data(rng=None, value_type=EffectiveVal)

Gets the data from the cells of this Tab.

Note

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

Parameters

  • rng (FullRange | HalfRange, optional) – An optional range value, to specify a subset of the Tab’s values to get, defaults to None, which fetches all values in the 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 Tab.

Return type

Tab

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

Adds a request to write data. Tab.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.

  • rng (FullRange, optional) – A specific range to write to, starting with the top-left-most cell in the range, defaults to None, which will write to the top-left-most cell of the 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 Tab.

Return type

Tab

classmethod new_tab_request(tab_title, tab_id=None, tab_idx=None, num_rows=1000, num_cols=26)

Creates a dictionary request to create a new tab in a Google Sheet.

Parameters

  • tab_title (str) – The name of the tab.

  • tab_id (int, optional) – The desired id of the tab, which cannot already exist in the Google Sheet, defaults to None, which will allow the Google Sheet to generate the tab_id.

  • tab_idx (int, optional) – The (0-based) index to create the tab at, defaults to None, meaning the tab will be created as the last tab in the Google Sheet.

  • num_rows (int, optional) – The starting number of rows in the new tab, defaults to 1000.

  • num_cols (int, optional) – The starting number of columns in the new tab, defaults to 26.

Returns

A dictionary ready to be passed as a request via a request commit.

Return type

Dict[str, Any]

gen_add_tab_request()

Generates a new tab request dictionary for this Tab. Useful when you have manually instantiated a Tab object instead of fetching it and want to add it to the parent GSheet.

Returns

A dictionary ready to be passed as a request via a request commit.

Return type

Dict[str, Any]

create()

Convenience method for generating a new tab request based on this Tab and immediately committing it, thus adding it to the parent Google Sheet.

Note

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

Returns

This Tab.

Return type

Tab

gen_range(rng)

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

Parameters

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

Returns

The newly generated Range.

Return type

Range

to_csv(p, header=None)

Saves values to a csv file.

Parameters

  • p (str | Path) – The path-like for the file to save the data to.

  • header (Sequence[Any], optional) – A header row. If supplied, must be the same number of columns as the data values. Defaults to None.

Return type

None

to_json(p, header=0)

Saves values to a json file, with one json per line.

Parameters

  • p (str | Path) – The path-like for the file to save the data to.

  • header (Sequence[Any] | int) – A header row or the index of a row in the values data to use as the header row. The header will be used as the keys for the json-formatted dictionaries. Defaults to 0, using the first row as the header.

Return type

None

commit()

Commits the amassed requests on this view, sending them to the Sheets api as a batch update request.

Returns

The response from the api.

Return type

Dict[str, Any]

Raises

NoConnectionError – If the view’s SheetsConnection is null.

ensure_full_range(backup, rng=None)

Convenience method for ensuring that a range argument that could be None or a string is always a FullRange.

Parameters
Returns

The passed FullRange, or the backup FullRange.

Return type

FullRange

static gen_alpha_keys(num)

Generates a list of characters from the Latin alphabet a la gsheet/excel headers.

Parameters

num (int) – The desired length of the list.

Returns

A list containing as many letters and letter combos as desired. Can be used to generate sets up to 676 in length.

Return type

List[str]