Compare commits
4 Commits
15955f552d
...
b97aab6f30
| Author | SHA1 | Date | |
|---|---|---|---|
| b97aab6f30 | |||
| 340e0777ce | |||
| 54292eb231 | |||
| 76708ce767 |
@@ -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
|
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
|
parses foreign keys and then ignores them; the ORM's cascades are the only
|
||||||
thing that actually removes dependent rows.
|
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
|
from collections import defaultdict
|
||||||
@@ -31,6 +37,7 @@ from sqlalchemy import func, or_, select
|
|||||||
from sqlalchemy import update as sa_update
|
from sqlalchemy import update as sa_update
|
||||||
from sqlalchemy.orm import Session
|
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 import reference as reference_crud
|
||||||
from app.crud.filters import LIKE_ESCAPE, like_pattern
|
from app.crud.filters import LIKE_ESCAPE, like_pattern
|
||||||
from app.models import (
|
from app.models import (
|
||||||
@@ -47,6 +54,7 @@ from app.schemas.paper import (
|
|||||||
PaperDocumentRead,
|
PaperDocumentRead,
|
||||||
PaperListItem,
|
PaperListItem,
|
||||||
PaperRead,
|
PaperRead,
|
||||||
|
PaperReferenceRead,
|
||||||
ParagraphRead,
|
ParagraphRead,
|
||||||
ParagraphUpdate,
|
ParagraphUpdate,
|
||||||
SentenceCreate,
|
SentenceCreate,
|
||||||
@@ -329,9 +337,71 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
|
|||||||
# --- 3. the union, in ascending position order --------------------------
|
# --- 3. the union, in ascending position order --------------------------
|
||||||
positions = sorted(set(placement_by_sort) | set(sentences_by_sort))
|
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] = []
|
paragraphs: list[ParagraphRead] = []
|
||||||
citations: list[PaperCitationRead] = []
|
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:
|
for position in positions:
|
||||||
placement = placement_by_sort.get(position)
|
placement = placement_by_sort.get(position)
|
||||||
@@ -363,30 +433,43 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
|
|||||||
sentences=sentences,
|
sentences=sentences,
|
||||||
)
|
)
|
||||||
|
|
||||||
# Citations are numbered in reading order, so a marker in the text and
|
# Citations are numbered in reading order and by work, so a marker in the
|
||||||
# its entry in the 参考文献 list cannot disagree.
|
# text and its entry in the 参考文献 list cannot disagree.
|
||||||
for sentence in sentences:
|
for sentence in sentences:
|
||||||
for citation in sentence.citations:
|
for citation in sentence.citations:
|
||||||
citation_index += 1
|
entry = entry_for(citation)
|
||||||
citations.append(
|
row = PaperCitationRead(
|
||||||
PaperCitationRead(
|
index=entry.index,
|
||||||
index=citation_index,
|
id=citation.id,
|
||||||
id=citation.id,
|
reference_id=citation.reference_id,
|
||||||
reference_id=citation.reference_id,
|
quote=citation.quote,
|
||||||
quote=citation.quote,
|
sentence_id=sentence.id,
|
||||||
sentence_id=sentence.id,
|
sentence_content=sentence.content,
|
||||||
sentence_content=sentence.content,
|
paper_template_filed_sort=position,
|
||||||
paper_template_filed_sort=position,
|
paragraph_name=paragraph.name,
|
||||||
paragraph_name=paragraph.name,
|
|
||||||
)
|
|
||||||
)
|
)
|
||||||
|
citations.append(row)
|
||||||
|
entry.citations.append(row)
|
||||||
|
|
||||||
paragraphs.append(paragraph)
|
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(
|
return PaperDocumentRead(
|
||||||
paper=read(paper),
|
paper=read(paper),
|
||||||
paragraphs=paragraphs,
|
paragraphs=paragraphs,
|
||||||
citations=citations,
|
citations=citations,
|
||||||
|
references=references,
|
||||||
|
reference_style=DEFAULT_STYLE,
|
||||||
warnings=warnings,
|
warnings=warnings,
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|||||||
+38
-11
@@ -34,7 +34,7 @@ from __future__ import annotations
|
|||||||
|
|
||||||
import json
|
import json
|
||||||
import re
|
import re
|
||||||
from collections.abc import Iterator, Sequence
|
from collections.abc import Iterator, Mapping, Sequence
|
||||||
from contextlib import contextmanager
|
from contextlib import contextmanager
|
||||||
from datetime import date, datetime
|
from datetime import date, datetime
|
||||||
from decimal import Decimal
|
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.
|
"""Print one paragraph exactly as the document renders it.
|
||||||
|
|
||||||
``separator_before`` is added, not invented: the server decided what
|
``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
|
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.
|
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] = []
|
parts: list[str] = []
|
||||||
for sentence in paragraph.sentences:
|
for sentence in paragraph.sentences:
|
||||||
parts.append(sentence.separator_before + sentence.content)
|
parts.append(sentence.separator_before + sentence.content)
|
||||||
if citations and sentence.citations:
|
if citations and sentence.citations:
|
||||||
markers = ",".join(str(index) for index in range(1, len(sentence.citations) + 1))
|
numbers = [
|
||||||
parts.append(f"[{markers}]")
|
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)
|
return "".join(parts)
|
||||||
|
|
||||||
|
|
||||||
@@ -306,22 +324,31 @@ def document_text(
|
|||||||
three rules the paper view renders by, applied here so a single tool call
|
three rules the paper view renders by, applied here so a single tool call
|
||||||
can hand a model the finished manuscript.
|
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] = []
|
lines: list[str] = []
|
||||||
for paragraph in document.paragraphs:
|
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:
|
if not body and not include_empty:
|
||||||
continue
|
continue
|
||||||
lines.append(paragraph.name if paragraph.matched and paragraph.name else "未设定")
|
lines.append(paragraph.name if paragraph.matched and paragraph.name else "未设定")
|
||||||
lines.append(body)
|
lines.append(body)
|
||||||
lines.append("")
|
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("参考文献")
|
lines.append("参考文献")
|
||||||
for citation in document.citations:
|
for entry in document.references:
|
||||||
reference = (
|
text = entry.text or "(未关联文献库条目)"
|
||||||
f"[{citation.reference_id}]" if citation.reference_id else ""
|
note = f"(缺 {'、'.join(entry.missing)})" if entry.missing else ""
|
||||||
)
|
lines.append(f"[{entry.index}] {text}{note}")
|
||||||
lines.append(f"[{citation.index}]{reference} {citation.quote}")
|
|
||||||
lines.append("")
|
lines.append("")
|
||||||
|
|
||||||
text = "\n".join(lines).rstrip("\n")
|
text = "\n".join(lines).rstrip("\n")
|
||||||
|
|||||||
@@ -14,6 +14,7 @@ from app.schemas.paper import (
|
|||||||
PaperDocumentRead,
|
PaperDocumentRead,
|
||||||
PaperListItem,
|
PaperListItem,
|
||||||
PaperRead,
|
PaperRead,
|
||||||
|
PaperReferenceRead,
|
||||||
PaperStatus,
|
PaperStatus,
|
||||||
PaperUpdate,
|
PaperUpdate,
|
||||||
ParagraphListRead,
|
ParagraphListRead,
|
||||||
@@ -75,6 +76,7 @@ __all__ = [
|
|||||||
"PaperDocumentRead",
|
"PaperDocumentRead",
|
||||||
"PaperListItem",
|
"PaperListItem",
|
||||||
"PaperRead",
|
"PaperRead",
|
||||||
|
"PaperReferenceRead",
|
||||||
"PaperStatus",
|
"PaperStatus",
|
||||||
"PaperUpdate",
|
"PaperUpdate",
|
||||||
"ParagraphListRead",
|
"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
|
reading every sentence of it and writing the whole set back, so the update
|
||||||
schema is a full replacement;
|
schema is a full replacement;
|
||||||
* the **document** — what the reader sees: the template's paragraphs in order,
|
* the **document** — what the reader sees: the template's paragraphs in order,
|
||||||
each carrying the sentences stored at its position, plus the flat citation
|
each carrying the sentences stored at its position, plus the 参考文献 list,
|
||||||
list for the 参考文献 block.
|
already formatted in one citation style.
|
||||||
|
|
||||||
Text normalisation is deliberately strict, because the two sides of the wire
|
Text normalisation is deliberately strict, because the two sides of the wire
|
||||||
have to agree on what counts as empty:
|
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 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
|
#: Writing states, mirroring :data:`app.models.paper.PAPER_STATUSES`. Kept as a
|
||||||
#: literal so the generated OpenAPI document describes the enum for clients.
|
#: literal so the generated OpenAPI document describes the enum for clients.
|
||||||
PaperStatus = Literal["draft", "writing", "done"]
|
PaperStatus = Literal["draft", "writing", "done"]
|
||||||
@@ -200,11 +202,13 @@ class ParagraphRead(BaseModel):
|
|||||||
|
|
||||||
|
|
||||||
class PaperCitationRead(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
|
A citation is not a row of the 参考文献 list, and this is the difference that
|
||||||
citations in reading order across the whole document, so the list and the
|
matters: a paper that cites the same article in three sentences has three
|
||||||
markers cannot disagree.
|
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
|
index: int
|
||||||
@@ -217,6 +221,30 @@ class PaperCitationRead(BaseModel):
|
|||||||
paragraph_name: str | None = None
|
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):
|
class PaperBase(BaseModel):
|
||||||
"""Shared body of the paper create payload."""
|
"""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
|
#: template or a sentence mentions appears exactly once, so an empty
|
||||||
#: paragraph is still a paragraph — the structure survives with no content.
|
#: paragraph is still a paragraph — the structure survives with no content.
|
||||||
paragraphs: list[ParagraphRead]
|
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]
|
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.
|
#: Anything the reader should be told about the document as a whole, e.g.
|
||||||
#: a template that places two fields at the same position.
|
#: a template that places two fields at the same position.
|
||||||
warnings: list[str] = Field(default_factory=list)
|
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("citations numbered", [c["sort"] for c in paragraph["sentences"][1]["citations"]] == [1, 2])
|
||||||
check("three citations in the paper", len(document["citations"]) == 3)
|
check("three citations in the paper", len(document["citations"]) == 3)
|
||||||
check(
|
check(
|
||||||
"citation index is reading order",
|
"a citation carries the number of its work, not of itself",
|
||||||
[c["index"] for c in document["citations"]] == [1, 2, 3],
|
[c["index"] for c in document["citations"]] == [1, 1, 2],
|
||||||
str([c["index"] for c in document["citations"]]),
|
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"])
|
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"]
|
second_sort = document["paragraphs"][1]["paper_template_filed_sort"]
|
||||||
reordered = call(
|
reordered = call(
|
||||||
"PUT",
|
"PUT",
|
||||||
@@ -202,7 +225,7 @@ def main() -> int:
|
|||||||
{"sentences": []},
|
{"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
|
# Chinese needs nothing after 。; English needs a space, or two
|
||||||
# sentences print as `First.Second.`
|
# sentences print as `First.Second.`
|
||||||
mixed = call(
|
mixed = call(
|
||||||
@@ -244,7 +267,7 @@ def main() -> int:
|
|||||||
# Clear it again so the counts asserted below stay meaningful.
|
# Clear it again so the counts asserted below stay meaningful.
|
||||||
call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []})
|
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(
|
bad = call(
|
||||||
"PUT",
|
"PUT",
|
||||||
f"/papers/{paper['id']}/paragraphs/{first_sort}",
|
f"/papers/{paper['id']}/paragraphs/{first_sort}",
|
||||||
@@ -262,7 +285,7 @@ def main() -> int:
|
|||||||
)
|
)
|
||||||
check("citation without content refused", "detail" in bad)
|
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
|
# A position neither template defines, so the check means the same
|
||||||
# thing before and after the switch below.
|
# thing before and after the switch below.
|
||||||
orphan_sort = (
|
orphan_sort = (
|
||||||
@@ -290,7 +313,7 @@ def main() -> int:
|
|||||||
p for p in document["paragraphs"] if p["paper_template_filed_sort"] == orphan_sort
|
p for p in document["paragraphs"] if p["paper_template_filed_sort"] == orphan_sort
|
||||||
)["name"] is None)
|
)["name"] is None)
|
||||||
|
|
||||||
print("9. switch the template")
|
print("10. switch the template")
|
||||||
switched = call("PATCH", f"/papers/{paper['id']}", {"template_id": narrow["id"]})
|
switched = call("PATCH", f"/papers/{paper['id']}", {"template_id": narrow["id"]})
|
||||||
check("template changed", switched["template_id"] == narrow["id"])
|
check("template changed", switched["template_id"] == narrow["id"])
|
||||||
document = call("GET", f"/papers/{paper['id']}/document")
|
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(
|
document = call(
|
||||||
"PUT",
|
"PUT",
|
||||||
f"/papers/{paper['id']}/paragraphs/{orphan_sort}",
|
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"]),
|
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")
|
listing = call("GET", f"/papers?keyword=冒烟&status=writing")
|
||||||
check("found by keyword and status", listing["total"] == 1, str(listing["total"]))
|
check("found by keyword and status", listing["total"] == 1, str(listing["total"]))
|
||||||
row = listing["items"][0]
|
row = listing["items"][0]
|
||||||
check("paragraph count", row["paragraph_count"] == 1, str(row["paragraph_count"]))
|
check("paragraph count", row["paragraph_count"] == 1, str(row["paragraph_count"]))
|
||||||
check("sentence count", row["sentence_count"] == 3, str(row["sentence_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)
|
conflict = call("DELETE", f"/templates/{narrow['id']}", expect=409)
|
||||||
check("template delete refused", "正被论文使用" in conflict["detail"], conflict["detail"])
|
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"]
|
sentence_id = target["sentences"][0]["id"]
|
||||||
updated = call(
|
updated = call(
|
||||||
"PATCH",
|
"PATCH",
|
||||||
@@ -362,7 +385,7 @@ def main() -> int:
|
|||||||
sum(len(p["sentences"]) for p in document["paragraphs"]) == 2,
|
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(
|
bare = call(
|
||||||
"POST",
|
"POST",
|
||||||
"/papers",
|
"/papers",
|
||||||
@@ -385,7 +408,7 @@ def main() -> int:
|
|||||||
call("DELETE", f"/papers/{bare['id']}", expect=204)
|
call("DELETE", f"/papers/{bare['id']}", expect=204)
|
||||||
created_papers.remove(bare["id"])
|
created_papers.remove(bare["id"])
|
||||||
|
|
||||||
print("15. delete the paper")
|
print("16. delete the paper")
|
||||||
call("DELETE", f"/papers/{paper['id']}", expect=204)
|
call("DELETE", f"/papers/{paper['id']}", expect=204)
|
||||||
created_papers.clear()
|
created_papers.clear()
|
||||||
for reference_id in created_references:
|
for reference_id in created_references:
|
||||||
|
|||||||
@@ -15,6 +15,12 @@ The order of the first two steps is the point of the tag library rather than an
|
|||||||
accident of the script: **tags are made first and applied second**. A reference
|
accident of the script: **tags are made first and applied second**. A reference
|
||||||
is created *with* tag ids, never with tag names, so a typo cannot invent a label
|
is created *with* tag ids, never with tag names, so a typo cannot invent a label
|
||||||
— which is what step 4 checks.
|
— which is what step 4 checks.
|
||||||
|
|
||||||
|
**Every entry this script creates carries a token in its title, its author and
|
||||||
|
its tag names.** The library it runs against is a real one and may hold hundreds
|
||||||
|
of entries, so "the search found one row" is only a meaningful assertion about
|
||||||
|
rows this run made. The token is what makes each count below a statement about
|
||||||
|
this run rather than about the library's size.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
@@ -24,10 +30,21 @@ import sys
|
|||||||
import urllib.error
|
import urllib.error
|
||||||
import urllib.parse
|
import urllib.parse
|
||||||
import urllib.request
|
import urllib.request
|
||||||
|
import uuid
|
||||||
from typing import Any
|
from typing import Any
|
||||||
|
|
||||||
BASE = "http://127.0.0.1:8000/api"
|
BASE = "http://127.0.0.1:8000/api"
|
||||||
|
|
||||||
|
#: Stamped into every entry this run creates, so each search below can be scoped
|
||||||
|
#: to this run instead of to an empty database. Short and uppercase: it travels
|
||||||
|
#: in titles, in an author name and in tag names, and shows up in failure output.
|
||||||
|
TOKEN = uuid.uuid4().hex[:6].upper()
|
||||||
|
|
||||||
|
#: A second token, carried by one contributor's *name* only. Titles and tag names
|
||||||
|
#: carry ``TOKEN``, so searching for it finds every row this run made; finding a
|
||||||
|
#: single row by author needs a string that is in exactly one place.
|
||||||
|
AUTHOR_TOKEN = f"AU{TOKEN}"
|
||||||
|
|
||||||
_checks = 0
|
_checks = 0
|
||||||
|
|
||||||
|
|
||||||
@@ -73,11 +90,19 @@ def main() -> int:
|
|||||||
survey = call(
|
survey = call(
|
||||||
"POST",
|
"POST",
|
||||||
"/reference-tags",
|
"/reference-tags",
|
||||||
{"name": " 综述 ", "color": "rgb(64, 158, 255)", "note": "综述性文献"},
|
{
|
||||||
|
"name": f" 综述-{TOKEN} ",
|
||||||
|
"color": "rgb(64, 158, 255)",
|
||||||
|
"note": "综述性文献",
|
||||||
|
},
|
||||||
expect=201,
|
expect=201,
|
||||||
)
|
)
|
||||||
created_tags.append(survey["id"])
|
created_tags.append(survey["id"])
|
||||||
check("a name is trimmed to one spelling", survey["name"] == "综述", survey["name"])
|
check(
|
||||||
|
"a name is trimmed to one spelling",
|
||||||
|
survey["name"] == f"综述-{TOKEN}",
|
||||||
|
survey["name"],
|
||||||
|
)
|
||||||
check(
|
check(
|
||||||
"a colour is canonicalised",
|
"a colour is canonicalised",
|
||||||
survey["color"] == "#409EFF",
|
survey["color"] == "#409EFF",
|
||||||
@@ -88,18 +113,27 @@ def main() -> int:
|
|||||||
must_read = call(
|
must_read = call(
|
||||||
"POST",
|
"POST",
|
||||||
"/reference-tags",
|
"/reference-tags",
|
||||||
{"name": "必读", "color": "#f56c6c"},
|
{"name": f"必读-{TOKEN}", "color": "#f56c6c"},
|
||||||
expect=201,
|
expect=201,
|
||||||
)
|
)
|
||||||
created_tags.append(must_read["id"])
|
created_tags.append(must_read["id"])
|
||||||
check("the second tag is stored", must_read["name"] == "必读")
|
check("the second tag is stored", must_read["name"] == f"必读-{TOKEN}")
|
||||||
|
|
||||||
print("2. a tag name is unique, and only a real colour is accepted")
|
print("2. a tag name is unique, and only a real colour is accepted")
|
||||||
duplicate = call(
|
duplicate = call(
|
||||||
"POST", "/reference-tags", {"name": "综述"}, expect=409
|
"POST", "/reference-tags", {"name": f"综述-{TOKEN}"}, expect=409
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"the refusal names the label",
|
||||||
|
TOKEN in duplicate["detail"],
|
||||||
|
duplicate["detail"],
|
||||||
|
)
|
||||||
|
call(
|
||||||
|
"POST",
|
||||||
|
"/reference-tags",
|
||||||
|
{"name": f"怪颜色-{TOKEN}", "color": "blue"},
|
||||||
|
expect=422,
|
||||||
)
|
)
|
||||||
check("the refusal names the label", "综述" in duplicate["detail"], duplicate["detail"])
|
|
||||||
call("POST", "/reference-tags", {"name": "怪颜色", "color": "blue"}, expect=422)
|
|
||||||
call("POST", "/reference-tags", {"name": " "}, expect=422)
|
call("POST", "/reference-tags", {"name": " "}, expect=422)
|
||||||
check("a blank name and a non-colour are refused", True)
|
check("a blank name and a non-colour are refused", True)
|
||||||
|
|
||||||
@@ -109,7 +143,7 @@ def main() -> int:
|
|||||||
"/references",
|
"/references",
|
||||||
{
|
{
|
||||||
"type": "journal-article",
|
"type": "journal-article",
|
||||||
"title": "技术惯性与冲量的耦合机制",
|
"title": f"技术惯性与冲量的耦合机制({TOKEN})",
|
||||||
"subtitle": "基于科学与技术融合网络的实证分析",
|
"subtitle": "基于科学与技术融合网络的实证分析",
|
||||||
"title_translated": "Coupling inertia and impulse in technology evolution",
|
"title_translated": "Coupling inertia and impulse in technology evolution",
|
||||||
"container_title": "Technological Forecasting and Social Change",
|
"container_title": "Technological Forecasting and Social Change",
|
||||||
@@ -126,7 +160,11 @@ def main() -> int:
|
|||||||
"authors": [
|
"authors": [
|
||||||
{"name": "张三", "family_name": "张", "given_name": "三"},
|
{"name": "张三", "family_name": "张", "given_name": "三"},
|
||||||
{"name": "李四"},
|
{"name": "李四"},
|
||||||
{"name": "Wang Wu", "family_name": "Wang", "given_name": "Wu"},
|
{
|
||||||
|
"name": f"Wang Wu {AUTHOR_TOKEN}",
|
||||||
|
"family_name": "Wang",
|
||||||
|
"given_name": "Wu",
|
||||||
|
},
|
||||||
{"name": "世界卫生组织", "role": "compiler"},
|
{"name": "世界卫生组织", "role": "compiler"},
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
@@ -137,7 +175,8 @@ def main() -> int:
|
|||||||
check("four contributors stored", len(article["authors"]) == 4)
|
check("four contributors stored", len(article["authors"]) == 4)
|
||||||
check(
|
check(
|
||||||
"they keep the order they were sent in",
|
"they keep the order they were sent in",
|
||||||
[a["name"] for a in article["authors"]] == ["张三", "李四", "Wang Wu", "世界卫生组织"],
|
[a["name"] for a in article["authors"]]
|
||||||
|
== ["张三", "李四", f"Wang Wu {AUTHOR_TOKEN}", "世界卫生组织"],
|
||||||
str([a["name"] for a in article["authors"]]),
|
str([a["name"] for a in article["authors"]]),
|
||||||
)
|
)
|
||||||
check(
|
check(
|
||||||
@@ -151,7 +190,8 @@ def main() -> int:
|
|||||||
check("not cited yet", article["citation_count"] == 0)
|
check("not cited yet", article["citation_count"] == 0)
|
||||||
check(
|
check(
|
||||||
"both tags are on the row",
|
"both tags are on the row",
|
||||||
sorted(tag["name"] for tag in article["tags"]) == ["必读", "综述"],
|
sorted(tag["name"] for tag in article["tags"])
|
||||||
|
== [f"必读-{TOKEN}", f"综述-{TOKEN}"],
|
||||||
str(article["tags"]),
|
str(article["tags"]),
|
||||||
)
|
)
|
||||||
|
|
||||||
@@ -159,11 +199,15 @@ def main() -> int:
|
|||||||
missing_tag = call(
|
missing_tag = call(
|
||||||
"POST",
|
"POST",
|
||||||
"/references",
|
"/references",
|
||||||
{"title": "引用了不存在的标签", "type": "book", "tag_ids": [999999]},
|
{
|
||||||
|
"title": f"引用了不存在的标签{TOKEN}",
|
||||||
|
"type": "book",
|
||||||
|
"tag_ids": [999999],
|
||||||
|
},
|
||||||
expect=400,
|
expect=400,
|
||||||
)
|
)
|
||||||
check("the refusal names the id", "999999" in missing_tag["detail"], missing_tag["detail"])
|
check("the refusal names the id", "999999" in missing_tag["detail"], missing_tag["detail"])
|
||||||
orphan = call("GET", "/references?keyword=引用了不存在的标签")
|
orphan = call("GET", f"/references?keyword=引用了不存在的标签{TOKEN}")
|
||||||
check("nothing was stored half-labelled", orphan["total"] == 0, str(orphan["total"]))
|
check("nothing was stored half-labelled", orphan["total"] == 0, str(orphan["total"]))
|
||||||
|
|
||||||
print("5. add a patent, which needs a country and a number")
|
print("5. add a patent, which needs a country and a number")
|
||||||
@@ -172,7 +216,7 @@ def main() -> int:
|
|||||||
"/references",
|
"/references",
|
||||||
{
|
{
|
||||||
"type": "patent",
|
"type": "patent",
|
||||||
"title": "一种基于多层聚类的人工智能技术识别方法",
|
"title": f"一种基于多层聚类的人工智能技术识别方法({TOKEN})",
|
||||||
"patent_country": "中国",
|
"patent_country": "中国",
|
||||||
"patent_number": "CN114000000A",
|
"patent_number": "CN114000000A",
|
||||||
"publication_year": 2023,
|
"publication_year": 2023,
|
||||||
@@ -185,7 +229,7 @@ def main() -> int:
|
|||||||
check("patent stored", patent["type"] == "patent" and patent["patent_number"] == "CN114000000A")
|
check("patent stored", patent["type"] == "patent" and patent["patent_number"] == "CN114000000A")
|
||||||
check(
|
check(
|
||||||
"tagging works on create for more than one entry",
|
"tagging works on create for more than one entry",
|
||||||
[tag["name"] for tag in patent["tags"]] == ["必读"],
|
[tag["name"] for tag in patent["tags"]] == [f"必读-{TOKEN}"],
|
||||||
str(patent["tags"]),
|
str(patent["tags"]),
|
||||||
)
|
)
|
||||||
|
|
||||||
@@ -204,28 +248,40 @@ def main() -> int:
|
|||||||
call(
|
call(
|
||||||
"POST",
|
"POST",
|
||||||
"/references",
|
"/references",
|
||||||
{"title": "没有标签的书", "authors": [{"name": "甲"}], "type": "book"},
|
{
|
||||||
|
"title": f"没有标签的书{TOKEN}",
|
||||||
|
"authors": [{"name": "甲"}],
|
||||||
|
"type": "book",
|
||||||
|
},
|
||||||
expect=201,
|
expect=201,
|
||||||
)
|
)
|
||||||
probe = call("GET", "/references?keyword=没有标签的书")
|
probe = call("GET", f"/references?keyword=没有标签的书{TOKEN}")
|
||||||
created_references.append(probe["items"][0]["id"])
|
created_references.append(probe["items"][0]["id"])
|
||||||
check("a book needs nothing else", probe["total"] == 1)
|
check("a book needs nothing else", probe["total"] == 1)
|
||||||
check("and may carry no tags at all", probe["items"][0]["tags"] == [])
|
check("and may carry no tags at all", probe["items"][0]["tags"] == [])
|
||||||
|
|
||||||
print("8. find it again: by author, by type, by year, by tag")
|
print("8. find it again: by author, by type, by year, by tag")
|
||||||
by_author = call("GET", "/references?keyword=Wang")
|
by_author = call("GET", f"/references?keyword={AUTHOR_TOKEN}")
|
||||||
check("search matches an author name", by_author["total"] == 1, str(by_author["total"]))
|
check(
|
||||||
|
"search matches an author name",
|
||||||
|
by_author["total"] == 1,
|
||||||
|
f'{by_author["total"]} (the token is on one author name)',
|
||||||
|
)
|
||||||
check(
|
check(
|
||||||
"the row prints an author line",
|
"the row prints an author line",
|
||||||
by_author["items"][0]["authors_line"].startswith("张三, 李四, Wang Wu"),
|
by_author["items"][0]["authors_line"].startswith("张三, 李四, Wang Wu"),
|
||||||
by_author["items"][0]["authors_line"],
|
by_author["items"][0]["authors_line"],
|
||||||
)
|
)
|
||||||
by_type = call("GET", "/references?type=patent")
|
by_type = call("GET", f"/references?type=patent&keyword={TOKEN}")
|
||||||
check("filter by type", by_type["total"] == 1, str(by_type["total"]))
|
check("filter by type", by_type["total"] == 1, str(by_type["total"]))
|
||||||
by_year = call("GET", "/references?year=2024")
|
by_year = call("GET", f"/references?year=2024&keyword={TOKEN}")
|
||||||
check("filter by year", by_year["total"] == 1, str(by_year["total"]))
|
check("filter by year", by_year["total"] == 1, str(by_year["total"]))
|
||||||
uncited = call("GET", "/references?cited=false")
|
uncited = call("GET", f"/references?cited=false&keyword={TOKEN}")
|
||||||
check("filter by not-yet-cited", uncited["total"] == len(created_references))
|
check(
|
||||||
|
"filter by not-yet-cited",
|
||||||
|
uncited["total"] == len(created_references),
|
||||||
|
f'{uncited["total"]} of {len(created_references)}',
|
||||||
|
)
|
||||||
|
|
||||||
by_tag = call("GET", f"/references?tag={must_read['id']}")
|
by_tag = call("GET", f"/references?tag={must_read['id']}")
|
||||||
check("filter by tag", by_tag["total"] == 2, str(by_tag["total"]))
|
check("filter by tag", by_tag["total"] == 2, str(by_tag["total"]))
|
||||||
@@ -240,31 +296,43 @@ def main() -> int:
|
|||||||
)
|
)
|
||||||
|
|
||||||
print("9. the tag table counts what carries each label")
|
print("9. the tag table counts what carries each label")
|
||||||
tags = call("GET", "/reference-tags")
|
tags = call("GET", f"/reference-tags?keyword={TOKEN}")
|
||||||
counts = {tag["name"]: tag["reference_count"] for tag in tags["items"]}
|
counts = {tag["name"]: tag["reference_count"] for tag in tags["items"]}
|
||||||
check("two labels in the library", tags["total"] == 2, str(tags["total"]))
|
check("two labels carry this run's token", tags["total"] == 2, str(tags["total"]))
|
||||||
check("the shared label counts two rows", counts["必读"] == 2, str(counts))
|
check(
|
||||||
check("the other counts one", counts["综述"] == 1, str(counts))
|
"the shared label counts two rows",
|
||||||
found = call("GET", "/reference-tags?keyword=综述")
|
counts[f"必读-{TOKEN}"] == 2,
|
||||||
|
str(counts),
|
||||||
|
)
|
||||||
|
check("the other counts one", counts[f"综述-{TOKEN}"] == 1, str(counts))
|
||||||
|
found = call("GET", f"/reference-tags?keyword=综述-{TOKEN}")
|
||||||
check("tags are searchable by name", found["total"] == 1, str(found["total"]))
|
check("tags are searchable by name", found["total"] == 1, str(found["total"]))
|
||||||
|
|
||||||
print("10. renaming a label follows it everywhere it is used")
|
print("10. renaming a label follows it everywhere it is used")
|
||||||
renamed = call(
|
renamed = call(
|
||||||
"PATCH",
|
"PATCH",
|
||||||
f"/reference-tags/{survey['id']}",
|
f"/reference-tags/{survey['id']}",
|
||||||
{"name": "综述文章", "note": "综述与述评"},
|
{"name": f"综述文章-{TOKEN}", "note": "综述与述评"},
|
||||||
)
|
)
|
||||||
check("the label is renamed", renamed["name"] == "综述文章")
|
check("the label is renamed", renamed["name"] == f"综述文章-{TOKEN}")
|
||||||
after = call("GET", f"/references/{article['id']}")
|
after = call("GET", f"/references/{article['id']}")
|
||||||
check(
|
check(
|
||||||
"the reference prints the new name",
|
"the reference prints the new name",
|
||||||
sorted(tag["name"] for tag in after["tags"]) == ["必读", "综述文章"],
|
sorted(tag["name"] for tag in after["tags"])
|
||||||
|
== [f"必读-{TOKEN}", f"综述文章-{TOKEN}"],
|
||||||
str(after["tags"]),
|
str(after["tags"]),
|
||||||
)
|
)
|
||||||
taken = call(
|
taken = call(
|
||||||
"PATCH", f"/reference-tags/{survey['id']}", {"name": "必读"}, expect=409
|
"PATCH",
|
||||||
|
f"/reference-tags/{survey['id']}",
|
||||||
|
{"name": f"必读-{TOKEN}"},
|
||||||
|
expect=409,
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"renaming onto a taken name is refused",
|
||||||
|
TOKEN in taken["detail"],
|
||||||
|
taken["detail"],
|
||||||
)
|
)
|
||||||
check("renaming onto a taken name is refused", "必读" in taken["detail"], taken["detail"])
|
|
||||||
|
|
||||||
print("11. edit it: replace the contributor list, a field and its tags")
|
print("11. edit it: replace the contributor list, a field and its tags")
|
||||||
updated = call(
|
updated = call(
|
||||||
@@ -283,7 +351,7 @@ def main() -> int:
|
|||||||
check("author list replaced wholesale", len(updated["authors"]) == 2)
|
check("author list replaced wholesale", len(updated["authors"]) == 2)
|
||||||
check(
|
check(
|
||||||
"tag list replaced wholesale too",
|
"tag list replaced wholesale too",
|
||||||
[tag["name"] for tag in updated["tags"]] == ["必读"],
|
[tag["name"] for tag in updated["tags"]] == [f"必读-{TOKEN}"],
|
||||||
str(updated["tags"]),
|
str(updated["tags"]),
|
||||||
)
|
)
|
||||||
check("untouched fields kept", updated["container_title"] == "Technological Forecasting and Social Change")
|
check("untouched fields kept", updated["container_title"] == "Technological Forecasting and Social Change")
|
||||||
@@ -291,7 +359,7 @@ def main() -> int:
|
|||||||
cleared = call("PATCH", f"/references/{patent['id']}", {"tag_ids": None})
|
cleared = call("PATCH", f"/references/{patent['id']}", {"tag_ids": None})
|
||||||
check(
|
check(
|
||||||
"omitting tags leaves them alone",
|
"omitting tags leaves them alone",
|
||||||
[tag["name"] for tag in cleared["tags"]] == ["必读"],
|
[tag["name"] for tag in cleared["tags"]] == [f"必读-{TOKEN}"],
|
||||||
str(cleared["tags"]),
|
str(cleared["tags"]),
|
||||||
)
|
)
|
||||||
|
|
||||||
@@ -300,7 +368,10 @@ def main() -> int:
|
|||||||
paper = call(
|
paper = call(
|
||||||
"POST",
|
"POST",
|
||||||
"/papers",
|
"/papers",
|
||||||
{"title": "参考文献冒烟测试论文", "template_id": templates[0]["id"]},
|
{
|
||||||
|
"title": f"参考文献冒烟测试论文{TOKEN}",
|
||||||
|
"template_id": templates[0]["id"],
|
||||||
|
},
|
||||||
expect=201,
|
expect=201,
|
||||||
)
|
)
|
||||||
created_papers.append(paper["id"])
|
created_papers.append(paper["id"])
|
||||||
@@ -338,7 +409,7 @@ def main() -> int:
|
|||||||
check("and the paper", citations[0]["paper_id"] == paper["id"])
|
check("and the paper", citations[0]["paper_id"] == paper["id"])
|
||||||
check("and the paragraph heading", citations[0]["paragraph_name"] is not None, str(citations[0]))
|
check("and the paragraph heading", citations[0]["paragraph_name"] is not None, str(citations[0]))
|
||||||
|
|
||||||
cited = call("GET", "/references?cited=true")
|
cited = call("GET", f"/references?cited=true&keyword={TOKEN}")
|
||||||
check("the cited filter now finds it", cited["total"] == 1, str(cited["total"]))
|
check("the cited filter now finds it", cited["total"] == 1, str(cited["total"]))
|
||||||
|
|
||||||
print("14. a cited reference cannot be deleted; an uncited one can")
|
print("14. a cited reference cannot be deleted; an uncited one can")
|
||||||
@@ -361,7 +432,25 @@ def main() -> int:
|
|||||||
str(left["total"]),
|
str(left["total"]),
|
||||||
)
|
)
|
||||||
|
|
||||||
print("16. clean up")
|
print("16. the 参考文献 list prints one entry per work, in Springer style")
|
||||||
|
document = call("GET", f"/papers/{paper['id']}/document")
|
||||||
|
check("the style is named in the response", document["reference_style"] == "springer")
|
||||||
|
check(
|
||||||
|
"one entry for the one work cited",
|
||||||
|
len(document["references"]) == 1,
|
||||||
|
str(len(document["references"])),
|
||||||
|
)
|
||||||
|
entry = document["references"][0]
|
||||||
|
check("the entry is a bibliography line", entry["text"].startswith("张三, 李四"), entry["text"])
|
||||||
|
check("and carries the year and the DOI", "(2024)" in entry["text"] and "https://doi.org/10.1016/j.techfore.2024.123456" in entry["text"], entry["text"])
|
||||||
|
check("it names the places it is cited", len(entry["citations"]) == 1, str(len(entry["citations"])))
|
||||||
|
check(
|
||||||
|
"and the in-text marker is that entry's number",
|
||||||
|
entry["citations"][0]["index"] == entry["index"],
|
||||||
|
f'{entry["citations"][0]["index"]} vs {entry["index"]}',
|
||||||
|
)
|
||||||
|
|
||||||
|
print("17. clean up")
|
||||||
call("DELETE", f"/papers/{paper['id']}", expect=204)
|
call("DELETE", f"/papers/{paper['id']}", expect=204)
|
||||||
created_papers.clear()
|
created_papers.clear()
|
||||||
for reference_id in created_references:
|
for reference_id in created_references:
|
||||||
@@ -370,13 +459,13 @@ def main() -> int:
|
|||||||
for tag_id in created_tags:
|
for tag_id in created_tags:
|
||||||
call("DELETE", f"/reference-tags/{tag_id}", expect=204)
|
call("DELETE", f"/reference-tags/{tag_id}", expect=204)
|
||||||
created_tags.clear()
|
created_tags.clear()
|
||||||
remaining = call("GET", "/references")
|
# Scoped by the token rather than by "the library is empty": the library
|
||||||
|
# this runs against holds real literature, and what must be true is that
|
||||||
|
# none of *this run's* rows survive.
|
||||||
|
remaining = call("GET", f"/references?keyword={TOKEN}")
|
||||||
check("nothing of ours is left", remaining["total"] == 0, str(remaining["total"]))
|
check("nothing of ours is left", remaining["total"] == 0, str(remaining["total"]))
|
||||||
check(
|
tags_left = call("GET", f"/reference-tags?keyword={TOKEN}")
|
||||||
"and no labels either",
|
check("and no labels either", tags_left["total"] == 0, str(tags_left["total"]))
|
||||||
call("GET", "/reference-tags")["total"] == 0,
|
|
||||||
str(call("GET", "/reference-tags")["total"]),
|
|
||||||
)
|
|
||||||
|
|
||||||
print(f"\nall {_checks} checks passed")
|
print(f"\nall {_checks} checks passed")
|
||||||
return 0
|
return 0
|
||||||
|
|||||||
+6
-1
@@ -249,7 +249,7 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
|||||||
| `paper_update` | 改元信息 / 换模板 | `paper_id`、`title?` `template_id?` `clear_template?` `author?` `status?` `keywords?` `target_journal?` |
|
| `paper_update` | 改元信息 / 换模板 | `paper_id`、`title?` `template_id?` `clear_template?` `author?` `status?` `keywords?` `target_journal?` |
|
||||||
| `paper_delete` | 删论文(连句子引用) | `paper_ids`(int 或数组)、`confirm=true` 必填 |
|
| `paper_delete` | 删论文(连句子引用) | `paper_ids`(int 或数组)、`confirm=true` 必填 |
|
||||||
| `paper_outline` | **写之前先看**:每段 position/标题/已写句数 | `paper_id` |
|
| `paper_outline` | **写之前先看**:每段 position/标题/已写句数 | `paper_id` |
|
||||||
| `paper_document` | 读全文 | `paper_id`、`format?`(`text`/`json`/`both`)`include_empty?` `citations?` |
|
| `paper_document` | 读全文(`format=text` 时末尾附 Springer 格式的参考文献表) | `paper_id`、`format?`(`text`/`json`/`both`)`include_empty?` `citations?` |
|
||||||
| `paper_write` | **批量写段落**(按标题或位置) | `paper_id`、`paragraphs`、`mode?`(`replace`/`append`) |
|
| `paper_write` | **批量写段落**(按标题或位置) | `paper_id`、`paragraphs`、`mode?`(`replace`/`append`) |
|
||||||
| `paper_write_text` | **整篇一次写入**(Markdown 标题分段) | `paper_id`、`text`、`split?` `mode?` `strict?` |
|
| `paper_write_text` | **整篇一次写入**(Markdown 标题分段) | `paper_id`、`text`、`split?` `mode?` `strict?` |
|
||||||
|
|
||||||
@@ -258,6 +258,11 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
|||||||
|
|
||||||
`paper_delete` 必须先被拒一次(告诉你删掉什么、不可恢复),确认后才带 `confirm=true` 重调。
|
`paper_delete` 必须先被拒一次(告诉你删掉什么、不可恢复),确认后才带 `confirm=true` 重调。
|
||||||
|
|
||||||
|
`paper_document` 的 `text` 里,正文的上标编号与末尾参考文献表的序号是**同一个号**:同一篇文献被引多次只占一个号、只列一条。
|
||||||
|
`json` 里对应的是 `references`(每条一个文献,`text` 就是排好版的条目)与 `reference_style`(当前是 `springer`),
|
||||||
|
以及 `citations`(每处引用一行,带自己的 `index`)。条目里缺哪些字段,看那条的 `missing`(如 `["卷期页码"]`),
|
||||||
|
不要自己去猜或补一个看起来合理的年份。
|
||||||
|
|
||||||
### 3.2 段落 paragraphs(5 个)
|
### 3.2 段落 paragraphs(5 个)
|
||||||
|
|
||||||
段落 = 位置。它由模板定义,或者由内容占据;**没有 `paragraph_create`**——往空位置写内容就是创建它。
|
段落 = 位置。它由模板定义,或者由内容占据;**没有 `paragraph_create`**——往空位置写内容就是创建它。
|
||||||
|
|||||||
+77
-9
@@ -370,6 +370,42 @@ The ORM cascades stay as well. `Template.items`, `Paper.sentences` and
|
|||||||
removes its dependents whether or not the database would have done it too —
|
removes its dependents whether or not the database would have done it too —
|
||||||
which keeps behaviour identical on a cluster with foreign keys switched off.
|
which keeps behaviour identical on a cluster with foreign keys switched off.
|
||||||
|
|
||||||
|
### The 参考文献 list is one entry per work, written by a style
|
||||||
|
|
||||||
|
A citation and a bibliography entry are two different counts, and confusing them
|
||||||
|
is the mistake this design is shaped around. `paper_sentence_reference` holds one
|
||||||
|
row per *place in the text* that quotes something: a paper of 86 citations to 65
|
||||||
|
works has 86 rows. The 参考文献 list has 65 entries, each numbered where the
|
||||||
|
reader first meets it, and every citation of that work carries the same number.
|
||||||
|
So `[7]` means one article everywhere — in the text, in the tooltip on the
|
||||||
|
marker, and in the list — and a work cannot appear twice under two numbers.
|
||||||
|
|
||||||
|
The entries themselves are written by :mod:`app.citation_styles`, which is a
|
||||||
|
package of one module per style:
|
||||||
|
|
||||||
|
```
|
||||||
|
app/citation_styles/
|
||||||
|
├── __init__.py the registry, DEFAULT_STYLE, format_reference/missing_fields
|
||||||
|
└── springer.py Springer's basic style — the numbered one
|
||||||
|
```
|
||||||
|
|
||||||
|
`GET /papers/{id}/document` returns `references` (the entries, in order) and
|
||||||
|
`reference_style` (which style wrote them). Three consequences are deliberate:
|
||||||
|
|
||||||
|
- **The client prints `text` verbatim.** Formatting a bibliography from fields
|
||||||
|
is a rule, and a second implementation of a rule prints a second bibliography
|
||||||
|
eventually. The paper view, the MCP text renderer and a future export all read
|
||||||
|
the same assembled entries.
|
||||||
|
- **A citation with no library row keeps its number and gets no entry.** It is
|
||||||
|
listed as its own entry with empty text and a warning, rather than dropped —
|
||||||
|
dropping it would leave a `[12]` in the text pointing at nothing.
|
||||||
|
- **A gap is reported, not filled in.** Each entry carries `missing` — the parts
|
||||||
|
a complete entry needs and does not have, in Chinese (「缺 责任者、出版年」) —
|
||||||
|
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; saying so
|
||||||
|
is the difference between a library that needs attention and a bibliography
|
||||||
|
that lies.
|
||||||
|
|
||||||
## API
|
## API
|
||||||
|
|
||||||
All routes are mounted under `/api`. Interactive docs at `/docs`.
|
All routes are mounted under `/api`. Interactive docs at `/docs`.
|
||||||
@@ -398,7 +434,7 @@ All routes are mounted under `/api`. Interactive docs at `/docs`.
|
|||||||
| `POST` | `/reference-tags` | name is unique — a duplicate is `409` naming it |
|
| `POST` | `/reference-tags` | name is unique — a duplicate is `409` naming it |
|
||||||
| `GET` `PATCH` `DELETE` | `/reference-tags/{id}` | renaming follows every reference carrying it |
|
| `GET` `PATCH` `DELETE` | `/reference-tags/{id}` | renaming follows every reference carrying it |
|
||||||
| `POST` | `/reference-tags/batch-delete` | body `{ "ids": [...] }`; unlabels, never deletes literature |
|
| `POST` | `/reference-tags/batch-delete` | body `{ "ids": [...] }`; unlabels, never deletes literature |
|
||||||
| `GET` | `/papers/{id}/document` | the whole paper: paragraphs in order, citations, warnings |
|
| `GET` | `/papers/{id}/document` | the whole paper: paragraphs in order, citations, the formatted `references`, warnings |
|
||||||
| `GET` | `/papers/{id}/paragraphs/{sort}` | one paragraph, assembled as the document renders it |
|
| `GET` | `/papers/{id}/paragraphs/{sort}` | one paragraph, assembled as the document renders it |
|
||||||
| `PUT` | `/papers/{id}/paragraphs/{sort}` | full replacement; optional `target_sort` moves it |
|
| `PUT` | `/papers/{id}/paragraphs/{sort}` | full replacement; optional `target_sort` moves it |
|
||||||
| `POST` | `/papers/{id}/sentences` | append one sentence |
|
| `POST` | `/papers/{id}/sentences` | append one sentence |
|
||||||
@@ -416,9 +452,14 @@ Conventions worth knowing:
|
|||||||
`/template-titles` for `template_title`, `/papers` for
|
`/template-titles` for `template_title`, `/papers` for
|
||||||
`paper`.
|
`paper`.
|
||||||
- A paper document returns its `paragraphs` in ascending position order,
|
- A paper document returns its `paragraphs` in ascending position order,
|
||||||
already carrying their sentences and citation numbering. The client sorts
|
already carrying their sentences and citation numbering, and its `references`
|
||||||
nothing and merges nothing: two implementations of the same ordering rule
|
as formatted entries. The client sorts nothing, merges nothing and formats
|
||||||
would eventually disagree.
|
nothing: two implementations of the same rule would eventually disagree.
|
||||||
|
- A citation's `index` is the number of its **work**, so 86 citations to 65
|
||||||
|
works produce 65 entries and repeated numbers in `citations` — see 「The
|
||||||
|
参考文献 list is one entry per work」 above.
|
||||||
|
- A document's `reference_style` names the style the entries were written in
|
||||||
|
(`springer`), so a client can label the block without hard-coding the choice.
|
||||||
- Sentence `content` is folded to a single line (leading, trailing and inner
|
- Sentence `content` is folded to a single line (leading, trailing and inner
|
||||||
whitespace runs collapse to one space), so an all-whitespace sentence becomes
|
whitespace runs collapse to one space), so an all-whitespace sentence becomes
|
||||||
the empty string — legal, and rendered as a blank line. A citation with a
|
the empty string — legal, and rendered as a blank line. A citation with a
|
||||||
@@ -630,8 +671,12 @@ alone knows how to do:
|
|||||||
- **an edit button beside every paragraph**, written or not — content only ever
|
- **an edit button beside every paragraph**, written or not — content only ever
|
||||||
enters a paper through the paragraph editor, so it may never be the thing that
|
enters a paper through the paragraph editor, so it may never be the thing that
|
||||||
is missing;
|
is missing;
|
||||||
- **numbered citation markers** in the text, matching the 参考文献 list, which
|
- **numbered citation markers** in the text, whose number is the number of the
|
||||||
is numbered in reading order rather than per paragraph;
|
*work* in the 参考文献 list below — a paper that cites one article in three
|
||||||
|
sentences prints the same number three times;
|
||||||
|
- **the 参考文献 block, printed from the server's entries and not reassembled** —
|
||||||
|
each entry is one work with its bibliography line, and the paragraphs that
|
||||||
|
cite it hang underneath it, with the quoted passages in the tooltip;
|
||||||
- **a 切换模板 dialog that previews the impact** — how much content lands under
|
- **a 切换模板 dialog that previews the impact** — how much content lands under
|
||||||
a new heading, how much keeps its place under 未设定, and how many empty
|
a new heading, how much keeps its place under 未设定, and how many empty
|
||||||
paragraphs the new template adds — because a switch re-shapes the whole
|
paragraphs the new template adds — because a switch re-shapes the whole
|
||||||
@@ -676,6 +721,8 @@ paper-doc/
|
|||||||
│ ├── app/
|
│ ├── app/
|
||||||
│ │ ├── api/routes/ # route handlers (health, papers, references,
|
│ │ ├── api/routes/ # route handlers (health, papers, references,
|
||||||
│ │ │ # reference_tags, templates, template_title)
|
│ │ │ # reference_tags, templates, template_title)
|
||||||
|
│ │ ├── citation_styles/ # how a reference prints: springer.py, and the
|
||||||
|
│ │ │ # registry that names the styles
|
||||||
│ │ ├── core/ # settings and configuration
|
│ │ ├── core/ # settings and configuration
|
||||||
│ │ ├── crud/ # data-access helpers
|
│ │ ├── crud/ # data-access helpers
|
||||||
│ │ ├── db/ # engine, session, declarative base
|
│ │ ├── db/ # engine, session, declarative base
|
||||||
@@ -687,6 +734,8 @@ paper-doc/
|
|||||||
│ ├── scripts/smoke_papers.py # end-to-end check of the writing loop
|
│ ├── scripts/smoke_papers.py # end-to-end check of the writing loop
|
||||||
│ ├── scripts/smoke_references.py # end-to-end check of the reference library
|
│ ├── scripts/smoke_references.py # end-to-end check of the reference library
|
||||||
│ │ # and its tags
|
│ │ # and its tags
|
||||||
|
│ ├── scripts/check_citation_styles.py # the formatter, one entry per type
|
||||||
|
│ │ # (no server, no database)
|
||||||
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
|
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
|
||||||
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
|
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
|
||||||
│ ├── alembic.ini
|
│ ├── alembic.ini
|
||||||
@@ -774,15 +823,34 @@ cd backend
|
|||||||
`scripts/smoke_references.py` makes the labels first, adds literature and tags
|
`scripts/smoke_references.py` makes the labels first, adds literature and tags
|
||||||
it, finds it again by author, type, year and tag, edits it, cites it from a
|
it, finds it again by author, type, year and tag, edits it, cites it from a
|
||||||
sentence, looks the citation up from the reference side, checks that a cited
|
sentence, looks the citation up from the reference side, checks that a cited
|
||||||
entry cannot be deleted while a tag can, and checks that a tag id the library
|
entry cannot be deleted while a tag can, that a tag id the library does not have
|
||||||
does not have is refused by name rather than invented. It cleans up after
|
is refused by name rather than invented, and that the paper's 参考文献 list
|
||||||
itself:
|
prints one formatted entry per work. It cleans up after itself:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd backend
|
cd backend
|
||||||
.venv/bin/python scripts/smoke_references.py
|
.venv/bin/python scripts/smoke_references.py
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Every row it creates carries a per-run token in its title, in one author's name
|
||||||
|
and in its label names, and it asserts against searches for that token. The
|
||||||
|
library it runs against is a real one, so "the search found one row" is only a
|
||||||
|
statement about this run if the run can name its own rows.
|
||||||
|
|
||||||
|
**Checking the citation formatter**
|
||||||
|
|
||||||
|
`scripts/check_citation_styles.py` needs nothing running: it builds a reference
|
||||||
|
of every document type in memory and asserts the exact entry Springer's basic
|
||||||
|
style calls for — authors and initials, the six-author limit, the en-dashed page
|
||||||
|
range, the DOI, and what is reported missing. A wrong branch here prints
|
||||||
|
something that *looks* like a bibliography entry, which is exactly the kind of
|
||||||
|
bug that survives a smoke test:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
.venv/bin/python scripts/check_citation_styles.py
|
||||||
|
```
|
||||||
|
|
||||||
**Checking the paper feature end to end**
|
**Checking the paper feature end to end**
|
||||||
|
|
||||||
`scripts/smoke_papers.py` walks the whole writing loop against a running API —
|
`scripts/smoke_papers.py` walks the whole writing loop against a running API —
|
||||||
|
|||||||
@@ -116,7 +116,14 @@ export interface PaperParagraph {
|
|||||||
|
|
||||||
/** One citation as it appears in the 参考文献 list. */
|
/** One citation as it appears in the 参考文献 list. */
|
||||||
export interface PaperCitation extends Citation {
|
export interface PaperCitation extends Citation {
|
||||||
/** The number shown in the text as `[index]`, in reading order. */
|
/**
|
||||||
|
* The number shown in the text as `[index]`, in reading order.
|
||||||
|
*
|
||||||
|
* It is the number of the **work**, not of the citation: a paper that cites
|
||||||
|
* the same article in three sentences prints `[7]` three times and lists the
|
||||||
|
* article once. Everything that numbers citations reads it from here, so the
|
||||||
|
* markers and the list cannot disagree.
|
||||||
|
*/
|
||||||
index: number
|
index: number
|
||||||
sentence_id: number
|
sentence_id: number
|
||||||
sentence_content: string
|
sentence_content: string
|
||||||
@@ -124,11 +131,35 @@ export interface PaperCitation extends Citation {
|
|||||||
paragraph_name: string | null
|
paragraph_name: string | null
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* One entry of the 参考文献 list: one work, however often it is cited.
|
||||||
|
*
|
||||||
|
* `text` is the whole entry as it prints, already formatted by the server in
|
||||||
|
* `reference_style`. A client prints it verbatim — assembling a bibliography
|
||||||
|
* from fields is a second implementation of a rule, and the two would drift.
|
||||||
|
*/
|
||||||
|
export interface PaperReference {
|
||||||
|
/** The number the text shows as `[index]`. */
|
||||||
|
index: number
|
||||||
|
/** The library row it came from, or `null` for a citation written before the
|
||||||
|
* literature was entered — `text` is empty in that case, and nothing is
|
||||||
|
* invented to fill it. */
|
||||||
|
reference_id: number | null
|
||||||
|
text: string
|
||||||
|
/** What a complete entry still lacks, in Chinese — 责任者、出版年、DOI… */
|
||||||
|
missing: string[]
|
||||||
|
/** Every place in the text that cites it, in reading order. */
|
||||||
|
citations: PaperCitation[]
|
||||||
|
}
|
||||||
|
|
||||||
/** The whole paper as it reads. */
|
/** The whole paper as it reads. */
|
||||||
export interface PaperDocument {
|
export interface PaperDocument {
|
||||||
paper: PaperDetail
|
paper: PaperDetail
|
||||||
paragraphs: PaperParagraph[]
|
paragraphs: PaperParagraph[]
|
||||||
citations: PaperCitation[]
|
citations: PaperCitation[]
|
||||||
|
references: PaperReference[]
|
||||||
|
/** The citation style the entries were written in, e.g. `springer`. */
|
||||||
|
reference_style: string
|
||||||
warnings: string[]
|
warnings: string[]
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -218,6 +249,16 @@ export async function getPaperDocument(id: number): Promise<PaperDocument> {
|
|||||||
return data
|
return data
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** Display names for the citation styles the server can print. */
|
||||||
|
export const REFERENCE_STYLE_LABELS: Record<string, string> = {
|
||||||
|
springer: 'Springer 基本格式',
|
||||||
|
}
|
||||||
|
|
||||||
|
/** The label for a style token, falling back to the token itself. */
|
||||||
|
export function referenceStyleLabel(style: string): string {
|
||||||
|
return REFERENCE_STYLE_LABELS[style] ?? style
|
||||||
|
}
|
||||||
|
|
||||||
export async function createPaper(payload: PaperPayload): Promise<PaperDetail> {
|
export async function createPaper(payload: PaperPayload): Promise<PaperDetail> {
|
||||||
const { data } = await http.post<PaperDetail>('/papers', payload)
|
const { data } = await http.post<PaperDetail>('/papers', payload)
|
||||||
return data
|
return data
|
||||||
|
|||||||
@@ -32,6 +32,8 @@ const props = defineProps<{
|
|||||||
paragraph: PaperParagraph
|
paragraph: PaperParagraph
|
||||||
/** Citation id -> the number shown in the text, assigned by reading order. */
|
/** Citation id -> the number shown in the text, assigned by reading order. */
|
||||||
citationIndex: Record<number, number>
|
citationIndex: Record<number, number>
|
||||||
|
/** Reference id -> its formatted entry, so a marker can say what it points at. */
|
||||||
|
referenceText: Record<number, string>
|
||||||
}>()
|
}>()
|
||||||
|
|
||||||
defineEmits<{ edit: [paragraph: PaperParagraph] }>()
|
defineEmits<{ edit: [paragraph: PaperParagraph] }>()
|
||||||
@@ -106,12 +108,19 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
|
|||||||
>
|
>
|
||||||
<template #content>
|
<template #content>
|
||||||
<div class="cite-tip">
|
<div class="cite-tip">
|
||||||
<div class="cite-tip-head">
|
<div class="cite-tip-head">[{{ citationIndex[citation.id] ?? '?' }}]</div>
|
||||||
[{{ citationIndex[citation.id] ?? '?' }}]
|
<!-- What the number means: the entry as the bibliography prints
|
||||||
<span v-if="citation.reference_id">引用 #{{ citation.reference_id }}</span>
|
it, not its database id. -->
|
||||||
<span v-else class="cite-tip-unlinked">未关联引用 id</span>
|
<div
|
||||||
|
v-if="citation.reference_id != null && referenceText[citation.reference_id]"
|
||||||
|
class="cite-tip-entry"
|
||||||
|
>
|
||||||
|
{{ referenceText[citation.reference_id] }}
|
||||||
</div>
|
</div>
|
||||||
<div class="cite-tip-quote">{{ citation.quote }}</div>
|
<div v-else class="cite-tip-unlinked">
|
||||||
|
这处引用还没有关联文献库条目
|
||||||
|
</div>
|
||||||
|
<div class="cite-tip-quote">「{{ citation.quote }}」</div>
|
||||||
</div>
|
</div>
|
||||||
</template>
|
</template>
|
||||||
<sup class="cite-mark">{{ citationIndex[citation.id] ?? '?' }}</sup>
|
<sup class="cite-mark">{{ citationIndex[citation.id] ?? '?' }}</sup>
|
||||||
@@ -222,7 +231,7 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
|
|||||||
}
|
}
|
||||||
|
|
||||||
.cite-tip {
|
.cite-tip {
|
||||||
max-width: 320px;
|
max-width: 380px;
|
||||||
}
|
}
|
||||||
|
|
||||||
.cite-tip-head {
|
.cite-tip-head {
|
||||||
@@ -232,7 +241,15 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
|
|||||||
font-weight: 600;
|
font-weight: 600;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/* The bibliography entry: the whole point of the tooltip. It is set as a
|
||||||
|
paragraph of running text because that is how it prints in the list. */
|
||||||
|
.cite-tip-entry {
|
||||||
|
margin-top: 4px;
|
||||||
|
line-height: 1.7;
|
||||||
|
}
|
||||||
|
|
||||||
.cite-tip-unlinked {
|
.cite-tip-unlinked {
|
||||||
|
margin-top: 4px;
|
||||||
font-weight: 400;
|
font-weight: 400;
|
||||||
opacity: 0.7;
|
opacity: 0.7;
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -29,7 +29,6 @@ import {
|
|||||||
Delete,
|
Delete,
|
||||||
Edit,
|
Edit,
|
||||||
Refresh,
|
Refresh,
|
||||||
Right,
|
|
||||||
Switch,
|
Switch,
|
||||||
Warning,
|
Warning,
|
||||||
} from '@element-plus/icons-vue'
|
} from '@element-plus/icons-vue'
|
||||||
@@ -41,8 +40,10 @@ import {
|
|||||||
getPaperDocument,
|
getPaperDocument,
|
||||||
PAPER_STATUS_LABELS,
|
PAPER_STATUS_LABELS,
|
||||||
PAPER_STATUS_TAG,
|
PAPER_STATUS_TAG,
|
||||||
|
referenceStyleLabel,
|
||||||
type PaperDocument,
|
type PaperDocument,
|
||||||
type PaperParagraph,
|
type PaperParagraph,
|
||||||
|
type PaperReference,
|
||||||
} from '@/api/papers'
|
} from '@/api/papers'
|
||||||
import PaperFormDialog from '@/components/papers/PaperFormDialog.vue'
|
import PaperFormDialog from '@/components/papers/PaperFormDialog.vue'
|
||||||
import ParagraphEditDialog from '@/components/papers/ParagraphEditDialog.vue'
|
import ParagraphEditDialog from '@/components/papers/ParagraphEditDialog.vue'
|
||||||
@@ -77,6 +78,52 @@ const citationIndex = computed<Record<number, number>>(() => {
|
|||||||
return map
|
return map
|
||||||
})
|
})
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reference id -> the formatted entry, for the marker tooltips.
|
||||||
|
*
|
||||||
|
* The tooltip on a `[7]` in the text should say what `[7]` *is*, and the entry
|
||||||
|
* is assembled once by the server — this is a lookup of that same string, not a
|
||||||
|
* second attempt at formatting it.
|
||||||
|
*/
|
||||||
|
const referenceText = computed<Record<number, string>>(() => {
|
||||||
|
const map: Record<number, string> = {}
|
||||||
|
for (const entry of paperDoc.value?.references ?? []) {
|
||||||
|
if (entry.reference_id != null && entry.text) {
|
||||||
|
map[entry.reference_id] = entry.text
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return map
|
||||||
|
})
|
||||||
|
|
||||||
|
/** How the entries are printed, named rather than hard-coded in the view. */
|
||||||
|
const styleLabel = computed(() =>
|
||||||
|
referenceStyleLabel(paperDoc.value?.reference_style ?? 'springer'),
|
||||||
|
)
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Where an entry is cited, one row per paragraph.
|
||||||
|
*
|
||||||
|
* The same work cited twice in one paragraph is one place with a count, not two
|
||||||
|
* identical links: what the reader needs from the list is where to look, and
|
||||||
|
* the quotes for that paragraph travel in the tooltip.
|
||||||
|
*/
|
||||||
|
function places(entry: PaperReference): { sort: number; name: string; quotes: string[] }[] {
|
||||||
|
const byParagraph = new Map<number, { sort: number; name: string; quotes: string[] }>()
|
||||||
|
for (const citation of entry.citations) {
|
||||||
|
const found = byParagraph.get(citation.paper_template_filed_sort)
|
||||||
|
if (found) {
|
||||||
|
found.quotes.push(citation.quote)
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
byParagraph.set(citation.paper_template_filed_sort, {
|
||||||
|
sort: citation.paper_template_filed_sort,
|
||||||
|
name: citation.paragraph_name ?? PARAGRAPH_UNSET_LABEL,
|
||||||
|
quotes: [citation.quote],
|
||||||
|
})
|
||||||
|
}
|
||||||
|
return [...byParagraph.values()]
|
||||||
|
}
|
||||||
|
|
||||||
/** How much of the structure has been written, for the header read-out. */
|
/** How much of the structure has been written, for the header read-out. */
|
||||||
const progress = computed(() => {
|
const progress = computed(() => {
|
||||||
if (!paperDoc.value) return { written: 0, total: 0, unmatched: 0 }
|
if (!paperDoc.value) return { written: 0, total: 0, unmatched: 0 }
|
||||||
@@ -268,33 +315,69 @@ onMounted(load)
|
|||||||
:key="paragraph.paper_template_filed_sort"
|
:key="paragraph.paper_template_filed_sort"
|
||||||
:paragraph="paragraph"
|
:paragraph="paragraph"
|
||||||
:citation-index="citationIndex"
|
:citation-index="citationIndex"
|
||||||
|
:reference-text="referenceText"
|
||||||
@edit="openParagraph"
|
@edit="openParagraph"
|
||||||
/>
|
/>
|
||||||
</div>
|
</div>
|
||||||
</el-card>
|
</el-card>
|
||||||
|
|
||||||
<el-card v-if="paperDoc?.citations.length" shadow="never">
|
<el-card v-if="paperDoc?.references.length" shadow="never">
|
||||||
<template #header>
|
<template #header>
|
||||||
<div class="paper-head">
|
<div class="paper-head">
|
||||||
<span class="paper-title">参考文献引用</span>
|
<span class="paper-title">参考文献</span>
|
||||||
<span class="paper-hint">按正文出现顺序编号,正文中的上标与这里的序号一一对应</span>
|
<span class="paper-hint">
|
||||||
|
按正文首次出现顺序编号,同一篇文献在多处引用共用同一个序号;条目按 {{ styleLabel }} 排版
|
||||||
|
</span>
|
||||||
</div>
|
</div>
|
||||||
</template>
|
</template>
|
||||||
|
|
||||||
<ol class="references">
|
<ol class="references">
|
||||||
<li v-for="citation in paperDoc.citations" :key="citation.id" class="reference">
|
<li v-for="entry in paperDoc.references" :key="entry.index" class="reference">
|
||||||
<span class="reference-index">[{{ citation.index }}]</span>
|
<span class="reference-index">[{{ entry.index }}]</span>
|
||||||
<div class="reference-body">
|
<div class="reference-body">
|
||||||
<div class="reference-quote">{{ citation.quote }}</div>
|
<!-- The entry as it prints. Whatever the library is missing shows
|
||||||
|
up as a shorter entry, so the gap is named underneath rather
|
||||||
|
than quietly filled in. -->
|
||||||
|
<p v-if="entry.text" class="reference-text">{{ entry.text }}</p>
|
||||||
|
<p v-else class="reference-text reference-text--unlinked">
|
||||||
|
这处引用还没有关联文献库条目,只有引用内容。
|
||||||
|
</p>
|
||||||
|
|
||||||
<div class="reference-meta">
|
<div class="reference-meta">
|
||||||
<el-tag v-if="citation.reference_id" size="small" effect="plain">
|
<el-tag
|
||||||
引用 #{{ citation.reference_id }}
|
v-if="entry.missing.length"
|
||||||
|
type="warning"
|
||||||
|
size="small"
|
||||||
|
effect="plain"
|
||||||
|
>
|
||||||
|
缺 {{ entry.missing.join('、') }}
|
||||||
</el-tag>
|
</el-tag>
|
||||||
<el-tag v-else size="small" type="warning" effect="plain">未关联引用 id</el-tag>
|
<el-tag v-if="!entry.reference_id" type="warning" size="small" effect="plain">
|
||||||
<el-button link type="primary" @click="scrollToParagraph(citation.paper_template_filed_sort)">
|
未关联文献
|
||||||
{{ citation.paragraph_name ?? PARAGRAPH_UNSET_LABEL }}
|
</el-tag>
|
||||||
<el-icon><Right /></el-icon>
|
<span class="reference-places">
|
||||||
</el-button>
|
<span class="reference-places-label">引用位置</span>
|
||||||
|
<el-tooltip
|
||||||
|
v-for="place in places(entry)"
|
||||||
|
:key="place.sort"
|
||||||
|
placement="top"
|
||||||
|
:show-after="200"
|
||||||
|
>
|
||||||
|
<template #content>
|
||||||
|
<div class="place-tip">
|
||||||
|
<div v-for="(quote, index) in place.quotes" :key="index">
|
||||||
|
「{{ quote }}」
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
<el-button link type="primary" @click="scrollToParagraph(place.sort)">
|
||||||
|
{{ place.name }}
|
||||||
|
<span v-if="place.quotes.length > 1" class="place-count">
|
||||||
|
×{{ place.quotes.length }}
|
||||||
|
</span>
|
||||||
|
</el-button>
|
||||||
|
</el-tooltip>
|
||||||
|
</span>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</li>
|
</li>
|
||||||
@@ -446,19 +529,56 @@ onMounted(load)
|
|||||||
|
|
||||||
.reference-body {
|
.reference-body {
|
||||||
min-width: 0;
|
min-width: 0;
|
||||||
|
flex: 1 1 auto;
|
||||||
}
|
}
|
||||||
|
|
||||||
.reference-quote {
|
/* The entry, printed as the style wrote it: one line of running text, hanging
|
||||||
|
under its number like a bibliography. */
|
||||||
|
.reference-text {
|
||||||
|
margin: 0;
|
||||||
font-size: 13px;
|
font-size: 13px;
|
||||||
line-height: 1.8;
|
line-height: 1.8;
|
||||||
color: var(--el-text-color-regular);
|
color: var(--el-text-color-regular);
|
||||||
overflow-wrap: anywhere;
|
overflow-wrap: anywhere;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
.reference-text--unlinked {
|
||||||
|
color: var(--el-color-warning);
|
||||||
|
}
|
||||||
|
|
||||||
.reference-meta {
|
.reference-meta {
|
||||||
display: flex;
|
display: flex;
|
||||||
align-items: center;
|
align-items: center;
|
||||||
gap: 8px;
|
gap: 8px;
|
||||||
margin-top: 4px;
|
margin-top: 4px;
|
||||||
|
flex-wrap: wrap;
|
||||||
|
}
|
||||||
|
|
||||||
|
.reference-places {
|
||||||
|
display: inline-flex;
|
||||||
|
align-items: center;
|
||||||
|
gap: 2px;
|
||||||
|
flex-wrap: wrap;
|
||||||
|
font-size: 12px;
|
||||||
|
color: var(--el-text-color-secondary);
|
||||||
|
}
|
||||||
|
|
||||||
|
.reference-places-label {
|
||||||
|
margin-right: 2px;
|
||||||
|
color: var(--el-text-color-placeholder);
|
||||||
|
}
|
||||||
|
|
||||||
|
.place-count {
|
||||||
|
margin-left: 2px;
|
||||||
|
color: var(--el-text-color-placeholder);
|
||||||
|
font-variant-numeric: tabular-nums;
|
||||||
|
}
|
||||||
|
|
||||||
|
.place-tip {
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
gap: 4px;
|
||||||
|
max-width: 420px;
|
||||||
|
line-height: 1.7;
|
||||||
}
|
}
|
||||||
</style>
|
</style>
|
||||||
|
|||||||
Reference in New Issue
Block a user