added 'raise_if_exists' parameter to Attachment.download()

Signed-off-by: flashdagger <flashdagger@googlemail.com>

HISTORY.rst

@@ -6,10 +6,20 @@ History
 
 0.3.0 (tbd)
 -----------
+* **breaking changes**
+
+    * none yet
 
+* **added features**
+
+    * added ``raise_if_exists`` parameter to :meth:`articles.Attachment.download` method
+
+* **fixes**
+
+    * none yet
 
 0.2.0 (2024-03-10)
------------
+------------------
 * **breaking changes**
 
     * :class:`client.Client` now uses ``http_auth=(username, password)`` as authentication parameter

tests/test_articles.py

@@ -126,6 +126,10 @@ def test_create_article_via_ticket(ticket_pair, rclient):
         assert downloaded_file == Path(tmpdir, filename_binary)
         assert downloaded_file.read_bytes() == content_binary
 
-        downloaded_file = text_attachment.download(tmpdir)
-        assert downloaded_file == Path(tmpdir, filename_text)
+        destination_file = Path(tmpdir, f"{filename_text}.bkp")
+        downloaded_file = text_attachment.download(destination_file)
+        assert downloaded_file == destination_file
         assert downloaded_file.read_text() == content_text
+
+        with pytest.raises(FileExistsError):
+            text_attachment.download(downloaded_file, raise_if_exists=True)

zammadoo/articles.py

@@ -102,17 +102,23 @@ def _response(self) -> requests.Response:
 
         return response
 
-    def download(self, path: "PathType" = ".") -> "Path":
+    def download(self, path: "PathType" = ".", raise_if_exists=False) -> "Path":
         """
         Downloads the attachment file to the filesystem.
 
+        :raises: :exc:`FileExistsError`
+
         :param path: optional download location (directory or full file path)
+        :param raise_if_exists: raises :exc:`FileExistsError` if destination file exists
         :return: the path of the downloaded attachment file
         """
         filepath = Path(path)
         if filepath.is_dir():
             filepath = filepath / self.filename
 
+        if raise_if_exists and filepath.exists():
+            raise FileExistsError(f"File already exists: {str(filepath)!r}")
+
         with filepath.open("wb") as fd:
             for chunk in self.iter_bytes():
                 fd.write(chunk)