smartsheet-python-sdk 3.5.5__py3-none-any.whl

smartsheet/events.py

@@ -0,0 +1,79 @@
+# pylint: disable=C0111,R0902,R0913
+# Smartsheet Python SDK.
+#
+# Copyright 2019 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
+
+import logging
+from datetime import datetime
+
+from . import fresh_operation
+
+
+class Events:
+    def __init__(self, smartsheet_obj):
+        """Init Events with base Smartsheet object."""
+        self._base = smartsheet_obj
+        self._log = logging.getLogger(__name__)
+
+    def list_events(
+        self, since=None, to=None, stream_position=None, max_count=None, numeric_dates=None # pylint: disable=invalid-name
+    ):
+        """Get the list of all Events.
+
+        Args:
+            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:
+            EventResult containing Event array as data[]
+        """
+        _op = fresh_operation("list_events")
+        _op["method"] = "GET"
+        _op["path"] = "/events"
+        if isinstance(since, datetime):
+            _op["query_params"]["since"] = since.isoformat()
+        else:
+            _op["query_params"]["since"] = since
+
+        if isinstance(to, datetime):
+            _op["query_params"]["to"] = to.isoformat()
+        else:
+            _op["query_params"]["to"] = to
+        _op["query_params"]["streamPosition"] = stream_position
+        _op["query_params"]["maxCount"] = max_count
+        _op["query_params"]["numericDates"] = numeric_dates
+
+        expected = ["EventResult", "Event"]
+
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response

smartsheet/exceptions.py

@@ -0,0 +1,130 @@
+# pylint: disable=C0302,C0111, E1121
+# Smartsheet Python SDK.
+#
+# Copyright 2016 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.
+
+
+
+class SmartsheetException(Exception):
+    """Root for SmartsheetErrors, never raised directly."""
+
+
+class ApiError(SmartsheetException):
+    """Errors produced by the Smartsheet API."""
+
+    def __init__(self, error, message=None, should_retry=False):
+        """
+        An error produced by the API.
+
+        Args:
+            error: An instance of the Error data type.
+            message (str): A human-readable message that can be
+                displayed to the end user. Is None, if unavailable.
+        """
+        super().__init__(error)
+        self.error = error
+        self.message = message
+        self.should_retry = should_retry
+
+    def __repr__(self):
+        return f"ApiError({self.error})"
+
+
+class HttpError(SmartsheetException):
+    """Errors produced at the HTTP layer."""
+
+    def __init__(self, status_code, body):
+        super().__init__(status_code, body)
+        self.status_code = status_code
+        self.body = body
+
+    def __repr__(self):
+        return f"HttpError({self.status_code}, {self.body!r})"
+
+
+class InternalServerError(HttpError):
+    """Errors due to a problem on Smartsheet."""
+
+    def __init__(self, status_code, message):
+        super().__init__(status_code, status_code, message)
+        self.status_code = status_code
+        self.message = message
+
+    def __repr__(self):
+        return f"InternalServerError({self.status_code}, {self.message!r})"
+
+
+class UnexpectedRequestError(SmartsheetException):
+    """Error originating from Requests API."""
+
+    def __init__(self, request, response):
+        super().__init__(request, response)
+        self.request = request
+        self.response = response
+
+    def __repr__(self):
+        return f"UnexpectedRequestError({self.request!r}, {self.response!r})"
+
+
+class SystemMaintenanceError(ApiError):
+    """Smartsheet.com is currently offline for system maintenance. ..."""
+
+    def __init__(self, error, message):
+        super().__init__(error, message, True)
+        self.error = error
+        self.message = message
+        self.should_retry = True
+
+    def __repr__(self):
+        return f"SystemMaintenanceError({self.message!r})"
+
+
+class ServerTimeoutExceededError(ApiError):
+    """Server timeout exceeded. Request has failed."""
+
+    def __init__(self, error, message):
+        super().__init__(error, message, True)
+        self.error = error
+        self.message = message
+        self.should_retry = True
+
+    def __repr__(self):
+        return f"ServerTimeoutExceededError({self.message!r})"
+
+
+class RateLimitExceededError(ApiError):
+    """Rate limit exceeded."""
+
+    def __init__(self, error, message):
+        super().__init__(error, message, True)
+        self.error = error
+        self.message = message
+        self.should_retry = True
+
+    def __repr__(self):
+        return f"RateLimitExceededError({self.message!r})"
+
+
+class UnexpectedErrorShouldRetryError(ApiError):
+    """An unexpected error has occurred. Please retry your request. If ..."""
+
+    def __init__(self, error, message):
+        super().__init__(error, message, True)
+        self.error = error
+        self.message = message
+        self.should_retry = True
+
+    def __repr__(self):
+        return f"UnexpectedErrorShouldRetryError({self.message!r})"

smartsheet/favorites.py

@@ -0,0 +1,116 @@
+# pylint: disable=C0111,R0902,R0913
+# Smartsheet Python SDK.
+#
+# Copyright 2016 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
+
+import logging
+
+from . import fresh_operation
+
+
+class Favorites:
+
+    """Class for handling Favorites operations."""
+
+    def __init__(self, smartsheet_obj):
+        """Init Favorites with base Smartsheet object."""
+        self._base = smartsheet_obj
+        self._log = logging.getLogger(__name__)
+
+    def add_favorites(self, favorite_obj):
+        """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.
+
+        Args:
+            favorite_obj (list[Favorite]): Array of one or
+                more Favorite objects
+
+        Returns:
+            Result
+        """
+        _op = fresh_operation("add_favorites")
+        _op["method"] = "POST"
+        _op["path"] = "/favorites"
+        _op["json"] = favorite_obj
+
+        expected = ["Result", "Favorite"]
+
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def list_favorites(self, page_size=None, page=None, include_all=None):
+        """Get a list of all the user's Favorite items.
+
+        Args:
+            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:
+            IndexResult
+        """
+        _op = fresh_operation("list_favorites")
+        _op["method"] = "GET"
+        _op["path"] = "/favorites"
+        _op["query_params"]["pageSize"] = page_size
+        _op["query_params"]["page"] = page
+        _op["query_params"]["includeAll"] = include_all
+
+        expected = ["IndexResult", "Favorite"]
+
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def remove_favorites(self, favorite_type, object_ids):
+        """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.
+
+        Args:
+            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:
+            Result
+        """
+        _op = fresh_operation("remove_favorites")
+        _op["method"] = "DELETE"
+        _op["path"] = "/favorites/" + str(favorite_type)
+        _op["query_params"]["objectIds"] = object_ids
+
+        expected = ["Result", None]
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response