pyyapper 1.4.0__tar.gz → 1.5.0__tar.gz

{pyyapper-1.4.0/src/pyyapper.egg-info → pyyapper-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyyapper
-Version: 1.4.0
+Version: 1.5.0
 Summary: An intuitive, async Python library for the Yapper bot API.
 Author: PyYapper contributors
 License-Expression: MIT

{pyyapper-1.4.0 → pyyapper-1.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyyapper"
-version = "1.4.0"
+version = "1.5.0"
 description = "An intuitive, async Python library for the Yapper bot API."
 readme = "README.md"
 license = "MIT"

{pyyapper-1.4.0 → pyyapper-1.5.0}/src/pyyapper/__init__.py

@@ -23,6 +23,7 @@ from .presence import Activity, Presence
 from .pagination import Paginator
 from .webhooks import Webhook
 from .wait_for import WaiterRegistry, wait_for
+from .oauth import OAuth2Client, OAuthError, generate_state, generate_pkce, YapperOAuth, LoginWithYapper
 from .config import load_config, load_env_file, get_token
 from .i18n import Translator, t as translate
 from .metrics import Metrics
@@ -38,6 +39,8 @@ __all__ = [
     "User", "Server", "Channel", "Category", "Member", "Message", "Role", "VoiceChannel", "picture_url",
     "Activity", "Presence",
     "Paginator", "Webhook", "WaiterRegistry", "wait_for",
+    "OAuth2Client", "OAuthError", "generate_state", "generate_pkce",
+    "YapperOAuth", "LoginWithYapper",
     "load_config", "load_env_file", "get_token",
     "Translator", "translate", "Metrics",
     "commands", "tasks",

pyyapper-1.5.0/src/pyyapper/_version.py

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

pyyapper-1.5.0/src/pyyapper/oauth.py

@@ -0,0 +1,217 @@
+"""OAuth2 "Login with Yapper" client for PyYapper.
+
+Implements the authorization-code flow (with optional PKCE) described in the
+Yapper developer docs. This is intended for web apps that let users log in with
+their Yapper account; it is independent of the bot API.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import secrets
+import urllib.parse
+from typing import Any, Optional
+
+import aiohttp
+
+from .errors import YapperError
+
+
+class OAuthError(YapperError):
+    """An OAuth2 request failed.
+
+    Attributes:
+        error: OAuth2 error code (e.g. ``invalid_grant``).
+        description: Human readable description.
+        status: HTTP status code.
+    """
+
+    def __init__(self, error: str, description: str = "", *, status: int = 400) -> None:
+        self.error = error
+        self.description = description
+        self.status = status
+        super().__init__(f"{error}: {description}".strip(": "))
+
+
+DEFAULT_BASE = "https://www.yapper.website"
+AUTHORIZE_PATH = "/oauth/authorize"
+TOKEN_PATH = "/api/oauth/token"
+ME_PATH = "/api/oauth/me"
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def generate_state(n: int = 32) -> str:
+    """Generate a random, URL-safe ``state`` value."""
+    return secrets.token_urlsafe(n)
+
+
+def generate_pkce(verifier_length: int = 64) -> tuple[str, str]:
+    """Generate a (code_verifier, code_challenge) pair for PKCE (S256)."""
+    verifier = secrets.token_urlsafe(verifier_length)[:128]
+    if len(verifier) < 43:
+        verifier = verifier + secrets.token_urlsafe(43 - len(verifier))
+    challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
+    return verifier, challenge
+
+
+class OAuth2Client:
+    """A client for one Yapper OAuth2 app.
+
+    Parameters
+    ----------
+    client_id:
+        The app's client id.
+    client_secret:
+        The app's client secret (omit for PKCE/public apps).
+    redirect_uri:
+        Default redirect URI (must match one registered for the app).
+    base_url:
+        Yapper base URL. Defaults to ``https://www.yapper.website``.
+    session:
+        Optional shared :class:`aiohttp.ClientSession`.
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: Optional[str] = None,
+        redirect_uri: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> None:
+        self.client_id = str(client_id)
+        self.client_secret = client_secret
+        self.redirect_uri = redirect_uri
+        self.base_url = base_url.rstrip("/")
+        self._session = session
+        self._owns_session = session is None
+
+    # ------------------------------------------------------------------ #
+    # Session management
+    # ------------------------------------------------------------------ #
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or getattr(self._session, "closed", False):
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self._session
+
+    async def close(self) -> None:
+        if self._owns_session and self._session is not None and not getattr(self._session, "closed", True):
+            await self._session.close()
+        self._session = None
+
+    async def __aenter__(self) -> "OAuth2Client":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    # ------------------------------------------------------------------ #
+    # Authorization URL
+    # ------------------------------------------------------------------ #
+    def authorization_url(
+        self,
+        state: str,
+        *,
+        scope: str = "identify",
+        redirect_uri: Optional[str] = None,
+        code_challenge: Optional[str] = None,
+        code_challenge_method: str = "S256",
+    ) -> str:
+        params: dict[str, Any] = {
+            "client_id": self.client_id,
+            "redirect_uri": redirect_uri or self.redirect_uri,
+            "response_type": "code",
+            "scope": scope,
+            "state": state,
+        }
+        if code_challenge is not None:
+            params["code_challenge"] = code_challenge
+            params["code_challenge_method"] = code_challenge_method
+        return f"{self.base_url}{AUTHORIZE_PATH}?{urllib.parse.urlencode(params)}"
+
+    # ------------------------------------------------------------------ #
+    # Token exchange
+    # ------------------------------------------------------------------ #
+    async def exchange_code(
+        self,
+        code: str,
+        *,
+        redirect_uri: Optional[str] = None,
+        code_verifier: Optional[str] = None,
+        use_basic_auth: bool = False,
+    ) -> dict[str, Any]:
+        url = f"{self.base_url}{TOKEN_PATH}"
+        body: dict[str, Any] = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri or self.redirect_uri,
+            "client_id": self.client_id,
+        }
+        if self.client_secret is not None and not use_basic_auth:
+            body["client_secret"] = self.client_secret
+        if code_verifier is not None:
+            body["code_verifier"] = code_verifier
+
+        headers: dict[str, str] = {"Content-Type": "application/x-www-form-urlencoded"}
+        if use_basic_auth and self.client_secret is not None:
+            import base64 as _b64
+
+            creds = _b64.b64encode(f"{self.client_id}:{self.client_secret}".encode()).decode()
+            headers["Authorization"] = f"Basic {creds}"
+            body.pop("client_secret", None)
+
+        session = await self._get_session()
+        async with session.post(url, data=body, headers=headers) as res:
+            raw = await res.read()
+            text = raw.decode("utf-8", errors="replace") if raw else ""
+            try:
+                payload = json.loads(text) if text else {}
+            except Exception:
+                payload = {}
+            if res.status >= 400:
+                err = payload.get("error", "invalid_request") if isinstance(payload, dict) else "invalid_request"
+                desc = payload.get("error_description", "") if isinstance(payload, dict) else ""
+                raise OAuthError(err, desc, status=res.status)
+            return payload if isinstance(payload, dict) else {}
+
+    # ------------------------------------------------------------------ #
+    # User info
+    # ------------------------------------------------------------------ #
+    async def fetch_user(self, access_token: str) -> dict[str, Any]:
+        url = f"{self.base_url}{ME_PATH}"
+        session = await self._get_session()
+        async with session.get(url, headers={"Authorization": f"Bearer {access_token}"}) as res:
+            raw = await res.read()
+            text = raw.decode("utf-8", errors="replace") if raw else ""
+            try:
+                payload = json.loads(text) if text else {}
+            except Exception:
+                payload = {}
+            if res.status >= 400:
+                err = payload.get("error", "invalid_token") if isinstance(payload, dict) else "invalid_token"
+                desc = payload.get("error_description", "") if isinstance(payload, dict) else ""
+                raise OAuthError(err, desc, status=res.status)
+            return payload if isinstance(payload, dict) else {}
+
+    # ------------------------------------------------------------------ #
+    # Convenience
+    # ------------------------------------------------------------------ #
+    async def login(self, code: str, **kw: Any) -> dict[str, Any]:
+        """Exchange ``code`` and immediately fetch the user. Returns ``{token, user}``."""
+        token = await self.exchange_code(code, **kw)
+        access_token = token.get("access_token")
+        user = await self.fetch_user(access_token) if access_token else None
+        return {"token": token, "user": user}
+
+
+# Aliases
+YapperOAuth = OAuth2Client
+LoginWithYapper = OAuth2Client

{pyyapper-1.4.0 → pyyapper-1.5.0/src/pyyapper.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyyapper
-Version: 1.4.0
+Version: 1.5.0
 Summary: An intuitive, async Python library for the Yapper bot API.
 Author: PyYapper contributors
 License-Expression: MIT

{pyyapper-1.4.0 → pyyapper-1.5.0}/src/pyyapper.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ src/pyyapper/http.py
 src/pyyapper/i18n.py
 src/pyyapper/metrics.py
 src/pyyapper/models.py
+src/pyyapper/oauth.py
 src/pyyapper/pagination.py
 src/pyyapper/presence.py
 src/pyyapper/py.typed
@@ -32,6 +33,7 @@ src/pyyapper/ext/commands/converters.py
 src/pyyapper/ext/commands/core.py
 src/pyyapper/ext/commands/errors.py
 tests/test_ext_commands.py
+tests/test_oauth.py
 tests/test_smoke.py
 tests/test_tasks.py
 tests/test_webhooks.py

pyyapper-1.5.0/tests/test_oauth.py

@@ -0,0 +1,35 @@
+import asyncio
+
+from pyyapper import OAuth2Client, generate_state, generate_pkce, OAuthError
+
+
+def test_auth_url():
+    c = OAuth2Client("cid", "secret", "https://example.com/cb")
+    url = c.authorization_url("st")
+    assert "client_id=cid" in url
+    assert "state=st" in url
+    assert "response_type=code" in url
+
+
+def test_pkce():
+    v, ch = generate_pkce()
+    assert len(v) >= 43
+    assert len(ch) >= 43
+
+
+def test_generate_state():
+    s = generate_state()
+    assert len(s) >= 32
+
+
+def test_oauth_error():
+    e = OAuthError("invalid_grant", "bad code", status=400)
+    assert e.error == "invalid_grant"
+    assert e.status == 400
+
+
+def test_async_context_manager():
+    async def main():
+        async with OAuth2Client("cid", redirect_uri="https://example.com/cb") as c:
+            assert c.client_id == "cid"
+    asyncio.run(main())

pyyapper-1.4.0/src/pyyapper/_version.py

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