Merge pull request #14 from fengdasuk19/master

Custom conflict_action for upload file, convert online office file

.gitignore

@@ -185,6 +185,9 @@ npm-debug.log
 # Restrict `.idea/` folder at all:
 .idea/
 
+# Vim
+*.swp
+
 # CMake
 cmake-build-debug/
 

README.md

@@ -164,15 +164,37 @@ file.name = strip_file_name(mail_attachment['name'])
 ret_upload = synd.upload_file(file, dest_folder_path=dest_folder_path)
 # upload to your private folder
 ret_upload = synd.upload_file(file)
+# custom conflict_action: 'version' to rewrite, 'autorename' to rename. Default: 'version'
+ret_upload = synd.upload_file(file, dest_folder_path=dest_folder_path, conflict_action='version')
 ```
 
 You can upload xlsx or docx as synology office file.
+
+**[\*\*Deprecation hint\*\*]** This API will be deprecated in the future. It's recommended to call `upload_file` and `convert_to_online_office` by yourself.
+
 ``` python
+# custom upload_conflict_action for upload: 'version' to rewrite, 'autorename' to rename. Default: 'version'
+# custom convert_conflict_action for convert: 'version' to rewrite, 'autorename' to rename. Default: 'autorename'
 with open('test.xlsx', 'rb') as file:
     nas_client.upload_as_synology_office_file(file, '/mydrive/')
 ```
 
+### Convert to online office
+
+Transform docx/xlsx/pptx to Synology online office file.
+
+```python
+# If delete_original_file is True, origin docx/xlsx/pptx will be deleted after transformed. Default: True
+# custom conflict_action: 'version' to rewrite, 'autorename' to rename. Default: 'autorename'
+ret_convert = synd.convert_to_online_office(dest_file_path,
+                                            delete_original_file=True,
+                                            conflict_action='autorename')
+```
+
+
+
 ### Download file
+
 New: Support osheet and odoc extensions.
 ```python
 file_name = 'test.osheet'

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "synology_drive_api"
-version = "1.0.12"
+version = "1.0.13"
 description = "synology drive api python wrapper"
 authors = ["zbjdonald <[email protected]>"]
 license = "MIT"

synology_drive_api/files.py

@@ -7,6 +7,7 @@
 from synology_drive_api.base import SynologyOfficeFileConvertFailed
 from synology_drive_api.utils import concat_drive_path
 from synology_drive_api.utils import form_urlencoded
+from synology_drive_api.utils import deprecate
 
 
 class FilesMixin:
@@ -130,19 +131,22 @@ def get_file_or_folder_info(self, file_or_folder_path: str) -> dict:
         urlencoded_data = form_urlencoded(data)
         return self.session.http_post(endpoint, data=urlencoded_data)
 
-    def upload_file(self, file: Union[io.BytesIO, BinaryIO], dest_folder_path: Optional[str] = None) -> dict:
+    def upload_file(self, file: Union[io.BytesIO, BinaryIO], dest_folder_path: Optional[str] = None,
+                    conflict_action='version')-> dict:
         """
         upload file to drive
         :param file: binary_file
         :param dest_folder_path: upload folder path
+        :param conflict_action: 'autorename' to rename the new, 'version' to rewrite the file.
+                                Default is 'version', same as UI default behaviour.
         :return:
         """
         file_name = file.name
         display_path = concat_drive_path(dest_folder_path, file_name)
         api_name = 'SYNO.SynologyDrive.Files'
         endpoint = 'entry.cgi'
         params = {'api': api_name, 'method': 'upload', 'version': 2, 'path': display_path,
-                  'type': 'file', 'conflict_action': 'version'}
+                  'type': 'file', 'conflict_action': conflict_action}
         files = {'file': file}
         upload_ret = self.session.http_post(endpoint, params=params, files=files)
         return upload_ret
@@ -169,11 +173,14 @@ def download_file(self, file_path: str) -> io.BytesIO:
             bio_ret_with_name.name = file_name
         return bio_ret_with_name
 
-    def convert_to_online_office(self, file_path: str, delete_original_file=True):
+    def convert_to_online_office(self, file_path: str, delete_original_file=True, conflict_action='autorename'):
         """
         convert file to online synology office file
+
         :param file_path:
         :param delete_original_file: indicator delete original file or not
+        :param conflict_action: 'autorename' to rename the new, 'version' to rewrite the file
+                                Default is 'autorename', same as UI default behaviour.
         :return:
         """
         if not file_path.isdigit() and '.' not in file_path:
@@ -186,7 +193,7 @@ def convert_to_online_office(self, file_path: str, delete_original_file=True):
         file_id = ret['data']['file_id']
         api_name = 'SYNO.SynologyDrive.Files'
         endpoint = 'entry.cgi'
-        data = {'api': api_name, 'method': 'convert_office', 'version': 2, 'conflict_action': 'autorename',
+        data = {'api': api_name, 'method': 'convert_office', 'version': 2, 'conflict_action': conflict_action,
                 'files': f"[\42id:{file_id}\42]"}
         urlencoded_data = form_urlencoded(data)
         ret = self.session.http_post(endpoint, data=urlencoded_data)
@@ -208,17 +215,26 @@ def convert_to_online_office(self, file_path: str, delete_original_file=True):
             self.delete_path(file_id)
         return ret
 
-    def upload_as_synology_office_file(self, file: Union[io.BytesIO, BinaryIO], dest_folder_path: Optional[str] = None):
+    @deprecate(['upload_file', 'convert_to_online_office'])
+    def upload_as_synology_office_file(self, file: Union[io.BytesIO, BinaryIO], dest_folder_path: Optional[str] = None,
+                                       upload_conflict_action='version', convert_conflict_action='autorename'):
         """
-        upload file to drive, and converted to
+        upload file to drive, and converted to online office file
+
         :param file: binary_file
         :param dest_folder_path: upload folder path
+        :param upload_conflict_action: 'autorename' to rename the new, 'version' to rewrite the file.
+                                        Default is 'version', same as UI default behaviour.
+        :param convert_conflict_action: 'autorename' to rename the new, 'version' to rewrite the file.
+                                        Default is 'autorename', same as UI default behaviour.
         :return:
         """
-        upload_ret = self.upload_file(file, dest_folder_path)
+        upload_ret = self.upload_file(file, dest_folder_path,
+                                      conflict_action=upload_conflict_action)
         # if conversion is failed, delete uploaded file.
         try:
-            convert_ret = self.convert_to_online_office(upload_ret['data']['file_id'])
+            convert_ret = self.convert_to_online_office(upload_ret['data']['file_id'],
+                                                        conflict_action=convert_conflict_action)
         except SynologyOfficeFileConvertFailed as e:
             self.delete_path(upload_ret['data']['file_id'])
             raise e

synology_drive_api/utils.py

@@ -1,4 +1,6 @@
 import urllib.parse
+import warnings
+import functools
 
 import simplejson as json
 from selenium import webdriver
@@ -56,3 +58,18 @@ def concat_drive_path(dest_path: str, end_point: str, default_folder: str = 'myd
         dest_path = f"{dest_path}/" if not dest_path.endswith('/') else dest_path
         display_path = f"{dest_path}{end_point}"
     return display_path
+
+
+def deprecate(alt_func_names):
+    def outer_wrapper(f):
+        @functools.wraps(f)
+        def inner(*args, **kwargs):
+            hint = ', '.join(alt_func_names)
+            warnings.warn(
+                f'[Deprecation] {f.__name__} will be deprecated in the future.'
+                f'Substitutions are: {hint}',
+                FutureWarning
+            )
+            return f(*args, **kwargs)
+        return inner
+    return outer_wrapper