improved documentation and added test case #81 Umlauts in file_upload()

churchtools_api/files.py

@@ -15,24 +15,22 @@ class ChurchToolsApiFiles(ChurchToolsApiAbstract):
     def __init__(self):
         super()
 
-    def file_upload(self, source_filepath, domain_type,
-                    domain_identifier, custom_file_name=None, overwrite=False):
+    def file_upload(self, source_filepath: str, domain_type: str,
+                    domain_identifier: int, custom_file_name: str = None, overwrite: bool = False) -> bool:
         """
         Helper function to upload an attachment to any module of ChurchTools
-        :param source_filepath: file to be opened e.g. with open('media/pinguin.png', 'rb')
-        :type source_filepath: str
-        :param domain_type:  The ct_domain type, currently supported are 'avatar', 'groupimage', 'logo', 'attatchments',
-         'html_template', 'service', 'song_arrangement', 'importtable', 'person', 'familyavatar', 'wiki_.?'.
-        :type domain_type: str
-        :param domain_identifier: ID of the object in ChurchTools
-        :type domain_identifier: int
-        :param custom_file_name: optional file name - if not specified the one from the file is used
-        :type custom_file_name: str
-        :param overwrite: if true delete existing file before upload of new one to replace \
-        it's content instead of creating a copy
-        :type overwrite: bool
-        :return: if successful
-        :rtype: bool
+
+        Args:
+            source_filepath: file to be opened e.g. with open('media/pinguin.png', 'rb')
+            domain_type: The ct_domain type, currently supported are 'avatar', 'groupimage', 'logo', 'attatchments',
+                     'html_template', 'service', 'song_arrangement', 'importtable', 'person', 'familyavatar', 'wiki_.?'.
+            domain_identifier: ID of the object in ChurchTools
+                     (HINT to work with attachments in songs please keep in mind these are linked with song_arrangements and these IDs differ from songId!)
+            custom_file_name: optional file name - if not specified the one from the file is used
+            overwrite: if true delete existing file before upload of new one to replace
+
+        Returns:
+            if successful
         """
 
         source_file = open(source_filepath, 'rb')

samples/test_umläut.txt

@@ -0,0 +1,2 @@
+This filename has a german "Umlaut" ä in its name and is used to test the api
+If this exists in a song arangement on a live system it can be safely deleted.

tests/test_churchtools_api_files.py

@@ -141,29 +141,49 @@ def test_file_upload_replace_delete(self):
         self.assertEqual(
             len(song['arrangements'][0]['files']), 0, 'check that files are deleted')
 
-    def test_file_download(self):
-        """ Test of file_download and file_download_from_url on https://elkw1610.krz.tools on any song
-        IDs  vary depending on the server used
-        On ELKW1610.KRZ.TOOLS song ID 762 has arrangement 774 does exist
-
-        Uploads a test file
-        downloads the file via same ID
-        checks that file and content match
-        deletes test file
-        """
-        test_id = 762
-
-        self.api.file_upload('samples/test.txt', 'song_arrangement', test_id)
+    def test_file_upload_download(self):
+        """ Test of file_upload, file_download and file_download_from_url
 
-        filePath = 'downloads/test.txt'
-        if os.path.exists(filePath):
-            os.remove(filePath)
+        IDs vary depending on the server used
+        On ELKW1610.KRZ.TOOLS song ID 750 has one arrangement with ID 762
 
-        self.api.file_download('test.txt', 'song_arrangement', test_id)
-        with open(filePath, "r") as file:
-            download_text = file.read()
-        self.assertEqual('TEST CONTENT', download_text)
+        1. Uploads a test file
+        2. downloads the file via same ID
+        3. checks that file and content match
+        4. deletes test file
 
-        self.api.file_delete('song_arrangement', test_id, 'test.txt')
-        if os.path.exists(filePath):
-            os.remove(filePath)
+        uses test.txt and test_umläut.txt
+        """
+        for filename in ['test.txt', 'test_umläut.txt']:
+            # 1 Upload
+            song_test_id = 762
+            filePath_sample = f'samples/{filename}'
+            self.api.file_upload(
+                filePath_sample,
+                'song_arrangement',
+                song_test_id)
+
+            # 2. Download
+            filePath_test = f'downloads/{filename}'
+            if os.path.exists(filePath_test):
+                os.remove(filePath_test)
+
+            self.api.file_download(
+                filename,
+                'song_arrangement',
+                song_test_id)
+
+            # 3. Compare
+            with open(filePath_sample, "r", encoding='utf8') as file:
+                sample_text = file.read()
+            with open(filePath_test, "r", encoding='utf8') as file:
+                test_text = file.read()
+            self.assertEqual(
+                sample_text,
+                test_text,
+                'If download and upload are successful the text should match')
+
+            # 4. Cleanup
+            self.api.file_delete('song_arrangement', song_test_id, filename)
+            if os.path.exists(filePath_test):
+                os.remove(filePath_test)