完善文档

alist/error.py

@@ -1,12 +1,21 @@
 class AListError(Exception):
+    '''
+    基础错误类
+    '''
     pass
 
 
 class AuthenticationError(AListError):
+    '''
+    验证错误
+    '''
     pass
 
 
 class ServerError(AListError):
+    '''
+    服务器错误
+    '''
     pass
 
 

alist/main.py

@@ -3,7 +3,6 @@
 import json
 import os.path
 import sys
-import asyncio
 
 from platform import platform
 from urllib.parse import quote
@@ -16,6 +15,11 @@
 class AList:
     """
     AList的SDK，此为主类。
+    
+    Attributes:
+        endpoint (str):AList地址
+        headers (dict):全局请求头
+        token (str):JWT Token
     """
 
     def __init__(self, endpoint: str):
@@ -24,7 +28,6 @@ def __init__(self, endpoint: str):
 
         Args:
             endpoint (str):AList地址
-            test (bool):是否测试服务器可用性
         """
         if "http" not in endpoint:
             raise ValueError(endpoint + "不是有效的uri")
@@ -110,16 +113,6 @@ async def login(self, user: utils.AListUser, otp_code: str = ""):
         return True
 
     def Login(self, *args, **kwargs):
-        """
-        登录
-
-        Args:
-            user (AListUser): AList用户
-
-        Returns:
-            (bool): 是否成功
-
-        """
         raise error.DeprecationError("请使用login函数")
 
     async def user_info(self):
@@ -328,7 +321,6 @@ async def RemoveFolder(self, path: Union[str, model.AListFolder]):
         Returns:
             (bool): 是否成功
 
-
         """
 
         data = json.dumps({"src_dir": str(path)})
@@ -422,8 +414,11 @@ def SiteConfig(self, *args, **kwargs):
 class AListAdmin(AList):
     """
     管理员操作
-    (继承于AList类)
-
+    
+    Attributes:
+        endpoint (str):AList地址
+        headers (dict):全局请求头
+        token (string):JWT Token
     """
 
     def __init__(self, user: utils.AListUser, endpoint: str):

alist/model.py

@@ -2,7 +2,33 @@
 
 
 class AListFile:
+    """
+    AList文件
+    
+    兼容文件对象
+    
+    Attributes:
+        path (str):文件路径
+        name (str):文件名
+        size (int):文件大小
+        provider (int):存储类型
+        modified (str):修改时间
+        created (str):创建时间
+        url (str):文件下载URL
+        sign (str):签名
+        content (bytes):文件内容
+        position (int):文件读取位置
+        raw (dict):原始返回信息
+    """
     def __init__(self, path, init):
+        """
+        初始化
+
+        Args:
+            path (str):文件路径
+            init (dict):初始化字典
+            
+        """
         self.path = path
         self.name = init["name"]
         self.provider = init["provider"]
@@ -13,6 +39,7 @@ def __init__(self, path, init):
         self.sign = init["sign"]
         self.content = None
         self.position = 0  # 文件读取位置
+        self.raw = init
 
     def __len__(self):
         return self.size
@@ -27,11 +54,20 @@ def __exit__(self, exc_type, exc_value, exc_tb):
         pass
 
     async def download(self):
+        """
+        下载文件至内存
+        """
         async with aiohttp.ClientSession() as session:
             async with session.get(self.url) as res:
                 self.content = res.content
 
     async def read(self, n=-1):
+        """
+        读文件
+
+        Args:
+            n (int):读取的字节大小
+        """
         if self.content is None:
             await self.download()
 
@@ -46,6 +82,13 @@ async def read(self, n=-1):
             return data
 
     def seek(self, offset, whence=0):
+        """
+        设置文件指针位置
+
+        Args:
+            offset (int):偏移量
+            whence (int):基准
+        """
         if whence == 0:
             self.position = offset
         elif whence == 1:
@@ -57,6 +100,12 @@ def seek(self, offset, whence=0):
         self.position = min(self.position, self.size)
 
     async def save(self, path):
+        """
+        保存文件至本地
+
+        Args:
+            path (str):路径
+        """
         if self.content is None:
             await self.download()
 
@@ -70,6 +119,14 @@ def close(self):
 class AListFolder:
     """
     AList文件夹
+    
+    Attributes:
+        path (str):文件路径
+        size (int):文件大小
+        provider (int):存储类型
+        modified (str):修改时间
+        created (str):创建时间
+        raw (dict):原始返回信息
     """
 
     def __init__(self, path: str, init: dict):
@@ -79,14 +136,13 @@ def __init__(self, path: str, init: dict):
         Args:
             path (str):文件夹路径
             init (dict):初始化字典
-
-
         """
         self.path = path
         self.provider = init["provider"]
         self.size = init["size"]
         self.modified = init["modified"]
         self.created = init["created"]
+        self.raw = init
 
     def __str__(self):
         return self.path

alist/sync.py

@@ -3,6 +3,9 @@
 from .model import AListFile
 
 class AListSync:
+    '''
+    AList的同步代理类
+    '''
     def __init__(self, *args, **kwargs):
         self._async_obj = AList(*args, **kwargs)
 
@@ -32,9 +35,15 @@ def sync_func(*args, **kwargs):
 
 
 class AListAdminSync(AListSync):
+    '''
+    AListAdmin的同步代理类
+    '''
     def __init__(self, *args, **kwargs):
         self._async_obj = AListAdmin(*args, **kwargs)
 
 class AListFileSync(AListSync):
+    '''
+    AListFile的同步代理类
+    '''
     def __init__(self, *args, **kwargs):
         self._async_obj = AListFile(*args, **kwargs)

alist/utils.py

@@ -8,10 +8,16 @@
 
 
 class ToClass:
+    '''
+    字典转class
+    
+    Attributes:
+        _conf_Dict (dict):原始字典
+    '''
     def __init__(self, conf: dict):
         self._conf_Dict = conf
         self.__name__ = "<Standard Dictionary>"
-        self.update()
+        self._update()
 
     def __getattr__(self, name):
         if name in self._conf_Dict:
@@ -21,7 +27,13 @@ def __getattr__(self, name):
                 f"'{self.__class__.__name__}' object has no attribute '{name}'"
             )
 
-    def update(self, conf: Union[dict, None] = None):
+    def _update(self, conf: Union[dict, None] = None):
+        '''
+        更新字典内容
+        
+        Args:
+            conf (dict):要更新的字典
+        '''
         if conf:
             self._conf_Dict = conf
         # 更新字典

docs/apis/error.md

@@ -0,0 +1,3 @@
+# 错误类
+
+::: alist.error

docs/apis/model.md

@@ -0,0 +1,3 @@
+# 数据模型类
+
+::: alist.model

docs/apis/sync.md

@@ -0,0 +1,3 @@
+# 同步代理
+
+::: alist.sync

docs/readme.md → docs/index.md

@@ -1,4 +1,5 @@
 # AList3SDK
+
 [!WARNING]
 本SDK已发生重大更新，完全不兼容上一个版本(v1.1.4)
 
@@ -21,7 +22,7 @@ from alist import AList, AListUser
 
 # 初始化 AList3SDK 客户端
 user = AListUser("<your-user-name>","<your-password>")
-alist = AList("<your-server-url>")
+client = AList("<your-server-url>")
 
 # 登录 AList 服务
 client.login(user)
@@ -57,3 +58,4 @@ A: 请确保您的 AList地址和账号密码正确，并具有足够的权限
 - 1.1.3 (2024-07-05): 更新文档，增加用户类加载
 - 1.1.4 (2024-08-11): 修复已知问题，优化用户体验
 - 1.2.0 (2024-11-04): 修改大量命名风格
+- 1.3.0 (2024-11-09): 增加异步支持

mkdocs.yml

@@ -11,7 +11,17 @@ plugins:
             - import sys
             - sys.path.insert(0, "..")
 
-
+nav:
+  - 主页: "index.md"
+  - API参考: 
+    - "apis/main.md"
+    - "apis/model.md"
+    - "apis/sync.md"
+    - "apis/utils.md"
+    - "apis/error.md"
+  - 示例:
+    - "examples/first.md"
+
 theme:
   name: material
   language: 'zh'  # 配置语言