smartsheet-python-sdk 3.1.0__tar.gz → 3.3.0__tar.gz

{smartsheet-python-sdk-3.1.0 → smartsheet_python_sdk-3.3.0}/ADVANCED.md

@@ -134,6 +134,7 @@ 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 on the [Events Description](https://smartsheet.redoc.ly/tag/eventsDescription) page of the API Documentation.
 
 ```python

{smartsheet-python-sdk-3.1.0 → smartsheet_python_sdk-3.3.0}/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.3.0] - 2025-10-07
+
+### Added
+
+- Support for new asset-based sharing endpoints in a new `sharing` module:
+  - `list_asset_shares`: List all shares for a specified asset
+  - `get_asset_share`: Get a specific share for a specified asset
+  - `share_asset`: Share an asset with specified users and/or groups
+  - `update_share`: Update a specific share for a specified asset
+  - `delete_share`: Delete a specific share for a specified asset
+- Added `AssetType` enum for use with sharing endpoints
+
+### Updated
+
+- Deprecated old sharing endpoints in the `sheets` module
+- Added deprecation notices and migration examples in documentation
+
+## [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

{smartsheet-python-sdk-3.1.0/smartsheet_python_sdk.egg-info → smartsheet_python_sdk-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: smartsheet-python-sdk
-Version: 3.1.0
+Version: 3.3.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
@@ -20,16 +20,40 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
 Description-Content-Type: text/markdown
-Provides-Extra: test
-Provides-Extra: develop
 License-File: LICENSE.md
 License-File: NOTICE
+Requires-Dist: requests
+Requires-Dist: requests-toolbelt
+Requires-Dist: six>=1.9
+Requires-Dist: certifi
+Requires-Dist: python-dateutil
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: coveralls; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: develop
+Requires-Dist: coverage; extra == "develop"
+Requires-Dist: coveralls[yaml]; extra == "develop"
+Requires-Dist: pytest; extra == "develop"
+Requires-Dist: pytest-instafail; extra == "develop"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
 
 # Smartsheet Python SDK
 
 [![Build Status](https://github.com/smartsheet/smartsheet-python-sdk/actions/workflows/test-build.yaml/badge.svg)](https://github.com/smartsheet/smartsheet-python-sdk/actions/workflows/test-build.yaml) [![Coverage Status](https://coveralls.io/repos/github/smartsheet/smartsheet-python-sdk/badge.svg?branch=mainline)](https://coveralls.io/github/smartsheet/smartsheet-python-sdk?branch=mainline) [![PyPI version](https://badge.fury.io/py/smartsheet-python-sdk.svg)](https://badge.fury.io/py/smartsheet-python-sdk)
 
-A library for connecting to the [Smartsheet API](https://smartsheet.redoc.ly) from Python applications.
+A library for connecting to the [Smartsheet API](https://developers.smartsheet.com/api/smartsheet/) from Python applications.
 
 ## Requirements
 
@@ -47,7 +71,7 @@ pip install smartsheet-python-sdk
 
 To get started with the Smartsheet Python SDK:
 
-1. Set **SMARTSHEET_ACCESS_TOKEN** in your environment, using your Smartsheet API key. Find out more about [Authentication and Access Tokens](https://smartsheet.redoc.ly/#section/API-Basics/Authentication-and-Access-Tokens) in the Smartsheet API Documentation. You can generate an access token in Smartsheet UI under Account > Personal Settings > API Access.
+1. Set **SMARTSHEET_ACCESS_TOKEN** in your environment, using your Smartsheet API key. Find out more about [Authentication and Access Tokens](https://developers.smartsheet.com/api/smartsheet/guides/basics/authentication) in the Smartsheet API Documentation. You can generate an access token in Smartsheet UI under Account > Personal Settings > API Access.
 
 2. Install the Smartsheet Python SDK (see the installation instructions above)
 
@@ -72,7 +96,7 @@ Use the following resources to learn more about the SDK capabilities:
 
 1. [Smartsheet Python SDK sample project](https://github.com/smartsheet-samples/python-read-write-sheet)
 2. [Python SDK documentation](https://smartsheet.github.io/smartsheet-python-sdk/)
-3. [Smartsheet API Documentation](https://smartsheet.redoc.ly)
+3. [Smartsheet API Documentation](https://developers.smartsheet.com/api/smartsheet/)
 
 ## Advanced Topics
 

{smartsheet-python-sdk-3.1.0 → smartsheet_python_sdk-3.3.0}/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://github.com/smartsheet/smartsheet-python-sdk/actions/workflows/test-build.yaml/badge.svg)](https://github.com/smartsheet/smartsheet-python-sdk/actions/workflows/test-build.yaml) [![Coverage Status](https://coveralls.io/repos/github/smartsheet/smartsheet-python-sdk/badge.svg?branch=mainline)](https://coveralls.io/github/smartsheet/smartsheet-python-sdk?branch=mainline) [![PyPI version](https://badge.fury.io/py/smartsheet-python-sdk.svg)](https://badge.fury.io/py/smartsheet-python-sdk)
 
-A library for connecting to the [Smartsheet API](https://smartsheet.redoc.ly) from Python applications.
+A library for connecting to the [Smartsheet API](https://developers.smartsheet.com/api/smartsheet/) from Python applications.
 
 ## Requirements
 
@@ -20,7 +20,7 @@ pip install smartsheet-python-sdk
 
 To get started with the Smartsheet Python SDK:
 
-1. Set **SMARTSHEET_ACCESS_TOKEN** in your environment, using your Smartsheet API key. Find out more about [Authentication and Access Tokens](https://smartsheet.redoc.ly/#section/API-Basics/Authentication-and-Access-Tokens) in the Smartsheet API Documentation. You can generate an access token in Smartsheet UI under Account > Personal Settings > API Access.
+1. Set **SMARTSHEET_ACCESS_TOKEN** in your environment, using your Smartsheet API key. Find out more about [Authentication and Access Tokens](https://developers.smartsheet.com/api/smartsheet/guides/basics/authentication) in the Smartsheet API Documentation. You can generate an access token in Smartsheet UI under Account > Personal Settings > API Access.
 
 2. Install the Smartsheet Python SDK (see the installation instructions above)
 
@@ -45,7 +45,7 @@ Use the following resources to learn more about the SDK capabilities:
 
 1. [Smartsheet Python SDK sample project](https://github.com/smartsheet-samples/python-read-write-sheet)
 2. [Python SDK documentation](https://smartsheet.github.io/smartsheet-python-sdk/)
-3. [Smartsheet API Documentation](https://smartsheet.redoc.ly)
+3. [Smartsheet API Documentation](https://developers.smartsheet.com/api/smartsheet/)
 
 ## Advanced Topics
 

{smartsheet-python-sdk-3.1.0 → smartsheet_python_sdk-3.3.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.3.0/smartsheet/asset_shares.py

@@ -0,0 +1,163 @@
+# pylint: disable=C0111,R0902,R0913
+# 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.
+
+import logging
+from . import fresh_operation
+from .models.enums import ShareScope
+
+
+class Sharing:
+    """Class for handling Sharing operations."""
+
+    def __init__(self, smartsheet_obj):
+        """Init Sharing with base Smartsheet object."""
+        self._base = smartsheet_obj
+        self._log = logging.getLogger(__name__)
+
+    def list_asset_shares(self, asset_type, asset_id, max_items=None, last_key=None,
+                          sharing_include: ShareScope = None):
+        """Get the list of all Users and Groups to whom the specified asset is
+        shared, and their access level.
+
+        Args:
+            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:
+            IndexResult
+        """
+        _op = fresh_operation('list_asset_shares')
+        _op['method'] = 'GET'
+        _op['path'] = '/shares'
+        _op['query_params']['assetType'] = asset_type
+        _op['query_params']['assetId'] = asset_id
+        _op['query_params']['maxItems'] = max_items
+        _op['query_params']['lastKey'] = last_key
+        _op['query_params']['sharingInclude'] = sharing_include.name if sharing_include else None
+
+        expected = ['IndexResult', 'Share']
+
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def get_asset_share(self, asset_type, asset_id, share_id):
+        """Get a specific share for the specified asset.
+
+        Args:
+            asset_type (AssetType): Type of asset (sheet, report, sight, workspace, etc.)
+            asset_id (int): Asset ID
+            share_id (str): Share ID
+
+        Returns:
+            Share
+        """
+        _op = fresh_operation('get_asset_share')
+        _op['method'] = 'GET'
+        _op['path'] = f'/shares/{share_id}'
+        _op['query_params']['assetType'] = asset_type
+        _op['query_params']['assetId'] = asset_id
+
+        expected = 'Share'
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def share_asset(self, share_obj, asset_type, asset_id, send_email=None):
+        """Share an asset with the specified Users and Groups.
+
+        Args:
+            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:
+            Result
+        """
+        _op = fresh_operation('share_asset')
+        _op['method'] = 'POST'
+        _op['path'] = '/shares'
+        _op['query_params']['assetType'] = asset_type
+        _op['query_params']['assetId'] = asset_id
+        _op['query_params']['sendEmail'] = send_email
+        _op['json'] = share_obj
+
+        expected = ['Result', 'Share']
+
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def update_asset_share(self, share_obj, asset_type, asset_id, share_id):
+        """Update the access level of a User or Group for the specified asset.
+
+        Args:
+            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:
+            Result
+        """
+        _op = fresh_operation('update_share')
+        _op['method'] = 'PATCH'
+        _op['path'] = f'/shares/{share_id}'
+        _op['query_params']['assetType'] = asset_type
+        _op['query_params']['assetId'] = asset_id
+        _op['json'] = share_obj
+
+        expected = ['Result', 'Share']
+
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def delete_asset_share(self, asset_type, asset_id, share_id):
+        """Delete the specified Share.
+
+        Args:
+            asset_type (AssetType): Type of asset (sheet, report, sight, workspace, etc.)
+            asset_id (int): Asset ID
+            share_id (str): Share ID
+
+        Returns:
+            Result
+        """
+        _op = fresh_operation('delete_share')
+        _op['method'] = 'DELETE'
+        _op['path'] = f'/shares/{share_id}'
+        _op['query_params']['assetType'] = asset_type
+        _op['query_params']['assetId'] = asset_id
+
+        expected = ['Result', None]
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response

{smartsheet-python-sdk-3.1.0 → smartsheet_python_sdk-3.3.0}/smartsheet/models/__init__.py

@@ -121,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.1.0 → smartsheet_python_sdk-3.3.0}/smartsheet/models/enums/__init__.py

@@ -19,6 +19,7 @@ from __future__ import absolute_import
 
 # import enums into enum package
 from .access_level import AccessLevel
+from .asset_type import AssetType
 from .attachment_parent_type import AttachmentParentType
 from .attachment_sub_type import AttachmentSubType
 from .attachment_type import AttachmentType
@@ -52,3 +53,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.3.0/smartsheet/models/enums/asset_type.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+class AssetType(str, Enum):
+    """Defines the asset types supported by the Sharing API."""
+    SHEET = 'sheet'
+    REPORT = 'report'
+    SIGHT = 'sight'
+    WORKSPACE = 'workspace'
+    COLLECTION = 'collection'
+    FILE = 'file'

smartsheet_python_sdk-3.3.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.1.0 → smartsheet_python_sdk-3.3.0}/smartsheet/models/token_paginated_result.py

@@ -18,7 +18,7 @@
 from __future__ import absolute_import
 
 from typing import TypeVar, Generic, List
-from ..types import String, json
+from ..types import String, json, TypedList, importlib
 from ..util import deserialize, serialize
 
 T = TypeVar('T')
@@ -27,13 +27,17 @@ T = TypeVar('T')
 class TokenPaginatedResult(Generic[T]):
     """Smartsheet TokenPaginatedResult data model with generic type support."""
 
-    def __init__(self, props=None, base_obj=None):
+    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._data = []
+        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:
@@ -48,7 +52,14 @@ class TokenPaginatedResult(Generic[T]):
 
     @data.setter
     def data(self, value):
-        self._data = 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):

{smartsheet-python-sdk-3.1.0 → smartsheet_python_sdk-3.3.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

smartsheet_python_sdk-3.3.0/smartsheet/models/user_plan.py

@@ -0,0 +1,68 @@
+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
+
+
+class UserPlan:
+
+    """Smartsheet Plan for a User data model."""
+
+    def __init__(self, props=None, base_obj=None):
+        """Initialize the UserPlan model."""
+        self._base = None
+        if base_obj is not None:
+            self._base = base_obj
+
+        self._plan_id = Number()
+        self._seat_type = EnumeratedValue(SeatType)
+        self._seat_type_last_changed_at = Timestamp()
+        self._is_internal = Boolean()
+
+        if props:
+            deserialize(self, props)
+
+        self.__initialized = True
+
+    @property
+    def plan_id(self):
+        return self._plan_id.value
+
+    @plan_id.setter
+    def plan_id(self, value):
+        self._plan_id.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 is_internal(self):
+        return self._is_internal.value
+
+    @is_internal.setter
+    def is_internal(self, value):
+        self._is_internal.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.1.0 → smartsheet_python_sdk-3.3.0}/smartsheet/sheets.py

@@ -30,7 +30,6 @@ from .models.summary_field import SummaryField
 from .types import TypedList
 from .util import deprecated
 
-
 class Sheets:
 
     """Class for handling Sheets operations."""
@@ -310,6 +309,7 @@ class Sheets:
 
         return response
 
+    @deprecated("Use sharing.delete_share instead")
     def delete_share(self, sheet_id, share_id):
         """Delete the specified Share.
 
@@ -319,6 +319,9 @@ class Sheets:
 
         Returns:
             Result
+            
+        Deprecated:
+            Use sharing.delete_share instead with assetType=AssetType.SHEET
         """
         _op = fresh_operation("delete_share")
         _op["method"] = "DELETE"
@@ -470,6 +473,7 @@ class Sheets:
 
         return response
 
+    @deprecated("Use sharing.get_asset_share instead")
     def get_share(self, sheet_id, share_id):
         """Get the specified Share.
 
@@ -479,6 +483,9 @@ class Sheets:
 
         Returns:
             Share
+            
+        Deprecated:
+            Use sharing.get_asset_share instead with assetType=AssetType.SHEET
         """
         _op = fresh_operation("get_share")
         _op["method"] = "GET"
@@ -991,6 +998,7 @@ class Sheets:
 
         return response
 
+    @deprecated("Use sharing.share_asset instead")
     def share_sheet(self, sheet_id, share_obj, send_email=None):
         """Share the specified Sheet.
 
@@ -1006,6 +1014,9 @@ class Sheets:
 
         Returns:
             Result
+            
+        Deprecated:
+            Use sharing.share_asset instead with assetType=AssetType.SHEET
         """
         _op = fresh_operation("share_sheet")
         _op["method"] = "POST"
@@ -1120,6 +1131,7 @@ class Sheets:
 
         return response
 
+    @deprecated("Use sharing.update_share instead")
     def update_share(self, sheet_id, share_id, share_obj):
         """Update the access level of a User or Group for the specified Sheet.
 
@@ -1130,6 +1142,9 @@ class Sheets:
 
         Returns:
             Result
+            
+        Deprecated:
+            Use sharing.update_share instead with assetType=AssetType.SHEET
         """
         if not all(val is not None for val in ["sheet_id", "share_id", "share_obj"]):
             raise ValueError(