Repository: cloud-py-api/nc_py_api (language: python)

Issue:
Missing files.find() method usage, docs, examples, bug when searching by "name"
### Discussed in https://github.com/cloud-py-api/nc_py_api/discussions/86

<div type='discussions-op-text'>

<sup>Originally posted by **CooperGerman** August 17, 2023</sup>
Hi,
I'm currently trying to implement some of the features of this package and i am facing some issues regarding the files.find() method.
I can't seem to properly use it and while debugging i found some code which i'm not very sure about in file `nc_py_api/files/files.py` lines 46-53.

```python
SEARCH_PROPERTIES_MAP = {
    "name:": "d:displayname",  # like, eq
    "mime": "d:getcontenttype",  # like, eq
    "last_modified": "d:getlastmodified",  # gt, eq, lt
    "size": "oc:size",  # gt, gte, eq, lt
    "favorite": "oc:favorite",  # eq
    "fileid": "oc:fileid",  # eq
}
```

For entry "name" should there be the colon inside the string ?

Thanks in advance for any help, i would really appreciate an example of this method allowing to verify if a file exists in a folder. </div>


Discussion / hints:

Fix patch:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a3f839fe..8ecb5216 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,7 +7,10 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 - `FsNode` can be created from Nextcloud `UiActionFileInfo` reply.
-- Finished documentation.
+
+### Fixed
+
+- `files.find` error when searching by `"name"`. Thanks to @CooperGerman
 
 ## [0.0.30 - 2023-08-15]
 
diff --git a/docs/FirstSteps.rst b/docs/FirstSteps.rst
index 9a257536..d2a3a47e 100644
--- a/docs/FirstSteps.rst
+++ b/docs/FirstSteps.rst
@@ -83,3 +83,12 @@ A very simple example of downloading an image as one piece of data to memory and
 .. note:: For big files, it is always better to use ``download2stream`` method, as it uses chunks.
 
 .. literalinclude:: ../examples/as_client/files/download.py
+
+Searching for a file
+""""""""""""""""""""
+
+Example of using ``file.find()`` to search for file objects.
+
+.. note:: We welcome the idea of how to make the definition of search queries more friendly.
+
+.. literalinclude:: ../examples/as_client/files/find.py
diff --git a/examples/as_client/files/find.py b/examples/as_client/files/find.py
new file mode 100644
index 00000000..66435d43
--- /dev/null
+++ b/examples/as_client/files/find.py
@@ -0,0 +1,16 @@
+import nc_py_api
+
+if __name__ == "__main__":
+    # create Nextcloud client instance class
+    nc = nc_py_api.Nextcloud(nextcloud_url="http://nextcloud.local", nc_auth_user="admin", nc_auth_pass="admin")
+
+    print("Searching for all files which names ends with `.txt`:")
+    result = nc.files.find(["like", "name", "%.txt"])
+    for i in result:
+        print(i)
+    print("")
+    print("Searching for all files which name is equal to `Nextcloud_Server_Administration_Manual.pdf`:")
+    result = nc.files.find(["eq", "name", "Nextcloud_Server_Administration_Manual.pdf"])
+    for i in result:
+        print(i)
+    exit(0)
diff --git a/nc_py_api/files/files.py b/nc_py_api/files/files.py
index fba7212b..bc9d41bc 100644
--- a/nc_py_api/files/files.py
+++ b/nc_py_api/files/files.py
@@ -44,7 +44,7 @@
 ]
 
 SEARCH_PROPERTIES_MAP = {
-    "name:": "d:displayname",  # like, eq
+    "name": "d:displayname",  # like, eq
     "mime": "d:getcontenttype",  # like, eq
     "last_modified": "d:getlastmodified",  # gt, eq, lt
     "size": "oc:size",  # gt, gte, eq, lt


Test patch:
diff --git a/tests/files_test.py b/tests/files_test.py
index 51ee02b8..d541a6c5 100644
--- a/tests/files_test.py
+++ b/tests/files_test.py
@@ -410,7 +410,7 @@ def test_find_files_listdir_depth(nc):
     nc.files.mkdir("test_root_folder")
     nc.files.mkdir("test_root_folder/child_folder")
     nc.files.upload("test_root_folder/image1.png", content=im1.read())
-    nc.files.upload("test_root_folder/test_root.txt", content="content!")
+    nc.files.upload("test_root_folder/test_root_very_unique_name768.txt", content="content!")
     nc.files.upload("test_root_folder/child_folder/image2.gif", content=im2.read())
     nc.files.upload("test_root_folder/child_folder/image3.jpg", content=im3.read())
     nc.files.upload("test_root_folder/child_folder/test.txt", content="content!")
@@ -429,6 +429,14 @@ def test_find_files_listdir_depth(nc):
         ["or", "and", "gt", "size", 0, "like", "mime", "image/%", "like", "mime", "text/%"], path="test_root_folder"
     )
     assert len(result) == 5
+    result = nc.files.find(["eq", "name", "test_root_very_unique_name768.txt"])
+    assert len(result) == 1
+    result = nc.files.find(["like", "name", "test_root_very_unique_name76%"])
+    assert len(result) == 1
+    result = nc.files.find(["eq", "name", "test_root_very_unique_name768.txt"], path="test_root_folder/child_folder")
+    assert not result
+    result = nc.files.find(["like", "name", "test_root_very_unique_name76%"], path="test_root_folder/child_folder")
+    assert not result
     result = nc.files.find(["gte", "size", 0], path="test_root_folder")
     assert len(result) == 6  # 1 sub dir + 3 images + 2 text files
     result = nc.files.find(["like", "mime", "text/%"], path="test_root_folder")