refstore 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- refstore-0.1.0/CONTRIBUTING.md +358 -0
- refstore-0.1.0/LICENSE +21 -0
- refstore-0.1.0/MANIFEST.in +6 -0
- refstore-0.1.0/PKG-INFO +501 -0
- refstore-0.1.0/README.md +433 -0
- refstore-0.1.0/pyproject.toml +167 -0
- refstore-0.1.0/refstore/__init__.py +105 -0
- refstore-0.1.0/refstore/_async/__init__.py +6 -0
- refstore-0.1.0/refstore/_async/buckets.py +79 -0
- refstore-0.1.0/refstore/_async/file_service.py +237 -0
- refstore-0.1.0/refstore/core/__init__.py +23 -0
- refstore-0.1.0/refstore/core/config.py +193 -0
- refstore-0.1.0/refstore/core/exceptions.py +41 -0
- refstore-0.1.0/refstore/core/retry.py +248 -0
- refstore-0.1.0/refstore/sync/__init__.py +6 -0
- refstore-0.1.0/refstore/sync/buckets.py +104 -0
- refstore-0.1.0/refstore/sync/file_service.py +410 -0
- refstore-0.1.0/refstore/utils/__init__.py +29 -0
- refstore-0.1.0/refstore/utils/uri.py +258 -0
- refstore-0.1.0/refstore/web/__init__.py +38 -0
- refstore-0.1.0/refstore/web/app.py +341 -0
- refstore-0.1.0/refstore/web/models.py +107 -0
- refstore-0.1.0/refstore.egg-info/PKG-INFO +501 -0
- refstore-0.1.0/refstore.egg-info/SOURCES.txt +47 -0
- refstore-0.1.0/refstore.egg-info/dependency_links.txt +1 -0
- refstore-0.1.0/refstore.egg-info/requires.txt +22 -0
- refstore-0.1.0/refstore.egg-info/top_level.txt +1 -0
- refstore-0.1.0/setup.cfg +4 -0
- refstore-0.1.0/setup.py +8 -0
- refstore-0.1.0/tests/test_async.py +109 -0
- refstore-0.1.0/tests/test_config.py +167 -0
- refstore-0.1.0/tests/test_sync.py +139 -0
- refstore-0.1.0/tests/test_uri.py +163 -0
|
@@ -0,0 +1,358 @@
|
|
|
1
|
+
# 贡献指南
|
|
2
|
+
|
|
3
|
+
感谢你有兴趣为 RefStore 做出贡献！我们欢迎任何形式的贡献，包括但不限于：
|
|
4
|
+
|
|
5
|
+
- 报告 Bug
|
|
6
|
+
- 提出新功能建议
|
|
7
|
+
- 提交代码改进
|
|
8
|
+
- 改进文档
|
|
9
|
+
- 提供使用示例
|
|
10
|
+
|
|
11
|
+
## 开发环境设置
|
|
12
|
+
|
|
13
|
+
### 前置要求
|
|
14
|
+
|
|
15
|
+
- Python 3.8 或更高版本
|
|
16
|
+
- Git
|
|
17
|
+
- pip
|
|
18
|
+
|
|
19
|
+
### 克隆仓库
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
git clone https://github.com/yourusername/refstore.git
|
|
23
|
+
cd refstore
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### 创建虚拟环境
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
python -m venv venv
|
|
30
|
+
source venv/bin/activate # Linux/macOS
|
|
31
|
+
# 或
|
|
32
|
+
venv\Scripts\activate # Windows
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### 安装开发依赖
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pip install -e ".[dev]"
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
这会安装所有开发依赖，包括：
|
|
42
|
+
- 测试框架（pytest）
|
|
43
|
+
- 代码格式化工具（black, isort）
|
|
44
|
+
- 代码检查工具（flake8, mypy）
|
|
45
|
+
- 覆盖率工具（pytest-cov）
|
|
46
|
+
|
|
47
|
+
## 代码风格
|
|
48
|
+
|
|
49
|
+
我们遵循以下代码风格指南：
|
|
50
|
+
|
|
51
|
+
### PEP 8
|
|
52
|
+
|
|
53
|
+
RefStore 遵循 PEP 8 编码规范。我们使用工具自动检查和格式化代码。
|
|
54
|
+
|
|
55
|
+
### Black
|
|
56
|
+
|
|
57
|
+
使用 Black 进行代码格式化：
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
black refstore tests examples
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
配置文件：`pyproject.toml` 中的 `[tool.black]` 部分。
|
|
64
|
+
|
|
65
|
+
### isort
|
|
66
|
+
|
|
67
|
+
使用 isort 对导入进行排序：
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
isort refstore tests examples
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
配置文件：`pyproject.toml` 中的 `[tool.isort]` 部分。
|
|
74
|
+
|
|
75
|
+
### Flake8
|
|
76
|
+
|
|
77
|
+
使用 Flake8 进行代码检查：
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
flake8 refstore tests examples
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### mypy
|
|
84
|
+
|
|
85
|
+
使用 mypy 进行类型检查：
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
mypy refstore
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
配置文件：`pyproject.toml` 中的 `[tool.mypy]` 部分。
|
|
92
|
+
|
|
93
|
+
## 提交代码前检查
|
|
94
|
+
|
|
95
|
+
在提交代码前，请确保：
|
|
96
|
+
|
|
97
|
+
1. 所有测试通过：`pytest`
|
|
98
|
+
2. 代码格式正确：`black refstore tests examples`
|
|
99
|
+
3. 导入已排序：`isort refstore tests examples`
|
|
100
|
+
4. 通过代码检查：`flake8 refstore tests examples`
|
|
101
|
+
5. 类型检查通过：`mypy refstore`
|
|
102
|
+
|
|
103
|
+
### Pre-commit Hooks
|
|
104
|
+
|
|
105
|
+
我们推荐使用 pre-commit 钩子自动在提交前执行这些检查：
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
pip install pre-commit
|
|
109
|
+
pre-commit install
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
现在每次提交代码时，pre-commit 会自动运行检查。
|
|
113
|
+
|
|
114
|
+
## 测试
|
|
115
|
+
|
|
116
|
+
### 运行测试
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
# 运行所有测试
|
|
120
|
+
pytest
|
|
121
|
+
|
|
122
|
+
# 运行特定测试文件
|
|
123
|
+
pytest tests/test_config.py
|
|
124
|
+
|
|
125
|
+
# 运行特定测试
|
|
126
|
+
pytest tests/test_config.py::TestConfigValidator::test_valid_config
|
|
127
|
+
|
|
128
|
+
# 显示详细输出
|
|
129
|
+
pytest -v
|
|
130
|
+
|
|
131
|
+
# 只运行失败的测试
|
|
132
|
+
pytest --lf
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### 测试覆盖率
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
# 生成覆盖率报告
|
|
139
|
+
pytest --cov=refstore --cov-report=html
|
|
140
|
+
|
|
141
|
+
# 在浏览器中查看覆盖率报告
|
|
142
|
+
open htmlcov/index.html # macOS
|
|
143
|
+
xdg-open htmlcov/index.html # Linux
|
|
144
|
+
start htmlcov/index.html # Windows
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### 编写测试
|
|
148
|
+
|
|
149
|
+
我们使用 pytest 作为测试框架。测试文件位于 `tests/` 目录。
|
|
150
|
+
|
|
151
|
+
测试文件命名：`test_*.py`
|
|
152
|
+
|
|
153
|
+
测试类命名：`Test*`
|
|
154
|
+
|
|
155
|
+
测试函数命名：`test_*`
|
|
156
|
+
|
|
157
|
+
示例：
|
|
158
|
+
|
|
159
|
+
```python
|
|
160
|
+
import pytest
|
|
161
|
+
from refstore import RefStore
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
class TestRefStore:
|
|
165
|
+
"""RefStore 测试类"""
|
|
166
|
+
|
|
167
|
+
def test_upload_file(self):
|
|
168
|
+
"""测试上传文件"""
|
|
169
|
+
config = {...}
|
|
170
|
+
store = RefStore(config)
|
|
171
|
+
|
|
172
|
+
data = b"test content"
|
|
173
|
+
uri = store.upload_file(data, "test.txt", logic_bucket="user")
|
|
174
|
+
|
|
175
|
+
assert uri is not None
|
|
176
|
+
assert uri.startswith("s3://")
|
|
177
|
+
|
|
178
|
+
@pytest.mark.asyncio
|
|
179
|
+
async def test_async_upload(self):
|
|
180
|
+
"""测试异步上传"""
|
|
181
|
+
from refstore import AsyncRefStore
|
|
182
|
+
|
|
183
|
+
config = {...}
|
|
184
|
+
async with AsyncRefStore(config) as store:
|
|
185
|
+
uri = await store.upload_file(b"test", "test.txt")
|
|
186
|
+
assert uri is not None
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### Mock 和 Fixture
|
|
190
|
+
|
|
191
|
+
使用 unittest.mock 进行测试时的模拟：
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
from unittest.mock import Mock, patch
|
|
195
|
+
|
|
196
|
+
def test_with_mock():
|
|
197
|
+
with patch('refstore.sync.file_service.Minio') as mock_minio:
|
|
198
|
+
mock_client = Mock()
|
|
199
|
+
mock_minio.return_value = mock_client
|
|
200
|
+
|
|
201
|
+
store = RefStore(config)
|
|
202
|
+
# ... 测试代码
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
使用 pytest fixtures：
|
|
206
|
+
|
|
207
|
+
```python
|
|
208
|
+
@pytest.fixture
|
|
209
|
+
def config():
|
|
210
|
+
"""测试配置 fixture"""
|
|
211
|
+
return {
|
|
212
|
+
"minio": {
|
|
213
|
+
"endpoint": "localhost:9000",
|
|
214
|
+
"access_key": "test",
|
|
215
|
+
"secret_key": "test",
|
|
216
|
+
},
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
def test_with_fixture(config):
|
|
220
|
+
"""使用 fixture 的测试"""
|
|
221
|
+
store = RefStore(config)
|
|
222
|
+
# ... 测试代码
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## 提交 Pull Request
|
|
226
|
+
|
|
227
|
+
### 分支策略
|
|
228
|
+
|
|
229
|
+
1. Fork 仓库
|
|
230
|
+
2. 从 `main` 分支创建功能分支：
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
git checkout -b feature/your-feature-name
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
3. 进行开发和测试
|
|
237
|
+
4. 提交更改
|
|
238
|
+
5. 推送到你的 fork
|
|
239
|
+
6. 创建 Pull Request
|
|
240
|
+
|
|
241
|
+
### Commit 消息格式
|
|
242
|
+
|
|
243
|
+
我们使用约定式提交（Conventional Commits）格式：
|
|
244
|
+
|
|
245
|
+
```
|
|
246
|
+
<type>(<scope>): <subject>
|
|
247
|
+
|
|
248
|
+
<body>
|
|
249
|
+
|
|
250
|
+
<footer>
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
类型（type）：
|
|
254
|
+
- `feat`: 新功能
|
|
255
|
+
- `fix`: 修复 Bug
|
|
256
|
+
- `docs`: 文档更改
|
|
257
|
+
- `style`: 代码格式（不影响代码含义）
|
|
258
|
+
- `refactor`: 重构
|
|
259
|
+
- `test`: 添加或修改测试
|
|
260
|
+
- `chore`: 构建过程或辅助工具的变动
|
|
261
|
+
|
|
262
|
+
示例：
|
|
263
|
+
|
|
264
|
+
```
|
|
265
|
+
feat(file_service): add support for multipart upload
|
|
266
|
+
|
|
267
|
+
Implement multipart upload for files larger than 5MB.
|
|
268
|
+
|
|
269
|
+
Closes #123
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
```
|
|
273
|
+
fix(config): validate endpoint format correctly
|
|
274
|
+
|
|
275
|
+
Fix validation to reject endpoints without port numbers.
|
|
276
|
+
|
|
277
|
+
Fixes #456
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
### Pull Request 检查清单
|
|
281
|
+
|
|
282
|
+
在提交 PR 前，请确保：
|
|
283
|
+
|
|
284
|
+
- [ ] 代码通过所有测试
|
|
285
|
+
- [ ] 代码覆盖率没有显著降低
|
|
286
|
+
- [ ] 代码已通过 Black 格式化
|
|
287
|
+
- [ ] 导入已通过 isort 排序
|
|
288
|
+
- [ ] 代码通过 Flake8 检查
|
|
289
|
+
- [ ] 代码通过 mypy 类型检查
|
|
290
|
+
- [ ] 添加了必要的测试
|
|
291
|
+
- [ ] 更新了相关文档
|
|
292
|
+
- [ ] PR 描述清晰说明了更改内容
|
|
293
|
+
|
|
294
|
+
## 报告 Bug
|
|
295
|
+
|
|
296
|
+
在报告 Bug 时，请提供：
|
|
297
|
+
|
|
298
|
+
1. Bug 的详细描述
|
|
299
|
+
2. 重现步骤
|
|
300
|
+
3. 期望行为
|
|
301
|
+
4. 实际行为
|
|
302
|
+
5. 环境信息：
|
|
303
|
+
- Python 版本
|
|
304
|
+
- RefStore 版本
|
|
305
|
+
- 操作系统
|
|
306
|
+
6. 错误堆栈跟踪（如果有）
|
|
307
|
+
7. 最小可重现示例（如果可能）
|
|
308
|
+
|
|
309
|
+
## 功能请求
|
|
310
|
+
|
|
311
|
+
在提出新功能时，请：
|
|
312
|
+
|
|
313
|
+
1. 清晰描述功能需求
|
|
314
|
+
2. 说明为什么需要这个功能
|
|
315
|
+
3. 描述期望的使用方式
|
|
316
|
+
4. 考虑是否会影响现有功能
|
|
317
|
+
5. 如果可能，提供伪代码或示例
|
|
318
|
+
|
|
319
|
+
## 文档
|
|
320
|
+
|
|
321
|
+
我们欢迎改进文档的贡献：
|
|
322
|
+
|
|
323
|
+
- 修正错误和拼写
|
|
324
|
+
- 添加使用示例
|
|
325
|
+
- 改进解释
|
|
326
|
+
- 翻译文档
|
|
327
|
+
- 添加图表和图片
|
|
328
|
+
|
|
329
|
+
## 代码审查
|
|
330
|
+
|
|
331
|
+
所有代码在合并前都需要经过代码审查。请：
|
|
332
|
+
|
|
333
|
+
- 保持开放的心态接受反馈
|
|
334
|
+
- 及时响应审查意见
|
|
335
|
+
- 解释你的设计决策
|
|
336
|
+
- 愿意根据反馈进行修改
|
|
337
|
+
|
|
338
|
+
## 行为准则
|
|
339
|
+
|
|
340
|
+
- 尊重所有贡献者
|
|
341
|
+
- 保持专业和友好的沟通
|
|
342
|
+
- 关注问题而不是个人
|
|
343
|
+
- 接受并尊重不同的观点
|
|
344
|
+
- 做出建设性的反馈
|
|
345
|
+
|
|
346
|
+
## 获取帮助
|
|
347
|
+
|
|
348
|
+
如果你在贡献过程中遇到问题：
|
|
349
|
+
|
|
350
|
+
- 查看现有的 Issue 和 Pull Request
|
|
351
|
+
- 在 Issue 中提问
|
|
352
|
+
- 加入社区讨论
|
|
353
|
+
|
|
354
|
+
## 许可证
|
|
355
|
+
|
|
356
|
+
通过贡献代码，你同意你的贡献将采用项目的 MIT 许可证。
|
|
357
|
+
|
|
358
|
+
感谢你的贡献！
|
refstore-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 RefStore Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|