API Reference¶
Collection of spreadsheets available from given OAuth 2.0 credentials or API key. |
|
Fetched collection of worksheets. |
|
Read-only view on the list of worksheets in a spreadsheet. |
|
Two-dimensional table with cells accessible via A1 notation. |
|
Make OAuth 2.0 credentials for scopes from |
|
Return a service endpoint for interacting with a Google API. |
Sheets¶
- class gsheets.Sheets(credentials=None, developer_key=None)¶
Collection of spreadsheets available from given OAuth 2.0 credentials or API key.
- __contains__(id)¶
Return if there is a spreadsheet with the given id.
- __getitem__(id)¶
Fetch and return the spreadsheet with the given id.
- __iter__()¶
Fetch and yield all available spreadsheets.
- Yields
new SpreadSheet spreadsheet instances
- __len__()¶
Return the number of available spreadsheets.
- Returns
number of spreadsheets
- Return type
- find(title)¶
Fetch and return the first spreadsheet with the given title.
- findall(title=None)¶
Fetch and return a list of spreadsheets with the given title.
- classmethod from_developer_key(developer_key)¶
Return a spreadsheet collection using an API key.
- classmethod from_files(secrets=None, storage=None, scopes=None, *, no_webserver=False)¶
Return a spreadsheet collection making OAauth 2.0 credentials.
- Parameters
- Returns
new Sheets instance with OAauth 2.0 credentials
- Return type
- get(id_or_url, default=None)¶
Fetch and return the spreadsheet with the given id or url.
- Parameters
id_or_url (str) – unique alphanumeric id or URL of the spreadsheet
- Returns
New SpreadSheet instance or given default if none is found
- Raises
ValueError – if an URL is given from which no id could be extracted
- ids()¶
Return a list of all available spreadsheet ids.
- Returns
list of unique alphanumeric id strings
- Return type
- iterfiles()¶
Yield
(id, title)
pairs for all available spreadsheets.- Yields
pairs of unique id (
str
) and title/name (str
)
SpreadSheet¶
- class gsheets.models.SpreadSheet(id, title, sheets, service)¶
Fetched collection of worksheets.
- __contains__(id)¶
Return if the spreadsheet has a worksheet with the given id.
- __getitem__(id)¶
Return the worksheet with the given id.
- __iter__()¶
Yield all contained worksheets.
- Yields
WorkSheet objects (spreadsheet members)
- find(title)¶
Return the first worksheet with the given title.
- findall(title=None)¶
Return a list of worksheets with the given title.
- property first_sheet¶
The first worksheet of the spreadsheet.
- get(id, default=None)¶
Return the worksheet with the given id or the given default.
- Parameters
id – numeric id of the worksheet
- Returns
contained worksheet object or given default
- Return type
- Raises
ValueError – if
id
is not anint
- property id¶
Unique alphanumeric id of the spreadsheet (
str
).see https://developers.google.com/sheets/guides/concepts#spreadsheet_id
- property sheets¶
List view of the worksheets in the spreadsheet (positional access).
- property title¶
Title/name of the spreadsheet (
str
).
- to_csv(*, encoding='utf-8', dialect='excel', make_filename='%(title)s - %(sheet)s.csv')¶
Dump all worksheets of the spreadsheet to individual CSV files.
- Parameters
If
make_filename
is a string, it is string-interpolated with an infos-dictionary with the fieldsid
(spreadhseet id),title
(spreadsheet title),sheet
(worksheet title),gid
(worksheet id),index
(worksheet index), anddialect
CSV dialect to generate the filename:filename = make_filename % infos
.If
make_filename
is a callable, it will be called with the infos-dictionary to generate the filename:filename = make_filename(infos)
.
- property url¶
URL pointing to the first worksheet of the spreadsheet (
str
).
SheetsView¶
- class gsheets.models.SheetsView(items)¶
Read-only view on the list of worksheets in a spreadsheet.
- __getitem__(index)¶
Return the worksheet at the given index (position).
- Parameters
index – zero-based position or slice
- Raises
IndexError – if
index
is out of range
WorkSheet¶
- class gsheets.models.WorkSheet(id, title, index, values)¶
Two-dimensional table with cells accessible via A1 notation.
- __getitem__(index)¶
Return the value(s) of the given cell(s).
- Parameters
index (str) – cell/row/col index (‘A1’, ‘2’, ‘B’) or slice (‘A1’:’C3’)
- Returns
value (cell), list(col, row), or nested list (two-dimentional slice)
- Raises
TypeError – if
index
is not a string or slice of stringsValueError – if
index
canot be parsedIndexError – if
index
is out of range
- at(row, col)¶
Return the value at the given cell position.
- Parameters
- Returns
cell value
- Raises
TypeError – if
row
orcol
is not anint
IndexError – if the position is out of range
- property id¶
Stable numeric worksheet id (
int
), unique within its spreadsheet.see https://developers.google.com/sheets/guides/concepts#sheet_id
- property index¶
Zero-based position of the worksheet.
- property ncells¶
Number of cells in the worksheet (
int
).
- property ncols¶
Number of columns in the worksheet (int).
- property nrows¶
Number of rows in the worksheet (
int
).
- property spreadsheet¶
Containing spreadsheet of the worksheet.
- property title¶
Worksheet title/name (
str
).
- to_csv(filename=None, *, encoding='utf-8', dialect='excel', make_filename='%(title)s - %(sheet)s.csv')¶
Dump the worksheet to a CSV file.
- Parameters
If
make_filename
is a string, it is string-interpolated with an infos-dictionary with the fieldsid
(spreadhseet id),title
(spreadsheet title),sheet
(worksheet title),gid
(worksheet id),index
(worksheet index), anddialect
CSV dialect to generate the filename:filename = make_filename % infos
.If
make_filename
is a callable, it will be called with the infos-dictionary to generate the filename:filename = make_filename(infos)
.
- to_frame(*, assign_name=False, **kwargs)¶
Return a pandas DataFrame loaded from the worksheet data.
- Parameters
assign_name (bool) – set name attribute on the DataFrame to sheet title.
**kwargs – passed to
pandas.read_csv()
(e.g.header
,index_col
)
- Returns
new
DataFrame
instance- Return type
pandas.DataFrame
- property url¶
URL pointing to the worksheet (
str
).
Low-level functions¶
- gsheets.get_credentials(scopes=None, secrets=None, storage=None, *, no_webserver=False)¶
Make OAuth 2.0 credentials for scopes from
secrets
andstorage
files.- Parameters
scopes – scope URL(s) or
'read'
,'write'
(default:'read'
)secrets – location of secrets file (default:
'~/client_secrets.json'
)storage – location of storage file (default:
'~/storage.json'
)no_webserver – url/code prompt instead of webbrowser based auth
see https://developers.google.com/sheets/quickstart/python see https://developers.google.com/api-client-library/python/guide/aaa_client_secrets
- gsheets.build_service(name=None, **kwargs)¶
Return a service endpoint for interacting with a Google API.