smartsheet package

Subpackages

smartsheet.models package

Submodules

smartsheet.attachments module

class smartsheet.attachments.Attachments(smartsheet_obj)

Bases: object

Class for handling Attachments operations.

attach_file_to_comment(sheet_id, comment_id, _file)

Add a file to a Comment.

Parameters:

sheet_id (int) – Sheet ID
comment_id (int) – Comment ID
_file (file) – String or file stream object.

Returns:

Result

attach_file_to_row(sheet_id, row_id, _file)

Add a file to the row.

Parameters:

sheet_id (int) – Sheet ID
row_id (int) – Row ID
_file (file) – String or file stream object.

Returns:

Result

attach_file_to_sheet(sheet_id, _file)

Attach a file to the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
_file (file) – String or file stream object.

Returns:

Result

attach_new_version(sheet_id, attachment_id, _file)

Upload a new version of a file to a Sheet or Row.

Parameters:

sheet_id (int) – Sheet ID
attachment_id (int) – Attachment ID
_file (file) – String or file stream object.

Returns:

Result

attach_url_to_comment(sheet_id, comment_id, attachment_obj)

Add a URL to a Comment.

Attachment object for this request should be limited to the following attributes: name, description, url, attachmentType, attachmentSubType.

The URL and attachmentType can be any of the following:

A Normal URL. attachmentType is LINK.

A Google Drive URL. attachmentType is LINK. Supports attachmentSubType values of DOCUMENT, SPREADSHEET, PRESENTATION, PDF and DRAWING.

A Box.com URL. attachmentType is BOX_COM.

A Dropbox URL. attachmentType is DROPBOX.

An Evernote URL. attachmentType is EVERNOTE.

An Egnyte URL. attachmentType is EGNYTE. Supports attachmentSubType of FOLDER.

Parameters:

sheet_id (int) – Sheet ID
comment_id (int) – Comment ID
attachment_obj (Attachment) – Attachment object.

Returns:

Result

attach_url_to_row(sheet_id, row_id, attachment_obj)

Add a URL to a Row.

Attachment object for this request should be limited to the following attributes: name, description, url, attachmentType, attachmentSubType.

The URL and attachmentType can be any of the following:

A Normal URL. attachmentType is LINK.

A Google Drive URL. attachmentType is LINK. Supports attachmentSubType values of DOCUMENT, SPREADSHEET, PRESENTATION, PDF and DRAWING.

A Box.com URL. attachmentType is BOX_COM.

A Dropbox URL. attachmentType is DROPBOX.

An Evernote URL. attachmentType is EVERNOTE.

An Egnyte URL. attachmentType is EGNYTE. Supports attachmentSubType of FOLDER.

Parameters:

sheet_id (int) – Sheet ID
row_id (int) – Row ID
attachment_obj (Attachment) – Attachment object.

Returns:

Result

attach_url_to_sheet(sheet_id, attachment_obj)

Add a URL to a Sheet.

Attachment object for this request should be limited to the following attributes: name, description, url, attachmentType, attachmentSubType.

The URL and attachmentType can be any of the following:

A Normal URL. attachmentType is LINK.

A Google Drive URL. attachmentType is LINK. Supports attachmentSubType values of DOCUMENT, SPREADSHEET, PRESENTATION, PDF and DRAWING.

A Box.com URL. attachmentType is BOX_COM.

A Dropbox URL. attachmentType is DROPBOX.

An Evernote URL. attachmentType is EVERNOTE.

An Egnyte URL. attachmentType is EGNYTE. Supports attachmentSubType of FOLDER.

Parameters:

sheet_id (int) – Sheet ID
attachment_obj (Attachment) – Attachment object.

Returns:

Result

delete_attachment(sheet_id, attachment_id)

Delete the specified Attachment.

Parameters:

sheet_id (int) – Sheet ID
attachment_id (int) – Attachment ID

Returns:

Result

delete_attachment_versions(sheet_id, attachment_id)

Delete all versions of the specified Attachment.

Delete all versions of the attachment corresponding to the specified Attachment ID.

Parameters:

sheet_id (int) – Sheet ID
attachment_id (int) – Attachment ID

Returns:

Result

download_attachment(attachment_obj, download_path, alternate_file_name=None)

Download the specified attachment as a file.

This method wraps the Requests module and performs a streaming file download to the specified location.

Parameters:

attachment_obj (Attachment) – Attachment object
download_path (str) – Directory path on local machine to save file.
alternate_file_name (str) – Filename to use instead of name suggested by Content-Disposition.

Returns:

DownloadedFile

get_attachment(sheet_id, attachment_id)

Fetch the specified Attachment.

Parameters:

sheet_id (int) – Sheet ID
attachment_id (int) – Attachment ID

Returns:

Attachment

list_all_attachments(sheet_id, page_size=None, page=None, include_all=None)

Get a list of Attachments for a Sheet.

Get a list of all Attachments for the specified Sheet, including Sheet, Row, and Discussion level Attachments.

Parameters:

sheet_id (int) – Sheet ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

list_attachment_versions(sheet_id, attachment_id, page_size=None, page=None, include_all=None)

Get a list of versions for an Attachment.

Get a list of all versions of the given Attachment ID, in order from newest to oldest.

Parameters:

sheet_id (int) – Sheet ID
attachment_id (int) – Attachment ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

list_discussion_attachments(sheet_id, discussion_id, page_size=None, page=None, include_all=None)

Get a list of Attachments for the Sheet Discussion.

Get a list of all Attachments for the specified Sheet Discussion.

Parameters:

sheet_id (int) – Sheet ID
discussion_id (int) – Discussion ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

list_row_attachments(sheet_id, row_id, page_size=None, page=None, include_all=None)

Get a list of all Attachments for the specified Sheet Row.

Parameters:

sheet_id (int) – Sheet ID
row_id (int) – Row ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

smartsheet.cells module

class smartsheet.cells.Cells(smartsheet_obj)

Bases: object

Class for handling Cells operations.

add_image_to_cell(sheet_id, row_id, column_id, file, file_type, override_validation=False, alt_text=None)

Uploads an image to the specified cell.

Parameters:

sheet_id (int) – Sheet ID
row_id (int) – Row ID
column_id (int) – Column ID
file (string) – path to image file.
file_type (string) – content type of image file
override_validation – override a column’s validation property
alt_text – alternate text for the image

Returns:

Result

get_cell_history(sheet_id, row_id, column_id, include=None, page_size=None, page=None, include_all=None, level=None)

Get the Cell modification history.

Parameters:

sheet_id (int) – Sheet ID
row_id (int) – Row ID
column_id (int) – Column ID
include (str) – Valid includes for CellHistory are: columnType, format, objectValue
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).
level (int) – compatibility level

Returns:

IndexResult

smartsheet.contacts module

class smartsheet.contacts.Contacts(smartsheet_obj)

Bases: object

Class for handling Contacts operations.

get_contact(contact_id)

Get the specified Contact.

Parameters:: contact_id (str) – Contact ID
Returns:: Contact

list_contacts(page_size=None, page=None, include_all=None)

Get a list of the user’s Smartsheet Contacts.

Parameters:

page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

smartsheet.discussions module

class smartsheet.discussions.Discussions(smartsheet_obj)

Bases: object

Class for handling Discussions operations.

add_comment_to_discussion(sheet_id, discussion_id, comment_obj=None)

Add a Comment to the specified Discussion

Parameters:

sheet_id (int) – Sheet ID
discussion_id (int) – Discussion ID
comment_obj (Comment) – Comment object.

Returns:

Result

add_comment_to_discussion_with_attachment(sheet_id, discussion_id, comment, _file=None)

Add a Comment with an Attachment to the specified Discussion

Parameters:

sheet_id (int) – Sheet ID
discussion_id (int) – Discussion ID
comment (file) – Comment object.
_file (file) – String or file stream object.

Returns:

Result

create_discussion_on_row(sheet_id, row_id, discussion_obj=None)

Create a new Discussion on a Row.

Parameters:

sheet_id (int) – Sheet ID
row_id (int) – Row ID
discussion_obj (Discussion) – Discussion object.

Returns:

Result

create_discussion_on_row_with_attachment(sheet_id, row_id, discussion, _file=None)

Create a new Discussion on a Row with an attachment.

Parameters:

sheet_id (int) – Sheet ID
row_id (int) – Row ID
discussion (file) – Discussion object.
_file (file) – String or file stream object.

Returns:

Result

create_discussion_on_sheet(sheet_id, discussion_obj=None)

Create a new Discussion on a Sheet.

Parameters:

sheet_id (int) – Sheet ID
discussion_obj (Discussion) – Discussion object.

Returns:

Result

create_discussion_on_sheet_with_attachment(sheet_id, discussion, _file=None)

Create a new Discussion on a Sheet with an attachment.

Parameters:

sheet_id (int) – Sheet ID
discussion (file) – Discussion object.
_file (file) – String or file stream object.

Returns:

Result

delete_discussion(sheet_id, discussion_id)

Delete the specified Discussion.

Parameters:

sheet_id (int) – Sheet ID
discussion_id (int) – Discussion ID

Returns:

Result

delete_discussion_comment(sheet_id, comment_id)

Delete the specified Sheet Comment.

Delete the specified Comment from the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
comment_id (int) – Comment ID

Returns:

Result

get_all_discussions(sheet_id, include=None, page_size=None, page=None, include_all=None)

Get a list of all Discussions on the specified Sheet.

Get a list of all Discussions associated with the specified Sheet (both sheet-level discussions and row-level discussions).

Parameters:

sheet_id (int) – Sheet ID
include (list[str]) – A comma-separated list of optional elements to include in the response. Valid list values: comments, attachments
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

get_discussion(sheet_id, discussion_id)

Get the specified Discussion.

Parameters:

sheet_id (int) – Sheet ID
discussion_id (int) – Discussion ID

Returns:

Discussion

get_discussion_comment(sheet_id, comment_id)

Get the specified Comment.

Parameters:

sheet_id (int) – Sheet ID
comment_id (int) – Comment ID

Returns:

Comment

get_row_discussions(sheet_id, row_id, include=None, page_size=None, page=None, include_all=None)

Get a list of all Discussions associated with the specified Row.

Parameters:

sheet_id (int) – Sheet ID
row_id (int) – Row ID
include (list[str]) – A comma-separated list of optional elements to include in the response. Valid list values: comments, attachments. (Attachments is effective only if comments is present, otherwise ignored.)
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

update_comment(sheet_id, comment_id, comment_obj)

Update the specified Comment.

Parameters:

sheet_id (int) – Sheet ID
comment_id (int) – Comment ID
comment_obj (Comment) – Comment object with the following attributes:

Returns:

Result

smartsheet.events module

class smartsheet.events.Events(smartsheet_obj)

Bases: object

list_events(since=None, to=None, stream_position=None, max_count=None, numeric_dates=None)

Get the list of all Events.

Parameters:

since (str or long) – Starting time for events to return. You must pass in a value for either since or streamPosition and never both.
to (str or long) – Ending time for events to return. This parameter specifies the endpoint in time for the events to be fetched. Similar to the since parameter, to can be passed in either as a datetime string in ISO 8601 format or as a UNIX epoch time in milliseconds. This allows for defining a precise time range for the events query. Note that to is optional and can be used in conjunction with since to specify both the start and end times for the event retrieval window.
stream_position (str) – Indicates next set of events to return. Use value of nextStreamPosition returned from the previous call. You must pass in a value for either since or streamPosition and never both.
max_count (int) – Maximum number of events to return as response to this call. Must be between 1 through 10,000 (inclusive).
numeric_dates (bool) – If true, dates are accepted and returned in Unix epoch time (milliseconds since midnight on January 1, 1970 in UTC time). Default is false, which means ISO-8601 format

Returns:

EventResult containing Event array as data[]

smartsheet.exceptions module

exception smartsheet.exceptions.ApiError(error, message=None, should_retry=False)

Bases: SmartsheetException

Errors produced by the Smartsheet API.

exception smartsheet.exceptions.HttpError(status_code, body)

Bases: SmartsheetException

Errors produced at the HTTP layer.

exception smartsheet.exceptions.InternalServerError(status_code, message)

Bases: HttpError

Errors due to a problem on Smartsheet.

exception smartsheet.exceptions.RateLimitExceededError(error, message)

Bases: ApiError

Rate limit exceeded.

exception smartsheet.exceptions.ServerTimeoutExceededError(error, message)

Bases: ApiError

Server timeout exceeded. Request has failed.

exception smartsheet.exceptions.SmartsheetException

Bases: Exception

Root for SmartsheetErrors, never raised directly.

exception smartsheet.exceptions.SystemMaintenanceError(error, message)

Bases: ApiError

Smartsheet.com is currently offline for system maintenance. …

exception smartsheet.exceptions.UnexpectedErrorShouldRetryError(error, message)

Bases: ApiError

An unexpected error has occurred. Please retry your request. If …

exception smartsheet.exceptions.UnexpectedRequestError(request, response)

Bases: SmartsheetException

Error originating from Requests API.

smartsheet.favorites module

class smartsheet.favorites.Favorites(smartsheet_obj)

Bases: object

Class for handling Favorites operations.

add_favorites(favorite_obj)

Add one or more items to the user’s list of Favorite items.

Adds one or more items to the user’s list of Favorite items. This operation supports both single-object and bulk semantics. If called with a single Favorite object, and that favorite already exists, error code 1129 will be returned. If called with an array of Favorite objects, any objects specified in the array that are already marked as favorites will be ignored and ommitted from the response.

Parameters:: favorite_obj (list[Favorite]) – Array of one or more Favorite objects
Returns:: Result

list_favorites(page_size=None, page=None, include_all=None)

Get a list of all the user’s Favorite items.

Parameters:

page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

remove_favorites(favorite_type, object_ids)

Delete one or more of Favorite objects of the specified type.

Specify a favorite type of: folder, report, sheet, template, workspace. The object IDs passed in will be deleted in a batch operation.

Parameters:

favorite_type (str) – Name of favorite type to manipulate.
object_ids (list[int]) – a comma-separated list of object IDs representing the items to work on.

Returns:

Result

smartsheet.folders module

class smartsheet.folders.Folders(smartsheet_obj)

Bases: object

Class for handling Folders operations.

copy_folder(folder_id, container_destination_obj, include=None, skip_remap=None)

Creates a copy of the specified Folder.

Parameters:

folder_id (int) – Folder ID
container_destination_obj – (ContainerDestination): Container Destination object.
include (list[str]) – A comma separated list of elements to copy. Valid list values: attachments, attachments, cellLinks, data, discussions, filters, forms, ruleRecipients, rules, shares, all (deprecated).
skip_remap (list[str]) – A comma separated list of references to NOT re-map for the newly created resource. Valid list items: cellLinks, reports, sheetHyperlinks, sights

Returns:

Result

create_folder_in_folder(folder_id, folder_obj)

Create a Folder in the specified Folder

Parameters:

folder_id (int) – Folder ID
folder_obj (Folder) – Folder object.

Returns:

Result

create_sheet_in_folder(folder_id, sheet_obj)

Create a Sheet from scratch in the specified Folder.

Parameters:

folder_id (int) – Folder ID
sheet_obj (Sheet) – Sheet object.

Returns:

Result

create_sheet_in_folder_from_template(folder_id, sheet_obj, include=None)

Create a Sheet in the specified Folder from the specified Template.

The Sheet object should be limited to the following attributes:

name (required): need not be unique. fromId (required): the ID of the Template to use in creating the Sheet.

The optional Include parameter is a list of elements to copy from the Template. It may include: data, attachments, discussions, cellLinks, forms

Parameters:

folder_id (int) – Folder ID
sheet_obj (Sheet) – Sheet object.
include (list[str]) – A list of optional elements to include from the source Template. Valid list values: data, attachments, discussions, cellLinks, forms.

Returns:

Result

delete_folder(folder_id)

Delete the Folder (and its contents) specified in the request.

Parameters:: folder_id (int) – Folder ID
Returns:: Result

get_folder(folder_id, include=None)

Get the specified Folder (and list its contents).

Parameters:

folder_id (int) – Folder ID
include (list[str]) – A comma-separated list of optional elements to include in the response. Valid list values: ownerInfo, sheetVersion, source.

Returns:

Folder

import_csv_sheet(folder_id, file, sheet_name=None, header_row_index=None, primary_column_index=None)

Imports a sheet in the specified folder.

Parameters:

folder_id (int) – folder ID
file (string) – path to CSV file.
sheet_name (string) – destination sheet name
header_row_index (int) – index (0 based) of row to be used for column names
primary_column_index (int) – index (0 based) of primary column

Returns:

Result

import_xlsx_sheet(folder_id, file, sheet_name=None, header_row_index=None, primary_column_index=None)

Imports a sheet in the specified folder.

Parameters:

folder_id (int) – folder ID
file (string) – path to XLSX file.
sheet_name (string) – destination sheet name
header_row_index (int) – index (0 based) of row to be used for column names
primary_column_index (int) – index (0 based) of primary column

Returns:

Result

list_folders(folder_id, page_size=None, page=None, include_all=None)

Get a list of top-level child Folders within the specified Folder.

Parameters:

folder_id (int) – Folder ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

move_folder(folder_id, container_destination_obj)

Moves the specified Folder to another location.

Parameters:

folder_id (int) – Folder ID
container_destination_obj – (ContainerDestination): Container Destination object.

Returns:

Result

update_folder(folder_id, folder_obj)

Update the specified Folder.

Parameters:

folder_id (int) – Folder ID
folder_obj (Folder) – Folder object.

Returns:

Result

smartsheet.groups module

class smartsheet.groups.Groups(smartsheet_obj)

Bases: object

Class for handling Groups operations.

add_members(group_id, group_member_obj)

Add one or more members to a Group.

Parameters:

group_id (int) – Group ID
group_member_obj (GroupMember) – Group member object(s).

Returns:

Result

create_group(group_obj)

Create a new Group

Parameters:: group_obj (Group) – Group object.
Returns:: Result

delete_group(group_id)

Delete the specified Group.

Parameters:: group_id (int) – Group ID
Returns:: Result

get_group(group_id)

Get the specified Group.

Parameters:: group_id (int) – Group ID
Returns:: Group

list_groups(page_size=None, page=None, include_all=None)

Get all Groups in an organization.

Get the list of all Groups in an organization. To fetch the members of an individual group, use the getGroup operation.

Parameters:

page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

remove_member(group_id, user_id)

Removes a member from the specified Group.

Parameters:

group_id (int) – Group ID
user_id (int) – User ID

Returns:

Result

update_group(group_id, group_obj)

Updates the specified Group.

Parameters:

group_id (int) – Group ID
group_obj (Group) – Group object.

Returns:

Result

smartsheet.home module

class smartsheet.home.Home(smartsheet_obj)

Bases: object

Class for handling Home operations.

create_folder(folder_obj)

Creates a Folder in the user’s Sheets folder (Home).

Parameters:: folder_obj (Folder) – Folder object.
Returns:: Result

create_sheet(sheet_obj)

Create a Sheet from scratch in the user’s Sheets folder within Home.

Parameters:: sheet_obj (Sheet) – Sheet object.
Returns:: Result

create_sheet_from_template(sheet_obj, include=None)

Create a Sheet in the Sheets folder from the specified Template.

The Sheet object should be limited to the following attributes:

name (required): need not be unique. fromId (required): the ID of the Template to use in creating the Sheet.

The optional Include parameter is a list of elements to copy from the Template. It may include: data, attachments, discussions, cellLinks, forms

Parameters:

sheet_obj (Sheet) – Sheet object.
include (list[str]) – A list of optional elements to include from the source Template. Valid list values: attachments, cellLinks, data, discussions, forms, rules and ruleRecipients.

Returns:

Result

list_all_contents(include=None, exclude=None)

Get a nested list of all Home objects, including Sheets, Workspaces, Folders, Reports and Templates.

Parameters:

include (list[str]) – A comma-separated list of optional elements to include in the response. Valid list values: ownerInfo, sheetVersion, source.
include – A comma-separated list of optional elements to exclude from the response. Valid list values: permalinks.

Returns:

Home

list_folders(page_size=None, page=None, include_all=None)

Gets a list of top-level child Folders within the user’s Sheets folder.

Parameters:

page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

smartsheet.images module

class smartsheet.images.Images(smartsheet_obj)

Bases: object

Class for handling Images operations.

get_image_urls(list_of_images)

Get URLs that can be used to retrieve specified cell images.

Parameters:: list_of_images (list[ImageURL]) – Array containing one or more ImageURL objects.
Returns:: ImageURLMap

smartsheet.object_value module

smartsheet.object_value.assign_to_object_value(value)

smartsheet.passthrough module

class smartsheet.passthrough.Passthrough(smartsheet_obj)

Bases: object

Class for handling Sheets operations.

delete(endpoint)

Issue a DELETE request on the specified URL.

Parameters:: endpoint (str) – Endpoint URL (relative to base), e.g. ‘/sheets/{id}’
Returns:: JSONObject

get(endpoint, query_params=None)

Issue a GET request on the specified URL.

Parameters:

endpoint (str) – Endpoint URL (relative to base), e.g. ‘/sheets’
query_params (dict) – Optional dictionary of additional query parameters

Returns:

JSONObject

post(endpoint, payload, query_params=None)

Issue a POST request on the specified URL.

Parameters:

endpoint (str) – Endpoint URL (relative to base), e.g. ‘/sheets’
payload (str, dict, or JSONObject) – JSON payload
query_params (dict) – Optional dictionary of additional query parameters

Returns:

JSONObject

put(endpoint, payload, query_params=None)

Issue a PUT request on the specified URL.

Parameters:

endpoint (str) – Endpoint URL (relative to base), e.g. ‘/sheets/{id}’
payload (str, dict or JSONObject) – JSON payload
query_params (dict) – Optional dictionary of additional query parameters

Returns:

JSONObject

smartsheet.reports module

class smartsheet.reports.Reports(smartsheet_obj)

Bases: object

Class for handling Reports operations.

delete_share(report_id, share_id)

Deletes the specified Share

Parameters:

report_id (int) – Report ID
share_id (str) – Share ID

Returns:

Result

get_publish_status(report_id)

Get the Publish status of the Report.

Get the status of the Publish settings of the Report, including URLs of any enabled publishings.

Parameters:: report_id (int) – Report ID
Returns:: ReportPublish

get_report(report_id, page_size=None, page=None, include=None, level=None)

Get the specified Report, including one page of Rows.

Get the specified Report, including one page of Rows, and optionally populated with Discussions, Attachments, and Source Sheets.

Parameters:

report_id (int) – Report ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include (list[str]) – A comma-separated list of optional elements to include in the response. Valid list values: attachments, discussions, format, objectValue, scope, source, sourceSheets.
level (int) – compatibility level

Returns:

Report

get_report_as_csv(report_id, download_path, alternate_file_name=None)

Get the specified Report as a CSV file.

Parameters:

report_id (int) – Report ID
download_path (str) – Directory path on local machine to save file.
alternate_file_name (str) – Filename to use instead of name suggested by Content-Disposition.

Returns:

DownloadedFile

get_report_as_excel(report_id, download_path, alternate_file_name=None)

Get the specified Report as an Excel .xls document.

Parameters:

report_id (int) – Report ID
download_path (str) – Directory path on local machine to save file.
alternate_file_name (str) – Filename to use instead of name suggested by Content-Disposition.

Returns:

DownloadedFile

get_share(report_id, share_id)

Get the specified Share.

Parameters:

report_id (int) – Report ID
share_id (str) – Share ID

Returns:

Share

list_reports(page_size=None, page=None, include_all=None, modified_since=None)

Get the list of all Reports accessible by the User.

Get the list of all Reports that the User has access to, in alphabetical order by name.

Parameters:

page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).
modified_since (datetime) – return reports modified after the specified modified_since

Returns:

IndexResult

list_shares(report_id, page_size=None, page=None, include_all=None, include_workspace_shares=False)

Get a list of all Users and Groups to whom the specified Report is shared, and their access level.

Parameters:

report_id (int) – Report ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).
include_workspace_shares (bool) – include Workspace shares

Returns:

IndexResult

send_report(report_id, sheet_email_obj)

Send the specified Report as a PDF attachment via email to the designated recipients.

Parameters:

report_id (int) – Report ID
sheet_email_obj (SheetEmail) – SheetEmail object.

Returns:

Result

set_publish_status(report_id, report_publish_obj)

Set the publish status of the Report and returns the new status, including the URLs of any enabled publishings.

Parameters:

report_id (int) – Report ID
report_publish_obj (ReportPublish) – ReportPublish object.

Returns:

Result

share_report(report_id, share_obj, send_email=False)

Shares a Report with the specified Users and Groups.

Parameters:

report_id (int) – Report ID
share_obj (Share) – Share object.
send_email (bool) – Either true or false to indicate whether or not to notify the user by email. Default is false.

Returns:

Result

update_share(report_id, share_id, share_obj)

Update the access level of a User or Group for the specified Report

Parameters:

report_id (int) – Report ID
share_id (str) – Share ID
share_obj (Share) – Share object.

Returns:

Result

smartsheet.search module

class smartsheet.search.Search(smartsheet_obj)

Bases: object

Class for handling Search operations.

search(query, include=None, location=None, modified_since=None, scopes=None)

Search all Sheets the User can access for the specified text.

Parameters:

query (str) – Text with which to perform the search.
include (str) – when specified with a value of ‘favoriteFlag’, response indicates which returned items are favorites
location (str) – when specified with a value of ‘personalWorkspace’, limits the response to only those items in the user’s Workspaces
modified_since (str) – includes items that are modified on or after the date and time specified
scopes (str) – comma-separated list of search filters: attachments cellData comments folderNames profileFields reportNames sheetNames sightNames summaryFields templateNames workspaceNames

Returns:

SearchResult

search_sheet(sheet_id, query)

Search the specified Sheet for the specified text.

Parameters:

sheet_id (int) – Sheet ID
query (str) – Text with which to perform the search.

Returns:

SearchResult

smartsheet.server module

class smartsheet.server.Server(smartsheet_obj)

Bases: object

Class for handling Server operations.

server_info(): Get application constants. :returns: ServerInfo

smartsheet.session module

smartsheet.session.pinned_session(pool_maxsize=8)

smartsheet.session.redact_token(res, *args, **kwargs)

smartsheet.sheets module

class smartsheet.sheets.Sheets(smartsheet_obj)

Bases: object

Class for handling Sheets operations.

add_columns(sheet_id, list_of_columns)

Insert one or more Columns into the specified Sheet

Parameters:

sheet_id (int) – Sheet ID
list_of_columns (list[Column]) – One or more Column objects

Returns:

Result

add_rows(sheet_id, list_of_rows)

Insert one or more Rows into the specified Sheet.

If multiple rows are specified in the request, all rows must be inserted at the same location (i.e. the toTop, toBottom, parentId, siblingId, and above attributes must be the same for all rows in the request.)

In a parent row, values of the following fields will be auto-calculated based upon values in the child rows (and therefore cannot be updated using the API): Start Date, End Date, Duration, % Complete.

Parameters:

sheet_id (int) – Sheet ID
row_or_list_of_rows (list[Row]) –
An array of Row objects with the following attributes:

One or more location-specifier attributes (optional)

format (optional)

expanded (optional)

locked (optional)

A cells attribute set to an array of Cell objects. To insert an empty row, set the cells attribute to empty or null. Each Cell object may contain the following attributes:

columnId (required)

value (required)

strict (optional)

format (optional)

hyperlink (optional)

Returns:

Result

add_rows_with_partial_success(sheet_id, list_of_rows)

Insert one or more Rows into the specified Sheet.

If multiple rows are specified in the request, all rows must be inserted at the same location (i.e. the toTop, toBottom, parentId, siblingId, and above attributes must be the same for all rows in the request.)

In a parent row, values of the following fields will be auto-calculated based upon values in the child rows (and therefore cannot be updated using the API): Start Date, End Date, Duration, % Complete.

Parameters:

sheet_id (int) – Sheet ID
list_of_rows (list[Row]) –
An array of Row objects with the following attributes:

One or more location-specifier attributes (optional)

format (optional)

expanded (optional)

locked (optional)

A cells attribute set to an array of Cell objects. To insert an empty row, set the cells attribute to empty or null. Each Cell object may contain the following attributes:

columnId (required)

value (required)

strict (optional)

format (optional)

hyperlink (optional)

Returns:

Result

add_sheet_summary_field_image(sheet_id, field_id, file, file_type, alt_text=None)

add_sheet_summary_fields(sheet_id, list_of_fields, rename_if_conflict=None)

Insert one or more SummaryFields into the specified Sheet

If an error occurs, the Error object returned will contain a detail attribute set to an object with the following attributes:

index: the array index of the summary field that caused the error
(0 if a single summary field was passed in)

If any error occurs, the entire request will fail (no summary fields will be updated), and the Error response returned will describe the first problem that was encountered.

Parameters:

sheet_id (int) – Sheet ID
list_of_fields (list[SummaryField]) – An array of SummaryField objects.
rename_if_conflict (Boolean) – Normally, this call will fail if it attempts to create a summary field name that already exists. (summary field names must be unique within a sheet.) If this parameter is set to true, then new summary field names will be adjusted to ensure uniqueness.

Returns:

Result

add_sheet_summary_fields_with_partial_success(sheet_id, list_of_fields, rename_if_conflict=None)

Insert one or more SummaryFields into the specified Sheet

When partial success is enabled, and one or more of the objects in the request fail to be added/updated/deleted, a standard Result object is returned, but with a message of ‘PARTIAL_SUCCESS’ (instead of ‘SUCCESS’), and a resultCode of 3. The object will contain a failedItems attribute - an array of BulkItemFailure objects that contains an item for each object in the request that failed to be added/updated/deleted.

Parameters:

sheet_id (int) – Sheet ID
list_of_fields (list[SummaryField]) – An array of SummaryField objects.
rename_if_conflict (Boolean) – Normally, this call will fail if it attempts to create a summary field name that already exists. (summary field names must be unique within a sheet.) If this parameter is set to true, then new summary field names will be adjusted to ensure uniqueness.

Returns:

Result

copy_rows(sheet_id, copy_or_move_row_directive_obj, include=None, ignore_rows_not_found=None)

Copies Row(s) from the specified Sheet to the bottom of another Sheet.

Parameters:

sheet_id (int) – Sheet ID
copy_or_move_row_directive_obj – (CopyOrMoveRowDirective): CopyOrMoveRowDirective object.
include (list[str]) – A comma-separated list of row elements to copy in addition to the cell data. Valid list values: attachments, discussions, children, all.
ignore_rows_not_found (bool) – If set to true, specifying row ids that do not exist within the source sheet will not cause an error response. If omitted or set to false (the default), specifying row ids that do not exist within the source sheet will cause an error response (and no rows will be altered).

Returns:

CopyOrMoveRowResult

copy_sheet(sheet_id, container_destination_obj, include=None, exclude=None)

Creates a copy of the specified Sheet

Parameters:

sheet_id (int) – Sheet ID
container_destination_obj – (ContainerDestination): Container Destination object.
include (list[str]) – A comma-separated list of optional elements to include in the response. Valid list values: attachments, cellLinks, data, discussions, filters, forms, ruleRecipients, rules, shares, all (deprecated).
exclude (list[str]) – A comma-separated list of optional elements to omit. Only current valid value is sheetHyperlinks

Returns:

Result

create_cross_sheet_reference(sheet_id, cross_sheet_reference_obj)

Creates a CrossSheetReference for the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
cross_sheet_reference_obj (CrossSheetReference) – CrossSheetReference object

Returns:

Result

create_update_request(sheet_id, update_request_obj)

Creates an UpdateRequest for the specified Rows(s) within the Sheet.

Parameters:

sheet_id (int) – Sheet ID
update_request_obj (UpdateRequest) – UpdateRequest object

Returns:

Result

delete_automation_rule(sheet_id, automation_rule_id)

Deletes an AutomationRule for the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
automation_rule_id (int) – AutomationRule ID

Returns:

Result

delete_column(sheet_id, column_id)

Delete the specified Column.

Parameters:

sheet_id (int) – Sheet ID
column_id (int) – Column ID

Returns:

Result

delete_filter(sheet_id, filter_id)

Deletes a Filter for the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
filter_id (int) – Filter ID

Returns:

Result

delete_rows(sheet_id, ids, ignore_rows_not_found=False)

Deletes one or more Row(s) from the specified Sheeet.

Parameters:

sheet_id (int) – Sheet ID
ids (list[int]) – a comma-separated list of object IDs representing the items to work on.
ignore_rows_not_found (bool) – If set to true, specifying row ids that do not exist within the source sheet will not cause an error response. If omitted or set to false (the default), specifying row ids that do not exist within the source sheet will cause an error response (and no rows will be altered).

Returns:

Result

delete_sent_update_request(sheet_id, sent_update_request_id)

Deletes a SentUpdateRequest for the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
sent_update_request_id (int) – SentUpdateRequest ID

Returns:

Result

delete_share(sheet_id, share_id)

Delete the specified Share.

Parameters:

sheet_id (int) – Sheet ID
share_id (str) – Share ID

Returns:

Result

delete_sheet(sheet_id)

Delete the specified Sheet.

Parameters:: sheet_id (int) – Sheet ID
Returns:: Result

delete_sheet_summary_fields(sheet_id, list_of_ids, ignore_summary_fields_not_found=None)

Deletes a list of SummaryFields for the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
list_of_ids (list[int]) – list of SummaryField ids
ignore_summary_fields_not_found (Boolean) – By default, any specified fieldId that isn’t found in the sheet summary will cause the entire operation to fail with a “not found” error. If true (default is false), then the operation will not be blocked by fieldIds that are not found. Response will indicate which fields were deleted.

Returns:

Result

delete_update_request(sheet_id, update_request_id)

Deletes an UpdateRequest for the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
update_request_id (int) – UpdateRequest ID

Returns:

Result

get_automation_rule(sheet_id, automation_rule_id)

Get the AutomationRule.

Parameters:

sheet_id (int) – Sheet ID
automation_rule_id (long) – AutomationRuleID

Returns:

AutomationRule

get_column(sheet_id, column_id, include=None)

Get the specified Column.

Parameters:

sheet_id (int) – Sheet ID
column_id (int) – Column ID
include (str) – (future)

Returns:

Column

get_column_by_title(sheet_id, title, include=None)

For those times when you don’t know the Column Id.

Note: returns the first matching title found.

Parameters:

sheet_id (int) – Sheet ID
title (str) – Title search string
include (str) – (future).

get_columns(sheet_id, include=None, page_size=None, page=None, include_all=None, level=None)

Get all columns belonging to the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
include (str) – (future)
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).
level (int) – compatibility level

Returns:

IndexResult

get_cross_sheet_reference(sheet_id, cross_sheet_reference_id)

Get the CrossSheetReference.

Parameters:

sheet_id (int) – Sheet ID
cross_sheet_reference_id (int) – CrossSheetReferenceID

Returns:

CrossSheetReference

get_filter(sheet_id, filter_id)

Get the Filter.

Parameters:

sheet_id (int) – Sheet ID
filter_id (int) – Filter ID

Returns:

Filter

get_publish_status(sheet_id)

Get the Publish status of the Sheet.

Get the status of the Publish settings of the Sheet, including URLs of any enabled publishings.

Parameters:: sheet_id (int) – Sheet ID
Returns:: SheetPublish

get_row(sheet_id, row_id, include=None, exclude=None, level=None)

Get the specified Row of the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
row_id (int) – Row ID
include (list[str]) – A comma-separated list of flags that indicate additional attributes to be included in each Row object within the response. Valid list values: discussions, attachments, format, filters, columnType, rowPermalink, rowWriterInfo.
exclude (str) – Response will not include cells that have never contained any data.
level (int) –
Indicates compatibility level of data to return. Valid options: 0, 1, 2 Option Descriptors:

0 - Backwards compatible text format 1 - multi-contact complex object 2 - multi-picklist complex object

Returns:

Row

get_sent_update_request(sheet_id, sent_update_request_id)

Get the SentUpdateRequest for Sheet.

Parameters:

sheet_id (int) – Sheet ID
sent_update_request_id (int) – SentUpdateRequest ID

Returns:

UpdateRequest

get_share(sheet_id, share_id)

Get the specified Share.

Parameters:

sheet_id (int) – Sheet ID
share_id (str) – Share ID

Returns:

Share

get_sheet(sheet_id, include=None, exclude=None, row_ids=None, row_numbers=None, column_ids=None, page_size=None, page=None, if_version_after=None, level=None, rows_modified_since=None, filter_id=None)

Get the specified Sheet.

Get the specified Sheet. Returns the Sheet, including Rows, and optionally populated with Discussion and Attachment objects.

Parameters:

sheet_id (int) – Sheet ID
include (list[str]) – A comma-separated list of optional elements to include in the response. Valid list values: attachments, columnType, crossSheetReferences, discussions, filters, filterDefinitions, format, objectValue, ownerInfo, rowPermalink, rowWriterInfo (deprecated - use writerInfo), source, summary, writerInfo.
exclude (str) – Response will not include cells that have never contained any data.
row_ids (list[int]) – comma-separated list of Row IDs on which to filter the rows included in the result.
row_numbers (list[int]) – comma-separated list of Row numbers on which to filter the rows included in the result. Non-existent row numbers are ignored.
column_ids (list[int]) – comma-separated list of Column IDs. The response will contain only the specified columns in the ‘columns’ array, and individual rows’ ‘cells’ array will only contain cells in the specified columns.
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
if_version_after (int) – only fetch Sheet if more recent version available.
level (int) – compatibility level
rows_modified_since – Date should be in ISO-8601 format, for example, rowsModifiedSince=2020-01-30T13:25:32-07:00.
filter_id (int) – Applies the given filter (if accessible by the calling user) and marks the affected rows as “filteredOut”: true

Returns:

Sheet

get_sheet_as_csv(sheet_id, download_path, alternate_file_name=None)

Get the specified Sheet as a CSV file.

Parameters:

sheet_id (int) – Sheet ID
download_path (str) – Directory path on local machine to save file.
alternate_file_name (str) – Filename to use instead of name suggested by Content-Disposition.

Returns:

DownloadedFile

get_sheet_as_excel(sheet_id, download_path, alternate_file_name=None)

Get the specified Sheet as an Excel .xls file.

Parameters:

sheet_id (int) – Sheet ID
download_path (str) – Directory path on local machine to save file.
alternate_file_name (str) – Filename to use instead of name suggested by Content-Disposition.

Returns:

DownloadedFile

get_sheet_as_pdf(sheet_id, download_path, paper_size=None, alternate_file_name=None)

Get the specified Sheet as a PDF file.

Parameters:

sheet_id (int) – Sheet ID
download_path (str) – Directory path on local machine to save file.
paper_size (str) – Applies to PDF only. One of: LETTER, LEGAL, WIDE, ARCHD, A4, A3, A2, A1, A0
alternate_file_name (str) – Filename to use instead of name suggested by Content-Disposition.

Returns:

DownloadedFile

get_sheet_by_name(name, include=None, exclude=None, row_ids=None, row_numbers=None, column_ids=None, page_size=None, page=None)

For those times when you don’t know the Sheet Id.

Note: returns the first matching name found.

Parameters:: get_sheet() (See arguments for)

get_sheet_summary(sheet_id, include=None, exclude=None)

Get the SheetSummary.

Parameters:

sheet_id (int) – Sheet ID
include (list[str]) – A comma-separated list of optional elements to include in the response. Valid list values: format, writerInfo
exclude (list[str]) – A comma-separated list of optional elements to exclude from the response. Valid list values: displayValue, image, imageAltText

Returns:

SheetSummary

get_sheet_summary_fields(sheet_id, include=None, exclude=None, page_size=None, page=None, include_all=None)

Get the list of summary fields for this Sheet.

Parameters:

sheet_id (int) – Sheet ID
include (list[str]) – A comma-separated list of optional elements to include in the response. Valid list values: format, writerInfo
exclude (list[str]) – A comma-separated list of optional elements to exclude from the response. Valid list values: displayValue, image, imageAltText
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

get_sheet_version(sheet_id)

Get the Sheet version without loading the entire Sheet.

Parameters:: sheet_id (int) – Sheet ID
Returns:: Version

get_update_request(sheet_id, update_request_id)

Get the UpdateRequest for Sheet that has a future schedule.

Parameters:

sheet_id (int) – Sheet ID
update_request_id (int) – UpdateRequest ID

Returns:

UpdateRequest

import_csv_sheet(file, sheet_name=None, header_row_index=None, primary_column_index=None)

Imports a sheet.

Parameters:

file (string) – path to CSV file.
sheet_name (string) – destination sheet name
header_row_index (int) – index (0 based) of row to be used for column names
primary_column_index (int) – index (0 based) of primary column

Returns:

Result

import_xlsx_sheet(file, sheet_name=None, header_row_index=None, primary_column_index=None)

Imports a sheet.

Parameters:

file (string) – path to XLSX file.
sheet_name (string) – destination sheet name
header_row_index (int) – index (0 based) of row to be used for column names
primary_column_index (int) – index (0 based) of primary column

Returns:

Result

list_automation_rules(sheet_id, page_size=None, page=None, include_all=None)

Get the list of all AutomationRules for this Sheet.

Parameters:

sheet_id (int) – Sheet ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

list_cross_sheet_references(sheet_id, page_size=None, page=None, include_all=None)

Get the list of all CrossSheetReferences for this Sheet.

Parameters:

sheet_id (int) – Sheet ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

list_filters(sheet_id, page_size=None, page=None, include_all=None)

Returns a list of all saved sheet filters

Parameters:

sheet_id (int) – Sheet ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

list_org_sheets()

Get a list of all Sheets owned by an organization.

Get the list of all Sheets owned by the members of the account (organization). :returns: IndexResult

list_sent_update_requests(sheet_id, page_size=None, page=None, include_all=None)

Get the list of all Sent UpdateRequests.

Parameters:

sheet_id (int) – Sheet ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

list_shares(sheet_id, page_size=None, page=None, include_all=None, include_workspace_shares=False, access_api_level=0)

Get the list of all Users and Groups to whom the specified Sheet is shared, and their access level.

Parameters:

sheet_id (int) – Sheet ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).
include_workspace_shares (bool) – Include Workspace shares

Returns:

IndexResult

list_sheets(include=None, page_size=None, page=None, include_all=None, modified_since=None)

Get the list of all Sheets the User has access to, in alphabetical order, by name.

Parameters:

include (list[str]) – A comma-separated list of optional elements to include in the response. Valid list values: ownerInfo, sheetVersion, source.
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).
modified_since (datetime) – Return sheets modified since provided datetime

Returns:

IndexResult

list_update_requests(sheet_id, page_size=None, page=None, include_all=None)

Get the list of all Sheet UpdateRequests.

Parameters:

sheet_id (int) – Sheet ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

move_rows(sheet_id, copy_or_move_row_directive_obj, include=None, ignore_rows_not_found=None)

Moves Row(s) to the bottom of another Sheet.

Up to 5,000 row IDs can be specified in the request, but if the total number of rows in the destination Sheet after the move exceeds the Smartsheet row limit, an error response will be returned.

Any child rows of the rows specified in the request will also be moved. Parent-child relationships amongst rows will be preserved within the destination Sheet.

Parameters:

sheet_id (int) – Sheet ID
copy_or_move_row_directive_obj – (CopyOrMoveRowDirective): CopyOrMoveRowDirective object.
include (list[str]) – A comma-separated list of row elements to move in addition to the cell data. Valid list values: attachments, discussions.
ignore_rows_not_found (bool) – If set to true, specifying row ids that do not exist within the source sheet will not cause an error response. If omitted or set to false (the default), specifying row ids that do not exist within the source sheet will cause an error response (and no rows will be altered).

Returns:

CopyOrMoveRowResult

move_sheet(sheet_id, container_destination_obj)

Move the specified Sheet to a new location.

Parameters:

sheet_id (int) – Sheet ID
container_destination_obj – (ContainerDestination): Container Destination object.

Returns:

Result

search_sheet(sheet_id, query)

Search the specified Sheet for the specified text.

Parameters:

sheet_id (int) – Sheet ID
query (str) – Text with which to perform the search.

Returns:

SearchResult

send_rows(sheet_id, multi_row_email_obj)

Send one or more rows via email

Parameters:

sheet_id (int) – Sheet ID
multi_row_email_obj (MultiRowEmail) – MultiRowEmail object.

Returns:

Result

send_sheet(sheet_id, sheet_email_obj)

Sends the sheet as an attachment via email to the designated recipients.

Parameters:

sheet_id (int) – Sheet ID
sheet_email_obj (SheetEmail) – SheetEmail object.

Returns:

Result

send_update_request(sheet_id, multi_row_email_obj)

Create an Update Request for the specified Row(s) within the Sheet. An email notification (containing a link to the update request) will be asynchronously send to the specified recipient(s).

Parameters:

sheet_id (int) – Sheet ID
multi_row_email_obj (MultiRowEmail) – MultiRowEmail object.

Returns:

Result

set_publish_status(sheet_id, sheet_publish_obj)

Set the publish status of the Sheet and returns the new status, including the URLs of any enabled publishings.

Parameters:

sheet_id (int) – Sheet ID
sheet_publish_obj (SheetPublish) – SheetPublish object.

Returns:

Result

share_sheet(sheet_id, share_obj, send_email=None)

Share the specified Sheet.

Share the specified Sheet with the specified Users and Groups.

Parameters:

sheet_id (int) – Sheet ID
share_obj (Share) – Share object.
send_email (bool) – Either true or false to indicate whether or not to notify the user by email. Default is false.

Returns:

Result

sort_sheet(sheet_id, sort_specifier_obj, level=None)

Sort Sheet according to SortSpecifier.

Parameters:

sheet_id (int) – Sheet ID
sort_specifier_obj (SortSpecifier) – SortSpecifier object
level (int) – compatibility level

Returns:

Sheet

update_automation_rule(sheet_id, automation_rule_id, automation_rule_obj)

Updates an AutomationRule for the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
automation_rule_id – AutomationRule ID
automation_rule_obj (AutomationRule) – AutomationRule object

Returns:

Result

update_column(sheet_id, column_id, column_obj)

Update properties of the specified Column.

Parameters:

sheet_id (int) – Sheet ID
column_id (int) – Column ID
column_obj (Column) – A Column object.

Returns:

Result

update_rows(sheet_id, list_of_rows)

Update properties of the specified Row.

Updates cell values in the specified row(s), expands/collapses the specified row(s), and/or modifies the position of the specified rows (including indenting/outdenting).

If a row’s position is updated, all child rows are moved with the row.

In a parent row, values of the following fields are auto-calculated based upon values in the child rows (and therefore cannot be updated using the API): Start Date, End Date, Duration, % Complete.

Parameters:

sheet_id (int) – Sheet ID
list_of_rows (list[Row]) – Array containing one or more Row objects.

Returns:

Result

update_rows_with_partial_success(sheet_id, list_of_rows)

Update properties of the specified Row(s).

Updates cell values in the specified row(s), expands/collapses the specified row(s), and/or modifies the position of the specified rows (including indenting/outdenting).

If a row’s position is updated, all child rows are moved with the row.

In a parent row, values of the following fields are auto-calculated based upon values in the child rows (and therefore cannot be updated using the API): Start Date, End Date, Duration, % Complete.

Parameters:

sheet_id (int) – Sheet ID
list_of_rows (list[Row]) – Array containing one or more Row objects.

Returns:

Result

update_share(sheet_id, share_id, share_obj)

Update the access level of a User or Group for the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
share_id (str) – Share ID
share_obj (Share) – Share object.

Returns:

Result

update_sheet(sheet_id, sheet_obj)

Updates the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
sheet_obj (Sheet) – Sheet object.

Returns:

Result

update_sheet_summary_fields(sheet_id, list_of_summary_fields, rename_if_conflict=None)

Updates a list of SummaryFields for the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
list_of_summary_fields (list[SummaryField]) – list of SummaryFields
rename_if_conflict (Boolean) – true to rename if a name conflict occurs

Returns:

Result

update_sheet_summary_fields_with_partial_success(sheet_id, list_of_summary_fields, rename_if_conflict=None)

Updates a list of SummaryFields for the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID
list_of_summary_fields (list[SummaryField]) – list of SummaryFields
rename_if_conflict (Boolean) – true to rename if a name conflict occurs

Returns:

Result

update_update_request(sheet_id, update_request_id, update_request_obj)

Updates an UpdateRequest for the specified Rows(s) within the Sheet.

Parameters:

sheet_id (int) – Sheet ID
update_request_id – Update request ID
update_request_obj (UpdateRequest) – UpdateRequest object

Returns:

Result

smartsheet.sights module

class smartsheet.sights.Sights(smartsheet_obj)

Bases: object

Class for handling Sights operations.

copy_sight(sight_id, container_destination_obj)

Creates a copy of the specified Sight

Parameters:

sight_id (int) – Sight ID
container_destination_obj – (ContainerDestination): Container Destination object.

Returns:

Result

delete_share(sight_id, share_id)

Delete the specified Share.

Parameters:

sight_id (int) – Sight ID
share_id (str) – Share ID

Returns:

Result

delete_sight(sight_id)

Delete the specified Sight.

Parameters:: sight_id (int) – Sight ID
Returns:: Result

get_publish_status(sight_id)

Get the Publish status of the Sight.

Get the status of the Publish settings of the Sight, including URLs of any enabled publishings.

Parameters:: sight_id (int) – Sight ID
Returns:: SightPublish

get_share(sight_id, share_id)

Get the specified Share.

Parameters:

sight_id (int) – Sight ID
share_id (str) – Share ID

Returns:

Share

get_sight(sight_id, level=None, include=None)

Get the specified Sight.

Parameters:

sight_id (int) – Sight ID
level (int) – compatibility level
include (list[str]) – optional include parameters

Returns:

Sight

list_shares(sight_id, page_size=None, page=None, include_all=None, include_workspace_shares=False)

Get the list of all Users and Groups to whom the specified Sight is shared, and their access level.

Parameters:

sight_id (int) – Sight ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).
include_workspace_shares (bool) – Include Workspace shares

Returns:

IndexResult

list_sights(page_size=None, page=None, include_all=None, modified_since=None)

Get the list of all Sights the User has access to, in alphabetical order, by name.

Parameters:

page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).
modified_since (datetime) – return sights modified since datetime

Returns:

IndexResult

move_sight(sight_id, container_destination_obj)

Creates a copy of the specified Sight

Parameters:

sight_id (int) – Sight ID
container_destination_obj – (ContainerDestination): Container Destination object.

Returns:

Result

set_publish_status(sight_id, sight_publish_obj)

Set the publish status of the Sight and returns the new status, including the URLs of any enabled publishings.

Parameters:

sight_id (int) – Sight ID
sight_publish_obj (SightPublish) – SightPublish object.

Returns:

Result

share_sight(sight_id, share_obj, send_email=False)

Share the specified Sight.

Share the specified Sight with the specified Users and Groups.

Parameters:

sight_id (int) – Sight ID
share_obj (Share) – Share object.
send_email (bool) – Either true or false to indicate whether or not to notify the user by email. Default is false.

Returns:

Result

update_share(sight_id, share_id, share_obj)

Update the access level of a User or Group for the specified Sight.

Parameters:

sight_id (int) – Sight ID
share_id (str) – Share ID
share_obj (Share) – Share object.

Returns:

Result

update_sight(sight_id, sight_obj)

Updates the specified Sight.

Parameters:

sight_id (int) – Sight ID
sight_obj (Sight) – Sight object.

Returns:

Result

smartsheet.smartsheet module

class smartsheet.smartsheet.AbstractUserCalcBackoff

Bases: object

calc_backoff(previous_attempts, total_elapsed_time, error_result)

class smartsheet.smartsheet.Smartsheet(access_token=None, max_connections=8, user_agent=None, max_retry_time=30, proxies=None, api_base='https://api.smartsheet.com/2.0')

Bases: object

Use this to make requests to the Smartsheet API.

as_test_scenario(name)

Identify requests made with this client as a test scenario.

Parameters:: name (str) – The name of the test scenario.

assume_user(email=None)

Assume identity of specified user.

As an administrator, you can assume the identity of any user in your organization.

Parameters:: email (str) – Valid email address of user whose identity should be assumed.

errors_as_exceptions(preference=True)

Set preference on whether or not to raise exceptions on API errors. When preference is True, exceptions will be raised. When False, instances of the Error data type will be returned.

The property raise_exceptions defaults to False. Therefore, this method should only be called if exceptions should be raised.

Parameters:: preference (bool) – Flag indicating whether errors should be raised as exceptions.

models = <module 'smartsheet.models' from '/home/runner/work/smartsheet-python-sdk/smartsheet-python-sdk/smartsheet/models/__init__.py'>

prepare_request(_op): Generate a Requests prepared request object.

request(prepped_request, expected, operation)

Make a request from the Smartsheet API.

Make a request from the Smartsheet API and validate that inputs and outputs are as expected. The API response is converted from raw wire messages to a native objects based on the value of expected.

Parameters:

prepped_request (Request) – Prepared request for the operation.
expected (list|str) – The expected response data type.
operation (dict) – Dictionary containing operation details

Returns:

The API operation result object.

request_with_retry(prepped_request, operation)

Perform the request with retry.

Parameters:

prepped_request (Request) – A prepared request object for the operation.
operation (dict) – Dictionary containing operation details

Returns:

Operation Result object.

with_change_agent(change_agent)

Request headers will contain the ‘Smartsheet-Change-Agent’ header value

Agrs:: change_agent: (str) the name of this change agent

smartsheet.smartsheet.fresh_operation(op_id): Create a default operation object.

smartsheet.templates module

class smartsheet.templates.Templates(smartsheet_obj)

Bases: object

Class for handling Templates operations.

list_public_templates(page_size=None, page=None, include_all=None)

Get the list of public Templates to which the User has access.

Parameters:

page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

list_user_created_templates(page_size=None, page=None, include_all=None)

Get the list of user-created Templates to which the user has access.

Parameters:

page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

smartsheet.token module

class smartsheet.token.Token(smartsheet_obj)

Bases: object

Class for handling Token operations.

get_access_token(client_id, code, _hash, redirect_uri=None)

Get an access token, as part of the OAuth process. For more information, see [OAuth Flow](http://smartsheet-platform.github.io/api-docs/index.html#oauth-flow)

Parameters:

client_id (str)
code (str)
_hash (str) – SHA-256 hash of your app_secret concatenated with a pipe and the authorization code.
redirect_uri (str) – Redirect URL registered for your app, including protocol (e.g. “http://”); if not provided, the redirect URL set during registration is used.

Returns:

AccessToken

refresh_access_token(client_id, refresh_token, _hash, redirect_uri=None)

Refresh an access token, as part of the OAuth process. For more information, see [OAuth Flow](http://smartsheet-platform.github.io/api-docs/index.html#oauth-flow)

Parameters:

client_id (str)
refresh_token (str)
_hash (str) – SHA-256 hash of your app_secret concatenated with a pipe and the refresh token value.
redirect_uri (str) – Redirect URL registered for your app, including protocol (e.g. “http://”); if not provided, the redirect URL set during registration is used.

Returns:

AccessToken

revoke_access_token()

Revoke the access token used to make the request.

Revoke the access token used to make the request. The access token will no longer be valid, and subsequent API calls using the token will fail. :returns: Result

smartsheet.types module

class smartsheet.types.Boolean(initial_value=None)

Bases: object

property value

class smartsheet.types.EnumeratedList(enum)

Bases: TypedList

load(value)

class smartsheet.types.EnumeratedValue(enum, value=None)

Bases: object

set(value)

property value

class smartsheet.types.Number(initial_value=None)

Bases: object

property value

class smartsheet.types.String(initial_value=None, accept=None)

Bases: object

property accept

property value

class smartsheet.types.Timestamp(initial_value=None)

Bases: object

property value

class smartsheet.types.TypedList(item_type)

Bases: MutableSequence

convert(item): Convert the input item to the desired object type.

insert(idx, value): S.insert(index, value) – insert value before index

load(value)

purge(): Zero out the underlying list object.

to_list()

class smartsheet.types.TypedObject(object_type)

Bases: object

property value

smartsheet.users module

class smartsheet.users.Users(smartsheet_obj)

Bases: object

Class for handling Users operations.

add_alternate_email(user_id, list_of_alternate_emails)

Add one or more alternate email addresses for the specified User

Parameters:

user_id (int) – User ID
list_of_alternate_emails (list[AlternateEmail]) – An array of one or more AlternateEmail objects.

Returns:

Result

add_profile_image(user_id, file, file_type)

Uploads a profile image for the specified user.

Parameters:

user_id (int) – user ID
file (string) – path to image file.
file_type (string) – content type of image file

Returns:

Result

add_user(user_obj, send_email=None)

Add a User to the organization.

Parameters:

user_obj (User) –
User object with the following attributes:

email (required)

admin (required)

licensedSheetCreator (required)

firstName (optional)

lastName (optional)

resourceViewer (optional)
send_email (bool) – Either true or false to indicate
false. (whether or not to notify the user by email. Default is)

Returns:

Result

delete_alternate_email(user_id, alternate_email_id)

Deletes the specified alternate email address for the specified User.

Parameters:

user_id (int) – User ID
alternate_email_id (int) – Alternate Email ID

Returns:

Result

get_alternate_email(user_id, alternate_email_id)

Get the specified Alternate Email

Parameters:

user_id (int) – User ID
alternate_email_id (int) – Alternate Email ID

Returns:

AlternateEmail

get_current_user(include=None): Get the currently authenticated User. :returns: UserProfile

get_user(user_id)

Get the specified User.

Parameters:: user_id (int) – User ID
Returns:: UserProfile

list_alternate_emails(user_id)

Get a list of the Alternate Emails for the specified User.

Parameters:: user_id (int) – User ID
Returns:: IndexResult

list_org_sheets(page_size=None, page=None, include_all=None, modified_since=None)

Get a list of all Sheets owned by an organization.

Get the list of all Sheets owned by the members of the account (organization).

Parameters:

page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).
modified_since (datetime) – list organization sheets modified since datetime

Returns:

IndexResult

list_users(email=None, page_size=None, page=None, include_all=None, include=None)

Get the list of Users in the organization.

Parameters:

email (list[str]) – Comma separated list of email addresses on which to filter the results.
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).
include (list[str]) – optional include parameter, only current accepted value is ‘lastLogin’

Returns:

IndexResult

promote_alternate_email(user_id, alt_id)

Promote an email address to primary

Parameters:

user_id (int) – User ID
alt_id (int) – AlternateEmail ID to be promoted

Returns:

Result

remove_user(user_id, transfer_to=None, transfer_sheets=False, remove_from_sharing=False)

Remove a user from an organization.

Remove a User from an organization. User is transitioned to a free collaborator with read-only access to owned sheets, unless those are optionally transferred to another User.

Parameters:

user_id (int) – User ID
transfer_to (int) – The ID of the User to transfer ownership to. If the User being removed owns groups, this value is required. Any groups owned by the User being removed will be transferred to the specified User. If the User owns sheets, _and_ transferSheets is true, the removed User’s sheets will be transferred to the specified User.
transfer_sheets (bool) – If true and transferTo is specified, the removed User’s sheets will be transferred. Otherwise, sheets will not be transferred. Defaults to false.
remove_from_sharing (bool) – Set to true to remove the user from sharing for all sheets/workspaces in the organization. If not specified, User will not be removed from sharing.

Returns:

Result

update_user(user_id, user_obj)

Update the specified User.

Parameters:

user_id (int) – User ID
user_obj (User) – User object with the following attributes:

Returns:

Result

smartsheet.util module

smartsheet.util.coerce_to_bytes(data)

smartsheet.util.deprecated(func): This is a decorator which can be used to mark functions as deprecated. It will result in a warning being emitted when the function is used.

smartsheet.util.deserialize(obj, props)

smartsheet.util.dump_message_headers(request)

smartsheet.util.format_header(name, value)

smartsheet.util.get_child_properties(obj)

smartsheet.util.is_multipart(request)

smartsheet.util.prep(prop, op_id=None, method=None): Serialize a value for JSON transformation.

smartsheet.util.serialize(obj)

smartsheet.webhooks module

class smartsheet.webhooks.Webhooks(smartsheet_obj)

Bases: object

Class for handling Webhooks operations.

create_webhook(webhook_obj)

Creates the specified Webhook.

Parameters:: webhook_obj (Webhook) – Webhook object.
Returns:: Result

delete_webhook(webhook_id)

Delete the specified Webhook.

Parameters:: webhook_id (int) – Webhook ID
Returns:: Result

get_webhook(webhook_id)

Get the specified Webhook.

Parameters:: webhook_id (int) – Webhook ID
Returns:: Webhook

list_webhooks(page_size=None, page=None, include_all=None)

Get the list of all Webhooks the User has access to, in alphabetical order, by name.

Parameters:

page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

reset_shared_secret(webhook_id)

Resets the shared secret for the specified Webhook.

Parameters:: webhook_id (int) – Webhook ID
Returns:: Webhook

update_webhook(webhook_id, webhook_obj)

Updates the specified Webhook.

Parameters:

webhook_id (int) – Webhook ID
webhook_obj (Webhook) – Webhook object.

Returns:

Result

smartsheet.workspaces module

class smartsheet.workspaces.Workspaces(smartsheet_obj)

Bases: object

Class for handling Workspaces operations.

copy_workspace(workspace_id, container_destination_obj, include=None, skip_remap=None)

Create a copy of the specified Workspace.

Parameters:

workspace_id (int) – Workspace ID
container_destination_obj (ContainerDestination) – Container Destination object.
include (list[str]) – A comma-separated list of optional elements to copy. Valid list values: attachments, cellLinks, data, discussions, filters, forms, ruleRecipients, rules, shares, all (deprecated). Cell history will not be copied, regardless of which include parameter values are specified.
skip_remap (list[str]) – A comma separated list of references to NOT re-map for the newly created resource. Valid list items: cellLinks, reports, sheetHyperlinks, sights

Returns:

Result

create_folder_in_workspace(workspace_id, folder_obj)

Creates a Folder in the specified Workspace

Parameters:

workspace_id (int) – Workspace ID
folder_obj (Folder) – Folder object.

Returns:

Result

create_sheet_in_workspace(workspace_id, sheet_obj)

Create a Sheet from scratch at the top-level of the specified Workspace.

Parameters:

workspace_id (int) – Workspace ID
sheet_obj (Sheet) – Sheet object.

Returns:

Result

create_sheet_in_workspace_from_template(workspace_id, sheet_obj, include=None)

Create a Sheet in the specified Workspace from the specified Template.

The Sheet object should be limited to the following attributes:

name (required): need not be unique. fromId (required): the ID of the Template to use in creating the Sheet.

The optional Include parameter is a list of elements to copy from the Template. It may include: data, attachments, discussions, cellLinks, forms

Parameters:

workspace_id (int) – Workspace ID
sheet_obj (Sheet) – Sheet object.
include (list[str]) – A list of optional elements to include from the source Template. Valid list values: data, attachments, discussions, cellLinks, forms.

Returns:

Result

create_workspace(workspace_obj)

Create a Workspace.

Parameters:: workspace_obj (Workspace) – A Workspace object.
Returns:: Result

delete_share(workspace_id, share_id)

Delete the Share specified.

Parameters:

workspace_id (int) – Workspace ID
share_id (str) – Share ID

Returns:

Result

delete_workspace(workspace_id)

Delete the specified Workspace and its contents.

Parameters:: workspace_id (int) – Workspace ID
Returns:: Result

get_share(workspace_id, share_id)

Get the specified Share.

Parameters:

workspace_id (int) – Workspace ID
share_id (str) – Share ID

Returns:

Share

get_workspace(workspace_id, load_all=False, include=None)

Get the specified Workspace and list its contents.

Get the specified Workspace and list its contents. By default, this operation only returns top-level items in the Workspace. To load all of the contents, including nested Folders, include the loadAll parameter with a value of true.

Parameters:

workspace_id (int) – Workspace ID
load_all (bool) – Load all contents, including nested items.
include (list[str]) – A comma-separated list of optional elements to include in the response. Valid list values: ownerInfo, sheetVersion, source.

Returns:

Workspace

import_csv_sheet(workspace_id, file, sheet_name=None, header_row_index=None, primary_column_index=None)

Imports a sheet in the specified workspace.

Parameters:

workspace_id (int) – workspace ID
file (string) – path to CSV file.
sheet_name (string) – destination sheet name
header_row_index (int) – index (0 based) of row to be used for column names
primary_column_index (int) – index (0 based) of primary column

Returns:

Result

import_xlsx_sheet(workspace_id, file, sheet_name=None, header_row_index=None, primary_column_index=None)

Imports a sheet in the specified workspace.

Parameters:

workspace_id (int) – workspace ID
file (string) – path to XLSX file.
sheet_name (string) – destination sheet name
header_row_index (int) – index (0 based) of row to be used for column names
primary_column_index (int) – index (0 based) of primary column

Returns:

Result

list_folders(workspace_id, page_size=None, page=None, include_all=None)

Get a list of top-level child Folders within the specified Workspace.

Parameters:

workspace_id (int) – Workspace ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

list_shares(workspace_id, page_size=None, page=None, include_all=None)

Get a list of all Users and Groups to whom the specified Workspace is shared, and their access level.

Parameters:

workspace_id (int) – Workspace ID
page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

list_workspaces(page_size=None, page=None, include_all=None)

Get the list of Workspaces the authenticated User may access.

Parameters:

page_size (int) – The maximum number of items to return per page.
page (int) – Which page to return.
include_all (bool) – If true, include all results (i.e. do not paginate).

Returns:

IndexResult

share_workspace(workspace_id, share_obj, send_email=False)

Share a Workspace with the specified Users and Groups.

Parameters:

workspace_id (int) – Workspace ID
share_obj (Share) – Share object.
send_email (bool) – Either true or false to indicate whether or not to notify the user by email. Default is false.

Returns:

Result

update_share(workspace_id, share_id, share_obj)

Update the access level of a User or Group for the specified Workspace.

Parameters:

workspace_id (int) – Workspace ID
share_id (str) – Share ID
share_obj (Share) – Share object.

Returns:

Result

update_workspace(workspace_id, workspace_obj)

Update the specified Workspace.

Parameters:

workspace_id (int) – Workspace ID
workspace_obj (Workspace) – A Workspace object.

Returns:

Result

smartsheet package

Subpackages

Submodules

smartsheet.attachments module

smartsheet.cells module

smartsheet.contacts module

smartsheet.discussions module

smartsheet.events module

smartsheet.exceptions module

smartsheet.favorites module

smartsheet.folders module

smartsheet.groups module

smartsheet.home module

smartsheet.images module

smartsheet.object_value module

smartsheet.passthrough module

smartsheet.reports module

smartsheet.search module

smartsheet.server module

smartsheet.session module

smartsheet.sheets module

smartsheet.sights module

smartsheet.smartsheet module

smartsheet.templates module

smartsheet.token module

smartsheet.types module

smartsheet.users module

smartsheet.util module

smartsheet.webhooks module

smartsheet.workspaces module

Module contents