pythonanywhere-core 0.1.7__tar.gz → 0.1.9__tar.gz

{pythonanywhere_core-0.1.7 → pythonanywhere_core-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pythonanywhere-core
-Version: 0.1.7
+Version: 0.1.9
 Summary: API wrapper for programmatic management of PythonAnywhere services.
 License: MIT
 Keywords: pythonanywhere,api,cloud,web hosting

{pythonanywhere_core-0.1.7 → pythonanywhere_core-0.1.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pythonanywhere-core"
-version = "0.1.7"
+version = "0.1.9"
 description = "API wrapper for programmatic management of PythonAnywhere services."
 authors = ["PythonAnywhere <developers@pythonanywhere.com>"]
 license = "MIT"
@@ -26,10 +26,12 @@ snakesay = "^0.10.2"
 typing_extensions = "^4.5.0"
 
 [tool.poetry.dev-dependencies]
-pytest = "^7.3.1"
-pytest-cov = "^4.0.0"
+pytest = "^8.0.0"
+pytest-cov = "^5.0.0"
 pytest-mock = "^3.10.0"
-responses = "^0.24.0"
+responses = "^0.25.0"
+sphinx = "7.1.2"
+sphinx-rtd-theme = "^2.0.0"
 
 [tool.black]
 line-length = 120

pythonanywhere_core-0.1.9/pythonanywhere_core/__init__.py

@@ -0,0 +1 @@
+__version__ = '0.1.9'

{pythonanywhere_core-0.1.7 → pythonanywhere_core-0.1.9}/pythonanywhere_core/base.py

@@ -41,6 +41,16 @@ def helpful_token_error_message() -> str:
 
 
 def call_api(url: str, method: str, **kwargs) -> requests.Response:
+    """Calls PythonAnywhere API with given url and method.
+
+    :param url: url to call
+    :param method: HTTP method to use
+    :param kwargs: additional keyword arguments to pass to requests.request
+    :returns: requests.Response object
+
+    :raises AuthenticationError: if API returns 401
+    :raises NoTokenError: if API_TOKEN environment variable is not set"""
+
     token = os.environ.get("API_TOKEN")
     if token is None:
         raise NoTokenError(helpful_token_error_message())

{pythonanywhere_core-0.1.7 → pythonanywhere_core-0.1.9}/pythonanywhere_core/files.py

@@ -55,6 +55,9 @@ class Files:
             return f": {msg}"
         return ""
 
+    def _make_sharing_url(self, sharing_url_suffix):
+        return urljoin(self.base_url.split("api")[0], sharing_url_suffix)
+
     def path_get(self, path: str) -> Union[dict, bytes]:
         """Returns dictionary of directory contents when `path` is an
         absolute path to of an existing directory or file contents if
@@ -116,16 +119,18 @@ class Files:
     def sharing_post(self, path: str) -> Tuple[int, str]:
         """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."""
+        Returns a tuple with a message and sharing link on
+        success, raises otherwise.  Message is "successfully shared" on success,
+        "was already shared" if file has been already shared."""
 
         url = self.sharing_endpoint
 
         result = call_api(url, "POST", json={"path": path})
 
         if result.ok:
-            return result.status_code, result.json()["url"]
+            msg = {200: "was already shared", 201: "successfully shared"}[result.status_code]
+            sharing_url_suffix = result.json()["url"]
+            return msg, self._make_sharing_url(sharing_url_suffix)
 
         raise PythonAnywhereApiException(
             f"POST to {url} to share '{path}' failed, got {result}{self._error_msg(result)}"
@@ -140,8 +145,11 @@ class Files:
         url = f"{self.sharing_endpoint}?path={path}"
 
         result = call_api(url, "GET")
-
-        return result.json()["url"] if result.ok else ""
+        if result.ok:
+            sharing_url_suffix = result.json()["url"]
+            return self._make_sharing_url(sharing_url_suffix)
+        else:
+            return ""
 
     def sharing_delete(self, path: str) -> int:
         """Stops sharing file at `path`.

pythonanywhere_core-0.1.9/pythonanywhere_core/students.py

@@ -0,0 +1,49 @@
+import getpass
+from typing import Optional
+
+from pythonanywhere_core.base import call_api, get_api_endpoint
+
+
+class StudentsAPI:
+    """Interface for 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.
+
+    Covers:
+    - GET
+    - DELETE
+
+    Methods:
+    - use :method: `StudentsAPI.get` to get list of students
+    - use :method: `StudentsAPI.delete` to remove a student
+    """
+
+    base_url: str = get_api_endpoint().format(username=getpass.getuser(), flavor="students")
+
+    def get(self) -> Optional[dict]:
+        """Returns list of PythonAnywhere students related with user's account."""
+
+        result = call_api(self.base_url, "GET")
+
+        if result.status_code == 200:
+            return result.json()
+
+        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."""
+
+        url = f"{self.base_url}{student_username}"
+
+        result = call_api(url, "DELETE")
+
+        if result.status_code == 204:
+            return result.status_code
+
+        detail = f": {result.text}" if result.text else ""
+        raise Exception(
+            f"DELETE to remove student {student_username!r} failed, got {result}{detail}"
+        )

{pythonanywhere_core-0.1.7 → pythonanywhere_core-0.1.9}/pythonanywhere_core/webapp.py

@@ -18,6 +18,14 @@ class Webapp:
     create url, which is stored in a class variable `Webapp.base_url`,
     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.
+
     """
     def __init__(self, domain: str) -> None:
         self.endpoint = get_api_endpoint()
@@ -31,6 +39,7 @@ class Webapp:
         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"""
         print(snakesay("Running API sanity checks"))
         token = os.environ.get("API_TOKEN")
         if not token:
@@ -54,6 +63,15 @@ class Webapp:
             )
 
     def create(self, python_version: str, virtualenv_path: Path, project_path: Path, nuke: bool) -> None:
+        """Create a webapp for the given domain, using the given python version and virtualenv path
+
+        :param python_version:  python version to use
+        :param virtualenv_path: path to the virtualenv
+        :param project_path: path to the project
+        :param nuke: if True, delete any existing webapp for this domain
+
+        :raises PythonAnywhereApiException: if API call fails
+        """
         print(snakesay("Creating web app via API"))
         if nuke:
             call_api(self.domain_url, "delete")
@@ -73,12 +91,19 @@ class Webapp:
             )
 
     def add_default_static_files_mappings(self, project_path: Path) -> None:
+        """Add default static files mappings for /static/ and /media/
+
+        :param project_path: path to the project
+        """
         print(snakesay("Adding static files mappings for /static/ and /media/"))
         url = f"{self.domain_url}static_files/"
         call_api(url, "post", json=dict(url="/static/", path=str(Path(project_path) / "static")))
         call_api(url, "post", json=dict(url="/media/", path=str(Path(project_path) / "media")))
 
     def reload(self) -> None:
+        """Reload webapp
+
+        :raises PythonAnywhereApiException: if API call fails"""
         print(snakesay(f"Reloading {self.domain} via API"))
         url = f"{self.domain_url}reload/"
         response = call_api(url, "post")
@@ -100,6 +125,11 @@ class Webapp:
             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
+
+        :param certificate: SSL certificate
+        :param private_key: SSL private key
+        """
         print(snakesay(f"Setting up SSL for {self.domain} via API"))
         url = f"{self.domain_url}ssl/"
         response = call_api(url, "post", json={"cert": certificate, "private_key": private_key})
@@ -115,6 +145,7 @@ class Webapp:
             )
 
     def get_ssl_info(self) -> dict[str, Any]:
+        """Get SSL certificate info"""
         url = f"{self.domain_url}ssl/"
         response = call_api(url, "get")
         if not response.ok:
@@ -125,6 +156,13 @@ class Webapp:
         return result
 
     def delete_log(self, log_type: str, index: int = 0) -> None:
+        """Delete log file
+
+        :param log_type: log type (access, error, server)
+        :param index: log file index (0 for current, 1 for previous, etc.)
+
+        :raises PythonAnywhereApiException: if API call fails
+        """
         if index:
             message = f"Deleting old (archive number {index}) {log_type} log file for {self.domain} via API"
         else:
@@ -144,7 +182,12 @@ class Webapp:
         if not response.ok:
             raise PythonAnywhereApiException(f"DELETE log file via API failed, got {response}:{response.text}")
 
-    def get_log_info(self):
+    def get_log_info(self) -> dict:
+        """Get log files info
+
+        :returns: dictionary with log files info
+
+        :raises PythonAnywhereApiException: if API call fails"""
         url = f"{self.files_url}tree/?path=/var/log/"
         response = call_api(url, "get")
         if not response.ok:

pythonanywhere_core-0.1.7/pythonanywhere_core/__init__.py

@@ -1 +0,0 @@
-__version__ = '0.1.0'