refactor User

* sync some funcsig of async methods
* generate docs
* remove User.star, add param star_type in User.star_content

Author: Arendelle

docs/docsgen/user-method.md

@@ -33,7 +33,7 @@ def get_comments(self, target_id: str, target_type: str, take: int = 16, skip: i
 
 对应的协程风格的api:
 ```Python
-async def async_get_comments(self, target_id: str, target_type: str, take: int = 16, skip: int = 0)
+async def async_get_comments(self, target_id: str, target_type: str, take: int = 16, skip: int = 0, comment_id: Optional[str] = None)
 ```
 
 ## 获取作品的详细信息, 物实第一次读取作品会使用此接口
@@ -83,7 +83,7 @@ async def async_get_message(self, message_id: str)
 
 ## 获取用户收到的消息
 ```Python
-def get_messages(self, category_id: int = 0, skip: int = 0, take: int = 16, no_templates: bool = True) -> dict
+def get_messages(self, category_id: int, skip: int = 0, take: int = 16, no_templates: bool = True) -> dict
 ```
 @param category_id: 消息类型:  
 0: 全部, 1: 系统邮件, 2: 关注和粉丝, 3: 评论和回复, 4: 作品通知, 5: 管理记录  
@@ -93,7 +93,7 @@ def get_messages(self, category_id: int = 0, skip: int = 0, take: int = 16, no_t
 
 对应的协程风格的api:
 ```Python
-async def async_get_messages(self, category_id: int = 0, skip: int = 0, take: int = 16, no_templates: bool = True)
+async def async_get_messages(self, category_id: int, skip: int = 0, take: int = 16, no_templates: bool = True)
 ```
 
 ## 获取用户主页信息
@@ -159,13 +159,13 @@ async def async_get_user(self, user_id: Optional[str] = None, name: Optional[str
 
 ## 修改用户签名
 ```Python
-def modify_info(self, target: str) -> dict
+def modify_information(self, target: str) -> dict
 ```
 @param target: 新签名  
 
 对应的协程风格的api:
 ```Python
-async def async_modify_info(self, target: str)
+async def async_modify_information(self, target: str)
 ```
 
 ## 发表评论
@@ -184,19 +184,20 @@ async def async_post_comment(self, target_id: str, target_type: str, content: st
 
 ## 查询实验
 ```Python
-def query_experiments(self, category: physicsLab.enums.Category, tags: Optional[List[physicsLab.enums.Tag]] = None, exclude_tags: Optional[List[physicsLab.enums.Tag]] = None, languages: Optional[List[str]] = None, user_id: Optional[str] = None, take: int = 18, skip: int = 0) -> dict
+def query_experiments(self, category: physicsLab.enums.Category, tags: Optional[List[physicsLab.enums.Tag]] = None, exclude_tags: Optional[List[physicsLab.enums.Tag]] = None, languages: Optional[List[str]] = None, exclude_languages: Optional[List[str]] = None, user_id: Optional[str] = None, take: int = 18, skip: int = 0) -> dict
 ```
 @param category: 实验区还是黑洞区  
 @param tags: 根据列表内的物实实验的标签进行对应的搜索  
 @param exclude_tags: 除了列表内的标签的实验都会被搜索到  
 @param languages: 根据列表内的语言进行对应的搜索  
+@param exclude_languages: 除了列表内的语言的实验都会被搜索到  
 @param user_id: 指定搜索的作品的发布者  
 @param take: 搜索数量  
 @param skip: 跳过搜索数量  
 
 对应的协程风格的api:
 ```Python
-async def async_query_experiments(self, category: physicsLab.enums.Category, tags: Optional[List[physicsLab.enums.Tag]] = None, exclude_tags: Optional[List[physicsLab.enums.Tag]] = None, languages: Optional[List[str]] = None, user_id: Optional[str] = None, take: int = 18, skip: int = 0)
+async def async_query_experiments(self, category: physicsLab.enums.Category, tags: Optional[List[physicsLab.enums.Tag]] = None, exclude_tags: Optional[List[physicsLab.enums.Tag]] = None, languages: Optional[List[str]] = None, exclude_languages: Optional[List[str]] = None, user_id: Optional[str] = None, take: int = 18, skip: int = 0)
 ```
 
 ## 领取每日签到奖励
@@ -208,19 +209,19 @@ def receive_bonus(self, activity_id: str, index: int) -> dict
 
 对应的协程风格的api:
 ```Python
-async def async_receive_bonus(self)
+async def async_receive_bonus(self, activity_id: str, index: int)
 ```
 
 ## 删除评论
 ```Python
-def remove_comment(self, CommentID: str, target_type: str) -> dict
+def remove_comment(self, comment_id: str, target_type: str) -> dict
 ```
-@param CommentID: 评论ID, 可以通过`get_comments`获取  
+@param comment_id: 评论ID, 可以通过`get_comments`获取  
 @param target_type: User, Discussion, Experiment  
 
 对应的协程风格的api:
 ```Python
-async def async_remove_comment(self, CommentID: str, target_type: str)
+async def async_remove_comment(self, comment_id: str, target_type: str)
 ```
 
 ## 修改用户昵称
@@ -234,31 +235,18 @@ def rename(self, nickname: str) -> dict
 async def async_rename(self, nickname: str)
 ```
 
-## 收藏某个实验
+## 收藏/支持 某个实验
 ```Python
-def star(self, content_id: str, category: physicsLab.enums.Category, status: bool = True) -> dict
+def star_content(self, content_id: str, category: physicsLab.enums.Category, star_type: int, status: bool = True) -> dict
 ```
 @param content_id: 实验ID  
 @param category: 实验区, 黑洞区  
-@param status: True: 收藏, False: 取消收藏  
+@param star_type: 0: 收藏, 1: 使用金币支持实验  
+@param status: True: 收藏, False: 取消收藏 (对支持无作用)  
 
 对应的协程风格的api:
 ```Python
-async def async_star(self, content_id: str, category: physicsLab.enums.Category, status: bool = True)
-```
-
-## 使用金币支持某实验
-```Python
-def star_content(self, content_id: str, category: physicsLab.enums.Category, status: bool = True) -> dict
-```
-@content_id: 实验id  
-@category: 实验区还是黑洞区  
-@status: 是否支持  
-@return: 返回的json数据  
-
-对应的协程风格的api:
-```Python
-async def async_star_content(self, content_id: str, category: physicsLab.enums.Category, status: bool = True)
+async def async_star_content(self, content_id: str, category: physicsLab.enums.Category, star_type: int, status: bool = True)
 ```
 
 ## 上传实验图片

docsgen/webapi.py

@@ -27,15 +27,19 @@ def main():
                 and not obj.__name__.startswith('_') \
                 and not obj.__name__.startswith("async")
     ):
+        method_signature: inspect.Signature = inspect.signature(fn_obj)
+        async_method_signature: inspect.Signature = inspect.signature(async_methods['async_' + fn_name])
+        assert method_signature.parameters == async_method_signature.parameters, fn_name
+
         doc: str = fn_obj.__doc__
         context += f"\n## {doc.splitlines()[0]}\n"
-        context += f"```Python\ndef {fn_name}{inspect.signature(fn_obj)}\n```\n"
+        context += f"```Python\ndef {fn_name}{method_signature}\n```\n"
         for line in doc.split('\n')[1:]:
             context += f"{(line + '  ').lstrip()}\n"
 
         context += f"对应的协程风格的api:\n" \
             f"```Python\n" \
-            f"async def {'async_' + fn_name}{inspect.signature(async_methods['async_' + fn_name])}\n" \
+            f"async def {'async_' + fn_name}{async_method_signature}\n" \
             f"```\n"
 
     with open(OUTPUT_FILE, 'w', encoding='utf-8') as f:

physicsLab/web/_api.py

@@ -12,9 +12,6 @@
 from physicsLab.enums import Tag, Category
 from physicsLab._typing import Optional, List, TypedDict, Callable
 
-def _take_warning() -> None:
-    errors.warning("take is less than 1")
-
 def _check_response(response: requests.Response, err_callback: Optional[Callable] = None) -> dict:
     ''' 检查返回的response
         @callback: 自定义物实返回的status对应的报错信息,
@@ -211,6 +208,7 @@ def query_experiments(
             @param tags: 根据列表内的物实实验的标签进行对应的搜索
             @param exclude_tags: 除了列表内的标签的实验都会被搜索到
             @param languages: 根据列表内的语言进行对应的搜索
+            @param exclude_languages: 除了列表内的语言的实验都会被搜索到
             @param user_id: 指定搜索的作品的发布者
             @param take: 搜索数量
             @param skip: 跳过搜索数量
@@ -292,8 +290,7 @@ def get_experiment(
 
         if category is not None:
             # 如果传入的是实验ID, 先获取summary来得到ContentID
-            summary = self.get_summary(content_id, category)
-            content_id = summary["Data"]["ContentID"]
+            content_id = self.get_summary(content_id, category)["Data"]["ContentID"]
 
         response = requests.post(
             "https://physics-api-cn.turtlesim.com:443/Contents/GetExperiment",
@@ -405,12 +402,12 @@ def post_comment(
 
         return _check_response(response)
 
-    def remove_comment(self, CommentID: str, target_type: str) -> dict:
+    def remove_comment(self, comment_id: str, target_type: str) -> dict:
         ''' 删除评论
-            @param CommentID: 评论ID, 可以通过`get_comments`获取
+            @param comment_id: 评论ID, 可以通过`get_comments`获取
             @param target_type: User, Discussion, Experiment
         '''
-        if not isinstance(CommentID, str) \
+        if not isinstance(comment_id, str) \
                 or not isinstance(target_type, str):
             raise TypeError
         if target_type not in ("User", "Discussion", "Experiment"):
@@ -420,7 +417,7 @@ def remove_comment(self, CommentID: str, target_type: str) -> dict:
             "https://physics-api-cn.turtlesim.com:443/Messages/RemoveComment",
             json={
                 "TargetType": target_type,
-                "CommentID": CommentID,
+                "CommentID": comment_id,
             },
             headers={
                 "Content-Type": "application/json",
@@ -573,53 +570,28 @@ def get_profile(self) -> dict:
 
         return _check_response(response)
 
-    def star(self, content_id: str, category: Category, status: bool = True) -> dict:
-        ''' 收藏某个实验
+    def star_content(self, content_id: str, category: Category, star_type: int, status: bool = True) -> dict:
+        ''' 收藏/支持 某个实验
             @param content_id: 实验ID
             @param category: 实验区, 黑洞区
-            @param status: True: 收藏, False: 取消收藏
+            @param star_type: 0: 收藏, 1: 使用金币支持实验
+            @param status: True: 收藏, False: 取消收藏 (对支持无作用)
         '''
         if not isinstance(content_id, str) \
                 or not isinstance(category, Category) \
-                or not isinstance(status, bool):
+                or not isinstance(status, bool) \
+                or not isinstance(star_type, int):
             raise TypeError
+        if star_type not in (0, 1):
+            raise ValueError
 
         response = requests.post(
             "https://physics-api-cn.turtlesim.com/Contents/StarContent",
             json={
                 "ContentID": content_id,
                 "Status": status,
                 "Category": category.value,
-            },
-            headers={
-                "Content-Type": "application/json",
-                "x-API-Token": self.token,
-                "x-API-AuthCode": self.auth_code,
-            }
-        )
-
-        return _check_response(response)
-
-    def star_content(self, content_id: str, category: Category, status: bool = True) -> dict:
-        ''' 使用金币支持某实验
-            @content_id: 实验id
-            @category: 实验区还是黑洞区
-            @status: 是否支持
-            @return: 返回的json数据
-        '''
-        if not isinstance(content_id, str) \
-                or not isinstance(category, Category) \
-                or not isinstance(status, bool):
-            raise TypeError
-
-        response = requests.post(
-            "https://physics-api-cn.turtlesim.com:443/Contents/StarContent",
-            json={
-                "ContentID": content_id,
-                "Status": status,
-                "Category": category.value,
-                "Status": status,
-                "Type": 1,
+                "Type": star_type,
             },
             headers={
                 "Content-Type": "application/json",
@@ -846,7 +818,7 @@ def rename(self, nickname: str) -> dict:
 
         return _check_response(response)
 
-    def modify_info(self, target: str) -> dict:
+    def modify_information(self, target: str) -> dict:
         ''' 修改用户签名
             @param target: 新签名
         '''

physicsLab/web/api.py

@@ -91,17 +91,18 @@ async def async_post_comment(
     ) -> dict:
         return await _async_wrapper(self.post_comment, target_id, target_type, content, reply_id)
 
-    async def async_remove_comment(self, CommentID: str, target_type:str):
-        return await _async_wrapper(self.remove_comment, CommentID, target_type)
+    async def async_remove_comment(self, comment_id: str, target_type:str):
+        return await _async_wrapper(self.remove_comment, comment_id, target_type)
 
     async def async_get_comments(
             self,
             target_id: str,
             target_type: str,
             take: int = 16,
             skip: int = 0,
+            comment_id: Optional[str] = None,
     ):
-        return await _async_wrapper(self.get_comments, target_id, target_type, take, skip)
+        return await _async_wrapper(self.get_comments, target_id, target_type, take, skip, comment_id)
 
     async def async_get_summary(self, content_id: str, category: Category):
         return await _async_wrapper(self.get_summary, content_id, category)
@@ -119,11 +120,8 @@ async def async_get_user(
     async def async_get_profile(self):
         return await _async_wrapper(self.get_profile)
 
-    async def async_star(self, content_id: str, category: Category, status: bool = True):
-        return await _async_wrapper(self.star, content_id, category, status)
-
-    async def async_star_content(self, content_id: str, category: Category, status: bool = True):
-        return await _async_wrapper(self.star_content, content_id, category, status)
+    async def async_star_content(self, content_id: str, category: Category, star_type: int, status: bool = True):
+        return await _async_wrapper(self.star_content, content_id, category, star_type, status)
 
     async def async_upload_image(self, policy: str, authorization: str, image_path: str):
         return await _async_wrapper(self.upload_image, policy, authorization, image_path)
@@ -133,7 +131,7 @@ async def async_get_message(self, message_id: str):
 
     async def async_get_messages(
             self,
-            category_id: int = 0,
+            category_id: int,
             skip: int = 0,
             take: int = 16,
             no_templates: bool = True,
@@ -165,8 +163,8 @@ async def async_follow(self, target_id: str, action: bool = True):
     async def async_rename(self, nickname: str):
         return await _async_wrapper(self.rename, nickname)
 
-    async def async_modify_info(self, target: str):
-        return await _async_wrapper(self.modify_info, target)
+    async def async_modify_information(self, target: str):
+        return await _async_wrapper(self.modify_information, target)
 
-    async def async_receive_bonus(self):
-        return await _async_wrapper(self.receive_bonus)
+    async def async_receive_bonus(self, activity_id: str, index: int):
+        return await _async_wrapper(self.receive_bonus, activity_id, index)