[Docs]Add docstring for file #202
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Southpika
changed the title
sijunhe
reviewed
Dec 25, 2023
| @@ -0,0 +1,95 @@ | |||
| # File 模块介绍 | |||
There was a problem hiding this comment.
加了之后file文件夹的落地页会有展示～也可以去掉~
|
已加入mkdocs的截断以及函数签名 |
juncaipeng
reviewed
Dec 26, 2023
| Examples: | ||
| >>> from erniebot_agent.file import GlobalFileManagerHandler | ||
| >>> async def demo_function(): | ||
| >>> file_manager = await GlobalFileManagerHandler().get() |
docs/modules/file.md
Outdated
|
|
||
| ## 1. File 简介 | ||
|
|
||
| 文件管理模块提供了用于管理文件的一系列类方便用户与Agent进行交互，其中包括 `File` 及其子类、`FileManager` 、`GlobalFileManagerHandler`以及与远程文件服务器交互的 `RemoteFileClient`。推荐使用 `GlobalFileManagerHandler`在事件循环开始时初始化 `FileManager`以及获取全局的 `FileManager`，之后只需通过这个全局的 `FileManager`对文件进行增、删、查等操作，**不推荐**用户自行操作 `File`类以免造成资源泄露。同时从效率方面考虑，`FileManager`将作为此模块中生命周期最长的对象，它会在关闭时回收所有的持有对象（RemoteClient/temp local file），请不要随意关闭它。 |
There was a problem hiding this comment.
中文整体需要润色一下，每段介绍需要注意逻辑由浅到深，多断句和换行。
docs/modules/file.md
Outdated
| @@ -0,0 +1,97 @@ | |||
| # File 模块介绍 | |||
|
|
|||
| ## 1. File 简介 | |||
docs/modules/file.md
Outdated
|
|
||
| 文件管理模块提供了用于管理文件的一系列类方便用户与Agent进行交互，其中包括 `File` 及其子类、`FileManager` 、`GlobalFileManagerHandler`以及与远程文件服务器交互的 `RemoteFileClient`。推荐使用 `GlobalFileManagerHandler`在事件循环开始时初始化 `FileManager`以及获取全局的 `FileManager`，之后只需通过这个全局的 `FileManager`对文件进行增、删、查等操作，**不推荐**用户自行操作 `File`类以免造成资源泄露。同时从效率方面考虑，`FileManager`将作为此模块中生命周期最长的对象，它会在关闭时回收所有的持有对象（RemoteClient/temp local file），请不要随意关闭它。 | ||
|
|
||
| ## 2. File 基类介绍 |
|
|
||
| `RemoteFileClient` 是用于与远程文件服务器交互的类。它定义了文件上传、文件下载、文件删除等操作的方法。`AIStudioFileClient` 是 `RemoteFileClient` 的一个具体推荐实现，用于与文件服务交互，用户使用 `access token`作为参数用于身份验证，之后能够在AIStudio文件服务中上传、检索、列出文件，以及创建临时URL以访问文件。`RemoteFileClient`使用时被 `FileManager`持有，一旦 `FileManager`关闭，`RemoteFileClient`也会相应被关闭，其中的资源也会被相应释放。 | ||
|
|
||
| ## 5. 使用方法 |
There was a problem hiding this comment.
## 5. 使用示例
建议示例包括GlobalFileManagerHandler的获取、配置，File的创建、保存、搜索，Agent中获取输出File
| @@ -12,4 +12,37 @@ | |||
| # See the License for the specific language governing permissions and | |||
| # limitations under the License. | |||
|
|
|||
| from erniebot_agent.file.global_file_manager_handler import GlobalFileManagerHandler | |||
| """ | |||
| File module is used to manage the file system by a global file manager: `GlobalFileManagerHandler`. | |||
There was a problem hiding this comment.
这部分会显示在文档的api中？ 建议配合中文文档写清楚些
There was a problem hiding this comment.
主要为显示在api中，为一个简单介绍以及一些notes，一些具体的内容会在详细的api中提到，考虑到如果复刻中文文档内容就太长了
| filename (str): File name. | ||
| byte_size (int): Size of the file in bytes. | ||
| created_at (str): Timestamp indicating the file creation time. | ||
| purpose (str): Purpose or use case of the file. [] |
There was a problem hiding this comment.
具体的参数在LocalFile以及RemoteFile中标注，基类中仅做用途介绍
|
|
||
| Args: | ||
| remote_file_client (Optional[RemoteFileClient]): The remote file client. | ||
| auto_register (bool): Automatically register files in the file registry. |
There was a problem hiding this comment.
auto_register删掉了，新增了prune_on_close
|
|
||
| ## 4. RemoteFileClient 类介绍 | ||
|
|
||
| `RemoteFileClient` 是用于与远程文件服务器交互的类。它定义了文件上传、文件下载、文件删除等操作的方法。`AIStudioFileClient` 是 `RemoteFileClient` 的一个具体推荐实现，用于与文件服务交互，用户使用 `access token`作为参数用于身份验证，之后能够在AIStudio文件服务中上传、检索、列出文件，以及创建临时URL以访问文件。`RemoteFileClient`使用时被 `FileManager`持有，一旦 `FileManager`关闭，`RemoteFileClient`也会相应被关闭，其中的资源也会被相应释放。 |
There was a problem hiding this comment.
说明大家一般不需要使用remotefile，默认情况下remotefile是关闭的。 （是否有必须使用remotefile的场景？）
juncaipeng
approved these changes
Dec 26, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
待漫晖的PR合入