📝 add docs and change to async

Author: yanyongyu

README.md

@@ -41,3 +41,92 @@ _✨ GitHub 协议适配 ✨_
     <img src="https://discordapp.com/api/guilds/847819937858584596/widget.png?style=shield" alt="Discord Server">
   </a>
 </p>
+
+## 安装
+
+```bash
+poetry add nonebot-adapter-github
+# 或者
+pip install nonebot-adapter-github
+```
+
+## 加载适配器
+
+```python
+import nonebot
+from nonebot.adapters.github import Adapter
+
+nonebot.init()
+
+driver = nonebot.get_driver()
+driver.register_adapter(Adapter)
+```
+
+## 配置
+
+### 配置 APP
+
+```dotenv
+GITHUB_APPS='
+[
+  {
+    "app_id": "123456",  # GitHub App ID 必填
+    "private_key": [
+      "-----BEGIN RSA PRIVATE KEY-----"
+      "...",
+      "-----END RSA PRIVATE KEY-----"
+    ],  # GitHub App 私钥必填
+    "client_id": "123456",  # OAuth App Client ID 必填，GitHub App 可选
+    "client_secret": "xxxxxx",  # OAuth App Client Secret 必填，GitHub App 可选
+    "webhook_secret": "xxxxxx"  # 可选
+  }
+]'
+```
+
+### 其他配置
+
+```dotenv
+GITHUB_BASE_URL=https://api.github.com
+GITHUB_ACCEPR_FORMAT=full+json
+GITHUB_PREVIEWS=["starfox"]
+```
+
+## 使用
+
+### WebHook
+
+URL: `/github/webhooks/<app_id>` (GitHub APP) / `/github/webhooks/<client_id>` (OAuth APP)
+
+事件格式:
+
+```python
+class Event(BaseModel):
+    id: str  # 事件 ID
+    name: str  # 事件名称
+    payload: Dict[str, Any]  # 事件内容
+
+    to_me: bool = False  # 是否 @ 了机器人或机器人昵称
+```
+
+具体事件类型及内容请参考 [GitHub Developer](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads)
+
+### 调用 API
+
+可以直接通过 bot 调用 API，但是请注意 **只能使用异步接口，参数必须是 keyword args**。具体使用方法参考 [githubkit](https://github.com/yanyongyu/githubkit)。
+
+```python
+async with bot.as_installation(installation_id=1):
+    resp = await bot.rest.issues.async_get(owner="owner", repo="repo", issue_number=1)
+    issue = resp.parsed_data
+
+    resp = await bot.async_graphql(query=query)
+
+    async for issue in bot.github.paginate(bot.rest.issues.async_list_for_repo, owner="owner", repo="repo"):
+        print(issue)
+```
+
+也可以直接使用 `githubkit`，但是将绕过 NoneBot 的 `call api hook`。
+
+```python
+github = bot.github
+```

nonebot/adapters/github/bot.py

@@ -1,7 +1,16 @@
 import re
 from typing_extensions import Self
-from contextlib import contextmanager
-from typing import TYPE_CHECKING, Any, Dict, List, Union, Callable, Optional, Generator
+from contextlib import asynccontextmanager
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    List,
+    Union,
+    Callable,
+    Optional,
+    AsyncGenerator,
+)
 
 from nonebot.typing import overrides
 from githubkit.utils import UNSET, Unset
@@ -59,11 +68,9 @@ def _check_nickname(bot: "Bot", event: Event) -> None:
     if message[0].type != "markdown":
         return
 
-    seg = message[0]
-    text = str(seg).lstrip()
-
     if nicknames := {nickname for nickname in bot.config.nickname if nickname}:
         # check if the user is calling me with my nickname
+        text = str(message[0]).lstrip()
         nickname_regex = "|".join(nicknames)
         if m := re.match(rf"^({nickname_regex})([\s,，]*|$)", text, re.IGNORECASE):
             event.to_me = True
@@ -156,29 +163,31 @@ def __init__(self, adapter: "Adapter", app: OAuthApp):
             timeout=self.config.api_timeout,
         )
 
-    @contextmanager
-    def as_web_user(
+    @asynccontextmanager
+    async def as_web_user(
         self, code: str, redirect_uri: Optional[str] = None
-    ) -> Generator[Self, None, None]:
+    ) -> AsyncGenerator[Self, None]:
         if self._ctx_github is not None:
             raise RuntimeError("Can not enter context twice.")
         self._ctx_github = self._github.with_auth(
             self._github.auth.as_web_user(code, redirect_uri)
         )
-        try:
-            yield self
-        finally:
-            self._ctx_github = None
-
-    @contextmanager
-    def as_user(self, token: str) -> Generator[Self, None, None]:
+        async with self._ctx_github:
+            try:
+                yield self
+            finally:
+                self._ctx_github = None
+
+    @asynccontextmanager
+    async def as_user(self, token: str) -> AsyncGenerator[Self, None]:
         if self._ctx_github is not None:
             raise RuntimeError("Can not enter context twice.")
         self._ctx_github = GitHub(TokenAuthStrategy(token))
-        try:
-            yield self
-        finally:
-            self._ctx_github = None
+        async with self._ctx_github:
+            try:
+                yield self
+            finally:
+                self._ctx_github = None
 
     @overrides(Bot)
     async def handle_event(self, event: Event) -> None:
@@ -207,59 +216,63 @@ async def _get_self_info(self):
             slug if isinstance((slug := res.parsed_data.slug), str) else None
         )
 
-    @contextmanager
-    def as_oauth_app(self) -> Generator[Self, None, None]:
+    @asynccontextmanager
+    async def as_oauth_app(self) -> AsyncGenerator[Self, None]:
         if self._ctx_github is not None:
             raise RuntimeError("Can not enter context twice.")
         self._ctx_github = self._github.with_auth(self._github.auth.as_oauth_app())
-        try:
-            yield self
-        finally:
-            self._ctx_github = None
-
-    @contextmanager
-    def as_installation(
+        async with self._ctx_github:
+            try:
+                yield self
+            finally:
+                self._ctx_github = None
+
+    @asynccontextmanager
+    async def as_installation(
         self,
         installation_id: int,
         repositories: Union[Unset, List[str]] = UNSET,
         repository_ids: Union[Unset, List[int]] = UNSET,
         permissions: Union[Unset, "AppPermissionsType"] = UNSET,
-    ) -> Generator[Self, None, None]:
+    ) -> AsyncGenerator[Self, None]:
         if self._ctx_github is not None:
             raise RuntimeError("Can not enter context twice.")
         self._ctx_github = self._github.with_auth(
             self._github.auth.as_installation(
                 installation_id, repositories, repository_ids, permissions
             )
         )
-        try:
-            yield self
-        finally:
-            self._ctx_github = None
-
-    @contextmanager
-    def as_web_user(
+        async with self._ctx_github:
+            try:
+                yield self
+            finally:
+                self._ctx_github = None
+
+    @asynccontextmanager
+    async def as_web_user(
         self, code: str, redirect_uri: Optional[str] = None
-    ) -> Generator[Self, None, None]:
+    ) -> AsyncGenerator[Self, None]:
         if self._ctx_github is not None:
             raise RuntimeError("Can not enter context twice.")
         self._ctx_github = self._github.with_auth(
             self._github.auth.as_oauth_app().as_web_user(code, redirect_uri)
         )
-        try:
-            yield self
-        finally:
-            self._ctx_github = None
-
-    @contextmanager
-    def as_user(self, token: str) -> Generator[Self, None, None]:
+        async with self._ctx_github:
+            try:
+                yield self
+            finally:
+                self._ctx_github = None
+
+    @asynccontextmanager
+    async def as_user(self, token: str) -> AsyncGenerator[Self, None]:
         if self._ctx_github is not None:
             raise RuntimeError("Can not enter context twice.")
         self._ctx_github = GitHub(TokenAuthStrategy(token))
-        try:
-            yield self
-        finally:
-            self._ctx_github = None
+        async with self._ctx_github:
+            try:
+                yield self
+            finally:
+                self._ctx_github = None
 
     @overrides(Bot)
     async def handle_event(self, event: Event) -> None: