pieforhead 0.0.1__py3-none-any.whl

pieforhead/__init__.py

@@ -0,0 +1,4 @@
+from .pieforhead import PieFed, PieFedAsync
+from .utils import __version__ as VERSION
+
+__all__ = ["PieFed", "PieFedAsync", "VERSION"]

pieforhead/clients.py

@@ -0,0 +1,481 @@
+import json
+import logging
+
+import httpx
+import semver
+
+from .exceptions import PieFedClientException
+from .utils import __version__ as VERSION
+
+
+logger = logging.getLogger(__name__)
+
+
+class BaseClient:
+    """Class that both synchronous and async clients inherit from."""
+
+    instance_url: str
+    timeout: float = 5.0
+    api_version: str = "alpha"
+    headers: dict = {}
+    jwt_token: str = ""
+    current_username_or_email: str = ""
+    current_password: str = ""
+    raise_exceptions: bool = True
+    _nodeinfo: dict | None = None
+    _instance_version: semver.Version | None = None
+
+    def __init__(
+        self,
+        instance_url: str,
+        timeout: float = 5.0,
+        api_version: str = "alpha",
+        raise_exceptions: bool = True,
+    ):
+        """Constructor for base client class.
+
+        Args:
+            instance_url str: url of the piefed instance e.g. https://site.tld
+            timeout (float, optional): Timeout value for requests. Defaults to 5.0.
+            api_version (str, optional): Version of the PieFed API. Defaults to "alpha".
+        """
+        self.instance_url = instance_url
+        self.timeout = timeout
+        self.api_version = api_version
+        self.raise_exceptions = raise_exceptions
+        self.headers = {"User-Agent": f"pieforhead/{VERSION}", "Accept": "application/json"}
+
+    def _request_error(self, message: str, error: Exception) -> dict | None:
+        # Always log the error
+        logger.error(message)
+
+        # Only raise if desired
+        if self.raise_exceptions:
+            raise PieFedClientException(message) from error
+
+        # Return None if raising is not desired
+        return
+
+
+class PieFedClient(BaseClient):
+    """Synchronous client for handling network requests."""
+
+    _client: httpx.Client | None = None
+
+    def __init__(
+        self,
+        instance_url: str,
+        timeout: float = 5.0,
+        api_version: str = "alpha",
+        existing_client: httpx.Client | None = None,
+        raise_exceptions: bool = True,
+    ):
+        """Constructor for Synchronous client.
+
+        Args:
+            instance_url str: url of the piefed instance e.g. https://site.tld
+            timeout (float, optional): Timeout value for requests. Defaults to 5.0.
+            api_version (str, optional): Version of the PieFed API. Defaults to "alpha".
+            existing_client (httpx.Client, optional): Pass an httpx.Client object to reuse it (mainly used for tests).
+                Defaults to None.
+            raise_exceptions (bool, optional): Whether to raise exceptions on request errors or just return None.
+                Defaults to True.
+        """
+        super().__init__(
+            instance_url=instance_url,
+            timeout=timeout,
+            api_version=api_version,
+            raise_exceptions=raise_exceptions,
+        )
+
+        base_url = f"{instance_url}/api/{api_version}/"
+
+        if existing_client:
+            self._client = existing_client
+        else:
+            self._client = httpx.Client(headers=self.headers, timeout=self.timeout, base_url=base_url)
+
+    def request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict = {},
+        data: dict = {},
+        files: dict | None = None,
+    ) -> dict | None:
+        """Function to handle network requests.
+
+        Args:
+            method (str): HTTP method for the request, one of ["GET", "POST", "PUT"]
+            endpoint (str): API endpoint to send request to e.g. "post/list"
+            params (dict, optional): url parameters for the request (only for "GET") Defaults to {}.
+            data (dict, optional): json payload for the request ("POST" and "PUT") Defaults to {}.
+            files (dict, optional): multipart files to include with the request.
+
+        Raises:
+            PieFedClientException: should also include error message returned from server if available
+
+        Returns:
+            dict: deserialized json returned by the server
+        """
+
+        if self.jwt_token and "Authorization" not in self.headers:
+            self.headers["Authorization"] = "Bearer " + self.jwt_token
+
+        try:
+            # Make the request
+            logger.debug(f"method={method}, endpoint={endpoint}, params={params}, data={data}")
+
+            resp = self._client.request(
+                method=method,
+                url=endpoint,
+                headers=self.headers,
+                timeout=self.timeout,
+                params=params,
+                json=data,
+                files=files,
+            )
+
+            resp.raise_for_status()
+
+            # Everything went well
+            return resp.json()
+
+        except httpx.HTTPStatusError as e:
+            # Server returned a bad status code, try to pull out the returned error message
+            logger.error(msg=str(e))
+
+            message = f"{method} request to {endpoint} failed with status {resp.status_code}"
+            try:
+                # A try...except inside a try...except kinda sucks - but more information is better, right?
+                error_body = resp.json()
+            except json.decoder.JSONDecodeError:
+                error_body = {}
+
+            if error_body and error_body.get("message", ""):
+                message += f": {error_body['message']}"
+
+            return self._request_error(message=message, error=e)
+
+        except httpx.TimeoutException as e:
+            # Server timed out
+            logger.error(msg=str(e))
+
+            message = f"{method} request to {endpoint} timed out"
+            return self._request_error(message=message, error=e)
+
+        except httpx.RequestError as e:
+            # Some other problem with the request
+            logger.error(msg=str(e))
+
+            message = f"{method} request to {endpoint} failed"
+            return self._request_error(message=message, error=e)
+
+        except json.decoder.JSONDecodeError as e:
+            # Server returned something that isn't JSON
+            logger.error(msg=str(e))
+
+            message = f"{method} request to {endpoint} did not return parseable JSON"
+            return self._request_error(message=message, error=e)
+
+    def close(self):
+        self._client.close()
+
+    def log_in(self, username_or_email: str, password: str) -> bool:
+        payload = {"username": username_or_email, "password": password}
+        method = "POST"
+
+        resp = self.request(method=method, endpoint="user/login", data=payload)
+
+        if resp is None:
+            # Problem with the request that was suppressed, just return False
+            return False
+
+        self.jwt_token = resp["jwt"]
+        self.headers["Authorization"] = "Bearer " + self.jwt_token
+        self.current_username_or_email = username_or_email
+        self.current_password = password
+
+        return True
+
+    def is_logged_in(self) -> bool:
+        return bool(self.jwt_token)
+
+    def log_out(self) -> bool:
+        method = "POST"
+
+        resp = self.request(method=method, endpoint="user/logout")
+
+        if resp is None:
+            # Problem with the request that was suppressed, just return False
+            return False
+
+        self.jwt_token = ""
+        self.current_username_or_email = ""
+        self.current_password = ""
+
+        return True
+
+    @property
+    def nodeinfo(self) -> dict | None:
+        """Dict containing the instance's nodeinfo output.
+
+        Returns:
+            dict: deserialized copy of the instance's nodeinfo or None if the request failed and exception ignored
+        """
+        if self._nodeinfo:
+            return self._nodeinfo
+
+        method = "GET"
+        endpoint = self.instance_url + "/nodeinfo/2.1.json"
+
+        resp = self.request(method=method, endpoint=endpoint)
+        self._nodeinfo = resp
+
+        return self._nodeinfo if self._nodeinfo else None
+
+    @property
+    def instance_version(self) -> semver.Version | None:
+        """The instance's software version from the nodeinfo.
+
+        Returns:
+            semver.Version: software version of the piefed instance or None if something failed and the exception was
+                suppressed
+        """
+
+        current_nodeinfo = self.nodeinfo
+
+        if current_nodeinfo is None:
+            # Problem with the request that was suppressed, just return False
+            return None
+
+        version_str = self.nodeinfo["software"]["version"]
+
+        try:
+            self._instance_version = semver.Version.parse(version_str)
+            return self._instance_version
+        except ValueError as e:
+            logger.error(msg=str(e))
+            logger.error(f"_instance_version={version_str}")
+
+            message = f"Instance version from nodeinfo not parseable: {version_str}"
+            return self._request_error(message=message, error=e)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+class AsyncPieFedClient(BaseClient):
+    """Asynchronous client for handling network requests."""
+
+    _client: httpx.AsyncClient = None
+
+    def __init__(
+        self,
+        instance_url: str,
+        timeout: float = 5.0,
+        api_version: str = "alpha",
+        existing_client: httpx.AsyncClient | None = None,
+        raise_exceptions: bool = True,
+    ):
+        """Constructor for Asynchronous client.
+
+        Args:
+            instance_url str: url of the piefed instance e.g. https://site.tld
+            timeout (float, optional): Timeout value for requests. Defaults to 5.0.
+            api_version (str, optional): Version of the PieFed API. Defaults to "alpha".
+            existing_client (httpx.Client, optional): Pass an httpx.Client object to reuse it (mainly used for tests).
+                Defaults to None.
+            raise_exceptions: (bool, optional): Whether to raise exceptions on request errors or just return None.
+                Defaults to True.
+        """
+        super().__init__(
+            instance_url=instance_url,
+            timeout=timeout,
+            api_version=api_version,
+            raise_exceptions=raise_exceptions,
+        )
+
+        base_url = f"{instance_url}/api/{api_version}/"
+
+        if existing_client:
+            self._client = existing_client
+        else:
+            self._client = httpx.AsyncClient(headers=self.headers, timeout=self.timeout, base_url=base_url)
+
+    async def request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict = {},
+        data: dict = {},
+        files: dict | None = None,
+    ) -> dict | None:
+        """Async function to handle network requests.
+
+        Args:
+            method (str): HTTP method for the request, one of ["GET", "POST", "PUT"]
+            endpoint (str): API endpoint to send request to e.g. "post/list"
+            params (dict, optional): url parameters for the request (only for "GET") Defaults to {}.
+            data (dict, optional): json payload for the request ("POST" and "PUT") Defaults to {}.
+            files (dict, optional): multipart files to include with the request.
+
+        Raises:
+            PieFedClientException: should also include error message returned from server if available
+
+        Returns:
+            dict: deserialized json returned by the server
+        """
+
+        if self.jwt_token and "Authorization" not in self.headers:
+            self.headers["Authorization"] = "Bearer " + self.jwt_token
+
+        try:
+            # Make the request
+            logger.debug(f"method={method}, endpoint={endpoint}, params={params}, data={data}")
+
+            resp = await self._client.request(
+                method=method,
+                url=endpoint,
+                headers=self.headers,
+                timeout=self.timeout,
+                params=params,
+                json=data,
+                files=files,
+            )
+
+            resp.raise_for_status()
+
+            # Everything went well
+            return resp.json()
+
+        except httpx.HTTPStatusError as e:
+            # Server returned a bad status code, try to pull out the returned error message
+            logger.error(msg=str(e))
+
+            message = f"{method} request to {endpoint} failed with status {resp.status_code}"
+            try:
+                # A try...except inside a try...except kinda sucks - but more information is better, right?
+                error_body = resp.json()
+            except json.decoder.JSONDecodeError:
+                error_body = {}
+
+            if error_body and error_body.get("message", ""):
+                message += f": {error_body['message']}"
+
+            return self._request_error(message=message, error=e)
+
+        except httpx.TimeoutException as e:
+            # Server timed out
+            logger.error(msg=str(e))
+
+            message = f"{method} request to {endpoint} timed out"
+            return self._request_error(message=message, error=e)
+
+        except httpx.RequestError as e:
+            # Some other problem with the request
+            logger.error(msg=str(e))
+
+            message = f"{method} request to {endpoint} failed"
+            return self._request_error(message=message, error=e)
+
+        except json.decoder.JSONDecodeError as e:
+            # Server returned something that isn't JSON
+            logger.error(msg=str(e))
+
+            message = f"{method} request to {endpoint} did not return parseable JSON"
+            return self._request_error(message=message, error=e)
+
+    async def aclose(self):
+        await self._client.aclose()
+
+    async def close(self):
+        await self.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.aclose()
+
+    async def log_in(self, username_or_email: str, password: str) -> bool:
+        payload = {"username": username_or_email, "password": password}
+        method = "POST"
+
+        resp = await self.request(method=method, endpoint="user/login", data=payload)
+
+        if resp is None:
+            # Problem with the request that was suppressed, just return False
+            return False
+
+        self.jwt_token = resp["jwt"]
+        self.headers["Authorization"] = "Bearer " + self.jwt_token
+        self.current_username_or_email = username_or_email
+        self.current_password = password
+
+        return True
+
+    async def is_logged_in(self) -> bool:
+        return bool(self.jwt_token)
+
+    async def log_out(self) -> bool:
+        method = "POST"
+
+        resp = await self.request(method=method, endpoint="user/logout")
+
+        if resp is None:
+            # Problem with the request that was suppressed, just return False
+            return False
+
+        self.jwt_token = ""
+        self.current_username_or_email = ""
+        self.current_password = ""
+
+        return True
+
+    @property
+    async def nodeinfo(self) -> dict:
+        """Dict containing the instance's nodeinfo output.
+
+        Returns:
+            dict: deserialized copy of the instance's nodeinfo or None if the request failed and exception ignored
+        """
+        if self._nodeinfo:
+            return self._nodeinfo
+
+        method = "GET"
+        endpoint = self.instance_url + "/nodeinfo/2.1.json"
+
+        resp = await self.request(method=method, endpoint=endpoint)
+        self._nodeinfo = resp
+
+        return self._nodeinfo if self._nodeinfo else None
+
+    @property
+    async def instance_version(self) -> semver.Version:
+        """The instance's software version from the nodeinfo.
+
+        Returns:
+            semver.Version: software version of the piefed instance
+        """
+
+        current_nodeinfo = await self.nodeinfo
+
+        if current_nodeinfo is None:
+            # Problem with the request that was suppressed, just return False
+            return None
+
+        version_str = current_nodeinfo["software"]["version"]
+
+        try:
+            self._instance_version = semver.Version.parse(version_str)
+            return self._instance_version
+        except ValueError as e:
+            logger.error(msg=str(e))
+            logger.error(f"_instance_version={version_str}")
+
+            message = f"Instance version from nodeinfo not parseable: {version_str}"
+            return self._request_error(message=message, error=e)

pieforhead/exceptions.py

@@ -0,0 +1,14 @@
+class PieFedClientException(Exception):
+    pass
+
+
+class NotImplementedError(Exception):
+    pass
+
+
+class SiteException(Exception):
+    pass
+
+
+class ImageException(Exception):
+    pass

pieforhead/image.py

@@ -0,0 +1,185 @@
+from io import IOBase
+from os import PathLike
+from pathlib import Path
+from typing import BinaryIO
+
+from .clients import AsyncPieFedClient, PieFedClient
+from .exceptions import ImageException
+
+
+class Image:
+    """Class to hold image endpoints."""
+
+    def __init__(self, client: PieFedClient):
+        self._client = client
+
+    def upload(
+        self,
+        image: str | BinaryIO | PathLike | tuple[str, bytes | bytearray, str],
+        other_endpoint: str | None = None,
+    ) -> dict | None:
+        """General function for uploading an image.
+
+        Args:
+            image (str | BinaryIO | PathLike | tuple[str, bytes  |  bytearray, str]): image to upload. Tuple argument
+                must have form suitable for httpx.request, meaning that it is of the form:
+                (filename, image_bytes, mime_type).
+            other_endpoint (str | None, optional): Used to divert request to one of the other upload endpoints.
+                Defaults to None.
+
+        Raises:
+            ImageException: raised if image type isn't understood or if unknown endpoint is provided
+
+        Returns:
+            dict | None: returns dict if successful and None if there is an error and exceptions were suppressed by the
+                client.
+        """
+
+        opened_file = False
+        file_obj = None
+
+        try:
+            # Figure out how to handle the image depending on the type provided
+            if isinstance(image, str | PathLike):
+                path = Path(image)
+                opened_file = True
+                file_obj = path.open("rb")
+            elif isinstance(image, tuple):
+                file_obj = image
+            elif isinstance(image, IOBase):
+                file_obj = image
+                file_obj.seek(0)
+            else:
+                if self._client.raise_exceptions:
+                    raise ImageException(f"Incompatible image type provided for upload: {type(image)}")
+                return
+
+            if not other_endpoint:
+                endpoint = "upload/image"
+            elif other_endpoint == "community":
+                endpoint = "upload/community_image"
+            elif other_endpoint == "user":
+                endpoint = "upload/user_image"
+            else:
+                if self._client.raise_exceptions:
+                    raise ImageException(f"Unknown image endpoint provided: {other_endpoint}")
+                return
+
+            files = {"file": file_obj}
+            return self._client.request(method="POST", endpoint=endpoint, files=files)
+        finally:
+            # Make sure to still close the file object no matter what happened with the request
+            if opened_file:
+                file_obj.close()
+
+    def upload_community_image(
+        self,
+        image: str | BinaryIO | PathLike | tuple[str, bytes | bytearray, str],
+    ) -> dict | None:
+        return self.upload(image=image, other_endpoint="community")
+
+    def upload_user_image(
+        self,
+        image: str | BinaryIO | PathLike | tuple[str, bytes | bytearray, str],
+    ) -> dict | None:
+        return self.upload(image=image, other_endpoint="user")
+
+    def delete(self, url: str) -> dict | None:
+        """Delete an uploaded image by providing its url.
+
+        Args:
+            url (str): url of the uploaded image to delete
+
+        Returns:
+            dict | None: should be {"result": "ok"} if successful. None if there is an exception that is suppressed
+        """
+        return self._client.request(method="POST", endpoint="image/delete", data={"file": url})
+
+
+class ImageAsync:
+    """Class to hold async image endpoints."""
+
+    def __init__(self, client: AsyncPieFedClient):
+        self._client = client
+
+    async def upload(
+        self,
+        image: str | BinaryIO | PathLike | tuple[str, bytes | bytearray, str],
+        other_endpoint: str | None = None,
+    ) -> dict | None:
+        """General function for uploading an image.
+
+        Args:
+            image (str | BinaryIO | PathLike | tuple[str, bytes  |  bytearray, str]): image to upload. Tuple argument
+                must have form suitable for httpx.request, meaning that it is of the form:
+                (filename, image_bytes, mime_type).
+            other_endpoint (str | None, optional): Used to divert request to one of the other upload endpoints.
+                Defaults to None.
+
+        Raises:
+            ImageException: raised if image type isn't understood or if unknown endpoint is provided
+
+        Returns:
+            dict | None: returns dict if successful and None if there is an error and exceptions were suppressed by the
+                client.
+        """
+
+        opened_file = False
+        file_obj = None
+
+        try:
+            # Figure out how to handle the image depending on the type provided
+            if isinstance(image, str | PathLike):
+                path = Path(image)
+                opened_file = True
+                file_obj = path.open("rb")
+            elif isinstance(image, tuple):
+                file_obj = image
+            elif isinstance(image, IOBase):
+                file_obj = image
+                file_obj.seek(0)
+            else:
+                if self._client.raise_exceptions:
+                    raise ImageException(f"Incompatible image type provided for upload: {type(image)}")
+                return
+
+            if not other_endpoint:
+                endpoint = "upload/image"
+            elif other_endpoint == "community":
+                endpoint = "upload/community_image"
+            elif other_endpoint == "user":
+                endpoint = "upload/user_image"
+            else:
+                if self._client.raise_exceptions:
+                    raise ImageException(f"Unknown image endpoint provided: {other_endpoint}")
+                return
+
+            files = {"file": file_obj}
+            return await self._client.request(method="POST", endpoint=endpoint, files=files)
+        finally:
+            # Make sure to still close the file object no matter what happened with the request
+            if opened_file:
+                file_obj.close()
+
+    async def upload_community_image(
+        self,
+        image: str | BinaryIO | PathLike | tuple[str, bytes | bytearray, str],
+    ) -> dict | None:
+        return await self.upload(image=image, other_endpoint="community")
+
+    async def upload_user_image(
+        self,
+        image: str | BinaryIO | PathLike | tuple[str, bytes | bytearray, str],
+    ) -> dict | None:
+        return await self.upload(image=image, other_endpoint="user")
+
+    async def delete(self, url: str) -> dict | None:
+        """Delete an uploaded image by providing its url.
+
+        Args:
+            url (str): url of the uploaded image to delete
+
+        Returns:
+            dict | None: should be {"result": "ok"} if successful. None if there is an exception that is suppressed
+        """
+        return await self._client.request(method="POST", endpoint="image/delete", data={"file": url})

pieforhead/pieforhead.py

@@ -0,0 +1,79 @@
+import logging
+
+import semver
+
+from .clients import AsyncPieFedClient, PieFedClient
+from .site import Site, SiteAsync
+from .image import Image, ImageAsync
+
+logger = logging.getLogger(__name__)
+
+
+class PieFed:
+    _client: PieFedClient
+    instance_url: str
+
+    def __init__(self, instance_url: str, timeout: float = 5.0, raise_exceptions: bool = True):
+        self.instance_url = instance_url.removesuffix("/")
+        self._client = PieFedClient(instance_url=instance_url, timeout=timeout, raise_exceptions=raise_exceptions)
+
+        # Initialize attributes used for different endpoint groupings
+        self.site = Site(client=self._client)
+        self.image = Image(client=self._client)
+
+    def __enter__(self):
+        return self
+
+    def log_in(self, username_or_email: str, password: str) -> bool:
+        return self._client.log_in(username_or_email, password)
+
+    def is_logged_in(self) -> bool:
+        return self._client.is_logged_in()
+
+    def log_out(self) -> bool:
+        return self._client.log_out()
+
+    def close(self):
+        self._client.close()
+
+    def __exit__(self, *args):
+        self.close()
+
+    @property
+    def instance_version(self) -> semver.Version:
+        return self._client.instance_version
+
+
+class PieFedAsync:
+    _client: AsyncPieFedClient
+    instance_url: str
+
+    def __init__(self, instance_url: str, timeout: float = 5.0, raise_exceptions: bool = True):
+        self.instance_url = instance_url.removesuffix("/")
+        self._client = AsyncPieFedClient(instance_url=instance_url, timeout=timeout, raise_exceptions=raise_exceptions)
+
+        # Initialize attributes used for different endpoint groupings
+        self.site = SiteAsync(client=self._client)
+        self.image = ImageAsync(client=self._client)
+
+    async def __aenter__(self):
+        return self
+
+    async def log_in(self, username_or_email: str, password: str) -> bool:
+        return await self._client.log_in(username_or_email, password)
+
+    async def is_logged_in(self) -> bool:
+        return await self._client.is_logged_in()
+
+    async def log_out(self) -> bool:
+        return await self._client.log_out()
+
+    async def close(self):
+        await self._client.close()
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    @property
+    async def instance_version(self) -> semver.Version:
+        return await self._client.instance_version

pieforhead/site.py

@@ -0,0 +1,142 @@
+import semver
+
+from .clients import PieFedClient, AsyncPieFedClient
+from .exceptions import NotImplementedError, SiteException
+
+
+class Site:
+    """Class to hold Site endpoints."""
+
+    def __init__(self, client: PieFedClient):
+        self._client = client
+
+    def get(self) -> dict | None:
+        """Dumps value returned from site endpoint into a dict.
+
+        Returns:
+            dict: contents of GET site endpoint
+        """
+
+        return self._client.request(method="GET", endpoint="site")
+
+    def version(self) -> semver.Version | None:
+        """Fetch software version from site/version endpoint.
+
+        Returns:
+            semver.Version: software version
+        """
+
+        resp = self._client.request(method="GET", endpoint="site/version")
+
+        if resp is None:
+            # Some problem with the request, but exceptions are suppressed
+            return
+
+        if "version" in resp:
+            try:
+                return semver.Version.parse(resp["version"])
+            except ValueError as e:
+                raise SiteException(f"Version not parseable: {resp['version']}") from e
+
+        return
+
+    def block(self, block: bool, instance_id: int) -> bool | None:
+        """Block or unblock an instance with a given id.
+
+        Args:
+            block (bool): True = block, False = unblock
+            instance_id (int): id of instance
+
+        Returns:
+            bool: True if instance is now blocked, False if it is now unblocked
+        """
+        payload = {"block": block, "instance_id": instance_id}
+
+        resp = self._client.request(method="POST", endpoint="site/block", data=payload)
+
+        if resp is None:
+            # Some problem with the request, but exceptions are suppressed
+            return
+
+        return resp["blocked"]
+
+    def instance_chooser(self):
+        if self._client.raise_exceptions:
+            raise NotImplementedError
+        else:
+            return
+
+    def instance_chooser_search(self):
+        if self._client.raise_exceptions:
+            raise NotImplementedError
+        else:
+            return
+
+
+class SiteAsync:
+    """Class to hold async Site endpoints."""
+
+    def __init__(self, client: AsyncPieFedClient):
+        self._client = client
+
+    async def get(self) -> dict | None:
+        """Dumps value returned from site endpoint into a dict.
+
+        Returns:
+            dict: contents of GET site endpoint
+        """
+
+        return await self._client.request(method="GET", endpoint="site")
+
+    async def version(self) -> semver.Version | None:
+        """Fetch software version from site/version endpoint.
+
+        Returns:
+            semver.Version: software version
+        """
+
+        resp = await self._client.request(method="GET", endpoint="site/version")
+
+        if resp is None:
+            # Some problem with the request, but exceptions are suppressed
+            return
+
+        if "version" in resp:
+            try:
+                return semver.Version.parse(resp["version"])
+            except ValueError as e:
+                raise SiteException(f"Version not parseable: {resp['version']}") from e
+
+        return
+
+    async def block(self, block: bool, instance_id: int) -> bool | None:
+        """Block or unblock an instance with a given id.
+
+        Args:
+            block (bool): True = block, False = unblock
+            instance_id (int): id of instance
+
+        Returns:
+            bool: True if instance is now blocked, False if it is now unblocked
+        """
+        payload = {"block": block, "instance_id": instance_id}
+
+        resp = await self._client.request(method="POST", endpoint="site/block", data=payload)
+
+        if resp is None:
+            # Some problem with the request, but exceptions are suppressed
+            return
+
+        return resp["blocked"]
+
+    async def instance_chooser(self):
+        if self._client.raise_exceptions:
+            raise NotImplementedError
+        else:
+            return
+
+    async def instance_chooser_search(self):
+        if self._client.raise_exceptions:
+            raise NotImplementedError
+        else:
+            return

pieforhead/utils.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

pieforhead-0.0.1.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: pieforhead
+Version: 0.0.1
+Summary: A python library for interacting with the PieFed API
+Project-URL: Homepage, https://github.com/wjs018/pieforhead
+Project-URL: Issues, https://github.com/wjs018/pieforhead/issues
+Author-email: wjs018 <wjs018@gmail.com>
+License-Expression: Unlicense
+License-File: LICENSE
+Keywords: fediverse,piefed
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Requires-Dist: semver
+Description-Content-Type: text/markdown
+
+# pieforhead
+
+A python wrapper for the PieFed API supporting both synchronous and asynchronous usage. This is an early work in progress, and few endpoints are supported yet.
+
+![pieforhead logo](logo.png)
+
+## Usage Notes
+
+In general, all successful requests to the server should return a `dict` with the server's json response. Due to the alpha nature of the PieFed API, the maintenance burden of creating and updating response models as features/fields are added to the API is a burden that I don't want to take on at this time. Please refer to the official PieFed OpenAPI specification ([stable version](https://stable.wjs018.xyz/api/alpha/swagger), [development version](https://crust.piefed.social/api/alpha/swagger)) to see what your code should expect as a response.
+
+By default, exceptions will be raised if something goes wrong (e.g. malformed request, network timeout, 5XX errors, etc.) to provide a trace. However, to suppress these exceptions, you can pass the `raise_exceptions=False` keyword argument when instantiating your client. This will cause a returned value of `None` instead of raising an exception. Please make sure that your code handles such a case appropriately.
+
+## Synchronous Client Usage
+
+Users familiar with network libraries like `requests` would probably be most familiar with synchronous usage. However, to make network requests a bit more efficient, this library makes use of `Client`s within `httpx` where you can take advantage of connection pooling for multiple network requests. This means that when you instantiate a `PieFed` class, it is best practice to close it when you are done with it. Here are a couple examples that show how this can be done.
+
+These snippets all do the same three things:
+
+1. Create a `PieFed` object with the given instance url (this creates the client)
+2. Log in using a username and password
+3. Close the client after we no longer need it
+
+Closing it manually using the `close` function:
+
+```python
+from piefedhead import PieFed
+
+piefed = PieFed("https://instance.tld")
+piefed.log_in("username", "password")
+
+piefed.close()
+```
+
+Using a context manager (a `with` block):
+
+```python
+# Inside a context manager
+with PieFed("https://instance.tld") as piefed:
+    piefed.log_in("username", "password")
+
+# The connection is closed after leaving the `with` block
+```
+
+Using a callback that ensures the `close` function is called when execution has ended:
+
+```python
+# Registering an event handler
+import atexit
+
+piefed = PieFed("https://instance.tld")
+atexit.register(piefed.close)  # Automatically closes the client at program termination
+```
+
+## Asynchronous Client Usage
+
+To use this libray in an async manner, there is a separate client, `PieFedAsync` that should be used. Everything else should work exactly the same as the synchronous client, except that results will need to be `await`ed.
+
+Here is a snippet that does the same three actions as outlined above for the synchronous client, but using the `PieFedAsync` client.
+
+```python
+# Put things in an async function so that we can use the await keyword
+async def main():
+    piefed_async = PieFedAsync("https://instance.tld")
+    await piefed_async.log_in("username", "password")  # Notice the await keyword
+
+    await piefed_async.close()
+
+# Start the event loop and execute the async function
+asyncio.run(main())
+```
+
+Similar to the synchronous client, you can also use a context handler to automatically close the async client:
+
+```python
+async def main():
+    async with PieFedAsync("https://instance.tld") as piefed_async:
+        await piefed_async.log_in("username", "password")
+
+    # Client is closed automatically once outside the context handler
+
+# Start the event loop and execute the async function
+asyncio.run(main())
+```
+
+## Endpoint Coverage
+
+This project is in an early stage. Here is a high level summary of where things stand with implementing the wrapper around different PieFed API endpoint groups:
+
+| Endpoint Group  | Sync Client | Async Client | Notes                                    |
+| :-------------: | :---------: | :----------: | :--------------------------------------- |
+|      Site       |     ✅      |      ✅      | Instance chooser endpoints unimplemented |
+|     Upload      |     ✅      |      ✅      |                                          |
+|      User       |     🟡      |      🟡      | Auth endpoints implemented               |
+|      Post       |     ❌      |      ❌      |                                          |
+|     Comment     |     ❌      |      ❌      |                                          |
+|    Community    |     ❌      |      ❌      |                                          |
+|      Feed       |     ❌      |      ❌      |                                          |
+|      Topic      |     ❌      |      ❌      |                                          |
+| Private Message |     ❌      |      ❌      |                                          |
+|      Admin      |     ❌      |      ❌      |                                          |
+|      Misc.      |     ❌      |      ❌      |                                          |

pieforhead-0.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+pieforhead/__init__.py,sha256=nvEcwCSSK6K4ywr78d9EXgk7WJCcGcaK86Zjj9uNSxc,134
+pieforhead/clients.py,sha256=RBWIfrR3dhlQI2nwXgxQ9VOeRhOj-B1pjoxSKc6jqEs,16167
+pieforhead/exceptions.py,sha256=Q-JiNqUJ7Bf9sThXfXqCfI9zs7UXEO2af4P9SbD5EG8,185
+pieforhead/image.py,sha256=0hiv6FCmd8-tICWb8sWZzyIGcBTIN25lzPPtEc8FXKM,6984
+pieforhead/pieforhead.py,sha256=U9sJExCd5hDf9m2BxBMg1XaE_yinDdUDcpUFhS82EiM,2386
+pieforhead/site.py,sha256=vgWNHg2Ey2sJRglTiGQifeeOHMyH121wBV7bskq14Jc,4115
+pieforhead/utils.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+pieforhead-0.0.1.dist-info/METADATA,sha256=rJp0cdOxcGaiOLFWhuKSUy8JptPh1mlHsk7yxd0bbUM,5772
+pieforhead-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pieforhead-0.0.1.dist-info/licenses/LICENSE,sha256=awOCsWJ58m_2kBQwBUGWejVqZm6wuRtCL2hi9rfa0X4,1211
+pieforhead-0.0.1.dist-info/RECORD,,

pieforhead-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pieforhead-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>