download2stream implementation

Signed-off-by: Alexander Piskun <bigcat88@icloud.com>

CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to this project will be documented in this file.
 
 - `VERIFY_NC_CERTIFICATE` option.
 - `apps.ex_app_get_list` and `apps.ex_app_get_info` methods.
+- `files.download2stream` method.
 
 ## [0.0.23 - 2023-07-07]
 

docs/index.rst

@@ -26,6 +26,7 @@ Have a great time with Python and Nextcloud!
 .. toctree::
    :maxdepth: 1
 
+   reference/index.rst
    benchmarks/AppEcosystem.rst
 
 Indices and tables

docs/reference/Files.rst

@@ -0,0 +1,8 @@
+File System
+===========
+
+The Files API is universal for both modes and provides all the necessary methods for working with the Nextcloud file system.
+Refer to the **fs examples** to see how to use them nicely.
+
+.. autoclass:: nc_py_api.files.FilesAPI
+    :members:

docs/reference/Session.rst

@@ -0,0 +1,7 @@
+Sessions Internal
+=================
+
+Currently Session API is private, and not exposed.
+
+.. autoclass:: nc_py_api._session.NcSessionBasic
+    :members:

docs/reference/index.rst

@@ -0,0 +1,8 @@
+Reference
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   Files.rst
+   Session.rst

nc_py_api/_session.py

@@ -5,12 +5,13 @@
 import asyncio
 import hmac
 from abc import ABC, abstractmethod
+from contextlib import contextmanager
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from hashlib import sha256
 from json import dumps, loads
 from os import environ
-from typing import Optional, TypedDict, Union
+from typing import Iterator, Optional, TypedDict, Union
 from urllib.parse import quote, urlencode
 
 from fastapi import Request
@@ -152,20 +153,37 @@ def _ocs(self, method: str, path_params: str, headers: dict, data: Optional[byte
             raise NextcloudException(status_code=ocs_meta["statuscode"], reason=ocs_meta["message"], info=info)
         return response_data["ocs"]["data"]
 
-    def dav(self, method: str, path: str, data: Optional[Union[str, bytes]] = None, **kwargs):
+    def dav(self, method: str, path: str, data: Optional[Union[str, bytes]] = None, **kwargs) -> Response:
         headers = kwargs.pop("headers", {})
         data_bytes = None
         if data is not None:
             data_bytes = data.encode("UTF-8") if isinstance(data, str) else data
         return self._dav(method, quote(self.cfg.dav_url_suffix + path), headers, data_bytes, **kwargs)
 
+    @contextmanager
+    def dav_stream(
+        self, method: str, path: str, data: Optional[Union[str, bytes]] = None, **kwargs
+    ) -> Iterator[Response]:
+        headers = kwargs.pop("headers", {})
+        data_bytes = None
+        if data is not None:
+            data_bytes = data.encode("UTF-8") if isinstance(data, str) else data
+        return self._dav_stream(method, quote(self.cfg.dav_url_suffix + path), headers, data_bytes, **kwargs)
+
     def _dav(self, method: str, path: str, headers: dict, data: Optional[bytes], **kwargs) -> Response:
         self.init_adapter()
         timeout = kwargs.pop("timeout", options.TIMEOUT_DAV)
         return self.adapter.request(
             method, self.cfg.endpoint + path, headers=headers, content=data, timeout=timeout, **kwargs
         )
 
+    def _dav_stream(self, method: str, path: str, headers: dict, data: Optional[bytes], **kwargs) -> Iterator[Response]:
+        self.init_adapter()
+        timeout = kwargs.pop("timeout", options.TIMEOUT_DAV)
+        return self.adapter.stream(
+            method, self.cfg.endpoint + path, headers=headers, content=data, timeout=timeout, **kwargs
+        )
+
     def init_adapter(self, restart=False) -> None:
         if getattr(self, "adapter", None) is None or restart:
             if restart and hasattr(self, "adapter"):
@@ -233,6 +251,10 @@ def _dav(self, method: str, path: str, headers: dict, data: Optional[bytes], **k
         self.sign_request(method, path, headers, data)
         return super()._dav(method, path, headers, data, **kwargs)
 
+    def _dav_stream(self, method: str, path: str, headers: dict, data: Optional[bytes], **kwargs) -> Iterator[Response]:
+        self.sign_request(method, path, headers, data)
+        return super()._dav_stream(method, path, headers, data, **kwargs)
+
     def _create_adapter(self) -> Client:
         adapter = Client(follow_redirects=True, limits=self.limits, verify=options.VERIFY_NC_CERTIFICATE)
         adapter.headers.update(

nc_py_api/_version.py

@@ -1,3 +1,3 @@
 """ Version of nc_py_api"""
 
-__version__ = "0.0.23"
+__version__ = "0.0.24"

nc_py_api/files.py

@@ -156,10 +156,29 @@ def find(self, req: list, path="", depth=-1) -> list[FsNode]:
         return self._lf_parse_webdav_records(webdav_response, self._session.user, request_info)
 
     def download(self, path: str) -> bytes:
+        """Downloads and returns the contents of a file.
+
+        :param path: Path to a file to download relative to root directory of the user.
+        """
+
         response = self._session.dav("GET", self._dav_get_obj_path(self._session.user, path))
         check_error(response.status_code, f"download: user={self._session.user}, path={path}")
         return response.content
 
+    def download2stream(self, path: str, fp, **kwargs) -> None:
+        """Downloads file to the given `fp` object.
+
+        :param path: Path to a file to download relative to root directory of the user.
+        :param fp: A filename (string), pathlib.Path object or a file object.
+            The object must implement the ``file.write`` method and be able to write binary data.
+        :param kwargs: **chunk_size** an int value specifying chunk size to write. Default = **512Kb**
+        """
+
+        with self._session.dav_stream("GET", self._dav_get_obj_path(self._session.user, path)) as response:
+            check_error(response.status_code, f"download: user={self._session.user}, path={path}")
+            for data_chunk in response.iter_raw(chunk_size=kwargs.get("chunk_size", 512 * 1024)):
+                fp.write(data_chunk)
+
     def upload(self, path: str, content: Union[bytes, str]) -> None:
         response = self._session.dav("PUT", self._dav_get_obj_path(self._session.user, path), data=content)
         check_error(response.status_code, f"upload: user={self._session.user}, path={path}, size={len(content)}")

tests/files_test.py

@@ -37,13 +37,43 @@ def test_file_download(nc):
 
 
 @pytest.mark.parametrize("nc", NC_TO_TEST)
-def test_file_not_found(nc):
+def test_file_download2stream(nc):
+    class MyBytesIO(BytesIO):
+        def __init__(self):
+            self.n_calls = 0
+            super().__init__()
+
+        def write(self, content):
+            self.n_calls += 1
+            super().write(content)
+
+    srv_admin_manual1_buf = MyBytesIO()
+    srv_admin_manual2_buf = MyBytesIO()
+    nc.files.upload("test_file.txt", content=randbytes(64))
+    nc.files.download2stream("test_file.txt", srv_admin_manual1_buf)
+    nc.files.download2stream("/test_file.txt", srv_admin_manual2_buf, chunk_size=16)
+    assert srv_admin_manual1_buf.getbuffer() == srv_admin_manual2_buf.getbuffer()
+    assert srv_admin_manual1_buf.n_calls == 1
+    assert srv_admin_manual2_buf.n_calls == 4
+
+
+@pytest.mark.parametrize("nc", NC_TO_TEST)
+def test_file_download_not_found(nc):
     with pytest.raises(NextcloudException):
         nc.files.download("file that does not exist on the server")
     with pytest.raises(NextcloudException):
         nc.files.listdir("non existing path")
 
 
+@pytest.mark.parametrize("nc", NC_TO_TEST)
+def test_file_download2stream_not_found(nc):
+    buf = BytesIO()
+    with pytest.raises(NextcloudException):
+        nc.files.download2stream("file that does not exist on the server", buf)
+    with pytest.raises(NextcloudException):
+        nc.files.download2stream("non existing path", buf)
+
+
 @pytest.mark.parametrize("nc", NC_TO_TEST)
 def test_file_upload(nc):
     file_name = "12345.txt"