smartsheet-python-sdk 3.0.5__tar.gz → 3.2.0__tar.gz

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/.gitignore

@@ -1,6 +1,7 @@
 .sw[op]
 .*.sw[op]
 *.pyc
+*.iml
 
 # Ignore setup.py artifacts
 build/

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/ADVANCED.md

@@ -80,7 +80,7 @@ response = client.Passthrough.post('/sheets', payload)
 
 ### Integration Tests
 
-1. Follow the instructions [here](tests/integration/README.md)
+1. Follow the [Integration test instructions](tests/integration/README.md)
 2. Run `pytest tests/integration`
 
 ### Mock API Tests
@@ -134,7 +134,8 @@ using the same `stream_position` value until the next list of events is retrieve
 Many events have additional information available as a part of the event. That information can be accessed using
 the Python dictionary stored in the `additional_details` property (Note that values of the `additional_details`
 dictionary use camelCase/JSON names, e.g. `sheetName` not `sheet_name`). Information about the additional details
-provided can be found [here.](https://smartsheet.redoc.ly/tag/eventsDescription)
+
+provided can be found on the [Events Description](https://smartsheet.redoc.ly/tag/eventsDescription) page of the API Documentation.
 
 ```python
 # this example is looking specifically for new sheet events
@@ -157,7 +158,7 @@ last_week = datetime.now() - timedelta(days=7)
 events_list = smartsheet_client.Events.list_events(since=last_week.isoformat(), max_count=1000)
 print_new_sheet_events_in_list(events_list)
 
-# continue listing events in the stream by using the stream_position, if the previous response indicates that more 
+# continue listing events in the stream by using the stream_position, if the previous response indicates that more
 # data is available.
 while events_list.more_available:
     events_list = smartsheet_client.Events.list_events(stream_position=events_list.next_stream_position, max_count=10000,

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [3.2.0] - 2025-09-25
+
+### Added
+
+- Support for POST /2.0/users/{userId}/plans/{planId}/downgrade
+- Support for POST /2.0/users/{userId}/plans/{planId}/upgrade
+- Support for GET /2.0/users/{userId}/plans
+- Support for GET /2.0/users?planId={planId}&seatType={seatType}
+- Support for DELETE /2.0/users/{userId}/plans/{planId}
+
+## [3.1.0] - 2025-08-28
+
+### Added
+
+- New `get_workspace_metadata()` method to get workspace metadata without children
+- New `get_workspace_children()` method to get workspace children with filtering and pagination support
+- New `get_folder_metadata()` method to get folder metadata without children
+- New `get_folder_children()` method to get folder children with filtering and pagination support
+- New `TokenPaginatedResult<T>` generic model for type-safe paginated API responses
+- New `PaginatedChildrenResult` model with custom deserialization for mixed children types based on resourceType
+- Updated `list_workspaces()` method to support Token-based pagination . Use the new `pagination_type='token'` parameter with `last_key` and `max_items` for more efficient pagination. When `pagination_type='token'` is used, the method returns a `Result` object containing `data` and `lastKey`.
+
+### Deprecated
+
+- `get_workspace()` - Use `get_workspace_metadata()` and `get_workspace_children()` instead
+- `list_folders()` in Workspaces - Use `get_workspace_children()` with `children_resource_types=['folders']` instead
+- `get_folder()` - Use `get_folder_metadata()` and `get_folder_children()` instead
+- `list_folders()` in Folders - Use `get_folder_children()` with `children_resource_types=['folders']` instead
+- `create_folder()` in Home
+- `create_sheet()` in Home
+- `create_sheet_from_template()` in Home
+- `list_all_contents()` in Home
+- `list_folders()` in Home
+- `page_size`, `page`, and `include_all` parameters in `list_workspaces()` method are now deprecated. Use `pagination_type='token'` with `max_items` and `last_key` instead. Deprecated parameters will issue `DeprecationWarning` when used.
+
 ## [3.0.5] - 2025-04-07
 
 ### Changed
@@ -253,7 +288,7 @@ if sheet.access_level == 'OWNER':
     ...
 ```
 
-[enum34](https://pypi.python.org/pypi/enum34) has been added as a required package for the SDK  
+[enum34](https://pypi.python.org/pypi/enum34) has been added as a required package for the SDK
 
 ## [1.3.0] - 2018-02-21
 

{smartsheet-python-sdk-3.0.5/smartsheet_python_sdk.egg-info → smartsheet-python-sdk-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: smartsheet-python-sdk
-Version: 3.0.5
+Version: 3.2.0
 Summary: Library that uses Python to connect to Smartsheet services (using API 2.0).
 Home-page: http://smartsheet-platform.github.io/api-docs/
 Author: Smartsheet

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/docs-source/index.rst

@@ -7,7 +7,11 @@
 Smartsheet Python SDK Documentation
 ===================================
 
-Release v\ |version|.
+* Release v\ |version|
+
+* `GitHub repository <https://github.com/smartsheet/smartsheet-python-sdk>`_
+
+* `Changelog <https://github.com/smartsheet/smartsheet-python-sdk/blob/mainline/CHANGELOG.md>`_
 
 Quickstart
 ----------

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/smartsheet/folders.py

@@ -22,6 +22,7 @@ import os.path
 
 from . import fresh_operation
 from .models.folder import Folder
+from .util import deprecated
 
 
 class Folders:
@@ -173,9 +174,13 @@ class Folders:
 
         return response
 
+    @deprecated
     def get_folder(self, folder_id, include=None):
         """Get the specified Folder (and list its contents).
 
+        Deprecated: 3.1.0
+           Use `get_folder_metadata` and `get_folder_children` instead.
+
         Args:
             folder_id (int): Folder ID
             include (list[str]): A comma-separated list of
@@ -196,9 +201,13 @@ class Folders:
 
         return response
 
+    @deprecated
     def list_folders(self, folder_id, page_size=None, page=None, include_all=None):
         """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.
+
         Args:
             folder_id (int): Folder ID
             page_size (int): The maximum number of items to
@@ -272,6 +281,59 @@ class Folders:
 
         return response
 
+    def get_folder_metadata(self, folder_id, include=None):
+        """Get the metadata of a folder.
+
+        Args:
+            folder_id (int): Folder ID
+            include (list[str]): A list of optional elements to include
+            in the response. Valid list values: source.
+
+        Returns:
+            Folder
+        """
+        _op = fresh_operation("get_folder_metadata")
+        _op["method"] = "GET"
+        _op["path"] = "/folders/" + str(folder_id) + "/metadata"
+        _op["query_params"]["include"] = include
+
+        expected = "Folder"
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def get_folder_children(self, folder_id, children_resource_types=None, include=None, last_key=None, max_items=None):
+        """Get the children of a folder.
+
+        Args:
+            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:
+            PaginatedChildrenResult
+        """
+        _op = fresh_operation("get_folder_children")
+        _op["method"] = "GET"
+        _op["path"] = "/folders/" + str(folder_id) + "/children"
+        _op["query_params"]["childrenResourceTypes"] = children_resource_types
+        _op["query_params"]["include"] = include
+        _op["query_params"]["lastKey"] = last_key
+        _op["query_params"]["maxItems"] = max_items
+
+        expected = "PaginatedChildrenResult"
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
     def import_csv_sheet(
         self,
         folder_id,

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/smartsheet/home.py

@@ -22,6 +22,7 @@ import logging
 from . import fresh_operation
 from .models.folder import Folder
 from .models.sheet import Sheet
+from .util import deprecated
 
 
 class Home:
@@ -33,6 +34,7 @@ class Home:
         self._base = smartsheet_obj
         self._log = logging.getLogger(__name__)
 
+    @deprecated
     def create_folder(self, folder_obj):
         """Creates a Folder in the user's Sheets folder (Home).
 
@@ -57,6 +59,7 @@ class Home:
 
         return response
 
+    @deprecated
     def create_sheet(self, sheet_obj):
         """Create a Sheet from scratch in the user's Sheets folder within
         Home.
@@ -82,6 +85,7 @@ class Home:
 
         return response
 
+    @deprecated
     def create_sheet_from_template(self, sheet_obj, include=None):
         """Create a Sheet in the Sheets folder from the specified Template.
 
@@ -118,6 +122,7 @@ class Home:
 
         return response
 
+    @deprecated
     def list_all_contents(self, include=None, exclude=None):
         """Get a nested list of all Home objects, including Sheets,
         Workspaces, Folders, Reports and Templates.
@@ -145,6 +150,7 @@ class Home:
 
         return response
 
+    @deprecated
     def list_folders(self, page_size=None, page=None, include_all=None):
         """Gets a list of top-level child Folders within the user's Sheets
         folder.

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/smartsheet/models/__init__.py

@@ -73,6 +73,8 @@ from .multi_row_email import MultiRowEmail
 from .number_object_value import NumberObjectValue
 from .o_auth_error import OAuthError
 from .object_value import ObjectValue
+from .paginated_children_result import PaginatedChildrenResult
+from .token_paginated_result import TokenPaginatedResult
 from .predecessor import Predecessor
 from .predecessor_list import PredecessorList
 from .project_settings import ProjectSettings
@@ -119,3 +121,4 @@ from .webhook_subscope import WebhookSubscope
 from .widget import Widget
 from .widget_content import WidgetContent
 from .workspace import Workspace
+from .user_plan import UserPlan

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/smartsheet/models/datetime_object_value.py

@@ -26,10 +26,10 @@ from .object_value import ObjectValue, six
 
 
 class DatetimeObjectValue(ObjectValue):
-    """Smartsheet DateObjectValue data model."""
+    """Smartsheet DatetimeObjectValue data model."""
 
     def __init__(self, props=None, object_type=None, base_obj=None):
-        """Initialize the DateObjectValue model."""
+        """Initialize the DatetimeObjectValue model."""
         super().__init__(object_type, base_obj)
         self._base = None
         if base_obj is not None:

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/smartsheet/models/enums/__init__.py

@@ -52,3 +52,4 @@ from .system_column_type import SystemColumnType
 from .update_request_status import UpdateRequestStatus
 from .user_status import UserStatus
 from .widget_type import WidgetType
+from .seat_type import SeatType, DowngradeSeatType, UpgradeSeatType

smartsheet-python-sdk-3.2.0/smartsheet/models/enums/seat_type.py

@@ -0,0 +1,17 @@
+from enum import Enum
+
+class SeatType(str, Enum):
+    VIEWER = 'VIEWER'
+    GUEST = 'GUEST'
+    MEMBER = 'MEMBER'
+    PROVISIONAL_MEMBER = 'PROVISIONAL_MEMBER'
+
+
+class DowngradeSeatType(str, Enum):
+    VIEWER = 'VIEWER'
+    GUEST = 'GUEST'
+
+
+class UpgradeSeatType(str, Enum):
+    GUEST = 'GUEST'
+    MEMBER = 'MEMBER'

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/smartsheet/models/folder.py

@@ -17,11 +17,12 @@
 
 from __future__ import absolute_import
 
-from ..types import Boolean, Number, String, TypedList, json
+from ..types import Boolean, Number, String, Timestamp, TypedList, TypedObject, json
 from ..util import deserialize, serialize
 from .report import Report
 from .sheet import Sheet
 from .sight import Sight
+from .source import Source
 from .template import Template
 
 
@@ -35,14 +36,17 @@ class Folder:
         if base_obj is not None:
             self._base = base_obj
 
+        self._created_at = Timestamp()
         self._favorite = Boolean()
         self._folders = TypedList(Folder)
         self._id_ = Number()
+        self._modified_at = Timestamp()
         self._name = String()
         self._permalink = String()
         self._reports = TypedList(Report)
         self._sheets = TypedList(Sheet)
         self._sights = TypedList(Sight)
+        self._source = TypedObject(Source)
         self._templates = TypedList(Template)
 
         if props:
@@ -64,6 +68,14 @@ class Folder:
         else:
             super().__setattr__(key, value)
 
+    @property
+    def created_at(self):
+        return self._created_at.value
+
+    @created_at.setter
+    def created_at(self, value):
+        self._created_at.value = value
+
     @property
     def favorite(self):
         return self._favorite.value
@@ -88,6 +100,14 @@ class Folder:
     def id_(self, value):
         self._id_.value = value
 
+    @property
+    def modified_at(self):
+        return self._modified_at.value
+
+    @modified_at.setter
+    def modified_at(self, value):
+        self._modified_at.value = value
+
     @property
     def name(self):
         return self._name.value
@@ -128,6 +148,14 @@ class Folder:
     def sights(self, value):
         self._sights.load(value)
 
+    @property
+    def source(self):
+        return self._source.value
+
+    @source.setter
+    def source(self, value):
+        self._source.value = value
+
     @property
     def templates(self):
         return self._templates

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/smartsheet/models/index_result.py

@@ -17,7 +17,7 @@
 
 from __future__ import absolute_import
 
-from ..types import Number, TypedList, importlib, json
+from ..types import Number, TypedList, importlib, json, String
 from ..util import deserialize, serialize
 
 
@@ -40,6 +40,7 @@ class IndexResult:
         self._page_size = Number()
         self._total_count = Number()
         self._total_pages = Number()
+        self._last_key = String()
 
         if props:
             deserialize(self, props)
@@ -94,6 +95,14 @@ class IndexResult:
     def total_pages(self, value):
         self._total_pages.value = value
 
+    @property
+    def last_key(self):
+        return self._last_key.value
+
+    @last_key.setter
+    def last_key(self, value):
+        self._last_key.value = value
+
     @property
     def result(self):
         """Simplify difference between Result and IndexResult"""

smartsheet-python-sdk-3.2.0/smartsheet/models/paginated_children_result.py

@@ -0,0 +1,80 @@
+# pylint: disable=C0111,R0902,R0904,R0912,R0913,R0915,E1101
+# Smartsheet Python SDK.
+#
+# Copyright 2018 Smartsheet.com, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from __future__ import absolute_import
+
+from typing import Union
+from ..util import deserialize
+from .token_paginated_result import TokenPaginatedResult
+from .folder import Folder
+from .sheet import Sheet
+from .sight import Sight
+from .report import Report
+
+# Type alias for children that can be any of these types
+ChildType = Union[Folder, Sheet, Sight, Report]
+
+
+class PaginatedChildrenResult(TokenPaginatedResult[ChildType]):
+    """Smartsheet PaginatedChildrenResult that deserializes mixed children based on resourceType."""
+
+    def __init__(self, props=None, base_obj=None):
+        """Initialize the PaginatedChildrenResult model."""
+        super().__init__(props=None, base_obj=base_obj)
+
+        if props:
+            self._deserialize_data(props)
+            deserialize(self, props)
+
+    def _deserialize_data(self, props):
+        """Custom deserialization for data array based on resourceType."""
+        if 'data' in props:
+            self._data = []
+            for item in props['data']:
+                self.append_data(item)
+
+    def append_data(self, item):
+        """Append data item, converting to appropriate model based on resourceType."""
+        # Get resource type from either dict or object
+        if isinstance(item, dict):
+            resource_type = item.get('resourceType', '').lower()
+        else:
+            resource_type = getattr(item, 'resourceType', '').lower()
+
+        # Convert to appropriate model object based on resource type
+        if resource_type == 'folder':
+            self._data.append(Folder(item, self._base))
+        elif resource_type == 'sheet':
+            self._data.append(Sheet(item, self._base))
+        elif resource_type == 'sight':
+            self._data.append(Sight(item, self._base))
+        elif resource_type == 'report':
+            self._data.append(Report(item, self._base))
+        else:
+            # If no resource type or unknown type, append as-is
+            self._data.append(item)
+
+    @property
+    def data(self):
+        return self._data
+
+    @data.setter
+    def data(self, value):
+        """Custom setter that handles deserialization of mixed resource types."""
+        self._data = []
+        for item in value:
+            self.append_data(item)

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/smartsheet/models/source.py

@@ -31,7 +31,7 @@ class Source:
         if base_obj is not None:
             self._base = base_obj
 
-        self.allowed_values = {"_type": ["report", "sheet", "sight", "template"]}
+        self.allowed_values = {"_type": ["folder", "report", "sheet", "sight", "template", "workspace"]}
 
         self._id_ = Number()
         self._type_ = String(accept=self.allowed_values["_type"])

smartsheet-python-sdk-3.2.0/smartsheet/models/token_paginated_result.py

@@ -0,0 +1,79 @@
+# pylint: disable=C0111,R0902,R0904,R0912,R0913,R0915,E1101
+# Smartsheet Python SDK.
+#
+# Copyright 2018 Smartsheet.com, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from __future__ import absolute_import
+
+from typing import TypeVar, Generic, List
+from ..types import String, json, TypedList, importlib
+from ..util import deserialize, serialize
+
+T = TypeVar('T')
+
+
+class TokenPaginatedResult(Generic[T]):
+    """Smartsheet TokenPaginatedResult data model with generic type support."""
+
+    def __init__(self, props=None, dynamic_data_type=None, base_obj=None):
+        """Initialize the TokenPaginatedResult model."""
+        self._base = None
+        if base_obj is not None:
+            self._base = base_obj
+
+        self._dynamic_data_type = None
+        if dynamic_data_type is not None:
+            self._dynamic_data_type = dynamic_data_type
+
+        self._data = TypedList(object)
+        self._last_key = String()
+
+        if props:
+            deserialize(self, props)
+
+        self.request_response = None
+        self.__initialized = True
+
+    @property
+    def data(self) -> List[T]:
+        return self._data
+
+    @data.setter
+    def data(self, value):
+        class_ = getattr(
+            importlib.import_module("smartsheet.models"), self._dynamic_data_type
+        )
+        if isinstance(value, list):
+            self._data = [class_(x, self._base) for x in value]
+        else:
+            self._data = class_(value, self._base)
+
+
+    @property
+    def last_key(self):
+        return self._last_key.value
+
+    @last_key.setter
+    def last_key(self, value):
+        self._last_key.value = value
+
+    def to_dict(self):
+        return serialize(self)
+
+    def to_json(self):
+        return json.dumps(self.to_dict())
+
+    def __str__(self):
+        return self.to_json()

{smartsheet-python-sdk-3.0.5 → smartsheet-python-sdk-3.2.0}/smartsheet/models/user_model.py

@@ -19,6 +19,7 @@ from __future__ import absolute_import
 
 from ..types import (Boolean, EnumeratedValue, Number, String, Timestamp,
                      TypedList, TypedObject, json)
+from ..models.enums import SeatType
 from ..util import deserialize, serialize
 from .alternate_email import AlternateEmail
 from .enums import UserStatus
@@ -44,6 +45,7 @@ class UserModel:
         self._first_name = String()
         self._group_admin = Boolean()
         self._id_ = Number()
+        self._is_internal = Boolean()
         self._last_login = Timestamp()
         self._last_name = String()
         self._licensed_sheet_creator = Boolean()
@@ -51,6 +53,8 @@ class UserModel:
         self._profile_image = TypedObject(ProfileImage)
         self._resource_viewer = Boolean()
         self._role = String()
+        self._seat_type = EnumeratedValue(SeatType)
+        self._seat_type_last_changed_at = Timestamp()
         self._sheet_count = Number()
         self._status = EnumeratedValue(UserStatus)
         self._title = String()
@@ -145,6 +149,14 @@ class UserModel:
     def id_(self, value):
         self._id_.value = value
 
+    @property
+    def is_internal(self):
+        return self._is_internal.value
+
+    @is_internal.setter
+    def is_internal(self, value):
+        self._is_internal.value = value
+
     @property
     def last_login(self):
         return self._last_login.value
@@ -201,6 +213,22 @@ class UserModel:
     def role(self, value):
         self._role.value = value
 
+    @property
+    def seat_type(self):
+        return self._seat_type
+
+    @seat_type.setter
+    def seat_type(self, value):
+        self._seat_type.set(value)
+
+    @property
+    def seat_type_last_changed_at(self):
+        return self._seat_type_last_changed_at.value
+
+    @seat_type_last_changed_at.setter
+    def seat_type_last_changed_at(self, value):
+        self._seat_type_last_changed_at.value = value
+
     @property
     def sheet_count(self):
         return self._sheet_count.value