modify: READNE.md

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chakcy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,173 @@
+# SQLite Virtual File System (SVFS)
+
+一个基于 SQLite 的虚拟文件系统实现，可以将本地文件夹打包成单个 SQLite 数据库文件，并支持从数据库中解包还原文件。
+
+## 特性
+- 高效存储: 使用 SQLite 数据库存储文件和目录结构
+- 压缩支持: 可选的文件压缩功能，节省存储空间
+- 完整元数据: 保留文件权限、创建时间、修改时间等元数据
+- 目录结构保持: 完整的目录层级结构保持
+- 简单易用: 提供命令行工具，支持打包和解包操作
+- 跨平台: 支持 Windows、Linux、macOS
+
+## 安装
+### 从源码安装
+```bash
+# 克隆仓库
+git clone <repository-url>
+cd svfs
+
+# 使用 uv 安装（推荐）
+uv sync
+
+# 或者使用 pip
+pip install -e .
+```
+### 使用 uv
+项目使用 uv 作为包管理器和构建工具，确保已安装 uv：
+
+```bash
+# 安装 uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 在项目目录中安装依赖
+uv sync
+```
+
+## 使用方法
+### 打包文件夹
+```bash
+# 基本用法
+vfspack <源文件夹路径> <输出数据库路径>
+
+# 启用压缩
+vfspack ./my_folder ./output.db --compress
+
+# 指定文件系统名称
+vfspack ./my_folder ./output.db --name "MyFileSystem"
+
+# 排除特定文件模式
+vfspack ./my_folder ./output.db --exclude "*.tmp" "*.log"
+```
+### 解包文件系统
+```bash
+# 解包整个文件系统
+vfsunpack <数据库路径> <目标文件夹路径>
+
+# 仅列出根目录内容
+vfsunpack ./output.db ./output --list-root
+
+# 解包特定文件或目录
+vfsunpack ./output.db ./output --path "docs/readme.txt"
+vfsunpack ./output.db ./output --path "images/"
+
+# 忽略时间戳错误（仅导出文件内容）
+vfsunpack ./output.db ./output --ignore-timestamps
+```
+## 项目结构
+```text
+svfs/
+├── pyproject.toml          # 项目配置和依赖
+├── src/svfs/
+│   ├── __init__.py
+│   ├── core.py             # 核心 SQLiteVFS 类
+│   ├── folder_packer.py    # 文件夹打包逻辑
+│   ├── folder_unpacker.py  # 文件夹解包逻辑
+│   └── cli/
+│       ├── __init__.py
+│       ├── packer.py       # 打包命令行工具
+│       └── unpacker.py     # 解包命令行工具
+└── README.md
+```
+## 核心组件
+### SQLiteVFS 类
+主要功能类，提供以下功能：
+
+- 创建和管理 SQLite 虚拟文件系统数据库
+- 添加/删除文件和目录
+- 读取文件内容
+- 导出文件到本地文件系统
+- 压缩和解压缩文件内容
+
+### FolderPacker 类
+文件夹打包工具：
+
+- 遍历本地文件夹结构
+- 将文件和目录信息存储到 SQLite 数据库
+- 支持文件排除模式
+
+### FolderUnpacker 类
+文件夹解包工具：
+
+- 从 SQLite 数据库恢复文件系统
+- 验证数据库完整性
+- 支持部分导出和完整导出
+
+## 数据库结构
+### filesystem_metadata 表
+存储文件系统元数据，包括名称、创建时间、文件总数和总大小。
+
+### files 表
+存储所有文件和目录信息：
+
+- path: 文件/目录路径（唯一）
+- name: 文件名
+- parent_path: 父目录路径
+- is_directory: 是否为目录
+- file_size: 文件大小
+- created_time: 创建时间
+- modified_time: 修改时间
+- permissions: 文件权限
+- content: 文件内容（BLOB）
+- compressed: 是否压缩
+
+## 开发
+### 设置开发环境
+```bash
+# 安装开发依赖
+uv sync --dev
+
+# 运行测试
+pytest
+
+# 构建包
+uv build
+```
+### 代码示例
+```python
+from svfs.core import SQLiteVFS
+
+# 创建文件系统
+vfs = SQLiteVFS("my_files.db", compress=True)
+vfs.connect()
+
+# 获取文件系统统计信息
+stats = vfs.get_stats()
+print(f"文件系统: {stats['name']}")
+print(f"文件数量: {stats['total_files']}")
+
+# 列出目录内容
+for item in vfs.list_directory("/"):
+    print(f"{'DIR' if item['is_directory'] else 'FILE'}: {item['name']}")
+
+vfs.close()
+```
+## 性能说明
+- 压缩功能默认对大于 1KB 的文件启用
+- 使用 zlib 压缩，压缩级别为 6（平衡压缩比和速度）
+- 文件索引优化，支持快速路径查找
+- 批量操作减少数据库事务开销
+
+## 注意事项
+1. 文件路径统一使用正斜杠（/）存储，与操作系统无关
+2. 时间戳使用 UTC 时间存储
+3. 文件权限使用 Unix 权限位表示
+4. 数据库文件可以在不同平台间迁移
+5. 大文件处理建议启用压缩以减少数据库大小
+
+## 许可证
+MIT License
+
+## 贡献
+欢迎提交 Issue 和 Pull Request 来改进项目。
+

main.py

@@ -0,0 +1,8 @@
+from sqlite_vfs.core import SQLiteVFS
+
+
+vfs = SQLiteVFS("appcation.svfs")
+print(vfs.get_file_info(".gitignore"))
+for item in vfs.list_directory("/"):
+    print(f"{'DIR' if item['is_directory'] else 'FILE'}: {item['path']}")
+vfs.close()

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 dependencies = []
-description = "Add your description here"
-name = "svfs"
+description = "sqlite virtual file system"
+name = "sqlite-vfs"
 readme = "README.md"
 requires-python = ">=3.7"
 version = "0.1.0"
@@ -12,16 +12,21 @@ url = "https://pypi.tuna.tsinghua.edu.cn/simple"
 
 [tool.uv.workspace]
 members = [
-    "devmo",
+  "devmo",
 ]
 
 [build-system]
 build-backend = "hatchling.build"
 requires = ["hatchling"]
 
+[dependency-groups]
+dev = [
+  "twine>=4.0.2",
+]
+
 [project.scripts]
-vfspack = "svfs.cli.packer:pack"
-vfsunpack = "svfs.cli.unpacker:unpack"
+vfspack = "sqlite_vfs.cli.packer:pack"
+vfsunpack = "sqlite_vfs.cli.unpacker:unpack"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/svfs"]
+packages = ["src/sqlite_vfs"]