PR #378 Add UserFile to API docs

Finetune/fix UserFile docs as well

docs/api.rst

@@ -86,6 +86,13 @@ openeo.rest.udp
     :members: RESTUserDefinedProcess
 
 
+openeo.rest.userfile
+----------------------
+
+.. automodule:: openeo.rest.userfile
+    :members:
+
+
 openeo.udf
 -------------
 

openeo/internal/jupyter.py

@@ -103,6 +103,7 @@ def render_component(component: str, data = None, parameters: dict = None):
     key = COMPONENT_MAP.get(component, component)
     if data is not None:
         if isinstance(data, list):
+            # TODO: make this `to_dict` usage more explicit with an internal API?
             data = [(x.to_dict() if hasattr(x, "to_dict") else x) for x in data]
         parameters[key] = data
 

openeo/rest/connection.py

@@ -1091,11 +1091,10 @@ def job_logs(self, job_id, offset) -> list:
 
     def list_files(self) -> List[UserFile]:
         """
-        Lists all files that the logged-in user uploaded.
+        Lists all user-uploaded files in the user workspace on the back-end.
 
-        :return: file_list: List of the user-uploaded files.
+        :return: List of the user-uploaded files.
         """
-
         files = self.get('/files', expected_status=200).json()['files']
         files = [UserFile.from_metadata(metadata=f, connection=self) for f in files]
         return VisualList("data-table", data=files, parameters={'columns': 'files'})
@@ -1104,10 +1103,9 @@ def get_file(
         self, path: Union[str, PurePosixPath], metadata: Optional[dict] = None
     ) -> UserFile:
         """
-        Gets a handle to a file in the user workspace on the back-end.
+        Gets a handle to a user-uploaded file in the user workspace on the back-end.
 
         :param path: The path on the user workspace.
-        :return: UserFile object.
         """
         return UserFile(path=path, connection=self, metadata=metadata)
 
@@ -1117,13 +1115,13 @@ def upload_file(
         target: Optional[Union[str, PurePosixPath]] = None,
     ) -> UserFile:
         """
-        Uploads a file to the given target location in the user workspace.
+        Uploads a file to the given target location in the user workspace on the back-end.
 
         If a file at the target path exists in the user workspace it will be replaced.
 
         :param source: A path to a file on the local file system to upload.
-        :param target: The desired path on the user workspace. If not set, defaults to the filename (without path) of the local file.
-        :return: UserFile object.
+        :param target: The desired path (which can contain a folder structure if desired) on the user workspace.
+            If not set: defaults to the original filename (without any folder structure) of the local file .
         """
         source = Path(source)
         target = target or source.name

openeo/rest/userfile.py

@@ -10,7 +10,9 @@
 
 
 class UserFile:
-    """Represents a file in the user-workspace of openeo."""
+    """
+    Handle to a (user-uploaded) file in the user workspace on a openEO back-end.
+    """
 
     def __init__(
         self,
@@ -34,25 +36,27 @@ def __init__(
 
     @classmethod
     def from_metadata(cls, metadata: dict, connection: "Connection") -> "UserFile":
-        """Build :py:class:`UserFile` from workspace file metadata dictionary."""
+        """Build :py:class:`UserFile` from a workspace file metadata dictionary."""
         return cls(path=None, connection=connection, metadata=metadata)
 
     def __repr__(self):
-        return '<{c} file={i!r}>'.format(c=self.__class__.__name__, i=self.path)
+        return "<{c} file={i!r}>".format(c=self.__class__.__name__, i=self.path)
 
     def _get_endpoint(self) -> str:
         return f"/files/{self.path!s}"
 
     def download(self, target: Union[Path, str] = None) -> Path:
         """
-        Downloads a user-uploaded file to the given location.
+        Downloads a user-uploaded file from the user workspace on the back-end
+        locally to the given location.
 
-         :param target: download target path. Can be an existing folder
+        :param target: local download target path. Can be an existing folder
              (in which case the file name advertised by backend will be used)
              or full file name. By default, the working directory will be used.
         """
-        # GET /files/{path}
-        response = self.connection.get(self._get_endpoint(), expected_status=200, stream=True)
+        response = self.connection.get(
+            self._get_endpoint(), expected_status=200, stream=True
+        )
 
         target = Path(target or Path.cwd())
         if target.is_dir():
@@ -67,24 +71,27 @@ def download(self, target: Union[Path, str] = None) -> Path:
 
     def upload(self, source: Union[Path, str]) -> "UserFile":
         """
-        Uploads a file to the given target location in the user workspace.
+        Uploads a local file to the path corresponding to this :py:class:`UserFile` in the user workspace
+        and returns new :py:class:`UserFile` of newly uploaded file.
+
+            .. tip::
+                Usually you'll just need
+                :py:meth:`Connection.upload_file() <openeo.rest.connection.Connection.upload_file>`
+                instead of this :py:class:`UserFile` method.
 
         If the file exists in the user workspace it will be replaced.
 
         :param source: A path to a file on the local file system to upload.
+        :return: new :py:class:`UserFile` instance of the newly uploaded file
         """
-        # PUT /files/{path}
         return self.connection.upload_file(source, target=self.path)
 
     def delete(self):
-        """ Delete a user-uploaded file."""
-        # DELETE /files/{path}
+        """Delete the user-uploaded file from the user workspace on the back-end."""
         self.connection.delete(self._get_endpoint(), expected_status=204)
 
     def to_dict(self) -> Dict[str, Any]:
-        """
-        Returns the provided metadata as dict.
-
-        This is used in internal/jupyter.py to detect and get the original metadata.
-        """
+        """Returns the provided metadata as dict."""
+        # This is used in internal/jupyter.py to detect and get the original metadata.
+        # TODO: make this more explicit with an internal API?
         return self.metadata