diff --git a/docs/api/index.rst b/docs/api/index.rst index ffdfeb8..233b64d 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -11,3 +11,4 @@ Programming Interface schedule students webapp + website diff --git a/pythonanywhere_core/files.py b/pythonanywhere_core/files.py index 3f908b8..d2659d5 100644 --- a/pythonanywhere_core/files.py +++ b/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") diff --git a/pythonanywhere_core/schedule.py b/pythonanywhere_core/schedule.py index 4ae70e1..dd5ba5f 100644 --- a/pythonanywhere_core/schedule.py +++ b/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") diff --git a/pythonanywhere_core/students.py b/pythonanywhere_core/students.py index ea71537..2115d08 100644 --- a/pythonanywhere_core/students.py +++ b/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}" diff --git a/pythonanywhere_core/webapp.py b/pythonanywhere_core/webapp.py index 1320a1d..4fa2991 100644 --- a/pythonanywhere_core/webapp.py +++ b/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() diff --git a/pythonanywhere_core/website.py b/pythonanywhere_core/website.py index c4df78b..a5bd356 100644 --- a/pythonanywhere_core/website.py +++ b/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: