citation-bibliography-generator

引用与参考文献生成器

以多种学术和专业格式生成规范的引用和参考文献。支持手动录入、结构化数据导入，以及通过 DOI/ISBN 自动查询元数据。

快速开始

from scripts.citation_generator import CitationGenerator

# Create generator with desired style
gen = CitationGenerator(style='apa')

# Cite a book
citation = gen.cite_book(
    authors=["Smith, John", "Doe, Jane"],
    title="Research Methods in Social Science",
    year=2020,
    publisher="Academic Press",
    city="New York"
)
print(citation)
# Output: Smith, J., & Doe, J. (2020). Research methods in social science. Academic Press.

# Build bibliography
gen.add_to_bibliography(citation)
bibliography = gen.generate_bibliography()
print(bibliography)

支持的引用格式

• APA（美国心理学会）——第 7 版
• MLA（现代语言协会）——第 9 版
• Chicago（《芝加哥格式手册》）——第 17 版
• IEEE（电气与电子工程师协会）
• Harvard（哈佛引用格式）

功能

1. 手动创建引用

按来源类型设置引用格式：

• 图书——专著、编著、版本
• 期刊文章——带 DOI 的同行评审文章
• 网站——带访问日期的在线来源
• 会议论文——会议论文集和演讲

2. 自动查询元数据

• DOI 查询——从 CrossRef API 获取文章元数据
• ISBN 查询——获取图书信息（如有）
• 自动检测来源类型并据此设置格式

3. 参考文献管理

• 添加多条引用
• 按作者、年份或标题自动排序
• 检测并移除重复项
• 导出为纯文本或 BibTeX

4. 文内引用

生成括号式或叙述式文内引用：

• 括号式：(Smith, 2020, p. 45)
• 叙述式：Smith (2020) argues that...
• 处理多位作者及 et al. 格式

5. 批量处理

从包含结构化数据的 CSV 文件导入引用，并生成完整的参考文献列表。

API 参考

CitationGenerator

初始化：

gen = CitationGenerator(style='apa')

参数：

• style（str）：引用格式——'apa'、'mla'、'chicago'、'ieee' 或 'harvard'

引用方法

cite_book()

citation = gen.cite_book(
    authors=["Last, First", "Last, First"],
    title="Book Title",
    year=2020,
    publisher="Publisher Name",
    city="City",           # Optional
    edition="3rd ed.",     # Optional
    isbn="978-0-123456-78-9"  # Optional
)

返回值：格式化后的引用字符串

cite_article()

citation = gen.cite_article(
    authors=["Last, First"],
    title="Article Title",
    journal="Journal Name",
    year=2020,
    volume=10,          # Optional
    issue=2,            # Optional
    pages="45-67",      # Optional
    doi="10.1234/example"  # Optional
)

返回值：格式化后的引用字符串

cite_website()

citation = gen.cite_website(
    authors=["Last, First"],  # Can be empty list
    title="Page Title",
    url="https://example.com",
    access_date="2024-01-15",
    publish_date="2023-12-01"  # Optional
)

返回值：格式化后的引用字符串

cite_from_doi()

citation = gen.cite_from_doi(doi="10.1234/example")

从 CrossRef API 查询文章元数据并生成格式化引用。

返回值：格式化后的引用字符串

参考文献管理

add_to_bibliography()

gen.add_to_bibliography(citation)

将引用添加到参考文献列表。

generate_bibliography()

bibliography = gen.generate_bibliography(
    sort_by='author',      # 'author', 'year', or 'title'
    deduplicate=True       # Remove duplicate entries
)

返回值：带悬挂缩进的格式化参考文献字符串

export_bibtex()

gen.export_bibtex(output_path='references.bib')

将参考文献导出为 LaTeX 文档使用的 BibTeX 格式。

文内引用

in_text_citation()

citation = gen.in_text_citation(
    authors=["Smith, J."],
    year=2020,
    page="45",          # Optional
    narrative=False     # True for narrative style
)

返回值：

• 括号式：(Smith, 2020, p. 45)
• 叙述式：Smith (2020)

批量处理

import_from_csv()

citations = gen.import_from_csv(csv_path='citations.csv')

从 CSV 文件导入多条引用。

CSV 格式：

type,authors,title,year,journal,publisher,doi,isbn,url,access_date
article,"Smith, J.|Doe, A.",Research Methods,2020,Journal of Science,,10.1234/example,,,
book,"Johnson, M.",Data Analysis,2019,,Academic Press,,978-0-123456-78-9,,
website,,"Web Page Title",2024,,,,,https://example.com,2024-01-15

注意：多位作者之间用 | 竖线字符分隔

返回值：格式化后的引用字符串列表

CLI 用法

单条引用

图书：

python scripts/citation_generator.py book \
    --authors "Smith, J." "Doe, A." \
    --title "Research Methods" \
    --year 2020 \
    --publisher "Academic Press" \
    --city "New York" \
    --style apa

文章：

python scripts/citation_generator.py article \
    --authors "Smith, J." \
    --title "Study Title" \
    --journal "Journal Name" \
    --year 2020 \
    --volume 10 \
    --issue 2 \
    --pages "45-67" \
    --doi "10.1234/example" \
    --style mla

网站：

python scripts/citation_generator.py website \
    --title "Page Title" \
    --url "https://example.com" \
    --access-date "2024-01-15" \
    --style chicago

DOI 查询

python scripts/citation_generator.py doi \
    --doi "10.1234/example" \
    --style apa

批量处理

python scripts/citation_generator.py batch \
    --input citations.csv \
    --style harvard \
    --output bibliography.txt \
    --sort author

BibTeX 导出

python scripts/citation_generator.py batch \
    --input citations.csv \
    --format bibtex \
    --output references.bib

CLI 参数

参数	说明	默认值
--style, -s	引用格式（apa/mla/chicago/ieee/harvard）	apa
--authors, -a	作者姓名（可指定多位）	-
--title, -t	作品标题	-
--year, -y	出版年份	-
--input, -i	输入 CSV 文件（批处理模式）	-
--output, -o	输出文件路径	stdout
--format, -f	输出格式（text/bibtex）	text
--sort	参考文献排序依据（author/year/title）	author

示例

示例 1：APA 图书引用

gen = CitationGenerator(style='apa')
citation = gen.cite_book(
    authors=["Doe, Jane", "Smith, John"],
    title="The Art of Research",
    year=2021,
    publisher="University Press",
    edition="2nd ed."
)
print(citation)
# Doe, J., & Smith, J. (2021). The art of research (2nd ed.). University Press.

示例 2：MLA 文章引用

gen = CitationGenerator(style='mla')
citation = gen.cite_article(
    authors=["Johnson, Mary"],
    title="Digital Humanities in the 21st Century",
    journal="Modern Research Quarterly",
    year=2022,
    volume=15,
    issue=3,
    pages="112-145",
    doi="10.5678/mrq.2022.15.3"
)
print(citation)
# Johnson, Mary. "Digital Humanities in the 21st Century." Modern Research Quarterly, vol. 15, no. 3, 2022, pp. 112-145. DOI: 10.5678/mrq.2022.15.3.

示例 3：Chicago 网站引用

gen = CitationGenerator(style='chicago')
citation = gen.cite_website(
    authors=["Brown, Robert"],
    title="Understanding Machine Learning",
    url="https://ml-guide.example.com",
    access_date="2024-01-20",
    publish_date="2023-11-15"
)
print(citation)
# Brown, Robert. "Understanding Machine Learning." Last modified November 15, 2023. Accessed January 20, 2024. https://ml-guide.example.com.

示例 4：构建参考文献列表

gen = CitationGenerator(style='apa')

# Add multiple citations
gen.add_to_bibliography(gen.cite_book(
    authors=["Smith, A."],
    title="First Book",
    year=2020,
    publisher="Press A"
))

gen.add_to_bibliography(gen.cite_article(
    authors=["Jones, B."],
    title="Research Article",
    journal="Journal X",
    year=2021
))

# Generate formatted bibliography
bibliography = gen.generate_bibliography(sort_by='author')
print(bibliography)

示例 5：DOI 查询

gen = CitationGenerator(style='ieee')
citation = gen.cite_from_doi(doi="10.1109/ACCESS.2019.2947014")
print(citation)
# Auto-fetches metadata and formats in IEEE style

示例 6：从 CSV 批量处理

gen = CitationGenerator(style='harvard')
citations = gen.import_from_csv('my_references.csv')

# Add all to bibliography
for citation in citations:
    gen.add_to_bibliography(citation)

# Generate and export
gen.export_bibtex('references.bib')

依赖项

pandas>=2.0.0
requests>=2.31.0

安装依赖项：

pip install -r scripts/requirements.txt

局限性

• API 可用性：DOI/ISBN 查询需要连接互联网，并依赖第三方 API（CrossRef）
• API 速率限制：CrossRef API 有速率限制；批量查询时应加入延迟
• 格式变体：某些引文格式存在学科特定的变体，未能完全覆盖
• 特殊字符：不同输出格式对重音符号和特殊字符的 Unicode 支持可能有所不同
• 版次编号：不同格式对版次的处理方式不同（序数词或文字）
• 作者姓名格式：输入应采用“姓，名”格式；解析其他格式时可能不一致
• 多位作者：各格式的 et al. 规则有所不同（APA：3 位及以上，MLA：3 位及以上，Chicago：4 位及以上）
• 在线优先发表的文章：先于印刷版在线发表的文章可能只有部分元数据
• 非英语来源：某些引文格式对非英语来源有特定规则，可能尚未完全实现

引文格式指南

APA（美国心理学会）

• 作者—日期制
• 在最后一位作者之前使用与号（&）
• 书名使用标题式大小写，文章标题使用句子式大小写
• DOI 采用 URL 格式：https://doi.org/10.xxxx

MLA（现代语言协会）

• 作者—页码制
• 在最后一位作者之前使用“And”
• 所有标题均使用标题式大小写
• 容器概念（期刊是文章的容器）

Chicago（《芝加哥格式手册》）

• 注释与参考书目制
• 在最后一位作者之前使用“And”
• 标题使用标题式大小写
• 网站需注明访问日期

IEEE（电气电子工程师学会）

• 使用编号参考文献 [1]、[2] 等
• 姓氏之前写名字首字母
• 文章标题使用引号
• 期刊名称使用缩写

Harvard

• 作者—日期制
• 在最后一位作者之前使用“And”
• 书名和期刊名使用斜体
• URL 使用“Available at:”标注