flaxfile 1.0.0__tar.gz

flaxfile-1.0.0/.gitignore

@@ -0,0 +1,155 @@
+examples/
+CACHE_LMDB
+CHACHE_SQLITE3.db
+CACHE_LEVELDB
+Log
+FLAXKV_DB
+test_db/
+
+/data/
+
+/kunyuan*
+
+/train_data_preview
+# Configuration files (may contain passwords)
+flaxkv.toml
+.flaxkv.toml
+*secret*.toml
+*password*.toml
+
+.pyc
+.idea
+.ipynb_checkpoints
+.pytest_cache
+
+
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+.vercel

flaxfile-1.0.0/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: flaxfile
+Version: 1.0.0
+Summary: 高性能文件传输工具 - 基于ZMQ优化的跨网络文件传输系统
+Project-URL: Homepage, https://github.com/KenyonY/flaxkv
+Project-URL: Documentation, https://github.com/KenyonY/flaxkv/tree/main/flaxfile#flaxfile
+Project-URL: Issues, https://github.com/KenyonY/flaxkv/issues
+Project-URL: Source, https://github.com/KenyonY/flaxkv/tree/main/flaxfile
+Author-email: "K.Y" <beidongjiedeguang@gmail.com>
+License: MIT
+Keywords: file-transfer,high-performance,network,streaming,zmq
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Requires-Dist: fire>=0.5.0
+Requires-Dist: pyzmq>=25.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# FlaxFile - 高性能文件传输工具
+
+基于ZMQ优化的跨网络文件传输系统，专为大文件高速传输设计。
+
+## ⚡ 性能
+
+- **本地测试**: 3800+ MB/s
+- **1Gbps网络**: 110-125 MB/s（跑满带宽）
+- **10Gbps网络**: 1000-1200 MB/s
+
+vs 其他方案：
+- **vs HTTP**: 13倍更快
+- **vs 原版ZMQ**: 2.7倍更快
+
+## 🚀 快速开始
+
+### 安装依赖
+
+```bash
+pip install pyzmq fire
+```
+
+### 启动服务器
+
+```bash
+# 方法1: 使用CLI
+python -m flaxfile.cli serve
+
+# 方法2: 直接运行
+python flaxfile/server.py
+
+# 监听所有网卡（允许远程连接）
+python -m flaxfile.cli serve --host 0.0.0.0
+
+# 自定义端口
+python -m flaxfile.cli serve --upload-port 26555 --download-port 26556
+```
+
+### 使用客户端
+
+```bash
+# 上传文件
+python -m flaxfile.cli set myfile /path/to/file.bin
+
+# 下载文件
+python -m flaxfile.cli get myfile output.bin
+
+# 删除文件
+python -m flaxfile.cli delete myfile
+
+# 查看版本
+python -m flaxfile.cli version
+```
+
+## 📖 详细使用
+
+### 配置管理
+
+```bash
+# 显示当前配置
+python -m flaxfile.cli config show
+
+# 添加远程服务器
+python -m flaxfile.cli config add-server prod 192.168.1.100
+
+# 添加服务器（自定义端口）
+python -m flaxfile.cli config add-server dev 10.0.0.5 \
+  --upload-port 26555 \
+  --download-port 26556 \
+  --control-port 26557
+
+# 设置默认服务器
+python -m flaxfile.cli config set-default prod
+
+# 删除服务器
+python -m flaxfile.cli config remove-server dev
+```
+
+配置文件位置：`~/.flaxfile/config.json`
+
+### 使用远程服务器
+
+```bash
+# 上传到指定服务器
+python -m flaxfile.cli set myfile /path/to/file.bin --server prod
+
+# 从指定服务器下载
+python -m flaxfile.cli get myfile output.bin --server prod
+
+# 删除远程服务器文件
+python -m flaxfile.cli delete myfile --server prod
+```
+
+### Python API
+
+```python
+from flaxfile import FlaxFileClient
+
+# 创建客户端
+client = FlaxFileClient(server_host="192.168.1.100")
+
+# 上传文件
+result = client.upload_file("test.bin", "remote_key")
+print(f"上传吞吐量: {result['throughput']:.2f} MB/s")
+
+# 下载文件
+result = client.download_file("remote_key", "output.bin")
+print(f"下载吞吐量: {result['throughput']:.2f} MB/s")
+
+# 删除文件
+client.delete_file("remote_key")
+
+# 关闭连接
+client.close()
+```
+
+## 🔧 高级配置
+
+### 服务器端
+
+```bash
+# 仅本地访问（安全）
+python -m flaxfile.cli serve --host 127.0.0.1
+
+# 允许所有网卡访问（生产环境）
+python -m flaxfile.cli serve --host 0.0.0.0
+
+# 自定义所有端口
+python -m flaxfile.cli serve \
+  --upload-port 26555 \
+  --download-port 26556 \
+  --control-port 26557
+```
+
+### 客户端端口配置
+
+如果服务器使用非默认端口，需要在配置中指定：
+
+```bash
+python -m flaxfile.cli config add-server custom 192.168.1.100 \
+  --upload-port 26555 \
+  --download-port 26556 \
+  --control-port 26557
+```
+
+## 📊 性能优化技术
+
+FlaxFile采用以下优化技术实现极致性能：
+
+1. **PUSH/PULL模式** - 单向数据流，无identity开销
+2. **批量接收** - 减少系统调用，提升吞吐量
+3. **大缓冲区** - 128MB缓冲区，充分利用网络
+4. **零拷贝发送** - 减少内存拷贝
+5. **大chunk size** - 4MB chunk，减少往返次数
+6. **TCP优化** - keepalive等参数优化
+
+详细技术文档：`../profile_results/FINAL_TCP_OPTIMIZATION_REPORT.md`
+
+## 🌐 网络性能
+
+### 本地loopback
+
+| 文件大小 | 上传 | 下载 |
+|---------|------|------|
+| 500MB | 3868 MB/s | 1327 MB/s |
+| 1GB+ | 3800+ MB/s | 1300+ MB/s |
+
+### 真实网络
+
+| 网络 | 理论上限 | 实际吞吐量 |
+|------|---------|----------|
+| 1Gbps | 125 MB/s | 110-125 MB/s |
+| 10Gbps | 1250 MB/s | 1000-1200 MB/s |
+
+## 🔒 安全注意事项
+
+**当前版本不支持加密传输**，仅适用于：
+- ✅ 内网/局域网传输
+- ✅ 可信网络环境
+- ✅ VPN隧道内传输
+
+**不推荐**：
+- ❌ 公网直接传输敏感数据
+- ❌ 不可信网络环境
+
+未来版本将支持TLS/SSL加密。
+
+## 📁 项目结构
+
+```
+flaxfile/
+├── __init__.py       # 包初始化
+├── server.py         # 服务器实现
+├── client.py         # 客户端实现
+├── config.py         # 配置管理
+├── cli.py            # CLI接口
+└── README.md         # 本文档
+```
+
+## 🆚 vs 其他方案
+
+| 方案 | 500MB上传 | 跨网络 | 大文件稳定 |
+|------|----------|--------|----------|
+| **FlaxFile** | **3868 MB/s** | ✅ | ✅ |
+| HTTP (FastAPI) | 292 MB/s | ✅ | ❌ |
+| scp | ~100 MB/s | ✅ | ✅ |
+| rsync | ~120 MB/s | ✅ | ✅ |
+
+## 🛠️ 故障排除
+
+### 连接超时
+
+```bash
+# 检查服务器是否启动
+lsof -i :25555
+
+# 检查防火墙
+# macOS
+sudo pfctl -s rules
+
+# Linux
+sudo iptables -L
+```
+
+### 端口已被占用
+
+```bash
+# 使用不同端口
+python -m flaxfile.cli serve --upload-port 26555 --download-port 26556 --control-port 26557
+```
+
+### 性能不佳
+
+1. 检查网络带宽是否为瓶颈
+2. 确保使用SSD而非HDD
+3. 检查CPU使用率
+4. 尝试增大系统TCP缓冲区：
+   ```bash
+   # Linux
+   sudo sysctl -w net.core.rmem_max=134217728
+   sudo sysctl -w net.core.wmem_max=134217728
+   ```
+
+## 📝 开发路线图
+
+- [ ] 支持TLS/SSL加密传输
+- [ ] 支持断点续传
+- [ ] 支持文件列表功能
+- [ ] 支持多文件批量传输
+- [ ] Web界面管理
+- [ ] 传输进度条美化
+
+## 📄 License
+
+MIT License
+
+## 🙏 致谢
+
+基于ZeroMQ (ØMQ)高性能消息传递库构建。
+
+---
+
+**FlaxFile** - 让大文件传输飞起来！ 🚀

flaxfile-1.0.0/PYPI_UPLOAD_GUIDE.md

@@ -0,0 +1,146 @@
+# FlaxFile PyPI 上传指南
+
+## ✅ 准备工作已完成
+
+1. ✅ 已创建 `pyproject.toml`（使用 hatchling 构建后端）
+2. ✅ 已重构目录结构为标准的 src-layout
+3. ✅ 已成功构建测试（v1.0.0）
+4. ✅ 已验证本地安装和功能
+
+## 📁 当前目录结构
+
+```
+flaxfile/  (项目根目录)
+├── pyproject.toml          # 项目配置文件
+├── README.md               # 项目说明（会显示在 PyPI 页面）
+├── QUICKSTART.md           # 快速开始指南
+├── dist/                   # 构建产物
+│   ├── flaxfile-1.0.0-py3-none-any.whl
+│   └── flaxfile-1.0.0.tar.gz
+└── src/
+    └── flaxfile/           # Python 包
+        ├── __init__.py     # 包含版本号 __version__ = "1.0.0"
+        ├── cli.py
+        ├── client.py
+        ├── config.py
+        └── server.py
+```
+
+## 🚀 上传到 PyPI
+
+### 1. 安装上传工具
+
+```bash
+pip install twine
+```
+
+### 2. 创建 PyPI 账号
+
+- 访问 https://pypi.org/account/register/
+- 注册账号并验证邮箱
+
+### 3. 配置 PyPI Token（推荐）
+
+1. 登录 PyPI，进入 Account Settings → API Tokens
+2. 创建新 token，scope 选择 "Entire account" 或针对 flaxfile 项目
+3. 保存 token（只会显示一次！）
+4. 在本地配置：
+
+```bash
+# 创建 ~/.pypirc 文件
+cat > ~/.pypirc << 'EOF'
+[pypi]
+username = __token__
+password = pypi-AgEIcHlwaS5vcmc...你的token...
+EOF
+
+chmod 600 ~/.pypirc
+```
+
+### 4. 测试上传（可选，推荐首次使用）
+
+先上传到 TestPyPI 测试：
+
+```bash
+# 注册 TestPyPI 账号：https://test.pypi.org/account/register/
+
+# 上传到 TestPyPI
+twine upload --repository testpypi dist/*
+
+# 测试安装
+pip install --index-url https://test.pypi.org/simple/ flaxfile
+```
+
+### 5. 正式上传到 PyPI
+
+```bash
+cd /Users/kunyuan/github/flaxkv/flaxfile
+
+# 确保构建是最新的
+rm -rf dist/
+python -m build
+
+# 检查构建产物
+twine check dist/*
+
+# 上传到 PyPI
+twine upload dist/*
+```
+
+### 6. 验证上传
+
+- 访问 https://pypi.org/project/flaxfile/
+- 测试安装：
+
+```bash
+pip install flaxfile
+flaxfile version
+```
+
+## 🔄 发布新版本
+
+1. 修改 `src/flaxfile/__init__.py` 中的版本号：
+   ```python
+   __version__ = "1.0.1"
+   ```
+
+2. 重新构建和上传：
+   ```bash
+   rm -rf dist/
+   python -m build
+   twine check dist/*
+   twine upload dist/*
+   ```
+
+## 📝 注意事项
+
+1. **版本号不可重复**：每次上传必须使用新的版本号
+2. **README.md**：会自动显示在 PyPI 项目页面
+3. **许可证**：使用父目录的 LICENSE 文件（MIT License）
+4. **依赖项**：
+   - pyzmq>=25.0.0
+   - fire>=0.5.0
+5. **Python 版本**：支持 Python 3.8+
+
+## ⚠️ 上传前检查清单
+
+- [ ] README.md 内容完整准确
+- [ ] 版本号已更新（如果不是首次发布）
+- [ ] 所有功能已测试
+- [ ] 构建成功：`python -m build`
+- [ ] 包检查通过：`twine check dist/*`
+- [ ] 本地安装测试：`pip install dist/*.whl`
+
+## 🎉 当前状态
+
+✅ **已准备就绪，可以直接上传到 PyPI！**
+
+当前构建的包：
+- flaxfile-1.0.0-py3-none-any.whl (16 KB)
+- flaxfile-1.0.0.tar.gz (14 KB)
+
+执行以下命令即可上传：
+```bash
+pip install twine
+twine upload dist/*
+```