Docstrings for classes and methods. by Piotr and Filip

Author: filiplajszczak

docs/api/index.rst

@@ -11,3 +11,4 @@ Programming Interface
    schedule
    students
    webapp
+   website

pythonanywhere_core/files.py

@@ -9,37 +9,34 @@
 
 
 class Files:
-    """ Interface for PythonAnywhere files API.
-
-    Uses `pythonanywhere_core.base` :method: `get_api_endpoint` to
-    create url, which is stored in a class variable `Files.base_url`,
-    then calls `call_api` with appropriate arguments to execute files
-    action.
-
-    Covers:
-    - GET, POST and DELETE for files path endpoint
-    - POST, GET and DELETE for files sharing endpoint
-    - GET for tree endpoint
-
-    "path" methods:
-    - use :method: `Files.path_get` to get contents of file or
-    directory from `path`
-    - use :method: `Files.path_post` to upload or update file at given
-    `dest_path` using contents from `source`
-    - use :method: `Files.path_delete` to delete file/directory on on
-    given `path`
-
-    "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)
     """
+    Interface for the PythonAnywhere Files API.
+
+    This class uses the `get_api_endpoint` function from ``pythonanywhere_core.base``
+    to construct the API URL, which is stored in the class variable ``base_url``.
+    It then calls the ``call_api`` method with the appropriate arguments to
+    perform file-related actions.
+
+    Supported Endpoints:
+        - `GET`, `POST`, and `DELETE` for the files path endpoint.
+        - `POST`, `GET`, and `DELETE` for the file sharing endpoint.
+        - `GET` for the tree endpoint.
+
+    Path Methods:
+        - :meth:`Files.path_get`: Retrieve the contents of a file or directory from a specified `path`.
+        - :meth:`Files.path_post`: Upload or update a file at the given `dest_path` using contents from `source`.
+        - :meth:`Files.path_delete`: Delete a file or directory at the specified `path`.
+
+    Sharing Methods:
+        - :meth:`Files.sharing_post`: Enable sharing of a file from the given `path` (if not already shared) and get a link to it.
+        - :meth:`Files.sharing_get`: Retrieve the sharing URL for a specified `path`.
+        - :meth:`Files.sharing_delete`: Disable sharing for a specified `path`.
+
+    Tree Method:
+        - :meth:`Files.tree_get`: Retrieve a list of regular files and subdirectories of a directory at the specified `path`
+          (limited to 1000 results).
+    """
+
 
     base_url = get_api_endpoint(username=getpass.getuser(), flavor="files")
     path_endpoint = urljoin(base_url, "path")

pythonanywhere_core/schedule.py

@@ -8,19 +8,25 @@
 
 
 class Schedule:
-    """Interface for PythonAnywhere scheduled tasks API.
-
-    Uses `pythonanywhere_core.api` :method: `get_api_endpoint` to create url,
-    which is stored in a class variable `Schedule.base_url`, then calls
-    `call_api` with appropriate arguments to execute scheduled tasks tasks
-    actions. Covers 'GET' and 'POST' methods for tasks list, as well as
-    'GET', 'PATCH' and 'DELETE' methods for task with id.
-
-    Use :method: `Schedule.get_list` to get all tasks list.
-    Use :method: `Schedule.create` to create new task.
-    Use :method: `Schedule.get_specs` to get existing task specs.
-    Use :method: `Schedule.delete` to delete existing task.
-    Use :method: `Schedule.update` to update existing task."""
+    """
+    Interface for the PythonAnywhere Scheduled Tasks API.
+
+    This class uses the `get_api_endpoint` function from ``pythonanywhere_core.api``
+    to construct the API URL, which is stored in the class variable ``base_url``.
+    It then calls the ``call_api`` method with appropriate arguments to perform
+    actions related to scheduled tasks.
+
+    Supported HTTP Methods:
+        - `GET` and `POST` for the tasks list.
+        - `GET`, `PATCH`, and `DELETE` for tasks with an ID.
+
+    Methods:
+        - :meth:`Schedule.get_list`: Retrieve the list of all scheduled tasks.
+        - :meth:`Schedule.create`: Create a new scheduled task.
+        - :meth:`Schedule.get_specs`: Retrieve the specifications of an existing task.
+        - :meth:`Schedule.delete`: Delete an existing task.
+        - :meth:`Schedule.update`: Update an existing task.
+    """
 
     base_url: str = get_api_endpoint(username=getpass.getuser(), flavor="schedule")
 

pythonanywhere_core/students.py

@@ -5,26 +5,30 @@
 
 
 class StudentsAPI:
-    """Interface for PythonAnywhere students API.
+    """
+    Interface for the PythonAnywhere Students API.
 
-    Uses `pythonanywhere.api.base` :method: `get_api_endpoint` to
-    create url, which is stored in a class variable `StudentsAPI.base_url`,
-    then calls `call_api` with appropriate arguments to execute student
-    action.
+    This class uses the `get_api_endpoint` function from
+    ``pythonanywhere.api.base`` to construct the API URL, which is stored
+    in the class variable ``base_url``. It then calls the ``call_api`` method
+    with the appropriate arguments to perform student-related actions.
 
-    Covers:
-    - GET
-    - DELETE
+    Supported HTTP Methods:
+        - `GET`
+        - `DELETE`
 
     Methods:
-    - use :method: `StudentsAPI.get` to get list of students
-    - use :method: `StudentsAPI.delete` to remove a student
+        - :meth:`StudentsAPI.get`: Retrieve a list of students.
+        - :meth:`StudentsAPI.delete`: Remove a student.
     """
 
     base_url: str = get_api_endpoint(username=getpass.getuser(), flavor="students")
 
     def get(self) -> Optional[dict]:
-        """Returns list of PythonAnywhere students related with user's account."""
+        """Returns list of PythonAnywhere students related with user's account.
+
+        :returns: dictionary with students info
+        """
 
         result = call_api(self.base_url, "GET")
 
@@ -34,7 +38,11 @@ def get(self) -> Optional[dict]:
         raise Exception(f"GET to list students failed, got {result.text}")
 
     def delete(self, student_username: str) -> Optional[int]:
-        """Returns 204 if student has been successfully removed, raises otherwise."""
+        """Returns 204 if student has been successfully removed, raises otherwise.
+
+        :param student_username: student username to be removed
+        :returns: 204 if student has been successfully removed
+        """
 
         url = f"{self.base_url}{student_username}"
 

pythonanywhere_core/webapp.py

@@ -19,13 +19,13 @@ class Webapp:
     then calls `call_api` with appropriate arguments to execute webapps
     action.
 
-    Use :method: `Webapp.create` to create new webapp.
-    Use :method: `Webapp.reload` to reload webapp.
-    Use :method: `Webapp.set_ssl` to set SSL certificate and private key.
-    Use :method: `Webapp.get_ssl_info` to get SSL certificate info.
-    Use :method: `Webapp.delete_log` to delete log file.
-    Use :method: `Webapp.get_log_info` to get log files info.
-
+    Methods:
+        - :meth:`Webapp.create`: Create a new webapp.
+        - :meth:`Webapp.reload`: Reload the webapp.
+        - :meth:`Webapp.set_ssl`: Set the SSL certificate and private key.
+        - :meth:`Webapp.get_ssl_info`: Retrieve SSL certificate information.
+        - :meth:`Webapp.delete_log`: Delete a log file.
+        - :meth:`Webapp.get_log_info`: Retrieve log file information.
     """
     def __init__(self, domain: str) -> None:
         self.username = getpass.getuser()

pythonanywhere_core/website.py

@@ -8,16 +8,19 @@
 class Website:
     """ Interface for PythonAnywhere websites API.
 
-    Uses ``pythonanywhere_core.base`` :method: ``get_api_endpoint`` to
+    Uses ``pythonanywhere_core.base`` function ``get_api_endpoint`` to
     create url, which is stored in a class variable ``Website.api_endpoint``,
     then calls ``call_api`` with appropriate arguments to execute websites
     action.
 
-    Use :method: ``Website.create`` to create new website.
-    Use :method: ``Website.get`` to get website info.
-    Use :method: ``Website.list`` to get all websites list.
-    Use :method: ``Website.reload`` to reload website.
-    Use :method: ``Website.delete`` to delete website.
+    Methods:
+        - :meth:`Website.create`: Create a new website.
+        - :meth:`Website.get`: Retrieve information about a specific website.
+        - :meth:`Website.list`: Get a list of all websites.
+        - :meth:`Website.reload`: Reload the website.
+        - :meth:`Website.auto_ssl`: Create and apply a Let's Encrypt SSL certificate.
+        - :meth:`Website.get_ssl_info`: Get SSL certificate information.
+        - :meth:`Website.delete`: Delete a website.
     """
 
     def __init__(self) -> None:
@@ -86,7 +89,9 @@ def auto_ssl(self, domain_name: str) -> dict:
         return response.json()
 
     def get_ssl_info(self, domain_name) -> dict:
-        """Get SSL certificate info"""
+        """Get SSL certificate info
+        :param domain_name: domain name for website to get SSL info
+        :return: dictionary with SSL certificate info"""
         url = f"{self.domains_base_url}{domain_name}/ssl/"
         response = call_api(url, "get")
         if not response.ok: