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.
This commit is contained in:
@@ -0,0 +1,87 @@
|
||||
"""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",
|
||||
]
|
||||
@@ -0,0 +1,564 @@
|
||||
"""Springer basic style: one stored reference, written out as a bibliography entry.
|
||||
|
||||
Springer's **basic** style is the numbered one — bracketed numerals in the text
|
||||
and a numbered list at the end — which is the shape this project already has.
|
||||
What it adds is the layout of the entry itself, taken from Springer's own
|
||||
examples:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Van der Geer, J., Hanraads, J.A.J., Lupton, R.A.: The art of writing a
|
||||
scientific article. J. Sci. Commun. 163(2), 51–59 (2010).
|
||||
https://doi.org/10.1016/j.Sc.2010.00372
|
||||
|
||||
Strunk Jr., W., White, E.B.: The Elements of Style, 4th edn. Longman,
|
||||
New York (2000)
|
||||
|
||||
Mettam, G.R., Adams, L.B.: How to prepare an electronic version of your
|
||||
article. In: Jones, B.S., Smith, R.Z. (eds.) Introduction to the Electronic
|
||||
Age, pp. 281–304. E-Publishing Inc., New York (2009)
|
||||
|
||||
So an entry is ``Names: Title. <where the entry sits> (year). <identifier>``,
|
||||
and *where it sits* is the only part that changes with the document type: a
|
||||
journal with its volume and pages, a book with its publisher, a chapter inside
|
||||
somebody else's book, a patent with its number.
|
||||
|
||||
Three rules here are decisions rather than transcription, and each is stated
|
||||
where it is applied:
|
||||
|
||||
* **Up to six contributors are named; more become the first three and
|
||||
``et al.``** — Springer's rule for this style.
|
||||
* **A journal prints under its 刊名缩写 when the writer stored one**, because
|
||||
Springer abbreviates journal titles and no algorithm abbreviates an arbitrary
|
||||
title correctly: the library has a column for the abbreviation precisely so a
|
||||
human decides it. Without one, the full 刊名 is printed rather than an
|
||||
invention.
|
||||
* **A CJK name is printed as stored**, halves or no halves: dotting 「三」 into
|
||||
an initial is wrong in Chinese and insufficient in English (see
|
||||
:func:`_name`).
|
||||
* **Nothing is invented to fill a gap.** A missing year prints no parentheses, a
|
||||
missing publisher no publisher; the field simply does not appear. What a
|
||||
complete entry would need is reported separately by :func:`missing_fields`, so
|
||||
the writer is told what is absent instead of being shown a plausible-looking
|
||||
fabrication.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from datetime import date
|
||||
from typing import Callable
|
||||
|
||||
from app.models import Reference, ReferenceAuthor
|
||||
|
||||
#: How many contributors are named before the list is cut short, and how many
|
||||
#: survive the cut. Springer's basic style names up to six, then the first three
|
||||
#: followed by ``et al.``
|
||||
_AUTHOR_LIMIT = 6
|
||||
_AUTHOR_KEEP = 3
|
||||
|
||||
#: ``122-141`` → ``122–141``. Springer prints ranges with an en dash, and the
|
||||
#: stored value is whatever the writer pasted — often a plain hyphen.
|
||||
_PAGE_RANGE = re.compile(r"(\d+)\s*[-–—]\s*(\d+)")
|
||||
|
||||
#: CJK ideographs and kana. A name containing one is printed as stored rather
|
||||
#: than inverted and initialised; see :func:`_name`.
|
||||
_CJK = re.compile(r"[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]")
|
||||
|
||||
_MONTHS = (
|
||||
"January",
|
||||
"February",
|
||||
"March",
|
||||
"April",
|
||||
"May",
|
||||
"June",
|
||||
"July",
|
||||
"August",
|
||||
"September",
|
||||
"October",
|
||||
"November",
|
||||
"December",
|
||||
)
|
||||
|
||||
#: For a web page the URL *is* the source, so it is printed where a journal
|
||||
#: would be rather than at the end as an identifier. Every other type keeps the
|
||||
#: URL for the trailing ``https://doi.org/…`` slot.
|
||||
_URL_IS_THE_SOURCE = frozenset({"web-page"})
|
||||
|
||||
|
||||
def format_reference(reference: Reference) -> str:
|
||||
"""Write one reference out as a Springer bibliography entry.
|
||||
|
||||
The clauses are assembled and joined by ``". "``, which is the style's own
|
||||
punctuation: the colon after the names, the period between the title and
|
||||
where the entry sits, and the period before the DOI all fall out of it.
|
||||
"""
|
||||
clauses = [
|
||||
clause
|
||||
for clause in (
|
||||
_head(reference),
|
||||
*_where(reference),
|
||||
_identifier(reference),
|
||||
_accessed(reference),
|
||||
)
|
||||
if clause
|
||||
]
|
||||
|
||||
# A clause that is nothing but a year is not a sentence, so it attaches to
|
||||
# what precedes it rather than following a full stop. This is the shape a
|
||||
# reference with a title and a year and nothing else takes: "…: Six (2021)",
|
||||
# not "…: Six. (2021)". Doing it here rather than in each of the fourteen
|
||||
# builders is one rule instead of fourteen chances to forget it.
|
||||
parts: list[str] = []
|
||||
for clause in clauses:
|
||||
if parts and clause.startswith("(") and clause.endswith(")"):
|
||||
parts[-1] = f"{parts[-1]} {clause}"
|
||||
else:
|
||||
parts.append(clause)
|
||||
return ". ".join(parts)
|
||||
|
||||
|
||||
# --- the two halves every entry has ------------------------------------------
|
||||
|
||||
|
||||
def _head(reference: Reference) -> str:
|
||||
"""``Names: Title`` — what the entry is, and who wrote it."""
|
||||
names = _head_names(reference)
|
||||
title = _title(reference)
|
||||
return f"{names}: {title}" if names else title
|
||||
|
||||
|
||||
def _title(reference: Reference) -> str:
|
||||
"""The title, with its subtitle after a colon.
|
||||
|
||||
The library stores 副题名 as its own column because a citation style is
|
||||
allowed to drop it; this one prints it, so the two are joined back into the
|
||||
title the reader saw.
|
||||
"""
|
||||
title = _clean(reference.title)
|
||||
subtitle = _clean(reference.subtitle)
|
||||
if subtitle and not title.endswith((":", ":")):
|
||||
title = f"{title}: {subtitle}"
|
||||
elif subtitle:
|
||||
title = f"{title} {subtitle}"
|
||||
|
||||
# For a whole book the edition belongs to the title ("The Elements of
|
||||
# Style, 4th edn"); for a chapter it belongs to the book it sits in, which
|
||||
# is where :func:`_where_chapter` puts it.
|
||||
if reference.type == "book" and _clean(reference.edition):
|
||||
title = f"{title}, {_clean(reference.edition)}"
|
||||
return title
|
||||
|
||||
|
||||
def _head_names(reference: Reference) -> str:
|
||||
"""The contributors that lead the entry.
|
||||
|
||||
Authors first. A book whose contributors are all marked 编者 is written by
|
||||
its editors — ``Jones, B.S. (ed.)`` — and a 汇编 / 译者 with no author at all
|
||||
still has to appear somewhere, so the last resort is the stored list in
|
||||
print order.
|
||||
"""
|
||||
authors = [author for author in reference.authors if author.role == "author"]
|
||||
if authors:
|
||||
return _name_list(authors)
|
||||
|
||||
editors = [author for author in reference.authors if author.role == "editor"]
|
||||
if editors:
|
||||
return _name_list(editors) + (" (ed.)" if len(editors) == 1 else " (eds.)")
|
||||
|
||||
return _name_list(list(reference.authors))
|
||||
|
||||
|
||||
def _editor_names(reference: Reference) -> str:
|
||||
"""The 编者 of a chapter's containing book, marked ``(ed.)`` / ``(eds.)``.
|
||||
|
||||
The library keeps one contributor list per entry, so these are the
|
||||
contributors the writer marked 编者. When there are none the container is
|
||||
printed without a mark rather than guessing whose book it is.
|
||||
"""
|
||||
editors = [author for author in reference.authors if author.role == "editor"]
|
||||
if not editors:
|
||||
return ""
|
||||
mark = " (ed.)" if len(editors) == 1 else " (eds.)"
|
||||
return _name_list(editors) + mark
|
||||
|
||||
|
||||
def _name_list(people: list[ReferenceAuthor]) -> str:
|
||||
"""The contributor list, cut to Springer's limit."""
|
||||
names = [_name(person) for person in people if person.name.strip()]
|
||||
if len(names) > _AUTHOR_LIMIT:
|
||||
return ", ".join(names[:_AUTHOR_KEEP]) + ", et al."
|
||||
return ", ".join(names)
|
||||
|
||||
|
||||
def _name(person: ReferenceAuthor) -> str:
|
||||
"""One contributor as ``Family, I.N.``
|
||||
|
||||
The halves are the authority for rewriting a name and the whole ``name`` is
|
||||
the authority for printing it, as the model says. So a row with Latin halves
|
||||
is inverted and initialised — some of them arrive already abbreviated
|
||||
(``Lai KK`` → ``Lai, K.K.``) — while a row without them is printed exactly as
|
||||
stored, which is the only correct thing to do for an institutional author
|
||||
(「世界卫生组织」, "World Health Organization") and for a CJK name whose
|
||||
romanisation the library was never told.
|
||||
|
||||
A CJK name keeps its printed form even *with* halves filled in. ``张`` +
|
||||
``三`` inverted and dotted gives 「张, 三.」, which is neither Chinese nor
|
||||
English: an initial is a Latin-script idea, and 「三」 is not the initial of
|
||||
a given name, it is the whole of it. Springer's own ``Zhang, S.`` needs a
|
||||
romanisation this library does not hold, so the stored 「张三」 is printed
|
||||
rather than turned into something that is wrong in both languages.
|
||||
"""
|
||||
family = _clean(person.family_name)
|
||||
given = _clean(person.given_name)
|
||||
if not family or _CJK.search(family) or _CJK.search(given):
|
||||
return _clean(person.name)
|
||||
initials = _initials(given)
|
||||
return f"{family}, {initials}" if initials else family
|
||||
|
||||
|
||||
def _initials(given: str) -> str:
|
||||
"""``Yong Ming`` → ``Y.M.``, ``AL`` → ``A.L.``, ``Jean-Luc`` → ``J.-L.``"""
|
||||
if not given:
|
||||
return ""
|
||||
|
||||
initials: list[str] = []
|
||||
for token in given.split():
|
||||
parts = [part for part in re.split(r"[-–]", token) if part]
|
||||
if len(parts) > 1:
|
||||
initials.append("-".join(_initial(part) for part in parts))
|
||||
else:
|
||||
initials.append(_initial(token))
|
||||
return "".join(part for part in initials if part)
|
||||
|
||||
|
||||
def _initial(token: str) -> str:
|
||||
"""One given-name token as initials.
|
||||
|
||||
A token that is already a block of initials is expanded letter by letter —
|
||||
``KK`` is two names, not one — and a token that is a name contributes its
|
||||
first letter.
|
||||
"""
|
||||
letters = [character for character in token if character.isalpha()]
|
||||
if not letters:
|
||||
return ""
|
||||
if len(letters) > 1 and token.isupper():
|
||||
return "".join(f"{character.upper()}." for character in letters)
|
||||
return f"{letters[0].upper()}."
|
||||
|
||||
|
||||
# --- where the entry sits ----------------------------------------------------
|
||||
|
||||
|
||||
def _where(reference: Reference) -> list[str]:
|
||||
"""The clauses between the title and the identifier, by document type."""
|
||||
builder: Callable[[Reference], list[str]] = _WHERE.get(
|
||||
reference.type, _where_generic
|
||||
)
|
||||
return builder(reference)
|
||||
|
||||
|
||||
def _where_journal(reference: Reference) -> list[str]:
|
||||
"""``J. Sci. Commun. 163(2), 51–59 (2010)``"""
|
||||
source = _join_space(_container(reference), _volume_issue(reference))
|
||||
source = _join_comma(source, _pages(reference))
|
||||
return [_with_year(source, reference)]
|
||||
|
||||
|
||||
def _where_newspaper(reference: Reference) -> list[str]:
|
||||
"""``The Times, p. 12 (2020)`` — a newspaper has a date, not a volume."""
|
||||
source = _join_comma(_container(reference), _pages(reference))
|
||||
return [_with_year(source, reference)]
|
||||
|
||||
|
||||
def _where_book(reference: Reference) -> list[str]:
|
||||
"""``Longman, New York (2000)``, with the series ahead of it."""
|
||||
clauses = []
|
||||
series = _join_comma(_clean(reference.series_title), _clean(reference.series_number))
|
||||
if series:
|
||||
clauses.append(series)
|
||||
place = _join_comma(_clean(reference.publisher), _clean(reference.publisher_place))
|
||||
clauses.append(_with_year(place, reference))
|
||||
return [clause for clause in clauses if clause]
|
||||
|
||||
|
||||
def _where_chapter(reference: Reference) -> list[str]:
|
||||
"""``In: Jones, B.S. (ed.) Book title, pp. 281–304. E-Publishing Inc., New York (2009)``"""
|
||||
inside = _container(reference)
|
||||
if inside and _clean(reference.edition):
|
||||
inside = f"{inside}, {_clean(reference.edition)}"
|
||||
pages = _pages(reference)
|
||||
if pages:
|
||||
inside = _join_comma(inside, f"pp. {pages}")
|
||||
|
||||
editors = _editor_names(reference)
|
||||
inside = _join_space(editors, inside) if editors else inside
|
||||
opening = f"In: {inside}" if inside else ""
|
||||
|
||||
place = _with_year(
|
||||
_join_comma(_clean(reference.publisher), _clean(reference.publisher_place)),
|
||||
reference,
|
||||
)
|
||||
return [clause for clause in (opening, place) if clause]
|
||||
|
||||
|
||||
def _where_conference(reference: Reference) -> list[str]:
|
||||
"""``In: Proceedings of …, pp. 10–20. Springer, Cham (2022)``"""
|
||||
inside = _container(reference) or _clean(reference.event_title)
|
||||
pages = _pages(reference)
|
||||
if pages:
|
||||
inside = _join_comma(inside, f"pp. {pages}")
|
||||
opening = f"In: {inside}" if inside else ""
|
||||
|
||||
place = _with_year(
|
||||
_join_comma(
|
||||
_clean(reference.publisher),
|
||||
_clean(reference.publisher_place) or _clean(reference.event_place),
|
||||
),
|
||||
reference,
|
||||
)
|
||||
return [clause for clause in (opening, place) if clause]
|
||||
|
||||
|
||||
def _where_thesis(reference: Reference) -> list[str]:
|
||||
"""``Thesis, 清华大学 (2020)``
|
||||
|
||||
The degree (PhD, 硕士) is not a field of this library, so the entry says
|
||||
what it knows rather than inventing a doctorate.
|
||||
"""
|
||||
return [_with_year(_join_comma("Thesis", _clean(reference.publisher)), reference)]
|
||||
|
||||
|
||||
def _where_patent(reference: Reference) -> list[str]:
|
||||
"""``中国 Patent CN114000000A (2023)`` — the country and number inside the mark."""
|
||||
mark = _join_space(_clean(reference.patent_country), "Patent")
|
||||
marked = _join_space(mark, _clean(reference.patent_number))
|
||||
return [_with_year(marked, reference)]
|
||||
|
||||
|
||||
def _where_standard(reference: Reference) -> list[str]:
|
||||
"""``GB/T 7714-2015. 中国标准出版社, 北京 (2015)``
|
||||
|
||||
The number follows the title rather than leading the entry: the title is
|
||||
what the writer searched by and what the reader recognises.
|
||||
"""
|
||||
number = _clean(reference.standard_number)
|
||||
place = _with_year(
|
||||
_join_comma(_clean(reference.publisher), _clean(reference.publisher_place)),
|
||||
reference,
|
||||
)
|
||||
return [clause for clause in (number, place) if clause]
|
||||
|
||||
|
||||
def _where_report(reference: Reference) -> list[str]:
|
||||
"""``NREL/TP-5000-12345, NREL, Golden (2012)``"""
|
||||
clause = _join_comma(
|
||||
_clean(reference.report_number),
|
||||
_clean(reference.publisher),
|
||||
_clean(reference.publisher_place),
|
||||
)
|
||||
return [_with_year(clause, reference)]
|
||||
|
||||
|
||||
def _where_web(reference: Reference) -> list[str]:
|
||||
"""``https://… (2021)`` — for a page the URL is where the entry sits."""
|
||||
return [_with_year(_clean(reference.url), reference)]
|
||||
|
||||
|
||||
def _where_dataset(reference: Reference) -> list[str]:
|
||||
"""``Dataset (2024)`` — the type stands where a journal name would."""
|
||||
return [_with_year("Dataset", reference)]
|
||||
|
||||
|
||||
def _where_software(reference: Reference) -> list[str]:
|
||||
"""``Software (2024)``"""
|
||||
return [_with_year("Software", reference)]
|
||||
|
||||
|
||||
def _where_preprint(reference: Reference) -> list[str]:
|
||||
"""``Preprint arXiv:2405.12345 (2024)`` — how a paper is cited before a DOI."""
|
||||
return [_with_year(_join_space("Preprint", _clean(reference.arxiv_id)), reference)]
|
||||
|
||||
|
||||
def _where_generic(reference: Reference) -> list[str]:
|
||||
"""Anything typed ``other``: the container, then the publisher.
|
||||
|
||||
The year closes whichever of the two is the last thing printed, so it never
|
||||
dangles on its own in the middle of an entry.
|
||||
"""
|
||||
source = _join_comma(_container(reference), _pages(reference))
|
||||
place = _join_comma(_clean(reference.publisher), _clean(reference.publisher_place))
|
||||
if place:
|
||||
return [clause for clause in (source, _with_year(place, reference)) if clause]
|
||||
return [_with_year(source, reference)]
|
||||
|
||||
|
||||
_WHERE: dict[str, Callable[[Reference], list[str]]] = {
|
||||
"journal-article": _where_journal,
|
||||
"newspaper-article": _where_newspaper,
|
||||
"book": _where_book,
|
||||
"book-chapter": _where_chapter,
|
||||
"conference-paper": _where_conference,
|
||||
"thesis": _where_thesis,
|
||||
"patent": _where_patent,
|
||||
"standard": _where_standard,
|
||||
"report": _where_report,
|
||||
"web-page": _where_web,
|
||||
"dataset": _where_dataset,
|
||||
"software": _where_software,
|
||||
"preprint": _where_preprint,
|
||||
}
|
||||
|
||||
|
||||
# --- the identifier, and the day it was read ---------------------------------
|
||||
|
||||
|
||||
def _identifier(reference: Reference) -> str:
|
||||
"""``https://doi.org/10.1016/j.Sc.2010.00372``, or the URL, or nothing.
|
||||
|
||||
A DOI is printed as the resolvable link, which is how Springer prints it —
|
||||
the column stores it bare so the two spellings cannot drift.
|
||||
"""
|
||||
doi = _clean(reference.doi)
|
||||
if doi:
|
||||
return f"https://doi.org/{doi}"
|
||||
if reference.type in _URL_IS_THE_SOURCE:
|
||||
return ""
|
||||
return _clean(reference.url)
|
||||
|
||||
|
||||
def _accessed(reference: Reference) -> str:
|
||||
"""``Accessed 12 May 2021`` — the day an online resource was read."""
|
||||
if reference.accessed_date is None:
|
||||
return ""
|
||||
return f"Accessed {_long_date(reference.accessed_date)}"
|
||||
|
||||
|
||||
def _long_date(value: date) -> str:
|
||||
return f"{value.day} {_MONTHS[value.month - 1]} {value.year}"
|
||||
|
||||
|
||||
# --- what a complete entry is still missing ----------------------------------
|
||||
|
||||
|
||||
#: The fields a complete entry needs, per type. ``None`` means "this type has no
|
||||
#: such field", so the list is not padded with requirements that do not apply.
|
||||
_REQUIRED: dict[str, tuple[str, ...]] = {
|
||||
"journal-article": ("责任者", "刊名", "卷期页码", "出版年"),
|
||||
"newspaper-article": ("责任者", "报纸名", "页码", "出版年"),
|
||||
"book": ("责任者", "出版者", "出版年"),
|
||||
"book-chapter": ("责任者", "书名", "页码", "出版者", "出版年"),
|
||||
"conference-paper": ("责任者", "会议名", "出版年"),
|
||||
"thesis": ("责任者", "培养单位", "出版年"),
|
||||
"patent": ("责任者", "专利号", "出版年"),
|
||||
"standard": ("标准编号", "出版年"),
|
||||
"report": ("责任者", "报告编号", "出版年"),
|
||||
"web-page": ("URL", "引用日期"),
|
||||
"dataset": ("URL", "出版年"),
|
||||
"software": ("URL", "出版年"),
|
||||
"preprint": ("责任者", "出版年"),
|
||||
"other": ("责任者", "出版年"),
|
||||
}
|
||||
|
||||
|
||||
def missing_fields(reference: Reference) -> list[str]:
|
||||
"""Which parts of a complete entry this reference still lacks, in Chinese.
|
||||
|
||||
The point is that a gap should be *reported* rather than quietly rendered as
|
||||
a shorter entry: an entry with no author and no year looks like a fact about
|
||||
the document instead of a field nobody filled in.
|
||||
"""
|
||||
missing: list[str] = []
|
||||
for field in _REQUIRED.get(reference.type, _REQUIRED["other"]):
|
||||
if not _has(reference, field):
|
||||
missing.append(field)
|
||||
return missing
|
||||
|
||||
|
||||
def _has(reference: Reference, field: str) -> bool:
|
||||
"""Whether the field this label names is filled in."""
|
||||
if field == "责任者":
|
||||
return bool(reference.authors)
|
||||
if field == "刊名" or field == "报纸名" or field == "会议名" or field == "书名":
|
||||
# A chapter's 书名 and a paper's 论文集名 are both the container; a
|
||||
# conference may carry its meeting name instead.
|
||||
return bool(
|
||||
_clean(reference.container_title)
|
||||
or (field == "会议名" and _clean(reference.event_title))
|
||||
)
|
||||
if field == "卷期页码":
|
||||
return bool(
|
||||
_clean(reference.volume)
|
||||
or _clean(reference.issue)
|
||||
or _clean(reference.pages)
|
||||
or _clean(reference.article_number)
|
||||
)
|
||||
if field == "页码":
|
||||
return bool(_clean(reference.pages) or _clean(reference.article_number))
|
||||
if field == "出版者" or field == "培养单位":
|
||||
return bool(_clean(reference.publisher))
|
||||
if field == "标准编号":
|
||||
return bool(_clean(reference.standard_number))
|
||||
if field == "报告编号":
|
||||
return bool(_clean(reference.report_number) or _clean(reference.publisher))
|
||||
if field == "专利号":
|
||||
return bool(_clean(reference.patent_number))
|
||||
if field == "URL":
|
||||
return bool(_clean(reference.url) or _clean(reference.doi))
|
||||
if field == "引用日期":
|
||||
return reference.accessed_date is not None
|
||||
if field == "出版年":
|
||||
return reference.publication_year is not None
|
||||
return True
|
||||
|
||||
|
||||
# --- small helpers -----------------------------------------------------------
|
||||
|
||||
|
||||
def _clean(value: str | None) -> str:
|
||||
"""Whitespace folded, or ``""`` — so a blank field is simply absent."""
|
||||
if value is None:
|
||||
return ""
|
||||
return " ".join(value.split())
|
||||
|
||||
|
||||
def _container(reference: Reference) -> str:
|
||||
"""The journal or book the entry sits in.
|
||||
|
||||
The abbreviation wins when the writer stored one: Springer abbreviates
|
||||
journal titles, and an algorithm cannot abbreviate an arbitrary title
|
||||
correctly, so the 刊名缩写 column is where a human decides it.
|
||||
"""
|
||||
return _clean(reference.container_title_short) or _clean(reference.container_title)
|
||||
|
||||
|
||||
def _volume_issue(reference: Reference) -> str:
|
||||
"""``163(2)``, ``163``, ``(2)`` or nothing."""
|
||||
volume = _clean(reference.volume)
|
||||
issue = _clean(reference.issue)
|
||||
if volume and issue:
|
||||
return f"{volume}({issue})"
|
||||
return volume or (f"({issue})" if issue else "")
|
||||
|
||||
|
||||
def _pages(reference: Reference) -> str:
|
||||
"""``51–59`` with an en dash, or the article number when there is no page."""
|
||||
pages = _clean(reference.pages)
|
||||
if pages:
|
||||
return _PAGE_RANGE.sub(lambda match: f"{match.group(1)}–{match.group(2)}", pages)
|
||||
return _clean(reference.article_number)
|
||||
|
||||
|
||||
def _with_year(clause: str, reference: Reference) -> str:
|
||||
"""``Journal 163(2), 51–59 (2010)`` — the year closes the clause it follows."""
|
||||
if reference.publication_year is None:
|
||||
return clause
|
||||
return f"{clause} ({reference.publication_year})" if clause else f"({reference.publication_year})"
|
||||
|
||||
|
||||
def _join_comma(*parts: str) -> str:
|
||||
return ", ".join(part for part in parts if part)
|
||||
|
||||
|
||||
def _join_space(*parts: str) -> str:
|
||||
return " ".join(part for part in parts if part)
|
||||
+98
-15
@@ -21,6 +21,12 @@ all three behaviours the feature needs:
|
||||
Deleting is done in Python rather than with ``ON DELETE CASCADE`` because TiDB
|
||||
parses foreign keys and then ignores them; the ORM's cascades are the only
|
||||
thing that actually removes dependent rows.
|
||||
|
||||
The 参考文献 list is assembled in the same pass, and by the same rule: a work is
|
||||
numbered where the reader first meets it, however many times it is cited
|
||||
afterwards. The entries themselves are written by :mod:`app.citation_styles`,
|
||||
because how a reference prints is a property of a style rather than of a
|
||||
citation.
|
||||
"""
|
||||
|
||||
from collections import defaultdict
|
||||
@@ -31,6 +37,7 @@ from sqlalchemy import func, or_, select
|
||||
from sqlalchemy import update as sa_update
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.citation_styles import DEFAULT_STYLE, format_reference, missing_fields
|
||||
from app.crud import reference as reference_crud
|
||||
from app.crud.filters import LIKE_ESCAPE, like_pattern
|
||||
from app.models import (
|
||||
@@ -47,6 +54,7 @@ from app.schemas.paper import (
|
||||
PaperDocumentRead,
|
||||
PaperListItem,
|
||||
PaperRead,
|
||||
PaperReferenceRead,
|
||||
ParagraphRead,
|
||||
ParagraphUpdate,
|
||||
SentenceCreate,
|
||||
@@ -329,9 +337,71 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
|
||||
# --- 3. the union, in ascending position order --------------------------
|
||||
positions = sorted(set(placement_by_sort) | set(sentences_by_sort))
|
||||
|
||||
# --- 4. the literature the document cites, in one query -----------------
|
||||
#
|
||||
# The 参考文献 list is assembled here rather than by the client, for the same
|
||||
# reason the paragraph order is: "which work is number 7" is a rule, and two
|
||||
# implementations of a rule eventually disagree. Formatting needs the rows
|
||||
# themselves — authors, container, pages, DOI — so they are loaded up front,
|
||||
# once, with their contributors.
|
||||
cited_ids = {
|
||||
citation.reference_id
|
||||
for sentence in paper.sentences
|
||||
for citation in sentence.citations
|
||||
if citation.reference_id is not None
|
||||
}
|
||||
cited_references = {
|
||||
row.id: row for row in reference_crud.get_many(db, sorted(cited_ids))
|
||||
}
|
||||
if len(cited_references) != len(cited_ids):
|
||||
# Only reachable if a citation points at a row the library no longer has,
|
||||
# which the foreign key is there to prevent — so it is a warning rather
|
||||
# than a crash, and the entries below print as unlinked.
|
||||
warnings.append(
|
||||
f"有 {len(cited_ids) - len(cited_references)} 条引用指向的文献已不在库中,"
|
||||
"参考文献表中只保留了引用位置。"
|
||||
)
|
||||
|
||||
paragraphs: list[ParagraphRead] = []
|
||||
citations: list[PaperCitationRead] = []
|
||||
citation_index = 0
|
||||
references: list[PaperReferenceRead] = []
|
||||
|
||||
#: Work → its entry in the list above. Keyed by reference id, because that is
|
||||
#: what "the same work" means; a citation with no id at all is its own work
|
||||
#: and is keyed by its citation id so it still gets one entry and one number.
|
||||
entry_by_work: dict[object, PaperReferenceRead] = {}
|
||||
|
||||
def entry_for(citation: PaperSentenceReference) -> PaperReferenceRead:
|
||||
"""The entry this citation belongs to, numbering it on first sight.
|
||||
|
||||
Numbering on first *sight* rather than on first citation is the whole
|
||||
rule: the entries come out in the order the reader meets the works, and a
|
||||
work met again keeps the number it already had.
|
||||
"""
|
||||
key: object = (
|
||||
("reference", citation.reference_id)
|
||||
if citation.reference_id is not None
|
||||
else ("citation", citation.id)
|
||||
)
|
||||
existing = entry_by_work.get(key)
|
||||
if existing is not None:
|
||||
return existing
|
||||
|
||||
reference = (
|
||||
cited_references.get(citation.reference_id)
|
||||
if citation.reference_id is not None
|
||||
else None
|
||||
)
|
||||
entry = PaperReferenceRead(
|
||||
index=len(references) + 1,
|
||||
reference_id=citation.reference_id,
|
||||
text=format_reference(reference),
|
||||
missing=missing_fields(reference),
|
||||
citations=[],
|
||||
)
|
||||
entry_by_work[key] = entry
|
||||
references.append(entry)
|
||||
return entry
|
||||
|
||||
for position in positions:
|
||||
placement = placement_by_sort.get(position)
|
||||
@@ -363,30 +433,43 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
|
||||
sentences=sentences,
|
||||
)
|
||||
|
||||
# Citations are numbered in reading order, so a marker in the text and
|
||||
# its entry in the 参考文献 list cannot disagree.
|
||||
# Citations are numbered in reading order and by work, so a marker in the
|
||||
# text and its entry in the 参考文献 list cannot disagree.
|
||||
for sentence in sentences:
|
||||
for citation in sentence.citations:
|
||||
citation_index += 1
|
||||
citations.append(
|
||||
PaperCitationRead(
|
||||
index=citation_index,
|
||||
id=citation.id,
|
||||
reference_id=citation.reference_id,
|
||||
quote=citation.quote,
|
||||
sentence_id=sentence.id,
|
||||
sentence_content=sentence.content,
|
||||
paper_template_filed_sort=position,
|
||||
paragraph_name=paragraph.name,
|
||||
)
|
||||
entry = entry_for(citation)
|
||||
row = PaperCitationRead(
|
||||
index=entry.index,
|
||||
id=citation.id,
|
||||
reference_id=citation.reference_id,
|
||||
quote=citation.quote,
|
||||
sentence_id=sentence.id,
|
||||
sentence_content=sentence.content,
|
||||
paper_template_filed_sort=position,
|
||||
paragraph_name=paragraph.name,
|
||||
)
|
||||
citations.append(row)
|
||||
entry.citations.append(row)
|
||||
|
||||
paragraphs.append(paragraph)
|
||||
|
||||
unlinked = sum(1 for entry in references if entry.reference_id is None)
|
||||
if unlinked:
|
||||
warnings.append(
|
||||
f"有 {unlinked} 处引用还没有关联文献库条目,参考文献表中缺少它们的条目。"
|
||||
)
|
||||
|
||||
incomplete = [entry for entry in references if entry.missing]
|
||||
if incomplete:
|
||||
numbers = "、".join(f"[{entry.index}]" for entry in incomplete)
|
||||
warnings.append(f"参考文献 {numbers} 的字段不完整,条目里会缺少相应信息。")
|
||||
|
||||
return PaperDocumentRead(
|
||||
paper=read(paper),
|
||||
paragraphs=paragraphs,
|
||||
citations=citations,
|
||||
references=references,
|
||||
reference_style=DEFAULT_STYLE,
|
||||
warnings=warnings,
|
||||
)
|
||||
|
||||
|
||||
+38
-11
@@ -34,7 +34,7 @@ from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
from collections.abc import Iterator, Sequence
|
||||
from collections.abc import Iterator, Mapping, Sequence
|
||||
from contextlib import contextmanager
|
||||
from datetime import date, datetime
|
||||
from decimal import Decimal
|
||||
@@ -277,19 +277,37 @@ def paragraph_row(paragraph: ParagraphRead, *, preview: int = 80) -> dict:
|
||||
}
|
||||
|
||||
|
||||
def paragraph_text(paragraph: ParagraphRead, *, citations: bool = False) -> str:
|
||||
def paragraph_text(
|
||||
paragraph: ParagraphRead,
|
||||
*,
|
||||
citations: bool = False,
|
||||
index_by_citation: Mapping[int, int] | None = None,
|
||||
) -> str:
|
||||
"""Print one paragraph exactly as the document renders it.
|
||||
|
||||
``separator_before`` is added, not invented: the server decided what
|
||||
belongs at each seam, so a tool result and the paper view agree on where
|
||||
the spaces go. Nothing here adds spacing of its own.
|
||||
|
||||
A marker's number comes from ``index_by_citation`` — the citation's *work*
|
||||
number as the whole document assigned it, not its position in this sentence —
|
||||
so what is printed in the text matches the 参考文献 list it points at. Read
|
||||
without that map there is no document to number against, and the marker
|
||||
falls back to the citation's place in the sentence.
|
||||
"""
|
||||
parts: list[str] = []
|
||||
for sentence in paragraph.sentences:
|
||||
parts.append(sentence.separator_before + sentence.content)
|
||||
if citations and sentence.citations:
|
||||
markers = ",".join(str(index) for index in range(1, len(sentence.citations) + 1))
|
||||
parts.append(f"[{markers}]")
|
||||
numbers = [
|
||||
str(
|
||||
index_by_citation.get(citation.id, position)
|
||||
if index_by_citation is not None
|
||||
else position
|
||||
)
|
||||
for position, citation in enumerate(sentence.citations, start=1)
|
||||
]
|
||||
parts.append(f"[{','.join(numbers)}]")
|
||||
return "".join(parts)
|
||||
|
||||
|
||||
@@ -306,22 +324,31 @@ def document_text(
|
||||
three rules the paper view renders by, applied here so a single tool call
|
||||
can hand a model the finished manuscript.
|
||||
"""
|
||||
# Citation id → the number of the work it cites, so the markers printed in
|
||||
# the text are the numbers the list below uses.
|
||||
index_by_citation = {row.id: row.index for row in document.citations}
|
||||
|
||||
lines: list[str] = []
|
||||
for paragraph in document.paragraphs:
|
||||
body = paragraph_text(paragraph, citations=citations)
|
||||
body = paragraph_text(
|
||||
paragraph, citations=citations, index_by_citation=index_by_citation
|
||||
)
|
||||
if not body and not include_empty:
|
||||
continue
|
||||
lines.append(paragraph.name if paragraph.matched and paragraph.name else "未设定")
|
||||
lines.append(body)
|
||||
lines.append("")
|
||||
|
||||
if citations and document.citations:
|
||||
if citations and document.references:
|
||||
# The entries, not the quotes: a 参考文献 list is a bibliography, and the
|
||||
# one assembled above already carries each work once, numbered as the
|
||||
# text numbers it. A work whose library row is missing prints the gap
|
||||
# rather than a fabricated entry.
|
||||
lines.append("参考文献")
|
||||
for citation in document.citations:
|
||||
reference = (
|
||||
f"[{citation.reference_id}]" if citation.reference_id else ""
|
||||
)
|
||||
lines.append(f"[{citation.index}]{reference} {citation.quote}")
|
||||
for entry in document.references:
|
||||
text = entry.text or "(未关联文献库条目)"
|
||||
note = f"(缺 {'、'.join(entry.missing)})" if entry.missing else ""
|
||||
lines.append(f"[{entry.index}] {text}{note}")
|
||||
lines.append("")
|
||||
|
||||
text = "\n".join(lines).rstrip("\n")
|
||||
|
||||
@@ -14,6 +14,7 @@ from app.schemas.paper import (
|
||||
PaperDocumentRead,
|
||||
PaperListItem,
|
||||
PaperRead,
|
||||
PaperReferenceRead,
|
||||
PaperStatus,
|
||||
PaperUpdate,
|
||||
ParagraphListRead,
|
||||
@@ -75,6 +76,7 @@ __all__ = [
|
||||
"PaperDocumentRead",
|
||||
"PaperListItem",
|
||||
"PaperRead",
|
||||
"PaperReferenceRead",
|
||||
"PaperStatus",
|
||||
"PaperUpdate",
|
||||
"ParagraphListRead",
|
||||
|
||||
@@ -8,8 +8,8 @@ Three shapes of payload live here:
|
||||
reading every sentence of it and writing the whole set back, so the update
|
||||
schema is a full replacement;
|
||||
* the **document** — what the reader sees: the template's paragraphs in order,
|
||||
each carrying the sentences stored at its position, plus the flat citation
|
||||
list for the 参考文献 block.
|
||||
each carrying the sentences stored at its position, plus the 参考文献 list,
|
||||
already formatted in one citation style.
|
||||
|
||||
Text normalisation is deliberately strict, because the two sides of the wire
|
||||
have to agree on what counts as empty:
|
||||
@@ -27,6 +27,8 @@ from typing import Literal
|
||||
|
||||
from pydantic import BaseModel, ConfigDict, Field, field_validator
|
||||
|
||||
from app.citation_styles import DEFAULT_STYLE as DEFAULT_REFERENCE_STYLE
|
||||
|
||||
#: Writing states, mirroring :data:`app.models.paper.PAPER_STATUSES`. Kept as a
|
||||
#: literal so the generated OpenAPI document describes the enum for clients.
|
||||
PaperStatus = Literal["draft", "writing", "done"]
|
||||
@@ -200,11 +202,13 @@ class ParagraphRead(BaseModel):
|
||||
|
||||
|
||||
class PaperCitationRead(BaseModel):
|
||||
"""One citation as it appears in the paper's 参考文献 list.
|
||||
"""One citation — one place in the text where one work is cited.
|
||||
|
||||
``index`` is the number shown in the text as ``[index]``; it counts
|
||||
citations in reading order across the whole document, so the list and the
|
||||
markers cannot disagree.
|
||||
A citation is not a row of the 参考文献 list, and this is the difference that
|
||||
matters: a paper that cites the same article in three sentences has three
|
||||
citations and **one** entry, so ``index`` is the number of the *work* and is
|
||||
shared by all three. The in-text markers and the list therefore cannot
|
||||
disagree about what ``[7]`` means.
|
||||
"""
|
||||
|
||||
index: int
|
||||
@@ -217,6 +221,30 @@ class PaperCitationRead(BaseModel):
|
||||
paragraph_name: str | None = None
|
||||
|
||||
|
||||
class PaperReferenceRead(BaseModel):
|
||||
"""One entry of the 参考文献 list: one work, however often it is cited.
|
||||
|
||||
``text`` is the entry as it prints — the whole point of the list — and it is
|
||||
assembled by :mod:`app.citation_styles` rather than by a client, so the paper
|
||||
view, an export and an agent all print the same bibliography.
|
||||
"""
|
||||
|
||||
#: The number the text shows as ``[index]``, assigned in order of first
|
||||
#: appearance so the list reads in the order the reader meets the works.
|
||||
index: int
|
||||
#: The library row it came from, or ``None`` for a citation written before
|
||||
#: the literature was entered.
|
||||
reference_id: int | None
|
||||
#: The formatted entry, or ``""`` when there is no library row to print.
|
||||
text: str
|
||||
#: Which parts a complete entry still lacks, in Chinese — 责任者、出版年、DOI…
|
||||
#: Empty for a complete entry, and empty for an unlinked one, where the
|
||||
#: question is not what is missing but what this is.
|
||||
missing: list[str] = Field(default_factory=list)
|
||||
#: Every place it is cited, in reading order.
|
||||
citations: list[PaperCitationRead] = Field(default_factory=list)
|
||||
|
||||
|
||||
class PaperBase(BaseModel):
|
||||
"""Shared body of the paper create payload."""
|
||||
|
||||
@@ -342,8 +370,18 @@ class PaperDocumentRead(BaseModel):
|
||||
#: template or a sentence mentions appears exactly once, so an empty
|
||||
#: paragraph is still a paragraph — the structure survives with no content.
|
||||
paragraphs: list[ParagraphRead]
|
||||
#: Citations in reading order, numbered to match the in-text markers.
|
||||
#: Citations in reading order, each carrying the number of the work it cites.
|
||||
#: One row per place in the text, not per work: this is what renders the
|
||||
#: in-text markers.
|
||||
citations: list[PaperCitationRead]
|
||||
#: The 参考文献 list: one entry per work, numbered in order of first
|
||||
#: appearance, already formatted. A client prints these and does not group,
|
||||
#: sort or assemble them — two implementations of the same rules would
|
||||
#: eventually print two different bibliographies.
|
||||
references: list[PaperReferenceRead] = Field(default_factory=list)
|
||||
#: The citation style the entries were written in, so a client can name it
|
||||
#: without hard-coding the choice (see ``app.citation_styles``).
|
||||
reference_style: str = DEFAULT_REFERENCE_STYLE
|
||||
#: Anything the reader should be told about the document as a whole, e.g.
|
||||
#: a template that places two fields at the same position.
|
||||
warnings: list[str] = Field(default_factory=list)
|
||||
|
||||
@@ -0,0 +1,435 @@
|
||||
"""Check the citation formatter against one reference of every type.
|
||||
|
||||
Run it with no server and no database::
|
||||
|
||||
.venv/bin/python scripts/check_citation_styles.py
|
||||
|
||||
The formatter is pure — a reference in, a printed entry out — so unlike the
|
||||
``smoke_*`` scripts this one needs nothing running. It builds a reference of each
|
||||
document type in memory, asserts the exact entry Springer's basic style calls
|
||||
for, and exits non-zero on the first entry that does not match.
|
||||
|
||||
Why it exists: the style has one branch per document type, and a branch that is
|
||||
wrong prints something that *looks* like a bibliography entry rather than
|
||||
failing loudly. A paper citing a patent would show a plausible-looking,
|
||||
incorrect line. Nineteen assertions is a cheap way to keep that from happening.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import sys
|
||||
from datetime import date
|
||||
from pathlib import Path
|
||||
|
||||
# Running this as a plain script puts scripts/ on sys.path, not backend/, so
|
||||
# `import app` would fail. Anchor to the backend directory instead.
|
||||
BACKEND_DIR = Path(__file__).resolve().parents[1]
|
||||
if str(BACKEND_DIR) not in sys.path:
|
||||
sys.path.insert(0, str(BACKEND_DIR))
|
||||
|
||||
from app.citation_styles import ( # noqa: E402
|
||||
DEFAULT_STYLE,
|
||||
STYLES,
|
||||
format_reference,
|
||||
missing_fields,
|
||||
)
|
||||
from app.models import Reference, ReferenceAuthor # noqa: E402
|
||||
|
||||
_checks = 0
|
||||
|
||||
|
||||
def check(label: str, actual: str, expected: str) -> None:
|
||||
"""Assert one printed entry, showing both sides when it differs."""
|
||||
global _checks
|
||||
_checks += 1
|
||||
if actual != expected:
|
||||
raise AssertionError(
|
||||
f"{label}\n expected: {expected}\n actual: {actual}"
|
||||
)
|
||||
print(f" ok {label}")
|
||||
|
||||
|
||||
def author(name: str, family: str | None = None, given: str | None = None,
|
||||
role: str = "author") -> ReferenceAuthor:
|
||||
"""One contributor, built in memory — no session, no flush."""
|
||||
return ReferenceAuthor(
|
||||
name=name, family_name=family, given_name=given, role=role, sort=0
|
||||
)
|
||||
|
||||
|
||||
def reference(**fields) -> Reference:
|
||||
"""A reference with sensible filled-in defaults, overridden per case."""
|
||||
base: dict = {
|
||||
"type": "journal-article",
|
||||
"title": "题名",
|
||||
"authors": [author("Smith J", "Smith", "J")],
|
||||
}
|
||||
base.update(fields)
|
||||
authors = base.pop("authors")
|
||||
row = Reference(**base)
|
||||
row.authors = authors
|
||||
return row
|
||||
|
||||
|
||||
def main() -> int:
|
||||
print(f"style: {DEFAULT_STYLE}(可用:{'、'.join(sorted(STYLES))})")
|
||||
|
||||
print("\n1. a journal article: names, title, journal, volume(issue), pages, year, DOI")
|
||||
check(
|
||||
"journal article",
|
||||
format_reference(
|
||||
reference(
|
||||
title="The art of writing a scientific article",
|
||||
container_title="Journal of Science Communication",
|
||||
container_title_short="J. Sci. Commun.",
|
||||
volume="163",
|
||||
issue="2",
|
||||
pages="51-59",
|
||||
publication_year=2010,
|
||||
doi="10.1016/j.Sc.2010.00372",
|
||||
authors=[
|
||||
author("Van der Geer J", "Van der Geer", "J"),
|
||||
author("Hanraads JAJ", "Hanraads", "JAJ"),
|
||||
author("Lupton RA", "Lupton", "RA"),
|
||||
],
|
||||
)
|
||||
),
|
||||
"Van der Geer, J., Hanraads, J.A.J., Lupton, R.A.: The art of writing a "
|
||||
"scientific article. J. Sci. Commun. 163(2), 51–59 (2010). "
|
||||
"https://doi.org/10.1016/j.Sc.2010.00372",
|
||||
)
|
||||
|
||||
print("\n2. the abbreviation wins when the writer stored one, and a range gets an en dash")
|
||||
entry = format_reference(
|
||||
reference(
|
||||
title="A paper",
|
||||
container_title="Full Journal Name",
|
||||
container_title_short=None,
|
||||
volume="9",
|
||||
pages="1000-1010",
|
||||
publication_year=2020,
|
||||
)
|
||||
)
|
||||
check(
|
||||
"full 刊名 when there is no 缩写",
|
||||
entry,
|
||||
"Smith, J.: A paper. Full Journal Name 9, 1000–1010 (2020)",
|
||||
)
|
||||
|
||||
print("\n3. more than six contributors become three and et al.")
|
||||
check(
|
||||
"seven authors",
|
||||
format_reference(
|
||||
reference(
|
||||
title="A crowded paper",
|
||||
volume="1",
|
||||
pages="1-2",
|
||||
publication_year=2021,
|
||||
authors=[
|
||||
author(f"Family{index} A", f"Family{index}", "A")
|
||||
for index in range(1, 8)
|
||||
],
|
||||
)
|
||||
),
|
||||
"Family1, A., Family2, A., Family3, A., et al.: A crowded paper. "
|
||||
"1, 1–2 (2021)",
|
||||
)
|
||||
check(
|
||||
"six authors are all named",
|
||||
format_reference(
|
||||
reference(
|
||||
title="Six",
|
||||
publication_year=2021,
|
||||
authors=[
|
||||
author(f"Family{index} A", f"Family{index}", "A")
|
||||
for index in range(1, 7)
|
||||
],
|
||||
)
|
||||
),
|
||||
"Family1, A., Family2, A., Family3, A., Family4, A., Family5, A., "
|
||||
"Family6, A.: Six (2021)",
|
||||
)
|
||||
|
||||
print("\n4. names: initials, blocks of initials, hyphens, and no halves at all")
|
||||
check(
|
||||
"given names become initials",
|
||||
format_reference(reference(title="T", authors=[author("Yong Ming Li", "Li", "Yong Ming")], publication_year=2020)),
|
||||
"Li, Y.M.: T (2020)",
|
||||
)
|
||||
check(
|
||||
"a block of initials is expanded letter by letter",
|
||||
format_reference(reference(title="T", authors=[author("Lai KK", "Lai", "KK")], publication_year=2020)),
|
||||
"Lai, K.K.: T (2020)",
|
||||
)
|
||||
check(
|
||||
"a hyphenated given name keeps its hyphen",
|
||||
format_reference(reference(title="T", authors=[author("Dupont JL", "Dupont", "Jean-Luc")], publication_year=2020)),
|
||||
"Dupont, J.-L.: T (2020)",
|
||||
)
|
||||
check(
|
||||
"an institutional author is printed as stored",
|
||||
format_reference(reference(title="T", authors=[author("世界卫生组织")], publication_year=2020)),
|
||||
"世界卫生组织: T (2020)",
|
||||
)
|
||||
check(
|
||||
"a CJK name with no halves is not romanised by guesswork",
|
||||
format_reference(reference(title="T", authors=[author("张三")], publication_year=2020)),
|
||||
"张三: T (2020)",
|
||||
)
|
||||
check(
|
||||
"a CJK name keeps its printed form even with halves filled in",
|
||||
format_reference(
|
||||
reference(
|
||||
title="T",
|
||||
authors=[author("张三", "张", "三")],
|
||||
publication_year=2020,
|
||||
)
|
||||
),
|
||||
"张三: T (2020)",
|
||||
)
|
||||
check(
|
||||
"editors of a book are marked (ed.)",
|
||||
format_reference(
|
||||
reference(
|
||||
type="book",
|
||||
title="Edited volume",
|
||||
publisher="Springer",
|
||||
publisher_place="Cham",
|
||||
publication_year=2021,
|
||||
authors=[author("Jones BS", "Jones", "BS", role="editor")],
|
||||
)
|
||||
),
|
||||
"Jones, B.S. (ed.): Edited volume. Springer, Cham (2021)",
|
||||
)
|
||||
|
||||
print("\n5. every other document type")
|
||||
check(
|
||||
"book with an edition and a series",
|
||||
format_reference(
|
||||
reference(
|
||||
type="book",
|
||||
title="The Elements of Style",
|
||||
edition="4th edn",
|
||||
series_title="Style Guides",
|
||||
series_number="7",
|
||||
publisher="Longman",
|
||||
publisher_place="New York",
|
||||
publication_year=2000,
|
||||
authors=[author("Strunk W", "Strunk", "W")],
|
||||
)
|
||||
),
|
||||
"Strunk, W.: The Elements of Style, 4th edn. Style Guides, 7. "
|
||||
"Longman, New York (2000)",
|
||||
)
|
||||
check(
|
||||
"book chapter, with the book's editors marked",
|
||||
format_reference(
|
||||
reference(
|
||||
type="book-chapter",
|
||||
title="How to prepare an electronic version of your article",
|
||||
container_title="Introduction to the Electronic Age",
|
||||
pages="281-304",
|
||||
publisher="E-Publishing Inc.",
|
||||
publisher_place="New York",
|
||||
publication_year=2009,
|
||||
authors=[
|
||||
author("Mettam GR", "Mettam", "GR"),
|
||||
author("Adams LB", "Adams", "LB"),
|
||||
author("Jones BS", "Jones", "BS", role="editor"),
|
||||
],
|
||||
)
|
||||
),
|
||||
"Mettam, G.R., Adams, L.B.: How to prepare an electronic version of your "
|
||||
"article. In: Jones, B.S. (ed.) Introduction to the Electronic Age, "
|
||||
"pp. 281–304. E-Publishing Inc., New York (2009)",
|
||||
)
|
||||
check(
|
||||
"conference paper",
|
||||
format_reference(
|
||||
reference(
|
||||
type="conference-paper",
|
||||
title="Crowdsourcing in the tourism industry",
|
||||
container_title="Proceedings of the 3rd International Conference on Tourism",
|
||||
pages="1-10",
|
||||
publisher="Springer",
|
||||
publisher_place="Cham",
|
||||
publication_year=2019,
|
||||
authors=[author("Garrigos-Simon FJ", "Garrigos-Simon", "FJ")],
|
||||
)
|
||||
),
|
||||
"Garrigos-Simon, F.J.: Crowdsourcing in the tourism industry. In: "
|
||||
"Proceedings of the 3rd International Conference on Tourism, pp. 1–10. "
|
||||
"Springer, Cham (2019)",
|
||||
)
|
||||
check(
|
||||
"conference paper that only knows its meeting",
|
||||
format_reference(
|
||||
reference(
|
||||
type="conference-paper",
|
||||
title="A meeting paper",
|
||||
event_title="第 20 届管理学年会",
|
||||
event_place="北京",
|
||||
publication_year=2022,
|
||||
)
|
||||
),
|
||||
"Smith, J.: A meeting paper. In: 第 20 届管理学年会. 北京 (2022)",
|
||||
)
|
||||
check(
|
||||
"thesis",
|
||||
format_reference(
|
||||
reference(
|
||||
type="thesis",
|
||||
title="A dissertation",
|
||||
publisher="清华大学",
|
||||
publisher_place="北京",
|
||||
publication_year=2020,
|
||||
)
|
||||
),
|
||||
"Smith, J.: A dissertation. Thesis, 清华大学 (2020)",
|
||||
)
|
||||
check(
|
||||
"patent",
|
||||
format_reference(
|
||||
reference(
|
||||
type="patent",
|
||||
title="一种基于多层聚类的技术识别方法",
|
||||
patent_country="中国",
|
||||
patent_number="CN114000000A",
|
||||
publication_year=2023,
|
||||
)
|
||||
),
|
||||
"Smith, J.: 一种基于多层聚类的技术识别方法. 中国 Patent CN114000000A (2023)",
|
||||
)
|
||||
check(
|
||||
"standard",
|
||||
format_reference(
|
||||
reference(
|
||||
type="standard",
|
||||
title="信息与文献 参考文献著录规则",
|
||||
standard_number="GB/T 7714-2015",
|
||||
publisher="中国标准出版社",
|
||||
publisher_place="北京",
|
||||
publication_year=2015,
|
||||
authors=[],
|
||||
)
|
||||
),
|
||||
"信息与文献 参考文献著录规则. GB/T 7714-2015. 中国标准出版社, 北京 (2015)",
|
||||
)
|
||||
check(
|
||||
"report",
|
||||
format_reference(
|
||||
reference(
|
||||
type="report",
|
||||
title="Annual technology review",
|
||||
report_number="NREL/TP-5000-12345",
|
||||
publisher="NREL",
|
||||
publisher_place="Golden",
|
||||
publication_year=2012,
|
||||
)
|
||||
),
|
||||
"Smith, J.: Annual technology review. NREL/TP-5000-12345, NREL, Golden (2012)",
|
||||
)
|
||||
check(
|
||||
"web page, with the day it was read",
|
||||
format_reference(
|
||||
reference(
|
||||
type="web-page",
|
||||
title="Cancer statistics for the UK",
|
||||
url="https://www.cancerresearchuk.org/health-professional/cancer-statistics",
|
||||
publication_year=2021,
|
||||
accessed_date=date(2021, 5, 12),
|
||||
authors=[author("Cancer Research UK")],
|
||||
)
|
||||
),
|
||||
"Cancer Research UK: Cancer statistics for the UK. "
|
||||
"https://www.cancerresearchuk.org/health-professional/cancer-statistics "
|
||||
"(2021). Accessed 12 May 2021",
|
||||
)
|
||||
check(
|
||||
"dataset",
|
||||
format_reference(
|
||||
reference(
|
||||
type="dataset",
|
||||
title="Patent citation network",
|
||||
url="https://doi.org/10.6084/m9.figshare.1234567",
|
||||
publication_year=2024,
|
||||
)
|
||||
),
|
||||
"Smith, J.: Patent citation network. Dataset (2024). "
|
||||
"https://doi.org/10.6084/m9.figshare.1234567",
|
||||
)
|
||||
check(
|
||||
"preprint, which has no DOI yet",
|
||||
format_reference(
|
||||
reference(
|
||||
type="preprint",
|
||||
title="A preprint",
|
||||
arxiv_id="arXiv:2405.12345",
|
||||
publication_year=2024,
|
||||
)
|
||||
),
|
||||
"Smith, J.: A preprint. Preprint arXiv:2405.12345 (2024)",
|
||||
)
|
||||
check(
|
||||
"newspaper article",
|
||||
format_reference(
|
||||
reference(
|
||||
type="newspaper-article",
|
||||
title="A news story",
|
||||
container_title="The Times",
|
||||
pages="12",
|
||||
publication_year=2020,
|
||||
)
|
||||
),
|
||||
"Smith, J.: A news story. The Times, 12 (2020)",
|
||||
)
|
||||
check(
|
||||
"a subtitle rejoins its title",
|
||||
format_reference(
|
||||
reference(
|
||||
title="技术惯性与冲量的耦合机制",
|
||||
subtitle="基于科学与技术融合网络的实证分析",
|
||||
volume="198",
|
||||
pages="122-141",
|
||||
publication_year=2024,
|
||||
)
|
||||
),
|
||||
"Smith, J.: 技术惯性与冲量的耦合机制: 基于科学与技术融合网络的实证分析. "
|
||||
"198, 122–141 (2024)",
|
||||
)
|
||||
|
||||
print("\n6. a gap is reported, not papered over")
|
||||
check(
|
||||
"an entry with no year prints no invented year",
|
||||
format_reference(reference(title="No year", volume="1", pages="1-2")),
|
||||
"Smith, J.: No year. 1, 1–2",
|
||||
)
|
||||
missing = missing_fields(
|
||||
reference(title="No year", volume=None, pages=None, container_title=None)
|
||||
)
|
||||
check("the missing fields are named in Chinese", "、".join(missing), "刊名、卷期页码、出版年")
|
||||
check(
|
||||
"a complete entry reports nothing missing",
|
||||
"、".join(missing_fields(reference(
|
||||
title="Complete",
|
||||
container_title="A Journal",
|
||||
volume="1",
|
||||
pages="1-2",
|
||||
publication_year=2020,
|
||||
))),
|
||||
"",
|
||||
)
|
||||
check(
|
||||
"a web page without a URL is told so, in the style's own terms",
|
||||
"、".join(missing_fields(reference(
|
||||
type="web-page", title="No address", url=None, doi=None, accessed_date=None
|
||||
))),
|
||||
"URL、引用日期",
|
||||
)
|
||||
|
||||
print(f"\nall {_checks} checks passed")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -165,13 +165,36 @@ def main() -> int:
|
||||
check("citations numbered", [c["sort"] for c in paragraph["sentences"][1]["citations"]] == [1, 2])
|
||||
check("three citations in the paper", len(document["citations"]) == 3)
|
||||
check(
|
||||
"citation index is reading order",
|
||||
[c["index"] for c in document["citations"]] == [1, 2, 3],
|
||||
"a citation carries the number of its work, not of itself",
|
||||
[c["index"] for c in document["citations"]] == [1, 1, 2],
|
||||
str([c["index"] for c in document["citations"]]),
|
||||
)
|
||||
|
||||
print("5. the 参考文献 list: one entry per work, in Springer's basic style")
|
||||
check(
|
||||
"two works — the article cited twice, and the unlinked quote",
|
||||
len(document["references"]) == 2,
|
||||
str(len(document["references"])),
|
||||
)
|
||||
first, second = document["references"]
|
||||
check("both places that cite the article share its entry", len(first["citations"]) == 2)
|
||||
check(
|
||||
"the entry is a bibliography line, not the quote",
|
||||
first["text"]
|
||||
== "测试作者: 用于验证引用链路的文献. 测试期刊 (2024)",
|
||||
first["text"],
|
||||
)
|
||||
check(
|
||||
"what a complete entry still lacks is named",
|
||||
first["missing"] == ["卷期页码"],
|
||||
str(first["missing"]),
|
||||
)
|
||||
check("the unlinked quote is its own entry", second["reference_id"] is None)
|
||||
check("and prints no fabricated entry", second["text"] == "", second["text"])
|
||||
check("the style is reported", document["reference_style"] == "springer", document["reference_style"])
|
||||
check("sentence template stamped", paragraph["sentences"][0]["template_id"] == wide["id"])
|
||||
|
||||
print("5. explicit sorts decide the order, not the order they were sent")
|
||||
print("6. explicit sorts decide the order, not the order they were sent")
|
||||
second_sort = document["paragraphs"][1]["paper_template_filed_sort"]
|
||||
reordered = call(
|
||||
"PUT",
|
||||
@@ -202,7 +225,7 @@ def main() -> int:
|
||||
{"sentences": []},
|
||||
)
|
||||
|
||||
print("6. the seam between sentences depends on the language")
|
||||
print("7. the seam between sentences depends on the language")
|
||||
# Chinese needs nothing after 。; English needs a space, or two
|
||||
# sentences print as `First.Second.`
|
||||
mixed = call(
|
||||
@@ -244,7 +267,7 @@ def main() -> int:
|
||||
# Clear it again so the counts asserted below stay meaningful.
|
||||
call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []})
|
||||
|
||||
print("7. reject a citation with no quote")
|
||||
print("8. reject a citation with no quote")
|
||||
bad = call(
|
||||
"PUT",
|
||||
f"/papers/{paper['id']}/paragraphs/{first_sort}",
|
||||
@@ -262,7 +285,7 @@ def main() -> int:
|
||||
)
|
||||
check("citation without content refused", "detail" in bad)
|
||||
|
||||
print("8. a sentence with no paragraph in the template survives a switch")
|
||||
print("9. a sentence with no paragraph in the template survives a switch")
|
||||
# A position neither template defines, so the check means the same
|
||||
# thing before and after the switch below.
|
||||
orphan_sort = (
|
||||
@@ -290,7 +313,7 @@ def main() -> int:
|
||||
p for p in document["paragraphs"] if p["paper_template_filed_sort"] == orphan_sort
|
||||
)["name"] is None)
|
||||
|
||||
print("9. switch the template")
|
||||
print("10. switch the template")
|
||||
switched = call("PATCH", f"/papers/{paper['id']}", {"template_id": narrow["id"]})
|
||||
check("template changed", switched["template_id"] == narrow["id"])
|
||||
document = call("GET", f"/papers/{paper['id']}/document")
|
||||
@@ -320,7 +343,7 @@ def main() -> int:
|
||||
),
|
||||
)
|
||||
|
||||
print("10. move one paragraph onto another position")
|
||||
print("11. move one paragraph onto another position")
|
||||
document = call(
|
||||
"PUT",
|
||||
f"/papers/{paper['id']}/paragraphs/{orphan_sort}",
|
||||
@@ -335,18 +358,18 @@ def main() -> int:
|
||||
all(p["paper_template_filed_sort"] != orphan_sort for p in document["paragraphs"]),
|
||||
)
|
||||
|
||||
print("11. paper list reports progress")
|
||||
print("12. paper list reports progress")
|
||||
listing = call("GET", f"/papers?keyword=冒烟&status=writing")
|
||||
check("found by keyword and status", listing["total"] == 1, str(listing["total"]))
|
||||
row = listing["items"][0]
|
||||
check("paragraph count", row["paragraph_count"] == 1, str(row["paragraph_count"]))
|
||||
check("sentence count", row["sentence_count"] == 3, str(row["sentence_count"]))
|
||||
|
||||
print("12. a template in use cannot be deleted")
|
||||
print("13. a template in use cannot be deleted")
|
||||
conflict = call("DELETE", f"/templates/{narrow['id']}", expect=409)
|
||||
check("template delete refused", "正被论文使用" in conflict["detail"], conflict["detail"])
|
||||
|
||||
print("13. single sentence edit and delete")
|
||||
print("14. single sentence edit and delete")
|
||||
sentence_id = target["sentences"][0]["id"]
|
||||
updated = call(
|
||||
"PATCH",
|
||||
@@ -362,7 +385,7 @@ def main() -> int:
|
||||
sum(len(p["sentences"]) for p in document["paragraphs"]) == 2,
|
||||
)
|
||||
|
||||
print("14. a paper with no template still works")
|
||||
print("15. a paper with no template still works")
|
||||
bare = call(
|
||||
"POST",
|
||||
"/papers",
|
||||
@@ -385,7 +408,7 @@ def main() -> int:
|
||||
call("DELETE", f"/papers/{bare['id']}", expect=204)
|
||||
created_papers.remove(bare["id"])
|
||||
|
||||
print("15. delete the paper")
|
||||
print("16. delete the paper")
|
||||
call("DELETE", f"/papers/{paper['id']}", expect=204)
|
||||
created_papers.clear()
|
||||
for reference_id in created_references:
|
||||
|
||||
Reference in New Issue
Block a user