Add undocumented search method #93

CHANGES.rst

@@ -6,6 +6,7 @@ Changelog
 
 - Use `pyproject.toml` instead of `setup.py` [tomgross]
 - Document `eapi`-endpoint for fs.opener [tomgross]
+- Implement undocumented `search`-method (#93) [tomgross]
 
 1.4 (2024-12-29)
 ----------------

README.rst

@@ -81,6 +81,14 @@ b) from data:
   >>> img.save(bio, format='jpeg')
   >>> pc.uploadfile(data=bio.getvalue(), filename="image.jpg", path='/path-to-pcloud-dir')
 
+Searching files
+---------------
+
+The pCloud-API allows searching files, even this is not documented in the official
+pCloud documentation.
+
+  >>> pcapi.search(query="foo", offset=20, limit=10)
+
 PyFilesystem integration
 ++++++++++++++++++++++++
 

src/pcloud/api.py

@@ -529,5 +529,23 @@ def trash_restorepath(self, **kwargs):
     def trash_restore(self, **kwargs):
         raise NotImplementedError
 
+    # convenience methods
+    @RequiredParameterCheck(("query",))
+    def search(self, **kwargs):
+        return self._do_request("search", **kwargs)
+
+    @RequiredParameterCheck(("path",))
+    def file_exists(self, **kwargs):
+        path = kwargs["path"]
+        resp = self.file_open(path=path, flags=O_APPEND)
+        result = resp.get("result")
+        if result == 0:
+            self.file_close(fd=resp["fd"])
+            return True
+        elif result == 2009:
+            return False
+        else:
+            raise OSError(f"pCloud error occured ({result}) - {resp['error']}:  {path}")
+
 
 # EOF

src/pcloud/tests/test_integration.py

@@ -16,6 +16,7 @@ def pycloud():
     return PyCloud(username, password, endpoint="eapi")
 
 
+testfilename = "Getting started with pCloud.pdf"
 folder_for_tests = "integration-test"
 # upload `data/upload.txt` to integration test instance,
 # generate a public link (code) and insert the code below.
@@ -65,7 +66,6 @@ def test_publink_zip(pycloud):
 
 
 def test_copyfile(pycloud, testfolder):
-    testfilename = "Getting started with pCloud.pdf"
     tofilename = f"/{folder_for_tests}/{testfilename}"
     resp = pycloud.copyfile(path=f"/{testfilename}", topath=tofilename)
     assert resp["result"] == 0
@@ -76,6 +76,16 @@ def test_copyfile(pycloud, testfolder):
         == "df745d42f69266c49141ea7270c45240cf883b9cdb6a14fffcdff33c04c5304c"
     ), f"Failure with checksum in {resp}"
 
+def test_search(pycloud):
+    resp = pycloud.search(query=testfilename, limit=1)
+    assert len(resp['items']) == 1
+    assert resp['items'][0]['name'] == testfilename
+
+def test_fileexists_true(pycloud):
+    assert pycloud.file_exists(path=f"/{testfilename}")
+
+def test_fileexists_false(pycloud):
+    assert pycloud.file_exists(path=f"/bogusfile.txt") == False
 
 def test_listtokens(pycloud):
     result = pycloud.listtokens()