pythonanywhere-core 0.1.6__tar.gz → 0.1.8__tar.gz

{pythonanywhere_core-0.1.6 → pythonanywhere_core-0.1.8}/PKG-INFO

@@ -1,21 +1,21 @@
 Metadata-Version: 2.1
 Name: pythonanywhere-core
-Version: 0.1.6
+Version: 0.1.8
 Summary: API wrapper for programmatic management of PythonAnywhere services.
 License: MIT
 Keywords: pythonanywhere,api,cloud,web hosting
 Author: PythonAnywhere
 Author-email: developers@pythonanywhere.com
-Requires-Python: >=3.7,<4.0
+Requires-Python: >=3.8,<4.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries
 Requires-Dist: python-dateutil (>=2.8.2,<3.0.0)
 Requires-Dist: requests (>=2.30.0,<3.0.0)

{pythonanywhere_core-0.1.6 → pythonanywhere_core-0.1.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pythonanywhere-core"
-version = "0.1.6"
+version = "0.1.8"
 description = "API wrapper for programmatic management of PythonAnywhere services."
 authors = ["PythonAnywhere <developers@pythonanywhere.com>"]
 license = "MIT"
@@ -10,26 +10,28 @@ classifiers = [
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Libraries",
     "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.7",
 ]
 keywords = ["pythonanywhere", "api", "cloud", "web hosting"]
 
 [tool.poetry.dependencies]
-python = "^3.7"
+python = "^3.8"
 python-dateutil = "^2.8.2"
 requests = "^2.30.0"
 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.23.0"
+responses = "^0.25.0"
+sphinx = "7.1.2"
+sphinx-rtd-theme = "^2.0.0"
 
 [tool.black]
 line-length = 120

pythonanywhere_core-0.1.8/pythonanywhere_core/__init__.py

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

{pythonanywhere_core-0.1.6 → pythonanywhere_core-0.1.8}/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.8/pythonanywhere_core/files.py

@@ -0,0 +1,171 @@
+import getpass
+from typing import Tuple, Union
+from urllib.parse import urljoin
+
+from requests.models import Response
+
+from pythonanywhere_core.base import call_api, get_api_endpoint
+from pythonanywhere_core.exceptions import PythonAnywhereApiException
+
+
+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)
+    """
+
+    base_url = get_api_endpoint().format(username=getpass.getuser(), flavor="files")
+    path_endpoint = urljoin(base_url, "path")
+    sharing_endpoint = urljoin(base_url, "sharing/")
+    tree_endpoint = urljoin(base_url, "tree/")
+
+    def _error_msg(self, result: Response)  -> str:
+        """TODO: error responses should be unified at the API side """
+
+        if "application/json" in result.headers.get("content-type", ""):
+            jsn = result.json()
+            msg = jsn.get("detail") or jsn.get("message") or jsn.get("error", "")
+            return f": {msg}"
+        return ""
+
+    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
+        `path` is an absolute path to an existing file -- both
+        available to the PythonAnywhere user.  Raises when `path` is
+        invalid or unavailable."""
+
+        url = f"{self.path_endpoint}{path}"
+
+        result = call_api(url, "GET")
+
+        if result.status_code == 200:
+            if "application/json" in result.headers.get("content-type", ""):
+                return result.json()
+            return result.content
+
+        raise PythonAnywhereApiException(
+            f"GET to fetch contents of {url} failed, got {result}{self._error_msg(result)}"
+        )
+
+    def path_post(self, dest_path: str, content: bytes) -> int:
+        """Uploads contents of `content` to `dest_path` which should be
+        a valid absolute path of a file available to a PythonAnywhere
+        user.  If `dest_path` contains directories which don't exist
+        yet, they will be created.
+
+        Returns 200 if existing file on PythonAnywhere has been
+        updated with `source` contents, or 201 if file from
+        `dest_path` has been created with those contents."""
+
+        url = f"{self.path_endpoint}{dest_path}"
+
+        result = call_api(url, "POST", files={"content": content})
+
+        if result.ok:
+            return result.status_code
+
+        raise PythonAnywhereApiException(
+            f"POST to upload contents to {url} failed, got {result}{self._error_msg(result)}"
+        )
+
+    def path_delete(self, path: str) -> int:
+        """Deletes the file at specified `path` (if file is a
+        directory it will be deleted as well).
+
+        Returns 204 on sucess, raises otherwise."""
+
+        url = f"{self.path_endpoint}{path}"
+
+        result = call_api(url, "DELETE")
+
+        if result.status_code == 204:
+            return result.status_code
+
+        raise PythonAnywhereApiException(
+            f"DELETE on {url} failed, got {result}{self._error_msg(result)}"
+        )
+
+    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."""
+
+        url = self.sharing_endpoint
+
+        result = call_api(url, "POST", json={"path": path})
+
+        if result.ok:
+            return result.status_code, result.json()["url"]
+
+        raise PythonAnywhereApiException(
+            f"POST to {url} to share '{path}' failed, got {result}{self._error_msg(result)}"
+        )
+
+    def sharing_get(self, path: str) -> str:
+        """Checks sharing status for a `path`.
+
+        Returns url with sharing link if file is shared or an empty
+        string otherwise."""
+
+        url = f"{self.sharing_endpoint}?path={path}"
+
+        result = call_api(url, "GET")
+
+        return result.json()["url"] if result.ok else ""
+
+    def sharing_delete(self, path: str) -> int:
+        """Stops sharing file at `path`.
+
+        Returns 204 on successful unshare."""
+
+        url = f"{self.sharing_endpoint}?path={path}"
+
+        result = call_api(url, "DELETE")
+
+        return result.status_code
+
+    def tree_get(self, path: str) -> dict:
+        """Returns list of absolute paths of regular files and
+        subdirectories of a directory at `path`.  Result is limited to
+        1000 items.
+
+        Raises if `path` does not point to an existing directory."""
+
+        url = f"{self.tree_endpoint}?path={path}"
+
+        result = call_api(url, "GET")
+
+        if result.ok:
+            return result.json()
+
+        raise PythonAnywhereApiException(f"GET to {url} failed, got {result}{self._error_msg(result)}")

pythonanywhere_core-0.1.8/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.6 → pythonanywhere_core-0.1.8}/pythonanywhere_core/webapp.py

@@ -13,6 +13,20 @@ from pythonanywhere_core.exceptions import SanityException, PythonAnywhereApiExc
 
 
 class Webapp:
+    """ Interface for PythonAnywhere webapps API.
+    Uses `pythonanywhere_core.base` :method: `get_api_endpoint` to
+    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()
         self.username = getpass.getuser()
@@ -25,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:
@@ -48,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")
@@ -67,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")
@@ -94,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})
@@ -109,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:
@@ -119,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:
@@ -138,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.6/pythonanywhere_core/__init__.py

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