From ff6b57abec6074556972e0e15879e28d07c07ba7 Mon Sep 17 00:00:00 2001
From: Piotr Kaznowski <piotrkaznowski@gmail.com>
Date: Fri, 18 Dec 2020 15:10:57 +0100
Subject: [PATCH] #29 updates Files methods docstrings. by Piotr

---
 pythonanywhere/api/files_api.py | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/pythonanywhere/api/files_api.py b/pythonanywhere/api/files_api.py
index 987b77b..a697744 100644
--- a/pythonanywhere/api/files_api.py
+++ b/pythonanywhere/api/files_api.py
@@ -29,6 +29,12 @@ class Files:
     "sharing" methods:
     - use :method: `Files.sharing_post` to enable sharing a file from `path` (if not shared before)
       and get a link to it
+    - use :method: `Files.sharing_get` to get sharing url for `path`
+    - use :method: `Files.sharing_delete` to disable sharing for `path`
+
+    "tree" method:
+    - use :method: `Files.tree_get` to get list of regular files and subdirectories
+      of a directory at `path` (limited to 1000 results)
     """
 
     base_url = get_api_endpoint().format(username=getpass.getuser(), flavor="files")
@@ -94,6 +100,10 @@ def path_post(self, dest_path, source, as_string=False):
         )
 
     def path_delete(self, path):
+        """Deletes the file at specified `path` (if file is a directory it will be deleted as well).
+
+        Returns 204 on sucess, raises otherwise."""
+
         url = f"{self.path_endpoint}{path}"
 
         result = call_api(url, "DELETE")
@@ -106,6 +116,11 @@ def path_delete(self, path):
         )
 
     def sharing_post(self, path):
+        """Starts sharing a file at `path`.
+
+        Returns a tuple with a status code and sharing link on success, raises otherwise.
+        Status code is 201 on success, 200 if file has been already shared."""
+
         url = self.sharing_endpoint
 
         result = call_api(url, "POST", json={'path': path})
@@ -118,6 +133,10 @@ def sharing_post(self, path):
         )
 
     def sharing_get(self, path):
+        """Checks sharing status for a `path`.
+
+        Returns url with sharing link if file is shared or an empty string otherwise."""
+
         url = f"{self.sharing_endpoint}?path={path}"
 
         result = call_api(url, "GET")
@@ -125,6 +144,10 @@ def sharing_get(self, path):
         return result.json()["url"] if result.ok else ""
 
     def sharing_delete(self, path):
+        """Stops sharing file at `path`.
+
+        Returns 204 on successful unshare."""
+
         url = f"{self.sharing_endpoint}?path={path}"
 
         result = call_api(url, "DELETE")
@@ -132,6 +155,11 @@ def sharing_delete(self, path):
         return result.status_code
 
     def tree_get(self, path):
+        """Returns list of absolute paths of regular files and subdirectories of a directory at `path`.
+        Result is limited to 1000 items.
+
+        Raises if `path` does not point to an existing directory."""
+
         url = f"{self.tree_endpoint}?path={path}"
 
         result = call_api(url, "GET")