Files
paper-doc/backend/app/citation_styles/__init__.py
T
govin 76708ce767 backend: print the 参考文献 list as a bibliography, one entry per work
The list was printing each citation's quote under a `引用 #53` tag: no authors,
no year, no pages, no DOI — the quoted passage where the entry should be — and
it numbered *citations*, so a paper with 86 citations to 65 works listed 21 of
them two or three times under different numbers. The same article was `[5]` in
one paragraph and `[17]` in another.

Two rules were wrong, so two are stated here:

**A work is numbered where the reader first meets it.** A citation is a place
in the text; an entry is a work. `citations` still has one row per place, and
each row now carries the number of its *work*, so the marker in the text, the
tooltip on it and the entry in the list are the same number. The document grew
a `references` list — the entries, in order — and `reference_style`, which
names the style that wrote them.

**How a reference prints is a property of a style, not of a citation.** The new
`app/citation_styles` package holds one module per style; `springer.py`
implements Springer's basic style, whose shape is
`Names: Title. <where it sits> (year). <identifier>` with a branch per document
type — a journal with its volume(issue) and pages, a book with publisher and
place, a chapter inside somebody else's book, a patent with its number, a page
whose URL is its source.

Three of its rules are decisions rather than transcription, and each is
documented where it applies: up to six contributors are named and more become
three plus `et al.`; a journal prints under its 刊名缩写 when the writer stored
one, because no algorithm abbreviates an arbitrary title correctly; and a CJK
name keeps its printed form even with halves filled in, because dotting 「三」
into an initial is wrong in Chinese and insufficient in English.

Nothing is invented to fill a gap. An entry says what it knows and reports the
rest as `missing` (「缺 责任者、出版年」), and the document warns about the
incomplete ones by number: an entry that is short because fields are empty
looks like a fact about the document rather than a library that needs attention.

`document_text` had the same bug in the MCP surface and now prints the entries,
with in-text markers taken from the document's numbering rather than from each
sentence's local position — which is what made the text an agent reads disagree
with the list under it.

`scripts/check_citation_styles.py` checks the formatter with no server and no
database: one reference of every type, and the exact entry the style calls for.
2026-09-22 21:50:27 +08:00

88 lines
3.0 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""Citation styles: a stored reference written out as a bibliography entry.
A reference is stored as fields — 题名, 刊名, 卷, 期, 页码, DOI, 责任者 — and a
*paper* prints those fields in the order and with the punctuation one particular
style asks for. The two are deliberately separate: the library holds the facts
once, and a style decides how to write them down, so adding a style adds a module
rather than a column.
The module is one style per file, registered in :data:`STYLES`, and this package
is the only thing the rest of the application imports:
.. code-block:: python
from app.citation_styles import DEFAULT_STYLE, format_reference
text = format_reference(reference) # the default style
gaps = missing_fields(reference) # 「缺 责任者、出版年」
``DEFAULT_STYLE`` is what a document is assembled with, and the document reports
it back as ``reference_style`` so a client can name the format it is showing
without hard-coding the choice.
"""
from typing import Protocol
from app.citation_styles import springer
from app.models import Reference
class Style(Protocol):
"""What a style module provides.
Structural rather than a base class: a style is a module of two functions,
and inheriting from something would only add an import to every one of them.
"""
def format_reference(self, reference: Reference) -> str:
"""Write one reference out as a bibliography entry."""
def missing_fields(self, reference: Reference) -> list[str]:
"""Which parts a complete entry is missing, in Chinese."""
#: The styles this build can print, by the token a document reports.
STYLES: dict[str, Style] = {"springer": springer}
#: The style a document is assembled with when nothing says otherwise.
#:
#: Springer's basic style: bracketed numerals in the text, a numbered list at the
#: end, and entries of the shape ``Names: Title. <where> (year). <identifier>``.
DEFAULT_STYLE = "springer"
def _style(name: str):
"""Look a style up, or say which ones exist."""
try:
return STYLES[name]
except KeyError:
known = "、".join(sorted(STYLES))
raise ValueError(f"未知的参考文献格式:{name}(可用:{known})") from None
def format_reference(reference: Reference | None, style: str = DEFAULT_STYLE) -> str:
"""Write one reference out as a bibliography entry.
``None`` — a citation whose row the library no longer has — yields the empty
string rather than a fabricated entry: the caller decides how to say
"unlinked", and this module never guesses.
"""
if reference is None:
return ""
return _style(style).format_reference(reference)
def missing_fields(reference: Reference | None, style: str = DEFAULT_STYLE) -> list[str]:
"""Which parts a complete entry is missing, in the style's own terms."""
if reference is None:
return []
return _style(style).missing_fields(reference)
__all__ = [
"DEFAULT_STYLE",
"STYLES",
"format_reference",
"missing_fields",
]