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

smartsheet/reports.py

@@ -0,0 +1,382 @@
+# 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
+import os.path
+from datetime import datetime
+
+from . import fresh_operation
+
+
+class Reports:
+
+    """Class for handling Reports operations."""
+
+    def __init__(self, smartsheet_obj):
+        """Init Reports with base Smartsheet object."""
+        self._base = smartsheet_obj
+        self._log = logging.getLogger(__name__)
+
+    def delete_share(self, report_id, share_id):
+        """Deletes the specified Share
+
+        Args:
+            report_id (int): Report ID
+            share_id (str): Share ID
+
+        Returns:
+            Result
+        """
+        _op = fresh_operation("delete_share")
+        _op["method"] = "DELETE"
+        _op["path"] = "/reports/" + str(report_id) + "/shares/" + str(share_id)
+
+        expected = ["Result", None]
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def get_report(
+        self, report_id, page_size=None, page=None, include=None, level=None
+    ):
+        """Get the specified Report, including one page of Rows.
+
+        Get the specified Report, including one page of Rows, and
+        optionally populated with Discussions, Attachments, and
+        Source Sheets.
+
+        Args:
+            report_id (int): Report ID
+            page_size (int): The maximum number of items to return per page.
+            page (int): Which page to return.
+            include (list[str]): A comma-separated list of
+                optional elements to include in the response. Valid list values:
+                attachments, discussions, format, objectValue, scope, source, sourceSheets.
+            level (int): compatibility level
+
+        Returns:
+            Report
+        """
+        _op = fresh_operation("get_report")
+        _op["method"] = "GET"
+        _op["path"] = "/reports/" + str(report_id)
+        _op["query_params"]["pageSize"] = page_size
+        _op["query_params"]["page"] = page
+        _op["query_params"]["include"] = include
+        _op["query_params"]["level"] = level
+
+        expected = "Report"
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def get_report_as_csv(self, report_id, download_path, alternate_file_name=None):
+        """Get the specified Report as a CSV file.
+
+        Args:
+            report_id (int): Report ID
+            download_path (str): Directory path on local
+                machine to save file.
+            alternate_file_name (str): Filename to use
+                instead of name suggested by Content-Disposition.
+
+        Returns:
+            DownloadedFile
+        """
+        if not os.path.isdir(download_path):
+            raise ValueError("download_path must be a directory.")
+
+        _op = fresh_operation("get_report_as_csv")
+        _op["method"] = "GET"
+        _op["path"] = "/reports/" + str(report_id)
+        _op["header_params"]["Accept"] = "text/csv"
+        _op["dl_path"] = download_path
+
+        expected = "DownloadedFile"
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+        if alternate_file_name is not None:
+            response.filename = alternate_file_name
+
+        response.save_to_file()
+        return response
+
+    def get_report_as_excel(self, report_id, download_path, alternate_file_name=None):
+        """Get the specified Report as an Excel .xls document.
+
+        Args:
+            report_id (int): Report ID
+            download_path (str): Directory path on local
+                machine to save file.
+            alternate_file_name (str): Filename to use
+                instead of name suggested by Content-Disposition.
+
+        Returns:
+            DownloadedFile
+        """
+        if not os.path.isdir(download_path):
+            raise ValueError("download_path must be a directory.")
+
+        _op = fresh_operation("get_report_as_excel")
+        _op["method"] = "GET"
+        _op["path"] = "/reports/" + str(report_id)
+        _op["header_params"]["Accept"] = "application/vnd.ms-excel"
+        _op["dl_path"] = download_path
+
+        expected = "DownloadedFile"
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+        if alternate_file_name is not None:
+            response.filename = alternate_file_name
+
+        response.save_to_file()
+        return response
+
+    def get_share(self, report_id, share_id):
+        """Get the specified Share.
+
+        Args:
+            report_id (int): Report ID
+            share_id (str): Share ID
+
+        Returns:
+            Share
+        """
+        _op = fresh_operation("get_share")
+        _op["method"] = "GET"
+        _op["path"] = "/reports/" + str(report_id) + "/shares/" + str(share_id)
+
+        expected = "Share"
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def list_reports(
+        self, page_size=None, page=None, include_all=None, modified_since=None
+    ):
+        """Get the list of all Reports accessible by the User.
+
+        Get the list of all Reports that the User has access to, in
+        alphabetical order by name.
+
+        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).
+            modified_since(datetime): return reports modified after the specified modified_since
+
+        Returns:
+            IndexResult
+        """
+        _op = fresh_operation("list_reports")
+        _op["method"] = "GET"
+        _op["path"] = "/reports"
+        _op["query_params"]["pageSize"] = page_size
+        _op["query_params"]["page"] = page
+        _op["query_params"]["includeAll"] = include_all
+        if isinstance(modified_since, datetime):
+            _op["query_params"]["modifiedSince"] = modified_since.isoformat()
+
+        expected = ["IndexResult", "Report"]
+
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def list_shares(
+        self,
+        report_id,
+        page_size=None,
+        page=None,
+        include_all=None,
+        include_workspace_shares=False,
+    ):
+        """Get a list of all Users and Groups to whom the specified Report is
+        shared, and their access level.
+
+        Args:
+            report_id (int): Report ID
+            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).
+            include_workspace_shares(bool): include Workspace shares
+
+        Returns:
+            IndexResult
+        """
+        _op = fresh_operation("list_shares")
+        _op["method"] = "GET"
+        _op["path"] = "/reports/" + str(report_id) + "/shares"
+        _op["query_params"]["pageSize"] = page_size
+        _op["query_params"]["page"] = page
+        _op["query_params"]["includeAll"] = include_all
+        if include_workspace_shares:
+            _op["query_params"]["include"] = "workspaceShares"
+
+        expected = ["IndexResult", "Share"]
+
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def send_report(self, report_id, sheet_email_obj):
+        """Send the specified Report as a PDF attachment via email to the
+        designated recipients.
+
+        Args:
+            report_id (int): Report ID
+            sheet_email_obj (SheetEmail): SheetEmail object.
+
+        Returns:
+            Result
+        """
+        _op = fresh_operation("send_report")
+        _op["method"] = "POST"
+        _op["path"] = "/reports/" + str(report_id) + "/emails"
+        _op["json"] = sheet_email_obj
+
+        expected = ["Result", None]
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def share_report(self, report_id, share_obj, send_email=False):
+        """Shares a Report with the specified Users and Groups.
+
+        Args:
+            report_id (int): Report ID
+            share_obj (Share): Share object.
+            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_report")
+        _op["method"] = "POST"
+        _op["path"] = "/reports/" + str(report_id) + "/shares"
+        _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_share(self, report_id, share_id, share_obj):
+        """Update the access level of a User or Group for the specified Report
+
+        Args:
+            report_id (int): Report ID
+            share_id (str): Share ID
+            share_obj (Share): Share object.
+
+        Returns:
+            Result
+        """
+        if not all(val is not None for val in ["report_id", "share_id", "share_obj"]):
+            raise ValueError(
+                ("One or more required values are missing from call to " + __name__)
+            )
+
+        _op = fresh_operation("update_share")
+        _op["method"] = "PUT"
+        _op["path"] = "/reports/" + str(report_id) + "/shares/" + str(share_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 get_publish_status(self, report_id):
+        """Get the Publish status of the Report.
+
+        Get the status of the Publish settings of the Report,
+        including URLs of any enabled publishings.
+
+        Args:
+            report_id (int): Report ID
+
+        Returns:
+            ReportPublish
+        """
+        _op = fresh_operation("get_publish_status")
+        _op["method"] = "GET"
+        _op["path"] = "/reports/" + str(report_id) + "/publish"
+
+        expected = "ReportPublish"
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def set_publish_status(self, report_id, report_publish_obj):
+        """Set the publish status of the Report and returns the new status,
+        including the URLs of any enabled publishings.
+
+        Args:
+            report_id (int): Report ID
+            report_publish_obj (ReportPublish): ReportPublish
+                object.
+
+        Returns:
+            Result
+        """
+        attributes = ["read_only_full_enabled", "read_only_full_accessible_by"]
+
+        fetch_first = False
+        # check for incompleteness, fill in from current status if necessary
+        for attribute in attributes:
+            val = getattr(report_publish_obj, attribute, None)
+            if val is None:
+                fetch_first = True
+                break
+
+        if fetch_first:
+            current_status = self.get_publish_status(report_id).to_dict()
+            current_status.update(report_publish_obj.to_dict())
+            report_publish_obj = self._base.models.ReportPublish(current_status)
+
+        _op = fresh_operation("set_publish_status")
+        _op["method"] = "PUT"
+        _op["path"] = "/reports/" + str(report_id) + "/publish"
+        _op["json"] = report_publish_obj
+
+        expected = ["Result", "ReportPublish"]
+
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response

smartsheet/search.py

@@ -0,0 +1,100 @@
+# 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 datetime import datetime
+
+from . import fresh_operation
+
+
+class Search:
+
+    """Class for handling Search operations."""
+
+    def __init__(self, smartsheet_obj):
+        """Init Search with base Smartsheet object."""
+        self._base = smartsheet_obj
+        self._log = logging.getLogger(__name__)
+
+    def search(
+        self, query, include=None, location=None, modified_since=None, scopes=None
+    ):
+        """Search all Sheets the User can access for the specified text.
+
+        Args:
+            query (str): Text with which to perform the search.
+            include (str): when specified with a value of 'favoriteFlag',
+                response indicates which returned items are favorites
+            location (str): when specified with a value of 'personalWorkspace',
+                limits the response to only those items in the user's Workspaces
+            modified_since (str): includes items that are modified on or after the
+                date and time specified
+            scopes (str): comma-separated list of search filters:
+                attachments
+                cellData
+                comments
+                folderNames
+                profileFields
+                reportNames
+                sheetNames
+                sightNames
+                summaryFields
+                templateNames
+                workspaceNames
+
+        Returns:
+            SearchResult
+        """
+        _op = fresh_operation("search")
+        _op["method"] = "GET"
+        _op["path"] = "/search"
+        _op["query_params"]["query"] = query
+        _op["query_params"]["include"] = include
+        _op["query_params"]["location"] = location
+        _op["query_params"]["scopes"] = scopes
+        if isinstance(modified_since, datetime):
+            _op["query_params"]["modifiedSince"] = modified_since.isoformat()
+
+        expected = "SearchResult"
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response
+
+    def search_sheet(self, sheet_id, query):
+        """Search the specified Sheet for the specified text.
+
+        Args:
+            sheet_id (int): Sheet ID
+            query (str): Text with which to perform the
+                search.
+
+        Returns:
+            SearchResult
+        """
+        _op = fresh_operation("search_sheet")
+        _op["method"] = "GET"
+        _op["path"] = "/search/sheets/" + str(sheet_id)
+        _op["query_params"]["query"] = query
+
+        expected = "SearchResult"
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response

smartsheet/server.py

@@ -0,0 +1,48 @@
+# 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 Server:
+
+    """Class for handling Server operations."""
+
+    def __init__(self, smartsheet_obj):
+        """Init Server with base Smartsheet object."""
+        self._base = smartsheet_obj
+        self._log = logging.getLogger(__name__)
+
+    def server_info(self):
+        """Get application constants.
+        Returns:
+            ServerInfo
+        """
+        _op = fresh_operation("server_info")
+        _op["method"] = "GET"
+        _op["path"] = "/serverinfo"
+        _op["auth_settings"] = None
+
+        expected = "ServerInfo"
+        prepped_request = self._base.prepare_request(_op)
+        response = self._base.request(prepped_request, expected, _op)
+
+        return response

smartsheet/session.py

@@ -0,0 +1,70 @@
+# pylint: disable=E0401,W0221,W0613
+# 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.
+
+# pylint: disable=no-member
+# known issue regarding ssl module and pylint.
+
+import ssl
+
+import certifi
+import requests
+from requests.adapters import HTTPAdapter
+from requests.packages.urllib3.poolmanager import PoolManager
+from requests.packages.urllib3.util import Retry
+
+_TRUSTED_CERT_FILE = certifi.where()
+
+
+class _SSLAdapter(HTTPAdapter):
+    def create_ssl_context(self):
+        ctx = ssl.create_default_context()
+        ctx.options |= ssl.OP_NO_SSLv2
+        ctx.options |= ssl.OP_NO_SSLv3
+        ctx.options |= ssl.OP_NO_TLSv1
+        return ctx
+
+    def init_poolmanager(self, connections, maxsize, block=False):
+        self.poolmanager = PoolManager(
+            num_pools=connections,
+            maxsize=maxsize,
+            block=block,
+            cert_reqs=ssl.CERT_REQUIRED,
+            ca_certs=_TRUSTED_CERT_FILE,
+            ssl_context=self.create_ssl_context(),
+        )
+
+
+def pinned_session(pool_maxsize=8):
+    http_adapter = _SSLAdapter(
+        pool_connections=4,
+        pool_maxsize=pool_maxsize,
+        max_retries=Retry(
+            total=1, allowed_methods=Retry.DEFAULT_ALLOWED_METHODS.union(["POST"])
+        ),
+    )
+
+    _session = requests.session()
+    _session.hooks = {"response": redact_token}
+    _session.mount("https://", http_adapter)
+
+    return _session
+
+
+def redact_token(res, *args, **kwargs):
+    if "Authorization" in res.request.headers:
+        res.request.headers.update({"Authorization": "[redacted]"})
+    return res