smartsheet-python-sdk 3.2.0__py2.py3-none-any.whl → 3.3.0__py2.py3-none-any.whl

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/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/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/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/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.dist-info → smartsheet_python_sdk-3.3.0.dist-info}/METADATA

@@ -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
@@ -27,21 +27,33 @@ 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"
-Provides-Extra: test
-Requires-Dist: coverage; extra == "test"
-Requires-Dist: coveralls; extra == "test"
-Requires-Dist: pytest; extra == "test"
+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
 
@@ -59,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)
 
@@ -84,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.dist-info → smartsheet_python_sdk-3.3.0.dist-info}/RECORD

@@ -1,4 +1,5 @@
 smartsheet/__init__.py,sha256=h2TD_nYTxqa7lcKb_mOIa-DMQN-pYaGk1Du0U3IVMyA,1152
+smartsheet/asset_shares.py,sha256=ztkh5uQOLKHT2AkjRnm_3yDRbFFUzNdBSCZbL5FhLVA,5839
 smartsheet/attachments.py,sha256=eZ1y5jS_TJSyZzzapc68ol1qhrLxCXc2sY8l8oY1Gvo,17865
 smartsheet/cells.py,sha256=1BCBps0mV9FV_nmdtsP5j7jT0avTVIfbYSAhnOqzlwM,4845
 smartsheet/contacts.py,sha256=IBV3ncoP7R7GmzQI0H1CIwq4scGk9iBC1ayyQ927YrQ,2383
@@ -16,7 +17,7 @@ smartsheet/reports.py,sha256=0B5bdQwVJHwu-V04aMSJ-Y7HaILK4rgjjMtn0--kcig,12835
 smartsheet/search.py,sha256=ffy1dkVl3GtuYgCxvuR-vwahOBWIehGv_zwzLoJMimA,3394
 smartsheet/server.py,sha256=9wySsa_y_G-VO88tEHGHp919zRVFS0kCFIhiM6crWEU,1429
 smartsheet/session.py,sha256=TQ3IgVZ64r7Dszwo8rMISFezWxuwFYshhW9QhzoA428,2125
-smartsheet/sheets.py,sha256=0JVg4N3u3z9ngnIeRnjo8fUejfXhcQLYmQXCyw207dk,70150
+smartsheet/sheets.py,sha256=nrqnvSz7ZqFi4f8lh6Xad5zEo8QrCtuMY0utzItnUHo,70797
 smartsheet/sights.py,sha256=IZgy8CJZBJ-pQo6vNwkDSBuoLCv5RAW39kNUMMNJ-oc,11569
 smartsheet/smartsheet.py,sha256=wOBejFgIh_xQu1KuIlh9ZAsq2OxG8EIWUqtBQpmz1y4,23408
 smartsheet/templates.py,sha256=z_Tj-4jZsu3RkLNbCAZWM2W05Zbio9T_uyU33rUPxzE,2898
@@ -24,7 +25,7 @@ smartsheet/token.py,sha256=5uz-IG5adx_zr2-uepH-W8ATv0dq9aZNjYLeZNwldqI,4703
 smartsheet/types.py,sha256=aIdRJ89jwclmiZ4RH3hnZHJTFWFxgNKW3d8fghm21eM,9126
 smartsheet/users.py,sha256=1KnqKJIzJEPMNy26BQY1b9jb3dItbzglrljV1MGD5ic,15887
 smartsheet/util.py,sha256=12Y6eluecB8k4Ns-at81AEM18ND2TCKa9bF4BlNRrKM,5633
-smartsheet/version.py,sha256=jXprrDLc5_o9OzizdGMr92Lmhow65AreA5_ht6m6bmA,160
+smartsheet/version.py,sha256=gPQor6drMcQZQs-T7xihCzC2lsOxfbNmH7QSOdvawII,160
 smartsheet/webhooks.py,sha256=7F7g4Ks0GyS3QxsNWm1SFtrOr00jBisCjj7-hcToHM8,4637
 smartsheet/workspaces.py,sha256=r81xh3HfYsX--ll5pQ-h7kSSJELokYV-bSjuD0WloeU,22651
 smartsheet/models/__init__.py,sha256=4P6wKY8TpbV_rI5Z5c1ifxiwJEWL5bsvecVcjtUSJ9U,4754
@@ -147,8 +148,9 @@ smartsheet/models/widget.py,sha256=G5UKR1latGSuXqm-MCRQxn9W7IJgo2FsUWJ9heEW0RA,6
 smartsheet/models/widget_content.py,sha256=hxv3DJWO8YPe4ND-HUZ59eOVU9LAy02owU-KQVWUsDU,1525
 smartsheet/models/widget_hyperlink.py,sha256=JPjaSftHFHiFj48tfOckGWzrew_CLKmE2k9lUA_RQSk,2059
 smartsheet/models/workspace.py,sha256=_YT4i4DEK32kEyqlWixZUQSQyBiZkNtwtSmuhc98H2s,4522
-smartsheet/models/enums/__init__.py,sha256=i-B6OYkAIRRQZwG8JgX19ZBHwVrBXWHfrLEWMUPXpj4,2322
+smartsheet/models/enums/__init__.py,sha256=qDpcuk-xU4jVTvwgD6aWz8hUM02hOZbiRNDfMLSniQM,2356
 smartsheet/models/enums/access_level.py,sha256=LvKh3Z2LrFeLm-R-dT0qOVinBsA4jEOxM02flg0LFaY,816
+smartsheet/models/enums/asset_type.py,sha256=hrNXZDk_mme57f-0wO86mk_RwzNP8zkb9h7GAEZbhjQ,253
 smartsheet/models/enums/attachment_parent_type.py,sha256=EFcrHg8xpx_ZxrrGb3vkk9Ji8PD74Q8GeWhXZMquVEw,770
 smartsheet/models/enums/attachment_sub_type.py,sha256=wZEo80LynIFDFZkTHCpQx5T-G5deT9HSRBMRdvHyh7Q,826
 smartsheet/models/enums/attachment_type.py,sha256=2c7TXc22Vzwq-8BG8rvEfqOpe29njT27otogdfVidwc,869
@@ -183,9 +185,9 @@ smartsheet/models/enums/system_column_type.py,sha256=UfhNUBGD_0K1Pas7fujGEuax55O
 smartsheet/models/enums/update_request_status.py,sha256=xYF84x1dTFhJMYVi1q3G1T9u1IGN3szlR1jj5HHC0hE,777
 smartsheet/models/enums/user_status.py,sha256=SB7qRcA0dhdRimsOKHCGF3CB6fL0XuifxQEWZGNNS8Q,766
 smartsheet/models/enums/widget_type.py,sha256=VfVq59fLZsT4ks_ZBrtv52u2Cl60iAdlA6mGD_elz-k,1072
-smartsheet_python_sdk-3.2.0.dist-info/LICENSE.md,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-smartsheet_python_sdk-3.2.0.dist-info/METADATA,sha256=MM8LT9xqe55C482AZXjBraonFBh1ofXzLcO2QEspIuI,4693
-smartsheet_python_sdk-3.2.0.dist-info/NOTICE,sha256=mXr2ryVjnCjykeW0J79kFfVXQG_Z9SV4BV_QPNENW1U,420
-smartsheet_python_sdk-3.2.0.dist-info/WHEEL,sha256=Kh9pAotZVRFj97E15yTA4iADqXdQfIVTHcNaZTjxeGM,110
-smartsheet_python_sdk-3.2.0.dist-info/top_level.txt,sha256=kozWEYiKjyJmSXzd6p5ugkQ5bhoHS9V3NnvLagUfcNw,11
-smartsheet_python_sdk-3.2.0.dist-info/RECORD,,
+smartsheet_python_sdk-3.3.0.dist-info/licenses/LICENSE.md,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+smartsheet_python_sdk-3.3.0.dist-info/licenses/NOTICE,sha256=mXr2ryVjnCjykeW0J79kFfVXQG_Z9SV4BV_QPNENW1U,420
+smartsheet_python_sdk-3.3.0.dist-info/METADATA,sha256=vtEVUHYsmSPTVCq_SkmyRJTKmq9nTBn_DW8EoZmYFbs,4987
+smartsheet_python_sdk-3.3.0.dist-info/WHEEL,sha256=AeO2BvogYWm3eGaHCvhzmUYt8ia7KfURiHzO_1atlys,109
+smartsheet_python_sdk-3.3.0.dist-info/top_level.txt,sha256=kozWEYiKjyJmSXzd6p5ugkQ5bhoHS9V3NnvLagUfcNw,11
+smartsheet_python_sdk-3.3.0.dist-info/RECORD,,

{smartsheet_python_sdk-3.2.0.dist-info → smartsheet_python_sdk-3.3.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.45.1)
+Generator: setuptools (79.0.1)
 Root-Is-Purelib: true
 Tag: py2-none-any
 Tag: py3-none-any