longwei 1.0.0.dev0__py3-none-any.whl

longwei/__init__.py

@@ -0,0 +1,74 @@
+"""Package 'longwei' level definitions."""
+
+import sys
+from enum import Enum
+from importlib.metadata import version
+from typing import Final
+
+from longwei.constants import INSTANCE_TYPE_MASTODON
+from longwei.constants import INSTANCE_TYPE_PLEROMA
+from longwei.constants import INSTANCE_TYPE_TAKAHE
+from longwei.exceptions import ActivityPubError
+from longwei.exceptions import ApiError
+from longwei.exceptions import ClientError
+from longwei.exceptions import ConflictError
+from longwei.exceptions import ForbiddenError
+from longwei.exceptions import GoneError
+from longwei.exceptions import NetworkError
+from longwei.exceptions import NotFoundError
+from longwei.exceptions import RatelimitError
+from longwei.exceptions import ServerError
+from longwei.exceptions import UnauthorizedError
+from longwei.exceptions import UnprocessedError
+from longwei.models import Account
+from longwei.types import ActivityPubClass
+from longwei.types import Status
+
+__display_name__: Final[str] = "Longwei"
+__version__: Final[str] = version(str(__package__))
+
+USER_AGENT: Final[str] = f"{__display_name__}_v{__version__}_Python_{sys.version.split()[0]}"
+
+
+class Visibility(str, Enum):
+    """Enumerating possible Visibility values for statuses."""
+
+    PUBLIC = "public"
+    UNLISTED = "unlisted"
+    PRIVATE = "private"
+    DIRECT = "direct"
+
+
+class SearchType(str, Enum):
+    """Enumerating possible type values for status searches."""
+
+    ACCOUNTS = "accounts"
+    HASHTAGS = "hashtags"
+    STATUSES = "statuses"
+
+
+__all__ = [  # noqa: RUF022
+    "Account",
+    "ActivityPubClass",
+    "ActivityPubError",
+    "ApiError",
+    "ClientError",
+    "ConflictError",
+    "__display_name__",
+    "ForbiddenError",
+    "GoneError",
+    "INSTANCE_TYPE_MASTODON",
+    "INSTANCE_TYPE_PLEROMA",
+    "INSTANCE_TYPE_TAKAHE",
+    "NetworkError",
+    "NotFoundError",
+    "RatelimitError",
+    "SearchType",
+    "ServerError",
+    "Status",
+    "UnauthorizedError",
+    "UnprocessedError",
+    "USER_AGENT",
+    "__version__",
+    "Visibility",
+]

longwei/_mixin_auth.py

@@ -0,0 +1,218 @@
+"""Auth mixin: OAuth app creation, token acquisition, authorization URL generation."""
+
+import json
+import logging
+from urllib.parse import urlencode
+
+from httpx import AsyncClient
+from httpx import HTTPError
+
+from longwei import USER_AGENT
+from longwei import __display_name__
+from longwei.constants import REDIRECT_URI
+from longwei.exceptions import NetworkError
+from longwei.utils import _check_exception
+
+logger = logging.getLogger(__display_name__)
+
+
+class _AuthMixin:
+    """Mixin providing static OAuth/authentication methods."""
+
+    @staticmethod
+    async def generate_authorization_url(
+        instance_url: str,
+        client_id: str,
+        user_agent: str = USER_AGENT,
+    ) -> str:
+        """Create URL to get access token interactively from website.
+
+        :param instance_url: The URL of the Mastodon instance you want to connect to
+        :param client_id: Client id of app as generated by create_app method
+        :param user_agent: User agent identifier to use. Defaults to longwei related one.
+
+        :returns: String containing URL to visit to get access token interactively from instance.
+        """
+        logger.debug(
+            "ActivityPub.get_auth_token_interactive(instance_url=%s, client=...,client_id=%s, user_agent=%s)",
+            instance_url,
+            client_id,
+            user_agent,
+        )
+        if "http" not in instance_url:
+            instance_url = f"https://{instance_url}"
+
+        url_params = urlencode(
+            {
+                "response_type": "code",
+                "client_id": client_id,
+                "redirect_uri": REDIRECT_URI,
+                "scope": "read write",
+            }
+        )
+        auth_url = f"{instance_url}/oauth/authorize?{url_params}"
+        logger.debug(
+            "ActivityPub.get_auth_token_interactive(...) -> %s",
+            auth_url,
+        )
+
+        return auth_url
+
+    @staticmethod
+    async def validate_authorization_code(
+        client: AsyncClient,
+        instance_url: str,
+        authorization_code: str,
+        client_id: str,
+        client_secret: str,
+    ) -> str:
+        """Validate an authorization code and get access token needed for API access.
+
+        :param client: httpx.AsyncClient
+        :param instance_url: The URL of the Mastodon instance you want to connect to
+        :param authorization_code: authorization code
+        :param client_id: client id as returned by create_app method
+        :param client_secret: client secret as returned by create_app method
+
+        :returns: access token
+        """
+        logger.debug(
+            "ActivityPub.validate_authorization_code(authorization_code=%s, client_id=%s, client_secret=<redacted>)",
+            authorization_code,
+            client_id,
+        )
+        if "http" not in instance_url:
+            instance_url = f"https://{instance_url}"
+
+        data = {
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "scope": "read write",
+            "redirect_uri": REDIRECT_URI,
+            "grant_type": "authorization_code",
+            "code": authorization_code,
+        }
+        try:
+            response = await client.post(url=f"{instance_url}/oauth/token", data=data)
+            logger.debug(
+                "ActivityPub.validate_authorization_code - response:\n%s",
+                response,
+            )
+            await _check_exception(response)
+            response_dict = response.json()
+        except HTTPError as error:
+            raise NetworkError from error
+
+        logger.debug(
+            "ActivityPub.validate_authorization_code - response.json: \n%s",
+            json.dumps(response_dict, indent=4),
+        )
+        return str(response_dict["access_token"])
+
+    @staticmethod
+    async def get_auth_token(  # noqa: PLR0913  - No way around needing all this parameters
+        instance_url: str,
+        username: str,
+        password: str,
+        client: AsyncClient,
+        user_agent: str = USER_AGENT,
+        client_website: str = "https://pypi.org/project/longwei/",
+    ) -> str:
+        """Create an app and use it to get an access token.
+
+        :param instance_url: The URL of the Mastodon instance you want to connect to
+        :param username: The username of the account you want to get an auth_token for
+        :param password: The password of the account you want to get an auth_token for
+        :param client: httpx.AsyncClient
+        :param user_agent: User agent identifier to use. Defaults to longwei related one.
+        :param client_website: Link to site for user_agent. Defaults to link to longwei on Pypi.org
+
+        :returns: The access token is being returned.
+        """
+        logger.debug(
+            "ActivityPub.get_auth_token(instance_url=%s, username=%s, password=<redacted>, client=..., "
+            "user_agent=%s, client_website=%s)",
+            instance_url,
+            username,
+            user_agent,
+            client_website,
+        )
+        if "http" not in instance_url:
+            instance_url = f"https://{instance_url}"
+
+        client_id, client_secret = await _AuthMixin.create_app(
+            client_website=client_website,
+            instance_url=instance_url,
+            client=client,
+            user_agent=user_agent,
+        )
+
+        data = {
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "scope": "read write",
+            "redirect_uris": REDIRECT_URI,
+            "grant_type": "password",
+            "username": username,
+            "password": password,
+        }
+
+        try:
+            response = await client.post(url=f"{instance_url}/oauth/token", data=data)
+            logger.debug("ActivityPub.get_auth_token - response:\n%s", response)
+            await _check_exception(response)
+            response_dict = response.json()
+        except HTTPError as error:
+            raise NetworkError from error
+
+        logger.debug(
+            "ActivityPub.get_auth_token - response.json: \n%s",
+            json.dumps(response_dict, indent=4),
+        )
+        return str(response_dict["access_token"])
+
+    @staticmethod
+    async def create_app(
+        instance_url: str,
+        client: AsyncClient,
+        user_agent: str = USER_AGENT,
+        client_website: str = "https://pypi.org/project/longwei/",
+    ) -> tuple[str, str]:
+        """Create an app.
+
+        :param instance_url: The URL of the Mastodon instance you want to connect to
+        :param client: httpx.AsyncClient
+        :param user_agent: User agent identifier to use. Defaults to longwei related one.
+        :param client_website: Link to site for user_agent. Defaults to link to longwei on Pypi.org
+
+        :returns: tuple(client_id, client_secret)
+        """
+        logger.debug(
+            "ActivityPub.create_app(instance_url=%s, client=..., user_agent=%s, client_website=%s)",
+            instance_url,
+            user_agent,
+            client_website,
+        )
+
+        if "http" not in instance_url:
+            instance_url = f"https://{instance_url}"
+
+        data = {
+            "client_name": user_agent,
+            "client_website": client_website,
+            "scopes": "read write",
+            "redirect_uris": REDIRECT_URI,
+        }
+        try:
+            response = await client.post(url=f"{instance_url}/api/v1/apps", data=data)
+            logger.debug("ActivityPub.create_app response: \n%s", response)
+            await _check_exception(response)
+            response_dict = response.json()
+        except HTTPError as error:
+            raise NetworkError from error
+
+        logger.debug(
+            "ActivityPub.create_app response.json: \n%s",
+            json.dumps(response_dict, indent=4),
+        )
+        return (response_dict["client_id"]), (response_dict["client_secret"])

longwei/_mixin_credentials.py

@@ -0,0 +1,103 @@
+"""Credentials mixin: verify_credentials, determine_instance_type, _set_instance_parameters."""
+
+import json
+import logging
+from typing import Any
+
+from httpx import HTTPError
+
+from longwei import __display_name__
+from longwei.constants import INSTANCE_TYPE_PLEROMA
+from longwei.constants import INSTANCE_TYPE_TAKAHE
+from longwei.constants import MAX_ATTACHMENTS_PLEROMA
+from longwei.constants import MAX_ATTACHMENTS_TAKAHE
+from longwei.exceptions import NetworkError
+from longwei.models import Account
+from longwei.types import ActivityPubClass
+from longwei.utils import _check_exception
+
+logger = logging.getLogger(__display_name__)
+
+
+class _CredentialsMixin:
+    """Mixin providing credential verification and instance type detection."""
+
+    async def verify_credentials(self: ActivityPubClass) -> Account:
+        """Verify the credentials of the user.
+
+        :returns: The account information for the authenticated user.
+
+        """
+        url = f"{self.instance}/api/v1/accounts/verify_credentials"
+        logger.debug("ActivityPub.verify_credentials() - url=%s", url)
+        try:
+            response = await self.client.get(url=url, headers=self.headers, timeout=self.timeout)
+            logger.debug(
+                "ActivityPub.verify_credentials - response: \n%s",
+                response,
+            )
+            self._update_ratelimit(response.headers)
+            await _check_exception(response=response)
+            self._parse_next_prev(links=response.headers.get("Link"))
+            account = Account.model_validate(response.json())
+        except HTTPError as error:
+            raise NetworkError from error
+
+        return account
+
+    async def determine_instance_type(self: ActivityPubClass) -> None:
+        """Check if the instance is a Pleroma instance or not."""
+        instance = self.instance
+        if "http" not in self.instance:
+            instance = f"https://{self.instance}"
+
+        try:
+            response = await self.client.get(url=f"{instance}/api/v1/instance", timeout=self.timeout)
+            await _check_exception(response=response)
+            response_dict = response.json()
+        except HTTPError as error:
+            raise NetworkError from error
+
+        logger.debug(
+            "ActivityPub.determine_instance_type -> response.dict:\n%s",
+            json.dumps(response_dict, indent=4),
+        )
+        self.instance = instance
+
+        self._set_instance_parameters(response_dict)
+
+        logger.debug(
+            "ActivityPub.determine_instance_type() ... instance_type=%s",
+            self.instance_type,
+        )
+
+    def _set_instance_parameters(self, response_dict: dict[str, Any]) -> None:
+        """Set instance parameters from the /api/v1/instance response dict.
+
+        :param response_dict: Dictionary returned by call to .../api/v1/instance
+        """
+        version = response_dict.get("version", "")
+        if INSTANCE_TYPE_TAKAHE in version:
+            self.instance_type = INSTANCE_TYPE_TAKAHE
+            self.max_attachments = MAX_ATTACHMENTS_TAKAHE
+        elif INSTANCE_TYPE_PLEROMA in version:
+            self.instance_type = INSTANCE_TYPE_PLEROMA
+            self.max_attachments = MAX_ATTACHMENTS_PLEROMA
+
+        instance_config = response_dict.get("configuration", {})
+
+        if (max_status_len := instance_config.get("statuses", {}).get("max_characters")) or (
+            max_status_len := response_dict.get("max_characters")
+        ):
+            self.max_status_len = max_status_len
+
+        if (max_attachments := instance_config.get("statuses", {}).get("max_media_attachments")) or (
+            max_attachments := response_dict.get("max_media_attachments")
+        ):
+            self.max_attachments = max_attachments
+
+        if max_att_size := instance_config.get("media_attachments", {}).get("image_size_limit"):
+            self.max_att_size = max_att_size
+
+        if mime_types := instance_config.get("media_attachments", {}).get("supported_mime_types"):
+            self.supported_mime_types = mime_types

longwei/_mixin_request_helpers.py

@@ -0,0 +1,115 @@
+"""Request helper mixin: rate-limit checking, pagination parsing, rate-limit updating."""
+
+import logging
+from typing import Any
+from urllib.parse import parse_qs
+from urllib.parse import urlparse
+
+from whenever import Instant
+
+from longwei import __display_name__
+from longwei.constants import INSTANCE_TYPE_PLEROMA
+from longwei.constants import INSTANCE_TYPE_TAKAHE
+from longwei.constants import PAGINATION_UNDEFINED
+from longwei.exceptions import RatelimitError
+from longwei.types import ActivityPubClass
+from longwei.utils import parse_rate_limit_reset
+
+logger = logging.getLogger(__display_name__)
+
+
+class _RequestHelpersMixin:
+    """Mixin providing _pre_call_checks, _parse_next_prev, and _update_ratelimit."""
+
+    async def _pre_call_checks(self: ActivityPubClass) -> None:
+        """Do checks before contacting the instance server.
+
+        Raises RatelimitError if rate limit is exhausted and reset is in the future.
+        """
+        logger.debug(
+            "ActivityPub.__pre_call_checks - Limit remaining: %s - Limit resetting at %s",
+            self.ratelimit_remaining,
+            self.ratelimit_reset,
+        )
+        if self.ratelimit_remaining == 0 and self.ratelimit_reset > Instant.now().py_datetime():
+            raise RatelimitError(
+                429,
+                None,
+                "Rate limited",
+                ratelimit_reset=self.ratelimit_reset,
+                ratelimit_limit=self.ratelimit_limit,
+            )
+
+    def _parse_next_prev(self: ActivityPubClass, links: str | None) -> None:
+        """Extract min_id and max_id from a Link header and store in self.pagination.
+
+        :param links: The links header from the response
+        """
+        logger.debug("ActivityPub.__parse_next_prev - links = %s", links)
+
+        if not links:
+            return
+
+        self.pagination = PAGINATION_UNDEFINED
+
+        for comma_links in links.split(sep=", "):
+            pagination_rel: str | None = None
+            if 'rel="next"' in comma_links:
+                pagination_rel = "next"
+            elif 'rel="prev"' in comma_links:
+                pagination_rel = "prev"
+            else:
+                continue
+
+            urls = comma_links.split(sep="; ")
+
+            logger.debug("ActivityPub.__parse_next_prev - rel = %s - urls = %s", pagination_rel, urls)
+
+            for url in urls:
+                parsed_url = urlparse(url=url.lstrip("<").rstrip(">"))
+                queries_dict = parse_qs(str(parsed_url.query))
+                logger.debug("ActivityPub.__parse_next_prev - queries_dict = %s", queries_dict)
+                min_id = queries_dict.get("min_id")
+                max_id = queries_dict.get("max_id")
+                if min_id:
+                    self.pagination[pagination_rel]["min_id"] = min_id[0]
+                if max_id:
+                    self.pagination[pagination_rel]["max_id"] = max_id[0]
+
+        logger.debug("ActivityPub.__parse_next_prev - pagination = %s", self.pagination)
+
+    def _update_ratelimit(self: ActivityPubClass, headers: Any) -> None:
+        """Update rate limit tracking from response headers.
+
+        :param headers: The headers of the response
+        """
+        temp_ratelimit_limit = temp_ratelimit_remaining = temp_ratelimit_reset = None
+
+        if self.instance_type in (INSTANCE_TYPE_TAKAHE, INSTANCE_TYPE_PLEROMA):
+            # Takahe and Pleroma do not return rate limit headers.
+            # Default to 5 minute rate limit reset time
+            temp_ratelimit_reset = (Instant.now().add(minutes=5)).format_iso()
+        else:
+            temp_ratelimit_limit = headers.get("X-RateLimit-Limit")
+            temp_ratelimit_remaining = headers.get("X-RateLimit-Remaining")
+            temp_ratelimit_reset = headers.get("X-RateLimit-Reset")
+
+        if temp_ratelimit_limit:
+            self.ratelimit_limit = int(temp_ratelimit_limit)
+        if temp_ratelimit_remaining:
+            self.ratelimit_remaining = int(temp_ratelimit_remaining)
+        if temp_ratelimit_reset:
+            parsed_reset = parse_rate_limit_reset(temp_ratelimit_reset)
+            if parsed_reset:
+                self.ratelimit_reset = parsed_reset.py_datetime()
+
+        logger.debug(
+            "ActivityPub.__update_ratelimit - Pleroma Instance: %s - RateLimit Limit %s",
+            self.instance_type == INSTANCE_TYPE_PLEROMA,
+            self.ratelimit_limit,
+        )
+        logger.debug(
+            "ActivityPub.__update_ratelimit - Limit remaining: %s - Limit resetting at %s",
+            self.ratelimit_remaining,
+            self.ratelimit_reset,
+        )