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

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

@@ -5,6 +5,23 @@ 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

{smartsheet-python-sdk-3.2.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.2.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.2.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.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.2.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

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.2.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(

{smartsheet-python-sdk-3.2.0 → smartsheet_python_sdk-3.3.0}/smartsheet/version.py

@@ -1,4 +1,4 @@
 # file generated by setuptools_scm
 # don't change, don't track in version control
-__version__ = version = '3.2.0'
-__version_tuple__ = version_tuple = (3, 2, 0)
+__version__ = version = '3.3.0'
+__version_tuple__ = version_tuple = (3, 3, 0)

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: smartsheet-python-sdk
-Version: 3.2.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.2.0 → smartsheet_python_sdk-3.3.0}/smartsheet_python_sdk.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ docs-source/Makefile
 docs-source/conf.py
 docs-source/index.rst
 smartsheet/__init__.py
+smartsheet/asset_shares.py
 smartsheet/attachments.py
 smartsheet/cells.py
 smartsheet/contacts.py
@@ -172,6 +173,7 @@ smartsheet/models/widget_hyperlink.py
 smartsheet/models/workspace.py
 smartsheet/models/enums/__init__.py
 smartsheet/models/enums/access_level.py
+smartsheet/models/enums/asset_type.py
 smartsheet/models/enums/attachment_parent_type.py
 smartsheet/models/enums/attachment_sub_type.py
 smartsheet/models/enums/attachment_type.py
@@ -231,6 +233,7 @@ tests/integration/test_regression.py
 tests/integration/test_reports.py
 tests/integration/test_rows.py
 tests/integration/test_server_info.py
+tests/integration/test_sharing.py
 tests/integration/test_sheet_summary.py
 tests/integration/test_sheets.py
 tests/integration/test_templates.py

smartsheet_python_sdk-3.3.0/tests/integration/test_sharing.py

@@ -0,0 +1,83 @@
+import pytest
+from smartsheet.exceptions import ApiError
+from smartsheet.models import Share
+
+@pytest.mark.usefixtures("smart_setup")
+class TestSharing:
+    def test_list_asset_shares(self, smart_setup):
+        smart = smart_setup['smart']
+        sheet_id = smart_setup['sheet_b'].id
+        
+        # Test listing shares for a sheet
+        action = smart.Sharing.list_asset_shares(
+            asset_type='sheet',
+            asset_id=sheet_id
+        )
+        assert action.result is not None
+        
+    def test_share_asset(self, smart_setup):
+        smart = smart_setup['smart']
+        sheet_id = smart_setup['sheet_b'].id
+        
+        # Create a share object
+        share = Share({
+            'email': 'test@example.com',
+            'access_level': 'VIEWER'
+        })
+        
+        # Share the sheet
+        action = smart.Sharing.share_asset(
+            asset_type='sheet',
+            asset_id=sheet_id,
+            shares=[share],
+            send_email=False
+        )
+        
+        # Verify the share was created
+        assert isinstance(action.result, list) and action.result
+        if isinstance(action.result, list) and action.result:
+            assert action.result[0].email == 'test@example.com'
+            assert action.result[0].access_level == 'VIEWER'
+        else:
+            pytest.fail(f"Unexpected result type/shape: {type(action.result)} ({action.result})")
+        
+        # Store the share ID for later tests
+        share_id = action.result[0].id
+        
+        # Test get_asset_share
+        get_action = smart.Sharing.get_asset_share(
+            asset_type='sheet',
+            asset_id=sheet_id,
+            share_id=share_id
+        )
+        assert get_action.result is not None
+        assert get_action.result.id == share_id
+        
+        # Test update_share
+        update_share_spec = Share({
+            'id': share_id,
+            'access_level': 'EDITOR'
+        })
+        
+        update_action = smart.Sharing.update_share(
+            asset_type='sheet',
+            asset_id=sheet_id,
+            share=update_share_spec
+        )
+        assert update_action.result is not None
+        assert update_action.result.access_level == 'EDITOR'
+        
+        # Test delete_share
+        smart.Sharing.delete_asset_share(
+            asset_type='sheet',
+            asset_id=sheet_id,
+            share_id=share_id
+        )
+        
+        # Verify the share was deleted by trying to get it (should raise exception)
+        with pytest.raises(ApiError):
+            smart.Sharing.get_asset_share(
+                asset_type='sheet',
+                asset_id=sheet_id,
+                share_id=share_id
+            )