HFdb

HFdb 是一个轻量级 Python 模块，可将私有 Hugging Face 数据集仓库转变为版本控制的 CSV 数据库。它非常适合存储小型结构化数据（例如 API 密钥、用户信用、功能标志），在这些场景下，您需要云持久化、无缝版本控制和零运维托管。

---

📦 功能

• ✅ 程序化创建私有数据集仓库
• ✅ CRUD 辅助函数（add_row、delete_row、replace_element、replace_row）
• ✅ Pandas 支持的接口（get_df 返回一个 DataFrame）
• ✅ 自动同步——每次更改时本地 CSV → Hub
• ✅ 在任何 Python 运行环境（脚本、Spaces、笔记本、Lambdas）中均可工作

---

📥 下载

选项 1) 在 HFdb 下载 ZIP 文件。

选项 2) 使用 Git 克隆

git clone https://github.com/TonyAssi/HFdb.git
cd HFdb

---

🚀 安装

pip install -r requirements.txt

---

⚡️ 快速入门

import HFdb

TOKEN = "hf_your_access_token"

# 1) Bootstrap a fresh, private dataset repo with blank CSV
db = HFdb.create(
    "username/my_db",               # repo_id
    ["key", "email", "credits"],    # CSV columns
    TOKEN
)

# 2) Later… reopen the same DB (auto-downloads latest CSV)
db = HFdb.db("username/my_db", TOKEN)

# ── CRUD in one line ────────────────────────────────────────────
db.add_row({"key": 1, "email": "tony@gmail.com", "credits": 5})

row      = db.get_row("key", 1)
exists   = db.row_exists("key", 1)
columns  = db.get_columns()
df       = db.get_df()                 # full DataFrame

db.replace_element("key", 1, "credits", 0)
db.replace_row("key", 1,
               {"key": 1, "email": "new@email.com", "credits": 0})
db.delete_row("key", 1)

---

🧩 API 参考

HFdb 在底层使用了两个 huggingface_hub 辅助函数

• hf_hub_download → 获取当前的 db.csv
• upload_file → 推送您更新后的 CSV（创建新提交）

---

⚙️ 工作原理

1. CSV 优先 – 您的数据存储在仓库根目录的 db.csv 中。
2. 原子写入 – 每个修改调用都会加载 CSV → 使用 Pandas 编辑 → 推送一个新文件。
3. 免费历史记录 – 每次推送都是一次 Git 备份提交，可在 Hub UI 中查看。
4. 身份验证 – 带有作用域的用户访问令牌可确保数据私有。

⚠️ 并发性：HFdb 适用于低流量、单写入的工作负载。两个客户端同时保存可能会发生竞态条件——如果这很重要，请考虑排队写入或添加文件锁。

---

📏 限制与最佳实践

---

🗺️ 路线图

• 🔒 可选的文件锁定
• 🍰 原生 Parquet 和 Arrow 支持
• 💾 差异化（行级）提交，而不是完整的 CSV 上传
• 🛠️ CLI 封装 (hfdb add-row …)
• 💡 有功能请求？提个问题！

---

🤝 贡献

git clone https://github.com/tonyassi/HFdb.git
poetry install      # or: pip install -r dev-requirements.txt
pre-commit install

1. 创建功能分支：git checkout -b feat/my-idea
2. 在 tests/ 中编写测试（由 pytest 提供支持）
3. 运行 black、ruff、mypy
4. 打开 PR – 请说明此更改为何有帮助 🫶

---

关于我

您好，我叫 托尼·阿西。我是一名居住在洛杉矶的设计师和创客。我拥有软件、时尚和营销背景。我目前为一家电子商务时尚品牌工作。查看我的 🤗 个人资料，了解更多应用程序、模型和数据集。

如有任何问题、意见、业务咨询或工作机会，请随时发送电子邮件至 tony.assi.media@gmail.com。