Add support for uploading local files when creating a message

Enhance the CiscoSparkAPI.messages.create() method by adding support
for uploading local files.  The files argument should contain a list
with a single item that is either an Internet HTTP/HTTPS URL or a path
to a local file.

Author: cmlccie

ciscosparkapi/api/messages.py

@@ -12,8 +12,11 @@
 from builtins import object
 from six import string_types
 
+from requests_toolbelt import MultipartEncoder
+
 from ciscosparkapi.exceptions import ciscosparkapiException
-from ciscosparkapi.helper import generator_container
+from ciscosparkapi.helper import generator_container, is_web_url, \
+    is_local_file, open_local_file
 from ciscosparkapi.restsession import RestSession
 from ciscosparkapi.sparkdata import SparkData
 
@@ -196,7 +199,11 @@ def create(self, roomId=None, toPersonId=None, toPersonEmail=None,
                 specified this parameter may be optionally used to provide
                 alternate text forUI clients that do not support rich text.
             markdown(string_types): The message, in markdown format.
-            files(list): A list of URL references for the message attachments.
+            files(list): A list containing local paths or URL references for
+                the message attachment(s).  The files attribute currently only
+                takes a list containing one (1) filename or URL as an input.
+                This is a Spark API limitation that may be lifted at a later
+                date.
 
         Returns:
             Message: With the details of the created message.
@@ -216,6 +223,7 @@ def create(self, roomId=None, toPersonId=None, toPersonEmail=None,
         assert markdown is None or isinstance(markdown, string_types)
         assert files is None or isinstance(files, list)
         post_data = {}
+        # Where is message to be posted?
         if roomId:
             post_data['roomId'] = roomId
         elif toPersonId:
@@ -227,18 +235,45 @@ def create(self, roomId=None, toPersonId=None, toPersonEmail=None,
                             "toPersonEmail to which you want to post a new " \
                             "message."
             raise ciscosparkapiException(error_message)
+        # Ensure some message 'content' is provided.
         if not text and not markdown and not files:
             error_message = "You must supply some message content (text, " \
                             "markdown, files) when posting a message."
             raise ciscosparkapiException(error_message)
+        # Process the content.
         if text:
             post_data['text'] = text
         if markdown:
             post_data['markdown'] = markdown
+        upload_local_file = False
         if files:
-            post_data['files'] = files
+            if len(files) > 1:
+                error_message = "The files attribute currently only takes a " \
+                                "list containing one (1) filename or URL as " \
+                                "an input.  This is a Spark API limitation " \
+                                "that may be lifted at a later date."
+                raise ciscosparkapiException(error_message)
+            if is_web_url(files[0]):
+                post_data['files'] = files
+            elif is_local_file(files[0]):
+                upload_local_file = True
+                post_data['files'] = open_local_file(files[0])
+            else:
+                error_message = "The provided files argument does not " \
+                                "contain a valid URL or local file path."
+                raise ciscosparkapiException(error_message)
         # API request
-        json_obj = self.session.post('messages', json=post_data)
+        if upload_local_file:
+            try:
+                multipart_data = MultipartEncoder(post_data)
+                headers = {'Content-type': multipart_data.content_type}
+                json_obj = self.session.post('messages',
+                                             data=multipart_data,
+                                             headers=headers)
+            finally:
+                post_data['files'].file_object.close()
+        else:
+            json_obj = self.session.post('messages', json=post_data)
         # Return a Message object created from the response JSON data
         return Message(json_obj)
 

ciscosparkapi/helper.py

@@ -5,8 +5,12 @@
 from future import standard_library
 standard_library.install_aliases()
 from builtins import object
+from six import string_types
 
+from collections import namedtuple
 import functools
+import mimetypes
+import os
 import urllib.parse
 
 from ciscosparkapi import ciscosparkapiException, SparkApiError
@@ -21,6 +25,10 @@
 }
 
 
+EncodableFile = namedtuple('EncodableFile',
+                           ['file_name', 'file_object', 'content_type'])
+
+
 def validate_base_url(base_url):
     """Verify that base_url specifies a protocol and network location."""
     parsed_url = urllib.parse.urlparse(base_url)
@@ -32,6 +40,36 @@ def validate_base_url(base_url):
         raise ciscosparkapiException(error_message)
 
 
+def is_web_url(string):
+    """Check to see if string is an validly-formatted web url."""
+    assert isinstance(string, string_types)
+    parsed_url = urllib.parse.urlparse(string)
+    if (parsed_url.scheme.lower() == 'http' \
+        or parsed_url.scheme.lower() == 'https') \
+        and parsed_url.netloc:
+        return True
+    else:
+        return False
+
+
+def is_local_file(string):
+    """Check to see if string is a valid local file path."""
+    assert isinstance(string, string_types)
+    return os.path.isfile(string)
+
+
+def open_local_file(file_path):
+    """Open the file and return an EncodableFile tuple."""
+    assert isinstance(file_path, string_types)
+    assert is_local_file(file_path)
+    file_name = os.path.basename(file_path)
+    file_object = open(file_path, 'rb')
+    content_type = mimetypes.guess_type(file_name)[0] or 'text/plain'
+    return EncodableFile(file_name=file_name,
+                         file_object=file_object,
+                         content_type=content_type)
+
+
 def raise_if_extra_kwargs(kwargs):
     """Raise a TypeError if kwargs is not empty."""
     if kwargs:

ciscosparkapi/restsession.py

@@ -152,17 +152,31 @@ def get_items(self, url, params=None, **kwargs):
                 for item in items:
                     yield item
 
-    def post(self, url, json, **kwargs):
+    def post(self, url, json=None, data=None, headers=None, **kwargs):
         # Process args
         assert isinstance(url, string_types)
-        assert isinstance(json, dict)
         abs_url = self.urljoin(url)
-        # Process kwargs
-        timeout = kwargs.pop('timeout', self.timeout)
+        # Process listed kwargs
+        request_args = {}
+        assert json is None or isinstance(json, dict)
+        assert headers is None or isinstance(headers, dict)
+        if json and data:
+            raise TypeError("You must provide either a json or data argument, "
+                            "not both.")
+        elif json:
+            request_args['json'] = json
+        elif data:
+            request_args['data'] = data
+        elif not json and not data:
+            raise TypeError("You must provide either a json or data argument.")
+        if headers:
+            request_args['headers'] = headers
+        # Process unlisted kwargs
+        request_args['timeout'] = kwargs.pop('timeout', self.timeout)
         erc = kwargs.pop('erc', ERC['POST'])
         raise_if_extra_kwargs(kwargs)
         # API request
-        response = self._req_session.post(abs_url, json=json, timeout=timeout)
+        response = self._req_session.post(abs_url, **request_args)
         # Process response
         check_response_code(response, erc)
         return extract_and_parse_json(response)

setup.py

@@ -46,7 +46,6 @@
         'Programming Language :: Python :: 2.6',
         'Programming Language :: Python :: 2.7',
         'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.3',
         'Programming Language :: Python :: 3.4',
         'Programming Language :: Python :: 3.5',
         'Topic :: Communications',
@@ -56,5 +55,5 @@
     keywords='cisco spark api enterprise messaging',
 
     packages=['ciscosparkapi', 'ciscosparkapi.api'],
-    install_requires=['requests>=2.4.2', 'six', 'future'],
+    install_requires=['requests>=2.4.2', 'requests_toolbelt', 'six', 'future'],
 )