py-synologydsm-api 2.4.5__py3-none-any.whl

py_synologydsm_api-2.4.5.dist-info/LICENSE.txt

@@ -0,0 +1,8 @@
+The MIT License (MIT)
+Copyright (c) 2020 mib1185
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

py_synologydsm_api-2.4.5.dist-info/METADATA

@@ -0,0 +1,426 @@
+Metadata-Version: 2.1
+Name: py-synologydsm-api
+Version: 2.4.5
+Summary: Python API for communication with Synology DSM
+Home-page: https://github.com/mib1185/py-synologydsm-api#readme
+Author: Michael Brussk (mib1185), Quentin POLLET (Quentame), FG van Zeelst (ProtoThis)
+License: MIT
+Project-URL: Changelog, https://github.com/mib1185/py-synologydsm-api/releases
+Project-URL: Repository, https://github.com/mib1185/py-synologydsm-api
+Project-URL: Documentation, https://github.com/mib1185/py-synologydsm-api#readme
+Keywords: synology-dsm,synology
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8.0
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: aiohttp
+
+# Asynchronous Python API for Synology DSM
+
+[![](https://github.com/mib1185/py-synologydsm-api/workflows/Tests/badge.svg)](https://github.com/mib1185/py-synologydsm-api/actions?query=workflow%3ATests+branch%3Amaster)
+[![Library version](https://img.shields.io/pypi/v/py-synologydsm-api.svg)](https://pypi.org/project/py-synologydsm-api)
+[![Supported versions](https://img.shields.io/pypi/pyversions/py-synologydsm-api.svg)](https://pypi.org/project/py-synologydsm-api)
+[![Downloads](https://pepy.tech/badge/py-synologydsm-api)](https://pypi.org/project/py-synologydsm-api)
+[![Formated with Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+# Installation
+
+```bash
+[sudo] pip install py-synologydsm-api
+```
+
+# Usage
+
+You can import the module as `synology_dsm`.
+
+## Constructor
+
+```python
+SynologyDSM(
+    session,
+    dsm_ip,
+    dsm_port,
+    username,
+    password,
+    use_https=False,
+    timeout=10,
+    device_token=None,
+    debugmode=False,
+)
+```
+
+For `session` a valid `aiohttp.ClientSession` needs to be provided. If ssl verification should be truned off, configure the session accordingly (eq. `aiohttp.ClientSession(connector=aiohttp.TCPConnector(verify_ssl=False)`)
+
+`device_token` should be added when using a two-step authentication account, otherwise DSM will ask to login with a One Time Password (OTP) and requests will fail (see the login section for more details).
+
+Default `timeout` is 10 seconds. `SynologyDSM` also takes a `aiohttp.ClientTimeout` as `timeout`.
+
+## Login
+
+Use the `login()` function to authenticate first, otherwise a `SynologyDSMNotLoggedInException` is raised.
+
+It will return a boolean if it successed or faild to authenticate to DSM.
+
+If your account need a two-step authentication (2SA), `login()` will raise `SynologyDSMLogin2SARequiredException`.
+Call the function again with a One Time Password (OTP) as parameter, like `login("123456")` (better to be a string to handle first zero).
+Store the `device_token` property so that you do not need to reconnect with password the next time you open a new `SynologyDSM` session.
+
+## Code example
+
+Every API has an `update()` function that is needed to get the first data, then the data is cached and updated at the next `update()` call.
+
+The `SynologyDSM` class can also `update()` all APIs at once.
+
+```python
+import asyncio
+import aiohttp
+from synology_dsm import SynologyDSM
+
+async def main():
+    print("Creating Valid API")
+    async with aiohttp.ClientSession(
+        connector=aiohttp.TCPConnector(verify_ssl=False)
+    ) as session:
+        await do(session)
+
+async def do(session: aiohttp.ClientSession):
+    api = SynologyDSM(session, "<IP/DNS>", "<port>", "<username>", "<password>")
+    await api.login()
+
+    print("=== Information ===")
+    await api.information.update()
+    print("Model:           " + str(api.information.model))
+    print("RAM:             " + str(api.information.ram) + " MB")
+    print("Serial number:   " + str(api.information.serial))
+    print("Temperature:     " + str(api.information.temperature) + " °C")
+    print("Temp. warning:   " + str(api.information.temperature_warn))
+    print("Uptime:          " + str(api.information.uptime))
+    print("Full DSM version:" + str(api.information.version_string))
+    print("--")
+
+    print("=== Utilisation ===")
+    await api.utilisation.update()
+    print("CPU Load:        " + str(api.utilisation.cpu_total_load) + " %")
+    print("Memory Use:      " + str(api.utilisation.memory_real_usage) + " %")
+    print("Net Up:          " + str(api.utilisation.network_up()))
+    print("Net Down:        " + str(api.utilisation.network_down()))
+    print("--")
+
+    print("=== Storage ===")
+    await api.storage.update()
+    for volume_id in api.storage.volumes_ids:
+        print("ID:          " + str(volume_id))
+        print("Status:      " + str(api.storage.volume_status(volume_id)))
+        print("% Used:      " + str(api.storage.volume_percentage_used(volume_id)) + " %")
+        print("--")
+
+    for disk_id in api.storage.disks_ids:
+        print("ID:          " + str(disk_id))
+        print("Name:        " + str(api.storage.disk_name(disk_id)))
+        print("S-Status:    " + str(api.storage.disk_smart_status(disk_id)))
+        print("Status:      " + str(api.storage.disk_status(disk_id)))
+        print("Temp:        " + str(api.storage.disk_temp(disk_id)))
+        print("--")
+
+    print("=== Shared Folders ===")
+    await api.share.update()
+    for share_uuid in api.share.shares_uuids:
+        print("Share name:        " + str(api.share.share_name(share_uuid)))
+        print("Share path:        " + str(api.share.share_path(share_uuid)))
+        print("Space used:        " + str(api.share.share_size(share_uuid, human_readable=True)))
+        print("Recycle Bin Enabled: " + str(api.share.share_recycle_bin(share_uuid)))
+        print("--")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Download Station usage
+
+```python
+import asyncio
+import aiohttp
+from synology_dsm import SynologyDSM
+
+async def main():
+    print("Creating Valid API")
+    async with aiohttp.ClientSession(
+        connector=aiohttp.TCPConnector(verify_ssl=False)
+    ) as session:
+        await do(session)
+
+async def do(session: aiohttp.ClientSession):
+    api = SynologyDSM(session, "<IP/DNS>", "<port>", "<username>", "<password>")
+    await api.login()
+
+    if "SYNO.DownloadStation.Info" in api.apis:
+
+        await api.download_station.get_info()
+        await api.download_station.get_config()
+
+        # The download list will be updated after each of the following functions:
+        # You should have the right on the (default) directory that the download will be saved, or you will get a 403 or 406 error
+        await api.download_station.create("http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4")
+        await api.download_station.pause("dbid_1")
+        # Like the other function, you can eather pass a str or a list
+        await api.download_station.resume(["dbid_1", "dbid_2"])
+        await api.download_station.delete("dbid_3")
+
+        # Manual update
+        await api.download_station.update()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## External USB storage usage
+
+```python
+import asyncio
+import aiohttp
+from synology_dsm import SynologyDSM
+
+async def main():
+    print("Creating Valid API")
+    async with aiohttp.ClientSession(
+        connector=aiohttp.TCPConnector(verify_ssl=False)
+    ) as session:
+        await do(session)
+
+async def do(session: aiohttp.ClientSession):
+    api = SynologyDSM(session, "<IP/DNS>", "<port>", "<username>", "<password>")
+    await api.login()
+
+    await api.external_usb.update()
+    for device in api.external_usb.get_devices.values():
+        print("Name:                   " + str(device.device_name))
+        print("Size:                   " + str(device.device_size_total(human_readable=True))
+        print("Size in mb:             " + str(device.device_size_total())
+        print("Partitions size total:  " + str(device.partitions_all_size_total(human_readable=True)))
+        print("Partitions size used:   " + str(device.partitions_all_size_used(human_readable=True)))
+        print("Partitions % Used:      " + str(device.partitions_all_percentage_used ) + " %")
+        print("    === Partitions ===")
+        for part in device.device_partitions.values():
+            print("    Share name:             " + str(part.share_name))
+            print("    Filesystem:             " + str(part.filesystem))
+            print("    Size:                   " + str(part.partition_size_total(human_readable=True)))
+            print("    Used:                   " + str(part.partition_size_used(human_readable=True)))
+            print("    % Used:                 " + str(part.partition_percentage_used) + " %")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Photos usage
+
+```python
+import asyncio
+import aiohttp
+from synology_dsm import SynologyDSM
+
+async def main():
+    print("Creating Valid API")
+    async with aiohttp.ClientSession(
+        connector=aiohttp.TCPConnector(verify_ssl=False)
+    ) as session:
+        await do(session)
+
+async def do(session: aiohttp.ClientSession):
+    api = SynologyDSM(session, "<IP/DNS>", "<port>", "<username>", "<password>")
+    await api.login()
+
+    albums = await api.photos.get_albums()
+
+    # download each item of each album
+    for album in albums:
+        print(f"'{album.name}' has {album.item_count} items")
+
+        items = await api.photos.get_items_from_album(album)
+        for item in items:
+            print(f"{item.file_name}")
+            with open(item.file_name, "wb") as fh:
+                fh.write(await api.photos.download_item(item))
+
+    # search for items and download them
+    items = await api.photos.get_items_from_search("pinky and the brain")
+    for item in items:
+        with open(item.file_name, "wb") as fh:
+            fh.write(await api.photos.download_item(item))
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Surveillance Station usage
+
+```python
+import asyncio
+import aiohttp
+from synology_dsm import SynologyDSM
+
+async def main():
+    print("Creating Valid API")
+    async with aiohttp.ClientSession(
+        connector=aiohttp.TCPConnector(verify_ssl=False)
+    ) as session:
+        await do(session)
+
+async def do(session: aiohttp.ClientSession):
+    api = SynologyDSM(session, "<IP/DNS>", "<port>", "<username>", "<password>")
+    await api.login()
+
+    surveillance = api.surveillance_station
+    await surveillance.update() # First update is required
+
+    # Returns a list of cached cameras available
+    cameras = surveillance.get_all_cameras()
+
+    # Assuming there's at least one camera, get the first camera_id
+    camera_id = cameras[0].camera_id
+
+    # Returns cached camera object by camera_id
+    camera = surveillance.get_camera(camera_id)
+
+    # Returns cached motion detection enabled
+    motion_setting = camera.is_motion_detection_enabled
+
+    # Return bytes of camera image
+    await surveillance.get_camera_image(camera_id)
+
+    # Updates all cameras/motion settings and cahce them
+    await surveillance.update()
+
+    # Gets Home Mode status
+    home_mode_status = await surveillance.get_home_mode_status()
+
+    # Sets home mode - true is on, false is off
+    await surveillance.set_home_mode(True)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## System usage
+
+```python
+import asyncio
+import aiohttp
+from synology_dsm import SynologyDSM
+
+async def main():
+    print("Creating Valid API")
+    async with aiohttp.ClientSession(
+        connector=aiohttp.TCPConnector(verify_ssl=False)
+    ) as session:
+        await do(session)
+
+async def do(session: aiohttp.ClientSession):
+    api = SynologyDSM(session, "<IP/DNS>", "<port>", "<username>", "<password>")
+    await api.login()
+
+    system = api.system
+
+    # Reboot NAS
+    await system.reboot()
+
+    # Shutdown NAS
+    await system.shutdown()
+
+    # Manual update system information
+    await system.update()
+
+    # Get CPU information
+    system.cpu_clock_speed
+    system.cpu_cores
+    system.cpu_family
+    system.cpu_series
+
+    # Get NTP settings
+    system.enabled_ntp
+    system.ntp_server
+
+    # Get system information
+    system.firmware_ver
+    system.model
+    system.ram_size
+    system.serial
+    system.sys_temp
+    system.time
+    system.time_zone
+    system.time_zone_desc
+    system.up_time
+
+    # Get list of all connected USB devices
+    system.usb_dev
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Upgrade usage
+
+```python
+import asyncio
+import aiohttp
+from synology_dsm import SynologyDSM
+
+async def main():
+    print("Creating Valid API")
+    async with aiohttp.ClientSession(
+        connector=aiohttp.TCPConnector(verify_ssl=False)
+    ) as session:
+        await do(session)
+
+async def do(session: aiohttp.ClientSession):
+    api = SynologyDSM(session, "<IP/DNS>", "<port>", "<username>", "<password>")
+    await api.login()
+    upgrade = api.upgrade
+
+    # Manual update upgrade information
+    await upgrade.update()
+
+    # check if DSM update is available
+    if upgrade.update_available:
+        do something ...
+
+    # get available version string (return None if no update available)
+    upgrade.available_version
+
+    # get need of reboot (return None if no update available)
+    upgrade.reboot_needed
+
+    # get need of service restarts (return None if no update available)
+    upgrade.service_restarts
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+# Credits / Special Thanks
+
+- [@florianeinfalt](https://github.com/florianeinfalt)
+- [@tchellomello](https://github.com/tchellomello)
+- [@Quentame](https://github.com/Quentame) (Multiple API addition & tests)
+- [@aaska](https://github.com/aaska) (DSM 5 tests)
+- [@chemelli74](https://github.com/chemelli74) (2SA tests)
+- [@snjoetw](https://github.com/snjoetw) (Surveillance Station library)
+- [@shenxn](https://github.com/shenxn) (Surveillance Station tests)
+- [@Gestas](https://github.com/Gestas) (Shared Folders)
+- [@lodesmets](https://github.com/lodesmets) (Synology Photos)
+
+Found Synology API "documentation" on this repo : https://github.com/kwent/syno/tree/master/definitions
+
+# Official references
+
+- [Calendar API documentation (2015-2019)](https://global.download.synology.com/download/Document/Software/DeveloperGuide/Package/Calendar/2.4/enu/Synology_Calendar_API_Guide_enu.pdf)
+- [Download Station API documentation (2012-2014)](https://global.download.synology.com/download/Document/Software/DeveloperGuide/Package/DownloadStation/All/enu/Synology_Download_Station_Web_API.pdf)
+- [File Station API documentation (2013-2019)](https://global.download.synology.com/download/Document/Software/DeveloperGuide/Package/FileStation/All/enu/Synology_File_Station_API_Guide.pdf)
+- [Surveillance Station API documentation (2012-2020)](https://global.download.synology.com/download/Document/Software/DeveloperGuide/Package/SurveillanceStation/All/enu/Surveillance_Station_Web_API.pdf)
+- [Virtual Machine Manager API documentation (2015-2019)](https://global.download.synology.com/download/Document/Software/DeveloperGuide/Package/Virtualization/All/enu/Synology_Virtual_Machine_Manager_API_Guide.pdf)

py_synologydsm_api-2.4.5.dist-info/RECORD

@@ -0,0 +1,32 @@
+synology_dsm/__init__.py,sha256=aInIYAdeWaaOVX_brHfDFdGlj6aaSeJpuA8Tl25OV-4,106
+synology_dsm/const.py,sha256=8aAkaVWl87iDsHbs1v-oCnzB6Z6SlPfmU6Syz0T9Lro,8020
+synology_dsm/exceptions.py,sha256=IaFYeiRr6RmCqzr9ewZQW0NcKvLASc9-Z4ShO-DunkU,4935
+synology_dsm/helpers.py,sha256=7AG1Q7u9CbFwKVXIkpgKbNT9aQ28PwmAsZhLZG5l9MU,1432
+synology_dsm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+synology_dsm/synology_dsm.py,sha256=xRhbvXa46M54Q6LOhxNgT8c31rhDokCXY4gQ6x8BLiE,20983
+synology_dsm/api/__init__.py,sha256=0qNb81jE2nFKVfPMzKaU7sIt8zg3CM_kjaUXFKk04-w,439
+synology_dsm/api/core/__init__.py,sha256=Sh_dB3xUjd-gkqR4nnp-tlj1wRxaKd-H2KURKg4k0yA,32
+synology_dsm/api/core/external_usb.py,sha256=d0WqM5jAf83EW21i1ZAaAAtKxn8hiWZtLv_3DZE0_dA,9177
+synology_dsm/api/core/security.py,sha256=7YIUnutktfSUIUcchgqVFfWjg2mD5l6yw4bZaUefeAM,2321
+synology_dsm/api/core/share.py,sha256=GwwxvMuRYnvwyhYg2bsZX4dOKrXgLz8-or1Hzcl9p44,3136
+synology_dsm/api/core/system.py,sha256=zCAQu4y74r27abF_fKtR2qSTmS2Mmg3Z35sNoWsYzRo,3599
+synology_dsm/api/core/upgrade.py,sha256=f6WdtIdBgupdyJxj03vNxiqe1YPzO_AWmsNJi15PPK0,1576
+synology_dsm/api/core/utilization.py,sha256=PklyNGXMkcvUoGliYiHEPNW0jbyyBHVqTfQirGmi_Vo,6551
+synology_dsm/api/download_station/__init__.py,sha256=JW-pSPoSZruwJynXjc1qVvpENWW5kbxH6cazaW5T0h4,4213
+synology_dsm/api/download_station/task.py,sha256=8vb0vql4K9WouxSLmRjNEyxeeeqtzCaTxGvlxtnGsTE,1922
+synology_dsm/api/dsm/__init__.py,sha256=8x8iUZWB67DgQabXVMBX6y97Gm5RnpbQV61fc0Cn6JM,31
+synology_dsm/api/dsm/information.py,sha256=47jgz9w7oHLIPO7MpoD6tmd00EZzuU8DaUmiHc3z3R8,1889
+synology_dsm/api/dsm/network.py,sha256=YGDPv5aF4RSGzY2TJuTNgRc0-GLt_fAP1xQ5-XtLJqQ,2305
+synology_dsm/api/photos/__init__.py,sha256=5KuwJ6TG5U24xkRQPU0IgzCmlLjhsyGaHH1KuF2UMWI,5658
+synology_dsm/api/photos/model.py,sha256=7R8ygNhJEtdrp9fC6zzMb1FtSzPjP8Yt7ZwNBxJhkKU,460
+synology_dsm/api/storage/__init__.py,sha256=utx2aAU6aFNAUFLXxODDpnzY1cU4IdaCWZ3PFcZhFcU,35
+synology_dsm/api/storage/storage.py,sha256=olJoVDjnnOmWBm-a6Ag0sabY_Z0fr_NYxta3jBfNHFE,8742
+synology_dsm/api/surveillance_station/__init__.py,sha256=TpYLmC0GSaNbrDE0MB9WNCkRgiEC5VxLOU3ZKMyU0EE,9694
+synology_dsm/api/surveillance_station/camera.py,sha256=mz1hpMniNY0RnnArrtb1OOkQ5DUmpZbPNawXZo39qdE,3804
+synology_dsm/api/surveillance_station/const.py,sha256=DqlhX0J2om-I8FBrmJ6519C1kDPcVi04ugMj6ZjNaVs,523
+py_synologydsm_api-2.4.5.dist-info/LICENSE.txt,sha256=WGCx5VLKE4StlP_eAwVq4Kj4yp-hntiKdTJuKAjzgIk,1081
+py_synologydsm_api-2.4.5.dist-info/METADATA,sha256=6t1L9o0Zzlfa6Ldos6TziKcyNJqzCM1QVpQw-aNoE6Y,15320
+py_synologydsm_api-2.4.5.dist-info/WHEEL,sha256=R0nc6qTxuoLk7ShA2_Y-UWkN8ZdfDBG2B6Eqpz2WXbs,91
+py_synologydsm_api-2.4.5.dist-info/entry_points.txt,sha256=TgCBHUoDqjOdg__EY85BPGjnSyDFgkwK_9H7s9mB85Q,63
+py_synologydsm_api-2.4.5.dist-info/top_level.txt,sha256=sTQIu0LAoi94eaOkhlUsrxVmxibEPEbmhqD2c4VMp-M,13
+py_synologydsm_api-2.4.5.dist-info/RECORD,,

py_synologydsm_api-2.4.5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (72.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_synologydsm_api-2.4.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+synologydsm-api = synology_dsm.__main__:main

py_synologydsm_api-2.4.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+synology_dsm

synology_dsm/__init__.py

@@ -0,0 +1,5 @@
+"""The synologydsm-api library."""
+
+from .synology_dsm import SynologyDSM
+
+__all__ = ["SynologyDSM"]

synology_dsm/api/__init__.py

@@ -0,0 +1,20 @@
+"""Synology API models."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from synology_dsm import SynologyDSM
+
+
+_DataT = TypeVar("_DataT")
+
+
+class SynoBaseApi(Generic[_DataT]):
+    """Base api class."""
+
+    def __init__(self, dsm: "SynologyDSM") -> None:
+        """Constructor method."""
+        self._dsm = dsm
+        self._data: _DataT = {}  # type: ignore[assignment]

synology_dsm/api/core/__init__.py

@@ -0,0 +1 @@
+"""Synology Core API models."""