ユーザーとコメントのdoc作成

Author: kakeruzoku

scapi/sites/comment.py

@@ -12,7 +12,24 @@
 )
 
 class Comment(base._BaseSiteAPI[int]):
+    """
+    コメントを表す。
 
+    .. note::
+        プロジェクト欄でコメントに関するAPIを使用する場合、プロジェクトの作者のユーザー名が必要です。データが取得されていない可能性がある場合、古いAPIを使用することを検討してください。
+
+    .. note::
+        プロフィール欄でコメントに関するAPIを使用する場合、必ず古いAPIが使用されます。新しいAPIでしか利用できない関数では TypeError が送出されることがあります。
+
+    Attributes:
+        id (int): コメントID
+        place (common.MAYBE_UNKNOWN[Project|Studio|User]): コメントの場所
+        parent_id (common.MAYBE_UNKNOWN[int|None]): 親コメントID
+        commentee_id (common.MAYBE_UNKNOWN[int|None]): メンションしたユーザーのID
+        content (common.MAYBE_UNKNOWN[str]): コメントの内容
+        author (common.MAYBE_UNKNOWN[User]): コメントしたユーザー
+        reply_count (common.MAYBE_UNKNOWN[int]): コメントにある返信の数
+    """
     def __repr__(self) -> str:
         return f"<Comment id:{self.id} content:{self.content} place:{self.place} user:{self.author} Session:{self.session}>"
 
@@ -108,14 +125,39 @@ def _update_from_html(self,data:bs4.element.Tag):
 
     @property
     def created_at(self) -> datetime.datetime|common.UNKNOWN_TYPE:
+        """
+        コメントが作成された時間を返す
+
+        Returns:
+            datetime.datetime|UNKNOWN_TYPE: データがある場合、その時間。
+        """
         return common.dt_from_isoformat(self._created_at)
 
     @property
     def modified_at(self) -> datetime.datetime|common.UNKNOWN_TYPE:
+        """
+        コメントが最後に編集された時間を返す
+        ユーザーがコメントを編集することはできないため、基本的に created_at と同じになります。
+
+        Returns:
+            datetime.datetime|UNKNOWN_TYPE: データがある場合、その時間。
+        """
         return common.dt_from_isoformat(self._modified_at)
 
 
     async def get_replies(self,limit:int|None=None,offset:int|None=None,*,use_cache:bool=True) -> AsyncGenerator["Comment", None]:
+        """
+        コメントの返信を取得する。
+        ユーザーページや、作者の不明なプロジェクト欄では取得できません。
+
+        Args:
+            limit (int|None, optional): 取得するコメントの数。初期値は40です。
+            offset (int|None, optional): 取得するコメントの開始位置。初期値は0です。
+            use_cache (bool, optional): 古いAPIから取得した時のキャッシュを使用するか。
+
+        Yields:
+            Comment: 取得したコメント
+        """
         if use_cache and self._cached_reply is not None:
             if limit is None:
                 limit = 40
@@ -129,6 +171,15 @@ async def get_replies(self,limit:int|None=None,offset:int|None=None,*,use_cache:
                 yield Comment._create_from_data(_c["id"],_c,place=self.place)
 
     async def get_parent(self,use_cache:bool=True) -> "Comment|None|common.UNKNOWN_TYPE":
+        """
+        親コメントを取得する。
+
+        Args:
+            use_cache (bool, optional): キャッシュを使用するか。デフォルトはTrueです。
+
+        Returns:
+            Comment|None|common.UNKNOWN_TYPE: 取得できる場合、取得されたコメント
+        """
         if not isinstance(self.parent_id,int):
             return self.parent_id
         if self._cached_parent is None or use_cache:
@@ -197,12 +248,29 @@ async def post_reply(
             content:str,
             commentee:"user.User|int|None|common.UNKNOWN_TYPE"=common.UNKNOWN,
             is_old:bool=False
-        ):
+        ) -> "Comment":
+        """
+        コメントを返信する。
+
+        Args:
+            content (str): コメントの内容
+            commentee (User|int|None, optional): メンションする場合、ユーザーかそのユーザーのID
+            is_old (bool, optional): 古いAPIを使用して送信するか
+
+        Returns:
+            comment.Comment: 投稿されたコメント
+        """
         if commentee is common.UNKNOWN:
             commentee = self.author and self.author.id or None
         return await Comment.post_comment(self.place,content,self.parent_id or self.id,commentee,is_old)
 
     async def delete(self,is_old:bool=False):
+        """
+        コメントを削除する。
+
+        Args:
+            is_old (bool, optional): 古いAPIを使用するか
+        """
         self.require_session()
         if isinstance(self.place,user.User):
             is_old = True
@@ -219,6 +287,12 @@ async def delete(self,is_old:bool=False):
             await self.client.delete(url,json={"reportId":None})
 
     async def report(self,is_old:bool=False):
+        """
+        コメントを報告する。
+
+        Args:
+            is_old (bool, optional): 古いAPIを使用するか
+        """
         self.require_session()
         if isinstance(self.place,user.User):
             is_old = True
@@ -227,9 +301,9 @@ async def report(self,is_old:bool=False):
             await self.client.post(url,json={"id":str(self.id)})
         else:
             if isinstance(self.place,project.Project):
-                url =  f"https://api.scratch.mit.edu/proxy/project/{self.place.id}/comment/{self.id}/report"
+                url = f"https://api.scratch.mit.edu/proxy/project/{self.place.id}/comment/{self.id}/report"
             elif isinstance(self.place,studio.Studio):
-                url =  f"https://api.scratch.mit.edu/proxy/studio/{self.place.id}/comment/{self.id}/report"
+                url = f"https://api.scratch.mit.edu/proxy/studio/{self.place.id}/comment/{self.id}/report"
             else:
                 raise TypeError("User comment updates are not supported.")
             await self.client.post(url,json={"reportId":None})

scapi/sites/user.py

@@ -59,49 +59,117 @@ def _update_from_old_data(self, data:OldUserPayload):
 
     @property
     def joined_at(self) -> datetime.datetime|common.UNKNOWN_TYPE:
+        """
+        ユーザーが参加した時間を返す。
+
+        Returns:
+            datetime.datetime|UNKNOWN_TYPE: データがある場合、その時間。
+        """
         return common.dt_from_isoformat(self._joined_at)
 
 
     async def get_featured(self) -> "project.ProjectFeatured|None":
+        """
+        ユーザーの注目のプロジェクト欄を取得する。
+
+        Returns:
+            project.ProjectFeatured|None: ユーザーが設定している場合、そのデータ。
+        """
         response = await self.client.get(f"https://scratch.mit.edu/site-api/users/all/{self.username}/")
         return project.ProjectFeatured(response.json(),self)
 
     async def get_followers(self,limit:int|None=None,offset:int|None=None) -> AsyncGenerator["User", None]:
+        """
+        ユーザーのフォロワーを取得する。
+
+        Args:
+            limit (int|None, optional): 取得するユーザーの数。初期値は40です。
+            offset (int|None, optional): 取得するユーザーの開始位置。初期値は0です。
+
+        Yields:
+            User: 取得したユーザー
+        """
         async for _u in common.api_iterative(
             self.client,f"https://api.scratch.mit.edu/users/{self.username}/followers/",
             limit=limit,offset=offset
         ):
             yield User._create_from_data(_u["username"],_u,self.client_or_session)
 
     async def get_followings(self,limit:int|None=None,offset:int|None=None) -> AsyncGenerator["User", None]:
+        """
+        ユーザーがフォローしているユーザーを取得する。
+
+        Args:
+            limit (int|None, optional): 取得するユーザーの数。初期値は40です。
+            offset (int|None, optional): 取得するユーザーの開始位置。初期値は0です。
+
+        Yields:
+            User: 取得したユーザー
+        """
         async for _u in common.api_iterative(
             self.client,f"https://api.scratch.mit.edu/users/{self.username}/following/",
             limit=limit,offset=offset
         ):
             yield User._create_from_data(_u["username"],_u,self.client_or_session)
 
     async def get_projects(self,limit:int|None=None,offset:int|None=None) -> AsyncGenerator["project.Project", None]:
+        """
+        ユーザーが共有しているプロジェクトを取得する。
+
+        Args:
+            limit (int|None, optional): 取得するプロジェクトの数。初期値は40です。
+            offset (int|None, optional): 取得するプロジェクトの開始位置。初期値は0です。
+
+        Yields:
+            Project: 取得したプロジェクト
+        """
         async for _p in common.api_iterative(
             self.client,f"https://api.scratch.mit.edu/users/{self.username}/projects/",
             limit=limit,offset=offset
         ):
             yield project.Project._create_from_data(_p["id"],_p,self.client_or_session)
 
     async def get_favorites(self,limit:int|None=None,offset:int|None=None) -> AsyncGenerator["project.Project", None]:
+        """
+        ユーザーのお気に入りのプロジェクトを取得する。
+
+        Args:
+            limit (int|None, optional): 取得するプロジェクトの数。初期値は40です。
+            offset (int|None, optional): 取得するプロジェクトの開始位置。初期値は0です。
+
+        Yields:
+            Project: 取得したプロジェクト
+        """
         async for _p in common.api_iterative(
             self.client,f"https://api.scratch.mit.edu/users/{self.username}/favorites/",
             limit=limit,offset=offset
         ):
             yield project.Project._create_from_data(_p["id"],_p,self.client_or_session)
 
     async def get_studios(self,limit:int|None=None,offset:int|None=None) -> AsyncGenerator["studio.Studio", None]:
+        """
+        ユーザーが参加しているスタジオを取得する。
+
+        Args:
+            limit (int|None, optional): 取得するスタジオの数。初期値は40です。
+            offset (int|None, optional): 取得するスタジオの開始位置。初期値は0です。
+
+        Yields:
+            Studio: 取得したスタジオ
+        """
         async for _s in common.api_iterative(
             self.client,f"https://api.scratch.mit.edu/users/{self.username}/studios/curate",
             limit=limit,offset=offset
         ):
             yield studio.Studio._create_from_data(_s["id"],_s,self.client_or_session)
 
     async def get_message_count(self) -> int:
+        """
+        ユーザーのメッセージの未読数を取得する。
+
+        Returns:
+            int: 未読のメッセージの数
+        """
         response = await self.client.get(
             f"https://api.scratch.mit.edu/users/{self.username}/messages/count/",
             params={"cachebust":str(random.randint(0,10000))}
@@ -110,6 +178,16 @@ async def get_message_count(self) -> int:
         return data.get("count")
 
     def get_comments(self,start_page:int|None=None,end_page:int|None=None) -> AsyncGenerator["comment.Comment", None]:
+        """
+        プロフィールに投稿されたコメントを取得する。
+
+        Args:
+            start_page (int|None, optional): 取得するコメントの開始ページ位置。初期値は1です。
+            end_page (int|None, optional): 取得するコメントの終了ページ位置。初期値はstart_pageの値です。
+
+        Returns:
+            Comment: 取得したコメント
+        """
         return comment.get_comment_from_old(self,start_page,end_page)
 
     get_comments_from_old = get_comments
@@ -120,15 +198,35 @@ async def post_comment(
         parent:"comment.Comment|int|None"=None,commentee:"User|int|None"=None,
         is_old:bool=True
     ) -> "comment.Comment":
+        """
+        コメントを投稿します。
+
+        Args:
+            content (str): コメントの内容
+            parent (Comment|int|None, optional): 返信する場合、返信元のコメントかID
+            commentee (User|int|None, optional): メンションする場合、ユーザーかそのユーザーのID
+            is_old (bool, optional): 古いAPIを使用して送信するか この値は使用されず、常に古いAPIが使用されます。
+
+        Returns:
+            comment.Comment: 投稿されたコメント
+        """
         return await comment.Comment.post_comment(self,content,parent,commentee,is_old)
 
     async def follow(self):
+        """
+        ユーザーをフォローする
+        """
+        self.require_session()
         await self.client.put(
             f"https://scratch.mit.edu/site-api/users/followers/{self.username}/add/",
             params={"usernames":self._session.username}
         )
 
     async def unfollow(self):
+        """
+        ユーザーのフォローを解除する
+        """
+        self.require_session()
         await self.client.put(
             f"https://scratch.mit.edu/site-api/users/followers/{self.username}/remove/",
             params={"usernames":self._session.username}
@@ -139,10 +237,25 @@ async def edit(
             self,*,
             bio:str|None=None,
             status:str|None=None,
-            featured_project_id:int|None=None,
+            featured_project_id:"int|project.Project|None"=None,
             featured_project_label:"ProjectFeaturedLabel|None"=None
         ) -> "None | project.ProjectFeatured":
+        """
+        プロフィール欄を編集する。
+
+        Args:
+            bio (str | None, optional): 私について欄の内容
+            status (str | None, optional): 私が取り組んでいることの内容
+            featured_project_id (int|project.Project|None, optional): 注目のプロジェクト欄に設定したいプロジェクトかそのID
+            featured_project_label (ProjectFeaturedLabel|None, optional): 注目のプロジェクト欄に使用したいラベル
+
+        Returns:
+            None | project.ProjectFeatured: 変更された注目のプロジェクト欄
+        """
+        self.require_session()
         _data = {}
+        if isinstance(featured_project_id,project.Project):
+            featured_project_id = featured_project_id.id
         if bio is not None: _data["bio"] = bio
         if status is not None: _data["status"] = status
         if featured_project_id is not None: _data["featured_project"] = featured_project_id
@@ -155,9 +268,20 @@ async def edit(
         return project.ProjectFeatured(data,self)
 
     async def toggle_comment(self):
+        """
+        プロフィールのコメント欄を開閉する。
+        """
+        self.require_session()
         await self.client.post(f"https://scratch.mit.edu/site-api/comments/user/{self.username}/toggle-comments/")
 
     async def set_icon(self,icon:file.File|bytes):
+        """
+        アイコンを変更する。
+
+        Args:
+            icon (file.File | bytes): アイコンのデータ
+        """
+        self.require_session()
         async with file._read_file(icon) as f:
             self.require_session()
             await self.client.post(
@@ -167,6 +291,9 @@ async def set_icon(self,icon:file.File|bytes):
 
 
 class ProjectFeaturedLabel(Enum):
+    """
+    注目のプロジェクト欄のラベルを表す。
+    """
     ProjectFeatured=""
     Tutorial="0"
     WorkInProgress="1"
@@ -185,4 +312,13 @@ async def get_from_id(cls,id:int|None) -> "ProjectFeaturedLabel":
         raise ValueError()
 
 def get_user(username:str,*,_client:client.HTTPClient|None=None) -> common._AwaitableContextManager[User]:
+    """
+    ユーザーを取得する。
+
+    Args:
+        username (str): 取得したいユーザーのユーザー名
+
+    Returns:
+        common._AwaitableContextManager[Studio]: await か async with で取得できるユーザー
+    """
     return common._AwaitableContextManager(User._create_from_api(username,_client))

scapi/utils/common.py

@@ -7,7 +7,7 @@
 
 from . import error,client,config
 
-__version__ = "3.0.0.dev1"
+__version__ = "3.0.0.dev2"
 
 _KT = TypeVar("_KT")
 _VT = TypeVar("_VT")
@@ -184,7 +184,7 @@ class _AwaitableContextManager(Generic[_AT]):
 
     obj = await coro または async with coro as obj: のようにして使用できます。
 
-    .. info::
+    .. note::
         特別な理由がない限りは async with で使用すべきです。
         awaitのみで使用する場合は、最後に実行すべき関数 (.client_close())などを確認してください。