smartsheet package

Subpackages

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) → Result[Attachment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Attachment], Error]

attach_file_to_row(sheet_id, row_id, _file) → Result[Attachment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Attachment], Error]

attach_file_to_sheet(sheet_id, _file) → Result[Attachment] | Error

Attach a file to the specified Sheet.

Parameters:

  • sheet_id (int) – Sheet ID

  • _file (file) – String or file stream object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Attachment], Error]

attach_new_version(sheet_id, attachment_id, _file) → Result[Attachment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Attachment], Error]

attach_url_to_comment(sheet_id, comment_id, attachment_obj) → Result[Attachment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Attachment], Error]

attach_url_to_row(sheet_id, row_id, attachment_obj) → Result[Attachment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Attachment], Error]

attach_url_to_sheet(sheet_id, attachment_obj) → Result[Attachment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Attachment], Error]

delete_attachment(sheet_id, attachment_id) → Result[None] | Error

Delete the specified Attachment.

Parameters:

  • sheet_id (int) – Sheet ID

  • attachment_id (int) – Attachment ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

delete_attachment_versions(sheet_id, attachment_id) → Result[None] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

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) → Attachment | Error

Fetch the specified Attachment.

Parameters:

  • sheet_id (int) – Sheet ID

  • attachment_id (int) – Attachment ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Attachment, Error]

list_all_attachments(sheet_id, page_size=None, page=None, include_all=None) → IndexResult[Attachment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Attachment], Error]

list_attachment_versions(sheet_id, attachment_id, page_size=None, page=None, include_all=None) → IndexResult[Attachment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Attachment], Error]

list_discussion_attachments(sheet_id, discussion_id, page_size=None, page=None, include_all=None) → IndexResult[Attachment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Attachment], Error]

list_row_attachments(sheet_id, row_id, page_size=None, page=None, include_all=None) → IndexResult[Attachment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Attachment], Error]

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) → Result[Row] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Row], Error]

get_cell_history(sheet_id, row_id, column_id, include=None, page_size=None, page=None, include_all=None, level=None) → IndexResult[CellHistory] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[CellHistory], Error]

smartsheet.contacts module

class smartsheet.contacts.Contacts(smartsheet_obj)

Bases: object

Class for handling Contacts operations.

get_contact(contact_id) → Contact | Error

Get the specified Contact.

Parameters:

contact_id (str) – Contact ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Contact, Error]

list_contacts(page_size=None, page=None, include_all=None) → IndexResult[Contact] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Contact], Error]

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) → Result[Comment] | Error

Add a Comment to the specified Discussion

Parameters:

  • sheet_id (int) – Sheet ID

  • discussion_id (int) – Discussion ID

  • comment_obj (Comment) – Comment object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Comment], Error]

add_comment_to_discussion_with_attachment(sheet_id, discussion_id, comment, _file=None) → Result[Comment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Comment], Error]

create_discussion_on_row(sheet_id, row_id, discussion_obj=None) → Result[Discussion] | Error

Create a new Discussion on a Row.

Parameters:

  • sheet_id (int) – Sheet ID

  • row_id (int) – Row ID

  • discussion_obj (Discussion) – Discussion object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Discussion], Error]

create_discussion_on_row_with_attachment(sheet_id, row_id, discussion, _file=None) → Result[Discussion] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Discussion], Error]

create_discussion_on_sheet(sheet_id, discussion_obj=None) → Result[Discussion] | Error

Create a new Discussion on a Sheet.

Parameters:

  • sheet_id (int) – Sheet ID

  • discussion_obj (Discussion) – Discussion object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Discussion], Error]

create_discussion_on_sheet_with_attachment(sheet_id, discussion, _file=None) → Result[Discussion] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Discussion], Error]

delete_discussion(sheet_id, discussion_id) → Result[None] | Error

Delete the specified Discussion.

Parameters:

  • sheet_id (int) – Sheet ID

  • discussion_id (int) – Discussion ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

delete_discussion_comment(sheet_id, comment_id) → Result[None] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

get_all_discussions(sheet_id, include=None, page_size=None, page=None, include_all=None) → IndexResult[Discussion] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Discussion], Error]

get_discussion(sheet_id, discussion_id) → Discussion | Error

Get the specified Discussion.

Parameters:

  • sheet_id (int) – Sheet ID

  • discussion_id (int) – Discussion ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Discussion, Error]

get_discussion_comment(sheet_id, comment_id) → Comment | Error

Get the specified Comment.

Parameters:

  • sheet_id (int) – Sheet ID

  • comment_id (int) – Comment ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Comment, Error]

get_row_discussions(sheet_id, row_id, include=None, page_size=None, page=None, include_all=None) → IndexResult[Discussion] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Discussion], Error]

update_comment(sheet_id, comment_id, comment_obj) → Result[Comment] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Comment], Error]

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) → EventResult[Event] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[EventResult[Event], Error]

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) → Result[Favorite | List[Favorite]] | Error

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:

The result of the operation - either a list or a single object, or an Error object if the request fails.

Return type:

Union[Result[Union[Favorite, List[Favorite]]], Error]

list_favorites(page_size=None, page=None, include_all=None) → IndexResult[Favorite] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Favorite], Error]

remove_favorites(favorite_type, object_ids) → Result[None] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

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) → Result[Folder] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Folder], Error]

create_folder_in_folder(folder_id, folder_obj) → Result[Folder] | Error

Create a Folder in the specified Folder

Parameters:

  • folder_id (int) – Folder ID

  • folder_obj (Folder) – Folder object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Folder], Error]

create_sheet_in_folder(folder_id, sheet_obj) → Result[Sheet] | Error

Create a Sheet from scratch in the specified Folder.

Parameters:

  • folder_id (int) – Folder ID

  • sheet_obj (Sheet) – Sheet object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

create_sheet_in_folder_from_template(folder_id, sheet_obj, include=None) → Result[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

delete_folder(folder_id) → Result[None] | Error

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

Parameters:

folder_id (int) – Folder ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

get_folder(folder_id, include=None) → Folder | Error

Get the specified Folder (and list its contents).

Deprecated: 3.1.0

Use get_folder_metadata and get_folder_children instead.

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Folder, Error]

get_folder_children(folder_id, children_resource_types=None, include=None, last_key=None, max_items=None) → PaginatedChildrenResult | Error

Get the children of a folder.

Parameters:

  • folder_id (int) – Folder ID

  • children_resource_types (list[str]) – The types of the children resources. If not provided, returns children of all types. Valid list values: sheets, reports, sights, folders.

  • include (list[str]) – A list of optional elements to include in the response. Valid list values: source, ownerInfo.

  • last_key (str) – The token from a previous request that will allow this one to fetch the next page of results.

  • max_items (int) – The maximum number of items to return in the response.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[PaginatedChildrenResult, Error]

get_folder_metadata(folder_id, include=None) → Folder | Error

Get the metadata of a folder.

Parameters:

  • folder_id (int) – Folder ID

  • include (list[str]) – A list of optional elements to include

  • values (in the response. Valid list) – source.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Folder, Error]

import_csv_sheet(folder_id, file, sheet_name=None, header_row_index=None, primary_column_index=None) → Result[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

import_xlsx_sheet(folder_id, file, sheet_name=None, header_row_index=None, primary_column_index=None) → Result[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

list_folders(folder_id, page_size=None, page=None, include_all=None) → IndexResult[Folder] | Error

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

Deprecated: 3.1.0

Use get_folder_children with children_resource_types=[‘folders’] instead.

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Folder], Error]

move_folder(folder_id, container_destination_obj) → Result[Folder] | Error

Moves the specified Folder to another location.

Parameters:

  • folder_id (int) – Folder ID

  • container_destination_obj – (ContainerDestination): Container Destination object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Folder], Error]

update_folder(folder_id, folder_obj) → Result[Folder] | Error

Update the specified Folder.

Parameters:

  • folder_id (int) – Folder ID

  • folder_obj (Folder) – Folder object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Folder], Error]

smartsheet.groups module

class smartsheet.groups.Groups(smartsheet_obj)

Bases: object

Class for handling Groups operations.

add_members(group_id, group_member_obj) → Result[GroupMember | List[GroupMember]] | Error

Add one or more members to a Group.

Parameters:

  • group_id (int) – Group ID

  • group_member_obj (GroupMember) – Group member object(s).

Returns:

The result of the operation - either a list or a single object, or an Error object if the request fails.

Return type:

Union[Result[Union[GroupMember, List[GroupMember]]], Error]

create_group(group_obj) → Result[Group] | Error

Create a new Group

Parameters:

group_obj (Group) – Group object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Group], Error]

delete_group(group_id) → Result[None] | Error

Delete the specified Group.

Parameters:

group_id (int) – Group ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

get_group(group_id) → Group | Error

Get the specified Group.

Parameters:

group_id (int) – Group ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Group, Error]

list_groups(page_size=None, page=None, include_all=None) → IndexResult[Group] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Group], Error]

remove_member(group_id, user_id) → Result[None] | Error

Removes a member from the specified Group.

Parameters:

  • group_id (int) – Group ID

  • user_id (int) – User ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

update_group(group_id, group_obj) → Result[Group] | Error

Updates the specified Group.

Parameters:

  • group_id (int) – Group ID

  • group_obj (Group) – Group object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Group], Error]

smartsheet.home module

class smartsheet.home.Home(smartsheet_obj)

Bases: object

Class for handling Home operations.

create_folder(folder_obj) → Result[Folder] | Error

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

Parameters:

folder_obj (Folder) – Folder object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Folder], Error]

create_sheet(sheet_obj) → Result[Sheet] | Error

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

Parameters:

sheet_obj (Sheet) – Sheet object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

create_sheet_from_template(sheet_obj, include=None) → Result[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

list_all_contents(include=None, exclude=None) → Home | Error

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) → IndexResult[Folder] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Folder], Error]

smartsheet.images module

class smartsheet.images.Images(smartsheet_obj)

Bases: object

Class for handling Images operations.

get_image_urls(list_of_images) → ImageUrlMap | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[ImageUrlMap, Error]

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) → JSONObject | Error

Issue a DELETE request on the specified URL.

Parameters:

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

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[JSONObject, Error]

get(endpoint, query_params=None) → JSONObject | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[JSONObject, Error]

post(endpoint, payload, query_params=None) → JSONObject | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[JSONObject, Error]

put(endpoint, payload, query_params=None) → JSONObject | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[JSONObject, Error]

smartsheet.reports module

class smartsheet.reports.Reports(smartsheet_obj)

Bases: object

Class for handling Reports operations.

delete_share(report_id, share_id) → Result[None] | Error

Deletes the specified Share

Parameters:

  • report_id (int) – Report ID

  • share_id (str) – Share ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

get_publish_status(report_id) → ReportPublish | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[ReportPublish, Error]

get_report(report_id, page_size=None, page=None, include=None, level=None) → Report | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Report, Error]

get_report_as_csv(report_id, download_path, alternate_file_name=None) → DownloadedFile | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[DownloadedFile, Error]

get_report_as_excel(report_id, download_path, alternate_file_name=None) → DownloadedFile | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[DownloadedFile, Error]

get_share(report_id, share_id) → Share | Error

Get the specified Share.

Parameters:

  • report_id (int) – Report ID

  • share_id (str) – Share ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Share, Error]

list_reports(page_size=None, page=None, include_all=None, modified_since=None) → IndexResult[Report] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Report], Error]

list_shares(report_id, page_size=None, page=None, include_all=None, include_workspace_shares=False) → IndexResult[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Share], Error]

send_report(report_id, sheet_email_obj) → Result[None] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

set_publish_status(report_id, report_publish_obj) → Result[ReportPublish] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[ReportPublish], Error]

share_report(report_id, share_obj, send_email=False) → Result[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Share], Error]

update_share(report_id, share_id, share_obj) → Result[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Share], Error]

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) → SearchResult | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[SearchResult, Error]

search_sheet(sheet_id, query) → SearchResult | Error

Search the specified Sheet for the specified text.

Parameters:

  • sheet_id (int) – Sheet ID

  • query (str) – Text with which to perform the search.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[SearchResult, Error]

smartsheet.server module

class smartsheet.server.Server(smartsheet_obj)

Bases: object

Class for handling Server operations.

server_info() → ServerInfo | Error

Get application constants. :returns: The result of the operation, or an Error object if the request fails. :rtype: Union[ServerInfo, Error]

smartsheet.session module

smartsheet.session.pinned_session(pool_maxsize=8)
smartsheet.session.redact_token(res, *args, **kwargs)

smartsheet.sharing module

class smartsheet.sharing.Sharing(smartsheet_obj)

Bases: object

Class for handling Sharing operations.

delete_asset_share(asset_type, asset_id, share_id) → Result[None] | Error

Delete the specified Share.

Parameters:

  • asset_type (AssetType) – Type of asset (sheet, report, sight, workspace, etc.)

  • asset_id (int) – Asset ID

  • share_id (str) – Share ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

get_asset_share(asset_type, asset_id, share_id) → AssetShare | Error

Get a specific share for the specified asset.

Parameters:

  • asset_type (AssetType) – Type of asset (sheet, report, sight, workspace, etc.)

  • asset_id (int) – Asset ID

  • share_id (str) – Share ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[AssetShare, Error]

list_asset_shares(asset_type, asset_id, max_items=None, last_key=None, sharing_include: ShareScope = None) → AssetSharesPaginatedResult[AssetShare] | Error

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

Parameters:

  • asset_type (AssetType) – Type of asset (sheet, report, sight, workspace, etc.)

  • asset_id (int) – Asset ID

  • max_items (int) – The maximum number of items to return in the response.

  • last_key (str) – The token from a previous request that will allow this one to pick up where the previous one left off.

  • sharing_include (ShareScope) – Scope of share to include in response

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[AssetSharesPaginatedResult[AssetShare], Error]

share_asset(share_obj, asset_type, asset_id, send_email=None) → Result[AssetShare] | Error

Share an asset with the specified Users and Groups.

Parameters:

  • share_obj (Share or list[Share]) – Share object or list of Share objects.

  • asset_type (AssetType) – Type of asset (sheet, report, sight, workspace, etc.)

  • asset_id (int) – Asset ID

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

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[AssetShare], Error]

update_asset_share(share_obj, asset_type, asset_id, share_id) → AssetShare | Error

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

Parameters:

  • share_obj (Share) – Share object.

  • asset_type (AssetType) – Type of asset (sheet, report, sight, workspace, etc.)

  • asset_id (int) – Asset ID

  • share_id (str) – Share ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[AssetShare, Error]

smartsheet.sheets module

class smartsheet.sheets.Sheets(smartsheet_obj)

Bases: object

Class for handling Sheets operations.

add_columns(sheet_id, list_of_columns) → Result[Column | List[Column]] | Error

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:

The result of the operation - either a list or a single object, or an Error object if the request fails.

Return type:

Union[Result[Union[Column, List[Column]]], Error]

add_rows(sheet_id, list_of_rows) → Result[Row | List[Row]] | Error

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:

The result of the operation - either a list or a single object, or an Error object if the request fails.

Return type:

Union[Result[Union[Row, List[Row]]], Error]

add_rows_with_partial_success(sheet_id, list_of_rows) → BulkItemResult[Row] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[BulkItemResult[Row], Error]

add_sheet_summary_field_image(sheet_id, field_id, file, file_type, alt_text=None) → Result[SummaryField] | Error
add_sheet_summary_fields(sheet_id, list_of_fields, rename_if_conflict=None) → Result[SummaryField] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[SummaryField], Error]

add_sheet_summary_fields_with_partial_success(sheet_id, list_of_fields, rename_if_conflict=None) → BulkItemResult[SummaryField] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[BulkItemResult[SummaryField], Error]

copy_rows(sheet_id, copy_or_move_row_directive_obj, include=None, ignore_rows_not_found=None) → CopyOrMoveRowResult | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[CopyOrMoveRowResult, Error]

copy_sheet(sheet_id, container_destination_obj, include=None, exclude=None) → Result[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

create_cross_sheet_reference(sheet_id, cross_sheet_reference_obj) → Result[CrossSheetReference] | Error

Creates a CrossSheetReference for the specified Sheet.

Parameters:

  • sheet_id (int) – Sheet ID

  • cross_sheet_reference_obj (CrossSheetReference) – CrossSheetReference object

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[CrossSheetReference], Error]

create_update_request(sheet_id, update_request_obj) → Result[UpdateRequest] | Error

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

Parameters:

  • sheet_id (int) – Sheet ID

  • update_request_obj (UpdateRequest) – UpdateRequest object

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[UpdateRequest], Error]

delete_automation_rule(sheet_id, automation_rule_id) → Result[None] | Error

Deletes an AutomationRule for the specified Sheet.

Parameters:

  • sheet_id (int) – Sheet ID

  • automation_rule_id (int) – AutomationRule ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

delete_column(sheet_id, column_id) → Result[None] | Error

Delete the specified Column.

Parameters:

  • sheet_id (int) – Sheet ID

  • column_id (int) – Column ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

delete_filter(sheet_id, filter_id) → Result[None] | Error

Deletes a Filter for the specified Sheet.

Parameters:

  • sheet_id (int) – Sheet ID

  • filter_id (int) – Filter ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

delete_rows(sheet_id, ids, ignore_rows_not_found=False) → Result[List[NumberObjectValue]] | Error

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:

The result of the operation - a list of deleted object IDs, or an Error object if the request fails.

Return type:

Union[Result[List[NumberObjectValue]], Error]

delete_sent_update_request(sheet_id, sent_update_request_id) → Result[None] | Error

Deletes a SentUpdateRequest for the specified Sheet.

Parameters:

  • sheet_id (int) – Sheet ID

  • sent_update_request_id (int) – SentUpdateRequest ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

delete_share(sheet_id, share_id) → Result[None] | Error

Delete the specified Share.

Parameters:

  • sheet_id (int) – Sheet ID

  • share_id (str) – Share ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

Deprecated:

Use sharing.delete_share instead with assetType=AssetType.SHEET

delete_sheet(sheet_id) → Result[None] | Error

Delete the specified Sheet.

Parameters:

sheet_id (int) – Sheet ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

delete_sheet_summary_fields(sheet_id, list_of_ids, ignore_summary_fields_not_found=None) → Result[NumberObjectValue] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[NumberObjectValue], Error]

delete_update_request(sheet_id, update_request_id) → Result[None] | Error

Deletes an UpdateRequest for the specified Sheet.

Parameters:

  • sheet_id (int) – Sheet ID

  • update_request_id (int) – UpdateRequest ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

get_automation_rule(sheet_id, automation_rule_id) → AutomationRule | Error

Get the AutomationRule.

Parameters:

  • sheet_id (int) – Sheet ID

  • automation_rule_id (long) – AutomationRuleID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[AutomationRule, Error]

get_column(sheet_id, column_id, include=None) → Column | Error

Get the specified Column.

Parameters:

  • sheet_id (int) – Sheet ID

  • column_id (int) – Column ID

  • include (str) – (future)

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Column, Error]

get_column_by_title(sheet_id, title, include=None) → Column | bool

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) → IndexResult[Column] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Column], Error]

get_cross_sheet_reference(sheet_id, cross_sheet_reference_id) → CrossSheetReference | Error

Get the CrossSheetReference.

Parameters:

  • sheet_id (int) – Sheet ID

  • cross_sheet_reference_id (int) – CrossSheetReferenceID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[CrossSheetReference, Error]

get_filter(sheet_id, filter_id) → SheetFilter | Error

Get the Filter.

Parameters:

  • sheet_id (int) – Sheet ID

  • filter_id (int) – Filter ID

Returns:

The result of the operation, or an Error object if the request fails.Filter

Return type:

Union[Sheet, Error]

get_publish_status(sheet_id) → SheetPublish | Error

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:

The result of the operation, or an Error object if the request fails.Publish

Return type:

Union[Sheet, Error]

get_row(sheet_id, row_id, include=None, exclude=None, level=None) → Row | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Row, Error]

get_sent_update_request(sheet_id, sent_update_request_id) → SentUpdateRequest | Error

Get the SentUpdateRequest for Sheet.

Parameters:

  • sheet_id (int) – Sheet ID

  • sent_update_request_id (int) – SentUpdateRequest ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[SentUpdateRequest, Error]

get_share(sheet_id, share_id) → Share | Error

Get the specified Share.

Parameters:

  • sheet_id (int) – Sheet ID

  • share_id (str) – Share ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Share, Error]

Deprecated:

Use sharing.get_asset_share instead with assetType=AssetType.SHEET

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) → Sheet | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Sheet, Error]

get_sheet_as_csv(sheet_id, download_path, alternate_file_name=None) → DownloadedFile | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[DownloadedFile, Error]

get_sheet_as_excel(sheet_id, download_path, alternate_file_name=None) → DownloadedFile | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[DownloadedFile, Error]

get_sheet_as_pdf(sheet_id, download_path, paper_size=None, alternate_file_name=None) → DownloadedFile | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[DownloadedFile, Error]

get_sheet_by_name(name, include=None, exclude=None, row_ids=None, row_numbers=None, column_ids=None, page_size=None, page=None) → Sheet | bool

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) → SheetSummary | Error

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:

The result of the operation, or an Error object if the request fails.Summary

Return type:

Union[Sheet, Error]

get_sheet_summary_fields(sheet_id, include=None, exclude=None, page_size=None, page=None, include_all=None) → IndexResult[SummaryField] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[SummaryField], Error]

get_sheet_version(sheet_id) → Version | Error

Get the Sheet version without loading the entire Sheet.

Parameters:

sheet_id (int) – Sheet ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Version, Error]

get_update_request(sheet_id, update_request_id) → UpdateRequest | Error

Get the UpdateRequest for Sheet that has a future schedule.

Parameters:

  • sheet_id (int) – Sheet ID

  • update_request_id (int) – UpdateRequest ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[UpdateRequest, Error]

import_csv_sheet(file, sheet_name=None, header_row_index=None, primary_column_index=None) → Result[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

import_xlsx_sheet(file, sheet_name=None, header_row_index=None, primary_column_index=None) → Result[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

list_automation_rules(sheet_id, page_size=None, page=None, include_all=None) → IndexResult[AutomationRule] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[AutomationRule], Error]

list_cross_sheet_references(sheet_id, page_size=None, page=None, include_all=None) → IndexResult[CrossSheetReference] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[CrossSheetReference], Error]

list_filters(sheet_id, page_size=None, page=None, include_all=None) → IndexResult[SheetFilter] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[SheetFilter], Error]

list_org_sheets() → IndexResult[Sheet] | Error

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: The result of the operation, or an Error object if the request fails. :rtype: Union[IndexResult[Sheet], Error]

list_sent_update_requests(sheet_id, page_size=None, page=None, include_all=None) → IndexResult[SentUpdateRequest] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[SentUpdateRequest], Error]

list_shares(sheet_id, page_size=None, page=None, include_all=None, include_workspace_shares=False, access_api_level=0) → IndexResult[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Share], Error]

list_sheets(include=None, page_size=None, page=None, include_all=None, modified_since=None) → IndexResult[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Sheet], Error]

list_update_requests(sheet_id, page_size=None, page=None, include_all=None) → IndexResult[UpdateRequest] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[UpdateRequest], Error]

move_rows(sheet_id, copy_or_move_row_directive_obj, include=None, ignore_rows_not_found=None) → CopyOrMoveRowResult | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[CopyOrMoveRowResult, Error]

move_sheet(sheet_id, container_destination_obj) → Result[Sheet] | Error

Move the specified Sheet to a new location.

Parameters:

  • sheet_id (int) – Sheet ID

  • container_destination_obj – (ContainerDestination): Container Destination object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

search_sheet(sheet_id, query) → SearchResult | Error

Search the specified Sheet for the specified text.

Parameters:

  • sheet_id (int) – Sheet ID

  • query (str) – Text with which to perform the search.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[SearchResult, Error]

send_rows(sheet_id, multi_row_email_obj) → Result[None] | Error

Send one or more rows via email

Parameters:

  • sheet_id (int) – Sheet ID

  • multi_row_email_obj (MultiRowEmail) – MultiRowEmail object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

send_sheet(sheet_id, sheet_email_obj) → Result[None] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

send_update_request(sheet_id, multi_row_email_obj) → Result[UpdateRequest] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[UpdateRequest], Error]

set_publish_status(sheet_id, sheet_publish_obj) → Result[SheetPublish] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[SheetPublish], Error]

share_sheet(sheet_id, share_obj, send_email=None) → Result[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Share], Error]

Deprecated:

Use sharing.share_asset instead with assetType=AssetType.SHEET

sort_sheet(sheet_id, sort_specifier_obj, level=None) → Sheet | Error

Sort Sheet according to SortSpecifier.

Parameters:

  • sheet_id (int) – Sheet ID

  • sort_specifier_obj (SortSpecifier) – SortSpecifier object

  • level (int) – compatibility level

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Sheet, Error]

update_automation_rule(sheet_id, automation_rule_id, automation_rule_obj) → Result[AutomationRule] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[AutomationRule], Error]

update_column(sheet_id, column_id, column_obj) → Result[Column] | Error

Update properties of the specified Column.

Parameters:

  • sheet_id (int) – Sheet ID

  • column_id (int) – Column ID

  • column_obj (Column) – A Column object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Column], Error]

update_rows(sheet_id, list_of_rows) → Result[Row] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Row], Error]

update_rows_with_partial_success(sheet_id, list_of_rows) → BulkItemResult[Row] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[BulkItemResult[Row], Error]

update_share(sheet_id, share_id, share_obj) → Result[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Share], Error]

Deprecated:

Use sharing.update_share instead with assetType=AssetType.SHEET

update_sheet(sheet_id, sheet_obj) → Result[Sheet] | Error

Updates the specified Sheet.

Parameters:

  • sheet_id (int) – Sheet ID

  • sheet_obj (Sheet) – Sheet object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

update_sheet_summary_fields(sheet_id, list_of_summary_fields, rename_if_conflict=None) → Result[SummaryField] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[SummaryField], Error]

update_sheet_summary_fields_with_partial_success(sheet_id, list_of_summary_fields, rename_if_conflict=None) → BulkItemResult[SummaryField] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[BulkItemResult[SummaryField], Error]

update_update_request(sheet_id, update_request_id, update_request_obj) → Result[UpdateRequest] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[UpdateRequest], Error]

smartsheet.sights module

class smartsheet.sights.Sights(smartsheet_obj)

Bases: object

Class for handling Sights operations.

copy_sight(sight_id, container_destination_obj) → Result[Sight] | Error

Creates a copy of the specified Sight

Parameters:

  • sight_id (int) – Sight ID

  • container_destination_obj – (ContainerDestination): Container Destination object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sight], Error]

delete_share(sight_id, share_id) → Result[None] | Error

Delete the specified Share.

Parameters:

  • sight_id (int) – Sight ID

  • share_id (str) – Share ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

delete_sight(sight_id) → Result[None] | Error

Delete the specified Sight.

Parameters:

sight_id (int) – Sight ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

get_publish_status(sight_id) → SightPublish | Error

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:

The result of the operation, or an Error object if the request fails.Publish

Return type:

Union[Sight, Error]

get_share(sight_id, share_id) → Share | Error

Get the specified Share.

Parameters:

  • sight_id (int) – Sight ID

  • share_id (str) – Share ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Share, Error]

get_sight(sight_id, level=None, include=None) → Sight | Error

Get the specified Sight.

Parameters:

  • sight_id (int) – Sight ID

  • level (int) – compatibility level

  • include (list[str]) – optional include parameters

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Sight, Error]

list_shares(sight_id, page_size=None, page=None, include_all=None, include_workspace_shares=False) → IndexResult[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Share], Error]

list_sights(page_size=None, page=None, include_all=None, modified_since=None) → IndexResult[Sight] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Sight], Error]

move_sight(sight_id, container_destination_obj) → Result[Sight] | Error

Creates a copy of the specified Sight

Parameters:

  • sight_id (int) – Sight ID

  • container_destination_obj – (ContainerDestination): Container Destination object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sight], Error]

set_publish_status(sight_id, sight_publish_obj) → Result[SightPublish] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[SightPublish], Error]

share_sight(sight_id, share_obj, send_email=False) → Result[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Share], Error]

update_share(sight_id, share_id, share_obj) → Result[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Share], Error]

update_sight(sight_id, sight_obj) → Result[Sight] | Error

Updates the specified Sight.

Parameters:

  • sight_id (int) – Sight ID

  • sight_obj (Sight) – Sight object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sight], Error]

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.

Attachments: Attachments
Contacts: Contacts
Discussions: Discussions
Events: Events
Favorites: Favorites
Folders: Folders
Groups: Groups
Home: Home
Images: Images
Passthrough: Passthrough
Reports: Reports
Search: Search
Server: Server
Sharing: Sharing
Sheets: Sheets
Sights: Sights
Templates: Templates
Token: Token
Users: Users
Webhooks: Webhooks
Workspaces: Workspaces
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

with_wiremock_test_case(test_name: str, request_id: str)

Configure client with x-test-name and x-request-id headers. Used for wiremock test cases.

Parameters:

  • test_name (str) – The name of the wiremock test case.

  • request_id (str) – The unique request ID for this test scenario.

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) → IndexResult[Template] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Template], Error]

list_user_created_templates(page_size=None, page=None, include_all=None) → IndexResult[Template] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Template], Error]

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) → AccessToken | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[AccessToken, Error]

refresh_access_token(client_id, refresh_token, _hash, redirect_uri=None) → AccessToken | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[AccessToken, Error]

revoke_access_token() → Result[None] | Error

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: The result of the operation, or an Error object if the request fails. :rtype: Union[Result[None], Error]

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) → Result[AlternateEmail | List[AlternateEmail]] | Error

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:

The result of the operation - either a list or a single object, or an Error object if the request fails.

Return type:

Union[Result[List[AlternateEmail]], Error]

add_profile_image(user_id, file, file_type) → Result[User] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[User], Error]

add_user(user_obj, send_email=None) → Result[User] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[User], Error]

deactivate_user(user_id) → Result[None] | Error

Deactivate the user associated with the current Smartsheet plan.

Blocks the user from using Smartsheet in any way. Deactivating a user does not affect their existing permissions on owned or shared items. Optionally, with Enterprise Plan Manager (EPM) enabled, you can deactivate a user from child organizations.

Parameters:

user_id (int) – User ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

Raises:

ApiError – If the user cannot be deactivated. This occurs when: - The user’s primary email address belongs to an ISP domain (e.g., gmail.com, yahoo.com, outlook.com) - The user’s primary email address is unassociated with the current Smartsheet plan domain(s) - The user is managed by an external source, such as an identity provider (IdP) or directory integration (DI) provider (e.g., Okta, Azure AD). Such users can only be deactivated via the external source.

Note

Requires System Admin permissions. This operation is unavailable for Smartsheet Gov.

delete_alternate_email(user_id, alternate_email_id) → Result[None] | Error

Deletes the specified alternate email address for the specified User.

Parameters:

  • user_id (int) – User ID

  • alternate_email_id (int) – Alternate Email ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

downgrade_user(user_id, plan_id, seat_type) → Result[None] | Error

Downgrades a user for a plan.

Parameters:

  • user_id (int) – User ID

  • plan_id (int) – Plan ID

  • seat_type (DowngradeSeatType) – Seat type to downgrade to

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

get_alternate_email(user_id, alternate_email_id) → AlternateEmail | Error

Get the specified Alternate Email

Parameters:

  • user_id (int) – User ID

  • alternate_email_id (int) – Alternate Email ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[AlternateEmail, Error]

get_current_user(include=None) → UserProfile | Error

Get the currently authenticated User. :returns: The result of the operation, or an Error object if the request fails. :rtype: Union[UserProfile, Error]

get_user(user_id) → UserProfile | Error

Get the specified User.

Parameters:

user_id (int) – User ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[UserProfile, Error]

list_alternate_emails(user_id) → IndexResult[AlternateEmail] | Error

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

Parameters:

user_id (int) – User ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[AlternateEmail], Error]

list_org_sheets(page_size=None, page=None, include_all=None, modified_since=None) → IndexResult[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Sheet], Error]

list_user_plans(user_id, last_key=None, max_items=None) → TokenPaginatedResult[UserPlan] | Error

List user’s plans. :param user_id: User ID :type user_id: int

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[TokenPaginatedResult[UserPlan], Error]

list_users(email=None, page_size=None, page=None, include_all=None, include=None, plan_id=None, seat_type=None) → IndexResult[User] | Error

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’

  • plan_id (int) – optional plan_id parameter, returns users in the selected plan.

  • seat_type (SeatType) – optional seat_type parameter, filters users by their seat type.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[User], Error]

promote_alternate_email(user_id, alt_id) → Result[AlternateEmail] | Error

Promote an email address to primary

Parameters:

  • user_id (int) – User ID

  • alt_id (int) – AlternateEmail ID to be promoted

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[AlternateEmail], Error]

reactivate_user(user_id) → Result[None] | Error

Reactivate the user associated with the current Smartsheet plan.

Restores the user’s access to Smartsheet, owned items, and shared items.

Important: The user can only be reactivated if they have been deactivated for less than thirty (30) days.

Optionally, with Enterprise Plan Manager (EPM) enabled, you can specify the ID of a user within your managed plan hierarchy.

Parameters:

user_id (int) – User ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

Raises:

ApiError – If the user cannot be reactivated. This occurs when: - The user’s primary email address belongs to an ISP domain (e.g., gmail.com, yahoo.com, outlook.com) - The user’s primary email address is unassociated with the current Smartsheet plan domain(s) - The user is not in the plan’s organization - The user has been deactivated for more than 30 days

Note

Requires System Admin permissions. This operation is unavailable for Smartsheet Gov.

remove_user(user_id, transfer_to=None, transfer_sheets=False, remove_from_sharing=False) → Result[None] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

remove_user_from_plan(user_id, plan_id) → Result[None] | Error
Remove user from plan.
Args:

user_id (int): User ID plan_id (int): Plan ID

Returns:

Union[Result[None], Error]: The result of the operation, or an Error object if the request fails.

update_user(user_id, user_obj) → Result[User] | Error

Update the specified User.

Parameters:

  • user_id (int) – User ID

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

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[User], Error]

upgrade_user(user_id, plan_id, seat_type) → Result[None] | Error

Upgrades a user for a plan.

Parameters:

  • user_id (int) – User ID

  • plan_id (int) – Plan ID

  • seat_type (UpgradeSeatType) – Seat type to upgrade to

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

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.fresh_operation(op_id)

Create a default operation object.

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) → Result[Webhook] | Error

Creates the specified Webhook.

Parameters:

webhook_obj (Webhook) – Webhook object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Webhook], Error]

delete_webhook(webhook_id) → Result[None] | Error

Delete the specified Webhook.

Parameters:

webhook_id (int) – Webhook ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

get_webhook(webhook_id) → Webhook | Error

Get the specified Webhook.

Parameters:

webhook_id (int) – Webhook ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Webhook, Error]

list_webhooks(page_size=None, page=None, include_all=None) → IndexResult[Webhook] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Webhook], Error]

reset_shared_secret(webhook_id) → Result[WebhookSecret] | Error

Resets the shared secret for the specified Webhook.

Parameters:

webhook_id (int) – Webhook ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[WebhookSecret], Error]

update_webhook(webhook_id, webhook_obj) → Result[Webhook] | Error

Updates the specified Webhook.

Parameters:

  • webhook_id (int) – Webhook ID

  • webhook_obj (Webhook) – Webhook object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Webhook], Error]

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) → Result[Workspace] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Workspace], Error]

create_folder_in_workspace(workspace_id, folder_obj) → Result[Folder] | Error

Creates a Folder in the specified Workspace

Parameters:

  • workspace_id (int) – Workspace ID

  • folder_obj (Folder) – Folder object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Folder], Error]

create_sheet_in_workspace(workspace_id, sheet_obj) → Result[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

create_sheet_in_workspace_from_template(workspace_id, sheet_obj, include=None) → Result[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

create_workspace(workspace_obj) → Result[Workspace] | Error

Create a Workspace.

Parameters:

workspace_obj (Workspace) – A Workspace object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Workspace], Error]

delete_share(workspace_id, share_id) → Result[None] | Error

Delete the Share specified.

Parameters:

  • workspace_id (int) – Workspace ID

  • share_id (str) – Share ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

delete_workspace(workspace_id) → Result[None] | Error

Delete the specified Workspace and its contents.

Parameters:

workspace_id (int) – Workspace ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[None], Error]

get_share(workspace_id, share_id) → Share | Error

Get the specified Share.

Parameters:

  • workspace_id (int) – Workspace ID

  • share_id (str) – Share ID

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Share, Error]

get_workspace(workspace_id, load_all=False, include=None) → Workspace | Error

Get the specified Workspace and list its contents.

Deprecated: 3.1.0

Use get_workspace_metadata and get_workspace_children instead.

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Workspace, Error]

get_workspace_children(workspace_id, children_resource_types=None, include=None, last_key=None, max_items=None) → PaginatedChildrenResult | Error

Get children of a workspace.

Parameters:

  • workspace_id (int) – Workspace ID

  • children_resource_types (list[str]) – The types of the children resources. If not provided, returns children of all types. Valid list values: sheets, reports, sights, folders.

  • include (list[str]) – A list of optional elements to include in the response. Valid list values: source, ownerInfo.

  • last_key (str) – The token from a previous request that will allow this one to fetch the next page of results.

  • max_items (int) – The maximum number of items to return in the response.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[PaginatedChildrenResult, Error]

get_workspace_metadata(workspace_id, include=None) → Workspace | Error

Get metadata of a workspace.

Parameters:

  • workspace_id (int) – Workspace ID

  • include (list[str]) – A list of optional elements to include in the response. Valid list values: source

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Workspace, Error]

import_csv_sheet(workspace_id, file, sheet_name=None, header_row_index=None, primary_column_index=None) → Result[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

import_xlsx_sheet(workspace_id, file, sheet_name=None, header_row_index=None, primary_column_index=None) → Result[Sheet] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Sheet], Error]

list_folders(workspace_id, page_size=None, page=None, include_all=None) → IndexResult[Folder] | Error

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

Deprecated: 3.1.0

Use get_workspace_children with children_resource_types=[‘folders’] instead.

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Folder], Error]

list_shares(workspace_id, page_size=None, page=None, include_all=None) → IndexResult[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[IndexResult[Share], Error]

list_workspaces(page_size: int | None = None, page: int | None = None, include_all: bool | None = None, last_key: str | None = None, max_items: int | None = None, pagination_type: str | None = None) → IndexResult[Workspace] | Error

Get the list of Workspaces the authenticated User may access.

Parameters:

  • page_size (int, optional) – [DEPRECATED] The maximum number of items to return per page. Use pagination_type=’token’ with max_items instead.

  • page (int, optional) – [DEPRECATED] Which page to return. Use pagination_type=’token’ with last_key instead.

  • include_all (bool, optional) – [DEPRECATED] If true, include all results (i.e. do not paginate). Use pagination_type=’token’ instead.

  • last_key (str, optional) – Pagination cursor for next page (token pagination only).

  • max_items (int, optional) – Maximum items per page (token pagination only). Must be a positive integer.

  • pagination_type (str, optional) – Use ‘token’ for efficient cursor-based pagination. Defaults to legacy offset-based pagination if not specified.

Returns:

The result of the operation, or an Error object if the request fails.

When using legacy pagination, contains paginated results with total_count, total_pages, etc.

Return type:

Union[IndexResult[Workspace], Error]

Raises:

ValueError – If pagination_type is not ‘token’ or None, or if max_items <= 0 when using token pagination.

share_workspace(workspace_id, share_obj, send_email=False) → Result[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Share], Error]

update_share(workspace_id, share_id, share_obj) → Result[Share] | Error

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:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Share], Error]

update_workspace(workspace_id, workspace_obj) → Result[Workspace] | Error

Update the specified Workspace.

Parameters:

  • workspace_id (int) – Workspace ID

  • workspace_obj (Workspace) – A Workspace object.

Returns:

The result of the operation, or an Error object if the request fails.

Return type:

Union[Result[Workspace], Error]

Module contents