PA-1319 Add Webapp get, delete and patch methods and update docstrings, by: Alex, Piotr

Author: caseneuve

pythonanywhere_core/webapp.py

@@ -4,6 +4,7 @@
 import getpass
 from pathlib import Path
 from textwrap import dedent
+from typing import Any
 
 from dateutil.parser import parse
 from snakesay import snakesay
@@ -22,11 +23,15 @@ class Webapp:
     Methods:
         - :meth:`Webapp.create`: Create a new webapp.
         - :meth:`Webapp.create_static_file_mapping`: Create a static file mapping.
+        - :meth:`Webapp.add_default_static_files_mappings`: Add default static files mappings.
         - :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.
+        - :meth:`Webapp.get`: Retrieve webapp information.
+        - :meth:`Webapp.delete`: Delete webapp.
+        - :meth:`Webapp.patch`: Patch webapp.
 
     Class Methods:
         - :meth:`Webapp.list_webapps`: List all webapps for the current user.
@@ -43,7 +48,12 @@ def __eq__(self, other: Webapp) -> bool:
         return self.domain == other.domain
 
     def sanity_checks(self, nuke: bool) -> None:
-        """Check that we have a token, and that we don't already have a webapp for this domain"""
+        """Check that we have a token, and that we don't already have a webapp for this domain.
+
+        :param nuke: if True, skip the check for existing webapp
+
+        :raises SanityException: if API token is missing or webapp already exists
+        """
         print(snakesay("Running API sanity checks"))
         token = os.environ.get("API_TOKEN")
         if not token:
@@ -98,14 +108,18 @@ def create_static_file_mapping(self, url_path: str, directory_path: Path) -> Non
 
         :param url_path: URL path (e.g., '/static/')
         :param directory_path: Filesystem path to serve (as Path)
+
+        :raises PythonAnywhereApiException: if API call fails
         """
         url = f"{self.domain_url}static_files/"
         call_api(url, "post", json=dict(url=url_path, path=str(directory_path)))
 
     def add_default_static_files_mappings(self, project_path: Path) -> None:
-        """Add default static files mappings for /static/ and /media/
+        """Add default static files mappings for /static/ and /media/.
 
         :param project_path: path to the project
+
+        :raises PythonAnywhereApiException: if API call fails
         """
         self.create_static_file_mapping("/static/", Path(project_path) / "static")
         self.create_static_file_mapping("/media/", Path(project_path) / "media")
@@ -134,10 +148,12 @@ def reload(self) -> None:
             raise PythonAnywhereApiException(f"POST to reload webapp via API failed, got {response}:{response.text}")
 
     def set_ssl(self, certificate: str, private_key: str) -> None:
-        """Set SSL certificate and private key for webapp
+        """Set SSL certificate and private key for webapp.
 
         :param certificate: SSL certificate
         :param private_key: SSL private key
+
+        :raises PythonAnywhereApiException: if API call fails
         """
         print(snakesay(f"Setting up SSL for {self.domain} via API"))
         url = f"{self.domain_url}ssl/"
@@ -154,7 +170,12 @@ def set_ssl(self, certificate: str, private_key: str) -> None:
             )
 
     def get_ssl_info(self) -> dict[str, Any]:
-        """Get SSL certificate info"""
+        """Get SSL certificate info.
+
+        :returns: dictionary with SSL certificate information including parsed expiration date
+
+        :raises PythonAnywhereApiException: if API call fails
+        """
         url = f"{self.domain_url}ssl/"
         response = call_api(url, "get")
         if not response.ok:
@@ -191,10 +212,11 @@ def delete_log(self, log_type: str, index: int = 0) -> None:
         if not response.ok:
             raise PythonAnywhereApiException(f"DELETE log file via API failed, got {response}:{response.text}")
 
-    def get_log_info(self) -> dict:
-        """Get log files info
+    def get_log_info(self) -> dict[str, list[int]]:
+        """Get log files info.
 
-        :returns: dictionary with log files info
+        :returns: dictionary with log files info, keys are log types ('access', 'error', 'server'), 
+                 values are lists of log file indices
 
         :raises PythonAnywhereApiException: if API call fails"""
         url = f"{self.files_url}tree/?path=/var/log/"
@@ -222,12 +244,63 @@ def get_log_info(self) -> dict:
         return logs
 
     @classmethod
-    def list_webapps(cls) -> list:
+    def list_webapps(cls) -> list[dict[str, Any]]:
         """List all webapps for the current user.
 
         :returns: list of webapps info as dictionaries
+
+        :raises PythonAnywhereApiException: if API call fails
         """
         response = call_api(cls.webapps_url, "get")
         if not response.ok:
-            raise PythonAnywhereApiException(f"GET webapps via API failed, got {response}:{response.text}")
+            raise PythonAnywhereApiException(
+                f"GET webapps via API failed, "
+                f"got {response}:{response.text}"
+            )
+        return response.json()
+
+    def get(self) -> dict[str, Any]:
+        """Retrieve webapp information.
+
+        :returns: dictionary with webapp information
+
+        :raises PythonAnywhereApiException: if API call fails
+        """
+        response = call_api(self.domain_url, "get")
+
+        if not response.ok:
+            raise PythonAnywhereApiException(
+                f"GET webapp for {self.domain} via API failed, got {response}:{response.text}"
+            )
+
+        return response.json()
+
+    def delete(self) -> None:
+        """Delete webapp.
+
+        :raises PythonAnywhereApiException: if API call fails
+        """
+        response = call_api(self.domain_url, "delete")
+
+        if response.status_code != 204:
+            raise PythonAnywhereApiException(
+                f"DELETE webapp for {self.domain} via API failed, got {response}:{response.text}"
+            )
+
+    def patch(self, data: dict) -> dict[str, Any]:
+        """Patch webapp with provided data.
+
+        :param data: dictionary with data to update
+        :returns: dictionary with updated webapp information
+
+        :raises PythonAnywhereApiException: if API call fails
+        """
+        response = call_api(self.domain_url, "patch", data=data)
+
+        if not response.ok:
+            raise PythonAnywhereApiException(
+                f"PATCH webapp for {self.domain} via API failed, "
+                f"got {response}:{response.text}"
+            )
+
         return response.json()

tests/test_webapp.py

@@ -47,6 +47,25 @@ def webapp(domain):
     return Webapp(domain)
 
 
+@pytest.fixture
+def webapp_info(domain):
+    username = getpass.getuser()
+    return {
+        "id": 2097234,
+        "user": username,
+        "domain_name": domain,
+        "python_version": "3.10",
+        "source_directory": f"/home/{username}/mysite",
+        "working_directory": f"/home/{username}/",
+        "virtualenv_path": "",
+        "expiry": "2025-10-16",
+        "force_https": False,
+        "password_protection_enabled": False,
+        "password_protection_username": "foo",
+        "password_protection_password": "bar"
+    }
+
+
 def test_init(base_url, domain, domain_url, webapp):
     assert webapp.domain == domain
     assert webapp.webapps_url == base_url
@@ -240,7 +259,6 @@ def test_adds_default_static_files_mappings(mocker, webapp):
     )
 
 
-
 def test_does_post_to_reload_url(api_responses, api_token, domain_url, webapp):
     reload_url = f"{domain_url}reload/"
     api_responses.add(responses.POST, reload_url, status=200)
@@ -478,3 +496,124 @@ def test_list_webapps_raises_on_error(api_responses, api_token, base_url):
     assert "GET webapps via API failed" in str(e.value)
     assert "server error" in str(e.value)
 
+
+# /api/v0/user/{username}/webapps/{domain_name}/
+## GET
+
+
+def test_get_to_domain_name_endpoint_returns_200_with_webapp_info_when_domain_name_exists(
+        api_responses, api_token, domain_url, webapp, webapp_info
+):
+    api_responses.add(
+        responses.GET,
+        domain_url,
+        status=200,
+        body=json.dumps(webapp_info)
+    )
+
+    response = webapp.get()
+
+    for key, value in webapp_info.items():
+        assert response[key] == value
+
+
+def test_get_to_domain_name_endpoint_returns_403_for_not_authorized_user(
+        api_responses, api_token, domain, domain_url, webapp
+):
+    api_responses.add(
+        responses.GET,
+        domain_url,
+        status=403,
+        body='{"detail":"You do not have permission to perform this action."}',
+    )
+
+    with pytest.raises(PythonAnywhereApiException) as e:
+        webapp.get()
+
+    assert f"GET webapp for {domain} via API failed" in str(e.value)
+    assert '{"detail":"You do not have permission to perform this action."}' in str(e.value)
+
+
+# /api/v0/user/{username}/webapps/{domain_name}/
+## DELETE
+
+def test_delete_to_domain_name_endpoint_returns_204_for_authorized_user_and_existing_webapp(
+        api_responses, api_token, domain_url, webapp
+):
+    api_responses.add(
+        responses.DELETE,
+        domain_url,
+        status=204,
+    )
+
+    webapp.delete()
+
+    request, response = api_responses.calls[0]
+    assert request.url == domain_url
+    assert request.method == "DELETE"
+    assert response.status_code == 204
+
+
+def test_delete_to_domain_name_endpoint_returns_403_for_authorized_user_and_non_existing_webapp(
+        api_responses, api_token, domain, domain_url, webapp
+):
+    message = '{"detail":"You do not have permission to perform this action."}'
+    api_responses.add(
+        responses.DELETE,
+        domain_url,
+        status=403,
+        body=message
+    )
+
+    with pytest.raises(PythonAnywhereApiException) as e:
+        webapp.delete()
+
+    assert f"DELETE webapp for {domain} via API failed" in str(e.value)
+    assert message in str(e.value)
+
+
+# /api/v0/user/{username}/webapps/{domain_name}/
+## PATCH
+
+
+def test_patch_to_domain_name_endpoint_returns_200_for_authorized_user_and_existing_webapp(
+        api_responses, api_token, domain_url, webapp, webapp_info
+):
+    new_force_https = not webapp_info["force_https"]
+    webapp_info["force_https"] = new_force_https
+
+    api_responses.add(
+        responses.PATCH,
+        domain_url,
+        status=200,
+        body=json.dumps(webapp_info)
+    )
+
+    response = webapp.patch({"force_https": new_force_https, "non-supported-field": "foo"})
+
+    for key, value in webapp_info.items():
+        if key == "force_https":
+            assert response[key] == new_force_https
+        else:
+            assert response[key] == value
+
+        assert "non-supported-field" not in response
+
+
+def test_patch_to_domain_name_endpoint_returns_403_for_authorized_user_and_non_existing_webapp(
+        api_responses, api_token, domain, domain_url, webapp
+):
+    message = '{"detail":"You do not have permission to perform this action."}'
+    data = {"force_https": True}
+    api_responses.add(
+        responses.PATCH,
+        domain_url,
+        status=403,
+        body=message
+    )
+
+    with pytest.raises(PythonAnywhereApiException) as e:
+        webapp.patch(data)
+
+    assert f"PATCH webapp for {domain} via API failed" in str(e.value)
+    assert message in str(e.value)