从零开始：Python初学者如何学习GitHub上的开源项目（以genanki-main为例）-CSDN博客

本文链接：https://blog.csdn.net/snail915/article/details/148101376

从零开始：Python初学者如何学习GitHub上的开源项目（以genanki-main为例）

作为Python初学者，当你第一次在GitHub上发现一个有趣的项目时，可能会感到既兴奋又困惑。今天，我们就以genanki-main这个生成Anki记忆卡片的Python库为例，手把手教你如何学习并使用GitHub上的Python项目。

第一步：了解项目概况

1. 阅读项目描述

打开genanki-main的GitHub页面，首先映入眼帘的是项目描述：

“genanki: A Library for Generating Anki Decks.”

简单明了！这是一个用于生成Anki记忆卡片的Python库。Anki是一款流行的记忆辅助软件，那么这个库应该能帮助我们通过Python代码自动创建Anki卡片。

2. 查看关键指标

星标数：2300+（说明这是一个受欢迎的项目）
最后更新时间：最后一次更新是 6 个月前，说明项目已臻稳定
开源协议：MIT（可以自由使用）

第二步：搭建学习环境

1. 安装Python环境

确保你已安装Python（建议3.6+版本）。在命令行输入：

python --version

2. 克隆或下载项目

你可以选择：

克隆仓库（推荐）：

git clone https://github.com/kerrickstaley/genanki.git

直接下载ZIP：点击GitHub页面的"Code" → “Download ZIP”

3. 创建虚拟环境

# 创建虚拟环境
python -m venv genanki_env

# 激活虚拟环境
./genanki_env/scripts/activate

4.安装依赖

进入项目目录，查看requirements.txt或setup.py文件了解依赖：

pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

第三步：阅读文档和示例

1. 仔细阅读README.md

genanki-main的README非常完善，包含：

安装说明
基本用法示例
高级功能
常见问题

2. 查看examples目录

很多项目会提供示例代码，genanki-main虽然没有专门的examples目录，但README中的代码示例非常丰富。

第四步：运行第一个示例

让我们尝试运行README中的基础示例：

import genanki

# 创建一个简单的记忆卡片模型
my_model = genanki.Model(
  1607392319,
  'Simple Model',
  fields=[
    {'name': 'Question'},
    {'name': 'Answer'},
  ],
  templates=[
    {
      'name': 'Card 1',
      'qfmt': '{{Question}}',
      'afmt': '{{FrontSide}}<hr id="answer">{{Answer}}',
    },
  ])

# 创建一个牌组
my_deck = genanki.Deck(
  2059400110,
  'Country Capitals')

# 添加卡片
my_note = genanki.Note(
  model=my_model,
  fields=['Capital of Argentina', 'Buenos Aires'])
my_deck.add_note(my_note)

# 生成Anki牌组文件
genanki.Package(my_deck).write_to_file('country_capitals.apkg')

运行这段代码后，你会得到一个country_capitals.apkg文件，可以导入Anki软件中。

第五步：深入理解项目结构

让我们看看genanki-main的主要文件结构：

genanki/
├── __init__.py      # 主模块文件
├── model.py         # 卡片模型实现
├── note.py          # 笔记/卡片实现
├── deck.py          # 牌组实现
├── package.py       # 打包功能
└── ...              # 其他支持文件

作为初学者，你可以从__init__.py开始，逐步了解各个模块的功能。

第六步：修改和实验

1. 修改示例代码

尝试修改示例代码，比如：

添加更多卡片
更改卡片样式
尝试不同的模型

2. 调试和理解

在代码中添加print语句，观察程序运行流程：

print("创建模型中...")
my_model = genanki.Model(...)

第七步：实战篇

现在我们的需求是，在我们的 anki 软件中有一个相对漂亮的模板，名叫prettify-dracula-basic。我们需要将这个模板导出为 json格式，然后使用 excel 创建多个卡片，通过 excel 批量导入，生成anki 卡片牌组文件 apkg 。以下是完整代码：

import pandas as pd
import genanki
import json
from pathlib import Path

# --- 1. 加载 Anki 模板 ---
def load_template(template_path: str) -> dict:
    """加载 Anki 模板 JSON 文件"""
    with open(template_path, "r", encoding="utf-8") as f:
        return json.load(f)

# --- 2. 创建 Anki 模型 ---
def create_model(template_data: dict) -> genanki.Model:
    """根据模板数据创建 genanki Model"""
    return genanki.Model(
        model_id=template_data["id"],
        name=template_data["name"],
        fields=[{"name": field["name"], "ord": field["ord"]} for field in template_data["flds"]],
        templates=template_data["tmpls"],
        css=template_data["css"]
    )

# --- 3. 从 Excel 读取卡片数据 ---
def read_notes_from_excel(excel_path: str) -> list[tuple[str, str, list[str]]]:
    """
    读取 Excel 文件中的卡片数据
    返回: [(front, back, tags), ...]
    """
    df = pd.read_excel(excel_path, engine="openpyxl")
    notes = []
    for _, row in df.iterrows():
        front = str(row["Front"])  # 确保数据为字符串
        back = str(row["Back"])
        tags = row["Tags"].split(",") if pd.notna(row["Tags"]) else []
        notes.append((front, back, tags))
    return notes

# --- 4. 主程序 ---
def main():
    # 配置文件路径
    TEMPLATE_PATH = "./Model/prettify-dracula-basic.json"
    EXCEL_PATH = "./from/notes.xlsx"
    OUTPUT_PATH = "./output/output.apkg"

    # 加载模板和创建模型
    template = load_template(TEMPLATE_PATH)
    model = create_model(template)

    # 创建 Deck
    deck = genanki.Deck(2059400110, "测试卡片库")

    # 从 Excel 读取数据并添加卡片
    for front, back, tags in read_notes_from_excel(EXCEL_PATH):
        note = genanki.Note(
            model=model,
            fields=[front, back],
            tags=tags
        )
        deck.add_note(note)

    # 生成 Anki 包
    genanki.Package(deck).write_to_file(OUTPUT_PATH)
    print(f"成功生成 Anki 包: {Path(OUTPUT_PATH).resolve()}")

if __name__ == "__main__":
    main()