update env doc

docs/wiki/Home.md

@@ -4,8 +4,8 @@
 在本wiki，你可以查阅到当前本仓库提供的一些API功能，帮助开发和维护SwanLab。
 如果你希望更好的了解本仓库，可以查看swankit的[源码](https://github.com/SwanHubX/SwanLab-Toolkit)
 
->
-出于一些考虑，本wiki只收录API的使用方法，如果需要查看更详细的文档，建议移步[docs](https://github.com/SwanHubX/SwanLab-Toolkit/tree/main/docs)
+> 出于一些考虑，本wiki只收录API的使用方法，如果需要查看更详细的文档，
+> 建议移步[docs](https://github.com/SwanHubX/SwanLab-Toolkit/tree/main/docs)
 
 
 

docs/wiki/第1部分：环境变量.md

@@ -0,0 +1,203 @@
+SwanLab将会有一些共享环境变量，这都将在SwanLab-Toolkit定义，这意味着引入swankit包时，就可以选择使用这些环境变量。
+
+这些环境变量被存储于[swankit/env.py](https://github.com/SwanHubX/SwanLab-Toolkit/blob/main/swankit/env.py)中，
+使用枚举类型收集和定义。
+
+## 访问和使用
+
+### 变量列表
+
+| 变量               | 名称                 | 描述                                      |
+|------------------|--------------------|-----------------------------------------|
+| SWANLAB_SAVE_DIR | swanlab全局文件夹保存的路径  | 默认为用户主目录下的.swanlab文件夹，支持相对路径，但推荐使用绝对路径  |
+| SWANLAB_LOG_DIR  | swanlab解析日志文件保存的路径 | 默认为当前运行目录的swanlog文件夹，支持相对路径，但推荐使用绝对路径   |
+| SWANLAB_MODE     | swanlab的解析模式       | 这将涉及操作员注册的[回调](/docs/wiki/第3部分：回调函数.md) |
+
+### 代码内访问
+
+为了方便维护，并且保证环境变量的不可改的特性，所以swankit使用枚举类型定义所有的环境变量，部分代码如下：
+
+```python
+from enum import Enum
+from typing import List
+
+
+class SwanLabSharedEnv(Enum):
+    SWANLAB_FOLDER = "SWANLAB_SAVE_DIR"
+    ...
+
+    @classmethod
+    def list(cls) -> List[str]:
+        ...
+```
+
+并且，可以通过如下方式访问这些共享的环境变量：
+
+```python
+from swankit.env import SwanLabSharedEnv
+
+# 拿到 `SWANLAB_SAVE_DIR` 这个环境变量Key
+save_dir = SwanLabSharedEnv.SWANLAB_FOLDER.value
+
+assert save_dir == "SWANLAB_SAVE_DIR"
+
+# 存在一个方法可以列出所有的环境变量
+envs = SwanLabSharedEnv.list()
+```
+
+不过需要注意的是，上述操作只能拿到环境变量的Key，而不能拿到环境变量的值。如果需要拿到值，则需要使用[API](#API)。
+
+### 模式
+
+此处对应的是`swanlab.init`的`mode`参数，在此处作出规定：
+
+```python
+from enum import Enum
+from typing import List
+
+
+class SwanLabMode(Enum):
+    """
+    swanlab的解析模式，枚举类
+    """
+    DISABLED = "disabled"
+    ...
+
+    @classmethod
+    def list(cls) -> List[str]:
+        ...
+```
+
+同样需要使用`.value`来获取对应的值：
+
+```python
+from swankit.env import SwanLabMode
+
+# 拿到 `disabled` 这个模式
+mode = SwanLabMode.DISABLED.value
+
+assert mode == "disabled"
+
+# 存在一个方法可以列出所有的模式
+modes = SwanLabMode.list()
+```
+
+> 使用枚举类型的好处是，可以避免在代码中硬编码，提高代码的可读性和可维护性，
+> 并且如果未来要为每个环境变量增加一些方法、属性等，可以很方便的在枚举类中添加。
+
+## API
+
+本部分列出环境的所有api，方便查阅和使用：
+
+| API                                 | 名称                    | 描述                |
+|-------------------------------------|-----------------------|-------------------|
+| [is_windows](#is_windows)           | 是否为windows系统          | 分为windows和类unix系统 |
+| [get_save_dir](#get_save_dir)       | 获取存放swanlab全局文件的文件夹路径 | 确保路径存在            |
+| [get_swanlog_dir](#get_swanlog_dir) | 获取存放swanlog日志文件的文件夹路径 | 不保证文件夹是否存在        | 
+| [get_mode](#get_mode)               | 获取当前的swanlab解析模式      | 如果没有设置，默认为cloud   |
+
+### is_windows
+
+本函数用于判断当前系统是否为windows系统，分为windows和类unix系统——主要是为了区分路径上的差别。
+
+#### 异常
+
+- [OSError](https://docs.python.org/3.12/library/exceptions.html#OSError):
+  未知系统错误，此时swanlab运行在未知系统上，这个系统不是windows或者类unix系统。
+
+#### 返回值
+
+- `bool`: 返回True表示当前系统为windows系统，返回False表示当前系统为类unix系统。
+
+#### 示例
+
+```python
+from swankit.env import is_windows
+
+if is_windows():
+    print("当前系统为windows系统")
+else:
+    print("当前系统为类unix系统")
+```
+
+### get_save_dir
+
+**此函数对应环境变量`SWANLAB_SAVE_DIR`**，用于获取存放swanlab全局文件的文件夹路径，执行此函数将自动创建相关文件夹。
+
+出于安全考虑，并不会递归创建文件夹，如果父目录不存在，将会抛出异常`FileNotFoundError`。
+
+#### 异常
+
+* [FileNotFoundError](https://docs.python.org/3.12/library/exceptions.html#FileNotFoundError): 目录的父目录不存在。
+* [NotADirectoryError](https://docs.python.org/3.12/library/exceptions.html#NotADirectoryError): 指定的路径不是一个目录。
+
+#### 返回值
+
+- `str`: 返回存放swanlab全局文件的文件夹路径，如果没有设置环境变量，默认为用户主目录下的`.swanlab`
+  文件夹，例如`/home/user/.swanlab`。
+
+#### 示例
+
+```python
+from swankit.env import get_save_dir
+
+save_dir = get_save_dir()
+
+print(f"存放swanlab全局文件的文件夹路径为：{save_dir}")  # 此时会自动创建文件夹
+```
+
+### get_swanlog_dir
+
+**此函数对应环境变量`SWANLAB_LOG_DIR`**，用于获取存放swanlog日志文件的文件夹路径，执行此函数将不会自动创建相关文件夹，只是返回路径。
+
+> 因为`disabled`模式的存在，所以不会自动创建文件夹，交由上层代码自行处理。
+
+#### 异常
+
+* [FileNotFoundError](https://docs.python.org/3.12/library/exceptions.html#FileNotFoundError): 目录的父目录不存在。
+* [NotADirectoryError](https://docs.python.org/3.12/library/exceptions.html#NotADirectoryError): 指定的路径不是一个目录。
+
+#### 返回值
+
+- `str`: 返回存放swanlog日志文件的文件夹路径，如果没有设置环境变量，默认为当前运行目录的`swanlog`
+  文件夹，例如`/home/user/xxx/swanlog`，执行此函数不会自动创建文件夹。
+
+#### 示例
+
+```python
+from swankit.env import get_swanlog_dir
+
+swanlog_dir = get_swanlog_dir()
+
+print(f"存放swanlog日志文件的文件夹路径为：{swanlog_dir}")  # 此时不会自动创建文件夹
+```
+
+### get_mode
+
+**此函数对应环境变量`SWANLAB_MODE`**，用于获取当前的swanlab解析模式，如果没有设置，默认为`cloud`模式。
+
+#### 异常
+
+- [ValueError](https://docs.python.org/3.12/library/exceptions.html#ValueError): 未知的解析模式。
+
+#### 返回值
+
+- `str`: 返回当前的swanlab解析模式，如果没有设置，默认为`cloud`模式，为枚举类型[模式](#模式)中的一种。
+
+#### 示例
+
+```python
+
+from swankit.env import get_mode, SwanLabMode
+
+mode = get_mode()
+
+print(f"当前的swanlab解析模式为：{mode}")
+
+assert mode in SwanLabMode.list()
+
+assert mode == SwanLabMode.CLOUD.value
+```
+
+
+

swankit/env.py

@@ -101,7 +101,7 @@ def get_save_dir() -> str:
 
 def get_swanlog_dir() -> str:
     """
-    获取存放swanlog日志文件的文件夹路径，如果不存在就创建
+    获取存放swanlog日志文件的文件夹路径
     此函数对应为SWANLAB_LOG_FOLDER全局变量，如果没有设置，默认为当前运行目录下的swanlog文件夹
     需要注意，此函数并不会保证文件夹的存在，但是会检查父文件夹是否存在以及folder是否是一个文件夹
     :raises