# Synology Drive API
[](https://pepy.tech/project/synology-drive-api)
[](https://opensource.org/licenses/MIT)
`synology-drive-api` is inspired by [synology-api](https://github.com/N4S4/synology-api).
This repo is aimed at providing **Synology drive** api wrapper and related helper functions. It helps you manage your files/folders/labels in synology drive. By means of Synology Office, you can edit spreadsheet on Drive and use this api wrapper read spreadsheet. It supports Python 3.7+.
## Installation
```bash
pip install synology-drive-api
```
## Get login session
You can access drive by IP, drive domain or nas domain + drive path.
> Synology Drive allows same user with multiple login session. if you need multiple login session and label functions, disable label cache.
```python
from synology_drive_api.drive import SynologyDrive
# default http port is 5000, https is 5001.
with SynologyDrive(NAS_USER, NAS_PASS, NAS_IP) as synd:
synd.list_folder('/mydrive') # write your code here
# Use specified port
with SynologyDrive(NAS_USER, NAS_PASS, NAS_IP, NAS_PORT) as synd:
synd.get_file_or_folder_info(path_or_path_id) # write your code here
# use http instead of https. https: default is True.
with SynologyDrive(NAS_USER, NAS_PASS, NAS_IP, https=False) as synd:
synd.create_folder('test', 'team-folder/folder2/') # write your code here
# Enable 2fa.
with SynologyDrive(NAS_USER, NAS_PASS, otp_code='XXXXXX') as synd:
synd.list_folder('/mydrive') # write your code here
# use domain name or name + path access drive
# Enabled in Application Portal | Application | Drive | General | Enable customized alias
drive_path_demo = 'your_nas_domain/drive'
# Enabled in Application Portal | Application | Drive | General | Enable customized domain
drive_path_demo2 = 'your_drive_domain'
with SynologyDrive(NAS_USER, NAS_PASS, drive_path_demo) as synd:
synd.upload_file(file, dest_folder_path=dest_folder_path) # write your code here
# disable label cache
with SynologyDrive(NAS_USER, NAS_PASS, drive_path_demo, enable_label_cache=False) as synd:
synd.list_folder('/mydrive') # write your code here
```
If you use dsm 7, default dsm_version is '6'.
```python
from synology_drive_api.drive import SynologyDrive
# default http port is 5000, https is 5001.
with SynologyDrive(NAS_USER, NAS_PASS, NAS_IP, dsm_version='7') as synd:
synd.download_file('/mydrive/test.osheet') # write your code here
```
## Manage labels
Synology drive thinks labels need to belong to single user. **If you want share labels between users, you should have access to these user accounts.** Another solution is creating a *tool user*.
Synology drive search function provide label union search rather than intersection search. **If you need label intersection search, combine them into one label.**
### Get label info
```python
# get single label info
synd.get_labels('your_label_name')
# get all labels info
synd.get_labels()
```
### Create/delete label
Label name is unique in drive.
```python
# create a label, color name: gray/red/orange/yellow/green/blue/purple.
# default color is gray, default position is end of labels. 0 is first position.
ret = synd.create_label('your_label_name', color='orange', pos=0)
# delete label by name/id.
ret = synd.delete_label('your_label_name')
ret = synd.delete_label(label_id=419)
```
### Add/delete path label
```python
# acition：add, delete
synd.manage_path_label(action, path, label)
```
path examples:
```python
1. '/team-folders/test_drive/SCU285/test.xls', '/mydrive/test_sheet_file.osheet'
2. '505415003021516807'
3. ['505415003021516807', '505415003021516817']
4. ["id:505415003021516807", "id:525657984139799470", "id:525657984810888112"]
5. ['/team-folders/test_drive/SCU285/test.xls', '/team-folders/test_drive/SCU283/test2.xls']
```
label examples:
```python
1. 'label_name'
2. ['label_name_1', 'lable_name_2']
3. [{"action": "add", "label_id": "15"}, {"action": "add", "label_id": "16"}]
```
### List labelled files
Filter files or folders by single label. If you want to use label union search, use search functions (todo).
```python
synd.list_labelled_file(label_name='your_label_name')
```
## Manage File/Folder
>Team folder start with `/team-folders/`, Private folder start with `/mydrive/`
### List TeamFolder
Teamfolder is virtual parent folder of shared folders in Synology drive. When you login in Drive, you can see your authorized shared folder.
```python
synd.get_teamfolder_info()
# {sub_folder_name: folder_id, ...}
```
### List Folder
List Folder or files info of a folder
```python
synd.list_folder('/mydrive')
```
### Get specific folder or file info
Get folder or file info such as created time.
```python
# file_path or file_id "552146100935505098"
synd.get_file_or_folder_info(path_or_path_id)
```
### Create Folder
```python
# create folder in your private folder
synd.create_folder(folder_name)
# create folder in dest folder
synd.create_folder('test', 'team-folder/folder2/')
```
### Upload file
You don't need create folder subfolder before uploading your file.
```python
# prepare your file
file = io.BytesIO(mail_attachment['file'])
# add a file name to file
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'
bio = synd.download_file(f'/mydrive/{file_name}')
with open(file_name, 'wb') as f:
f.write(bio.getvalue())
```
### Download Synology office file
```python
import pandas as pd
# download osheet as xlsx and read into pandas dataframe.
bio = synd.download_synology_office_file('/mydrive/test.osheet') # or
bio = synd.download_file('/mydrive/test.osheet')
pd.read_excel(bio, sheet_name=None)
# dowloand odoc as docx
bio = synd.download_synology_office_file('/mydrive/test.odoc')
with open('test.docx', 'wb') as f:
f.write(bio.getvalue())
```
### Delete file or folder
Delete file or folder is an async task.
```python
synd.delete_path('/mydrive/abc_folder')
synd.delete_path('598184594644187768')
```
### Rename file or folder
```python
# Rename file '/mydrive/H3_AP201812091265503218_1.pdf' to '/mydrive/new.pdf'
synd.rename_path('new.pdf', '/mydrive/H3_AP201812091265503218_1.pdf')
# Rename folder '/mydrive/test_folder' to '/mydrive/abc_folder'
synd.rename_path('abc_folder', '/mydrive/test_folder')
```
### Share file or folder
Get unique file url.
```python
synd.create_link('team-folders/operation/H3_AP201812091265503218_1.pdf')
```
Raw data
{
"_id": null,
"home_page": "https://github.com/zbjdonald/synology-drive-api",
"name": "synology-drive-api",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "synology,synology-drive",
"author": "zbjdonald",
"author_email": "zbjdonald@qq.com",
"download_url": "https://files.pythonhosted.org/packages/95/92/7815ea1aaf8b0a601ce41da51bab9010e66cc58f0a88aef5320649e6aafd/synology_drive_api-1.0.15.tar.gz",
"platform": null,
"description": "# Synology Drive API\n[](https://pepy.tech/project/synology-drive-api)\n\n[](https://opensource.org/licenses/MIT)\n\n\n`synology-drive-api` is inspired by [synology-api](https://github.com/N4S4/synology-api). \nThis repo is aimed at providing **Synology drive** api wrapper and related helper functions. It helps you manage your files/folders/labels in synology drive. By means of Synology Office, you can edit spreadsheet on Drive and use this api wrapper read spreadsheet. It supports Python 3.7+.\n\n## Installation\n```bash\npip install synology-drive-api\n```\n\n## Get login session\n\nYou can access drive by IP, drive domain or nas domain + drive path. \n\n> Synology Drive allows same user with multiple login session. if you need multiple login session and label functions, disable label cache.\n\n```python\nfrom synology_drive_api.drive import SynologyDrive\n\n# default http port is 5000, https is 5001. \nwith SynologyDrive(NAS_USER, NAS_PASS, NAS_IP) as synd:\n synd.list_folder('/mydrive') # write your code here\n# Use specified port\nwith SynologyDrive(NAS_USER, NAS_PASS, NAS_IP, NAS_PORT) as synd:\n synd.get_file_or_folder_info(path_or_path_id) # write your code here\n# use http instead of https. https: default is True.\nwith SynologyDrive(NAS_USER, NAS_PASS, NAS_IP, https=False) as synd:\n synd.create_folder('test', 'team-folder/folder2/') # write your code here\n# Enable 2fa.\nwith SynologyDrive(NAS_USER, NAS_PASS, otp_code='XXXXXX') as synd:\n synd.list_folder('/mydrive') # write your code here\n# use domain name or name + path access drive\n# Enabled in Application Portal | Application | Drive | General | Enable customized alias\ndrive_path_demo = 'your_nas_domain/drive'\n# Enabled in Application Portal | Application | Drive | General | Enable customized domain\ndrive_path_demo2 = 'your_drive_domain'\nwith SynologyDrive(NAS_USER, NAS_PASS, drive_path_demo) as synd:\n synd.upload_file(file, dest_folder_path=dest_folder_path) # write your code here\n# disable label cache\nwith SynologyDrive(NAS_USER, NAS_PASS, drive_path_demo, enable_label_cache=False) as synd:\n synd.list_folder('/mydrive') # write your code here\n```\nIf you use dsm 7, default dsm_version is '6'. \n```python\nfrom synology_drive_api.drive import SynologyDrive\n\n# default http port is 5000, https is 5001. \nwith SynologyDrive(NAS_USER, NAS_PASS, NAS_IP, dsm_version='7') as synd:\n synd.download_file('/mydrive/test.osheet') # write your code here\n```\n## Manage labels\n\nSynology drive thinks labels need to belong to single user. **If you want share labels between users, you should have access to these user accounts.** Another solution is creating a *tool user*.\n\nSynology drive search function provide label union search rather than intersection search. **If you need label intersection search, combine them into one label.**\n\n### Get label info\n\n```python\n# get single label info\nsynd.get_labels('your_label_name')\n# get all labels info\nsynd.get_labels()\n```\n\n### Create/delete label\n\nLabel name is unique in drive.\n\n```python\n# create a label, color name: gray/red/orange/yellow/green/blue/purple.\n# default color is gray, default position is end of labels. 0 is first position.\nret = synd.create_label('your_label_name', color='orange', pos=0)\n# delete label by name/id.\nret = synd.delete_label('your_label_name')\nret = synd.delete_label(label_id=419)\n```\n\n### Add/delete path label\n\n```python\n# acition\uff1aadd, delete\nsynd.manage_path_label(action, path, label)\n```\n\npath examples:\n\n```python\n1. '/team-folders/test_drive/SCU285/test.xls', '/mydrive/test_sheet_file.osheet'\n2. '505415003021516807'\n3. ['505415003021516807', '505415003021516817']\n4. [\"id:505415003021516807\", \"id:525657984139799470\", \"id:525657984810888112\"]\n5. ['/team-folders/test_drive/SCU285/test.xls', '/team-folders/test_drive/SCU283/test2.xls']\n```\n\nlabel examples:\n\n```python\n1. 'label_name'\n2. ['label_name_1', 'lable_name_2']\n3. [{\"action\": \"add\", \"label_id\": \"15\"}, {\"action\": \"add\", \"label_id\": \"16\"}]\n```\n\n### List labelled files\n\nFilter files or folders by single label. If you want to use label union search, use search functions (todo).\n\n```python\nsynd.list_labelled_file(label_name='your_label_name')\n```\n\n## Manage File/Folder\n\n>Team folder start with `/team-folders/`, Private folder start with `/mydrive/`\n\n### List TeamFolder\n\nTeamfolder is virtual parent folder of shared folders in Synology drive. When you login in Drive, you can see your authorized shared folder.\n\n```python\nsynd.get_teamfolder_info()\n# {sub_folder_name: folder_id, ...}\n```\n\n### List Folder\n\nList Folder or files info of a folder\n\n```python\nsynd.list_folder('/mydrive')\n```\n\n### Get specific folder or file info\n\nGet folder or file info such as created time.\n\n```python\n# file_path or file_id \"552146100935505098\"\nsynd.get_file_or_folder_info(path_or_path_id)\n```\n\n### Create Folder\n\n```python\n# create folder in your private folder\nsynd.create_folder(folder_name)\n# create folder in dest folder\nsynd.create_folder('test', 'team-folder/folder2/')\n```\n\n### Upload file\n\nYou don't need create folder subfolder before uploading your file.\n\n```python\n# prepare your file\nfile = io.BytesIO(mail_attachment['file'])\n# add a file name to file\nfile.name = strip_file_name(mail_attachment['name'])\nret_upload = synd.upload_file(file, dest_folder_path=dest_folder_path)\n# upload to your private folder\nret_upload = synd.upload_file(file)\n# custom conflict_action: 'version' to rewrite, 'autorename' to rename. Default: 'version'\nret_upload = synd.upload_file(file, dest_folder_path=dest_folder_path, conflict_action='version')\n```\n\nYou can upload xlsx or docx as synology office file.\n\n**[\\*\\*Deprecation hint\\*\\*]** This API will be deprecated in the future. It's recommended to call `upload_file` and `convert_to_online_office` by yourself.\n\n``` python\n# custom upload_conflict_action for upload: 'version' to rewrite, 'autorename' to rename. Default: 'version'\n# custom convert_conflict_action for convert: 'version' to rewrite, 'autorename' to rename. Default: 'autorename'\nwith open('test.xlsx', 'rb') as file:\n nas_client.upload_as_synology_office_file(file, '/mydrive/')\n```\n\n### Convert to online office\n\nTransform docx/xlsx/pptx to Synology online office file.\n\n```python\n# If delete_original_file is True, origin docx/xlsx/pptx will be deleted after transformed. Default: True\n# custom conflict_action: 'version' to rewrite, 'autorename' to rename. Default: 'autorename'\nret_convert = synd.convert_to_online_office(dest_file_path,\n delete_original_file=True,\n conflict_action='autorename')\n```\n\n\n\n### Download file\n\nNew: Support osheet and odoc extensions.\n```python\nfile_name = 'test.osheet'\nbio = synd.download_file(f'/mydrive/{file_name}')\nwith open(file_name, 'wb') as f:\n f.write(bio.getvalue())\n```\n\n### Download Synology office file\n\n```python\nimport pandas as pd\n\n# download osheet as xlsx and read into pandas dataframe.\nbio = synd.download_synology_office_file('/mydrive/test.osheet') # or\nbio = synd.download_file('/mydrive/test.osheet')\npd.read_excel(bio, sheet_name=None)\n\n# dowloand odoc as docx\nbio = synd.download_synology_office_file('/mydrive/test.odoc')\nwith open('test.docx', 'wb') as f:\n f.write(bio.getvalue())\n```\n\n### Delete file or folder\n\nDelete file or folder is an async task.\n\n```python\nsynd.delete_path('/mydrive/abc_folder')\nsynd.delete_path('598184594644187768')\n```\n\n### Rename file or folder\n\n```python\n# Rename file '/mydrive/H3_AP201812091265503218_1.pdf' to '/mydrive/new.pdf'\nsynd.rename_path('new.pdf', '/mydrive/H3_AP201812091265503218_1.pdf')\n# Rename folder '/mydrive/test_folder' to '/mydrive/abc_folder'\nsynd.rename_path('abc_folder', '/mydrive/test_folder')\n```\n\n### Share file or folder\n\nGet unique file url.\n\n```python\nsynd.create_link('team-folders/operation/H3_AP201812091265503218_1.pdf')\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "synology drive api python wrapper",
"version": "1.0.15",
"project_urls": {
"Homepage": "https://github.com/zbjdonald/synology-drive-api",
"Repository": "https://github.com/zbjdonald/synology-drive-api"
},
"split_keywords": [
"synology",
"synology-drive"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2747490d94a0e3d199e9f49988bf6a5a738fa1f1e4af61dc7861b607b6c6d55f",
"md5": "56495e55b39b5eb454d0f1cdf1cfe473",
"sha256": "c4ed4ad20d2eee0138cc6a3eaff944c72afa501c6602c02d5127f4f56581becf"
},
"downloads": -1,
"filename": "synology_drive_api-1.0.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "56495e55b39b5eb454d0f1cdf1cfe473",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 15398,
"upload_time": "2023-12-18T09:18:27",
"upload_time_iso_8601": "2023-12-18T09:18:27.544930Z",
"url": "https://files.pythonhosted.org/packages/27/47/490d94a0e3d199e9f49988bf6a5a738fa1f1e4af61dc7861b607b6c6d55f/synology_drive_api-1.0.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "95927815ea1aaf8b0a601ce41da51bab9010e66cc58f0a88aef5320649e6aafd",
"md5": "f6b2b4f9be23767c011b50f650af36cd",
"sha256": "88a5fd3327f61899e68129da693907a8384622de7b4bcf8998639bd785cee52b"
},
"downloads": -1,
"filename": "synology_drive_api-1.0.15.tar.gz",
"has_sig": false,
"md5_digest": "f6b2b4f9be23767c011b50f650af36cd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 16253,
"upload_time": "2023-12-18T09:18:29",
"upload_time_iso_8601": "2023-12-18T09:18:29.663705Z",
"url": "https://files.pythonhosted.org/packages/95/92/7815ea1aaf8b0a601ce41da51bab9010e66cc58f0a88aef5320649e6aafd/synology_drive_api-1.0.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-18 09:18:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zbjdonald",
"github_project": "synology-drive-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "synology-drive-api"
}
JSON
