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).

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, 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.
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: smartsheet.exceptions.SmartsheetException

Errors produced by the Smartsheet API.

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

Bases: smartsheet.exceptions.SmartsheetException

Errors produced at the HTTP layer.

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

Bases: smartsheet.exceptions.HttpError

Errors due to a problem on Smartsheet.

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

Bases: smartsheet.exceptions.ApiError

Rate limit exceeded.

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

Bases: smartsheet.exceptions.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: smartsheet.exceptions.ApiError

Smartsheet.com is currently offline for system maintenance. …

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

Bases: smartsheet.exceptions.ApiError

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

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

Bases: smartsheet.exceptions.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.

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 – 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.

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 – 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.

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.
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: arguments for get_sheet() (See) –

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

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.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 'D:\\Smartsheet\\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.

class smartsheet.smartsheet.AbstractUserCalcBackoff¶

Bases: object

calc_backoff(previous_attempts, total_elapsed_time, error_result)¶

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: smartsheet.types.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: collections.abc.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 whether or not to notify the user by email. Default
false. (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.version module¶

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.version module¶

smartsheet.webhooks module¶

smartsheet.workspaces module¶

Module contents¶