"""Request/response schemas for the reference library (参考文献). The field set and where it comes from is documented on :mod:`app.models.reference`; this module is about the wire format: * **Nothing is stored that a style can derive.** ``authors`` arrives as an ordered list and replaces the stored list wholesale, like a template's placements — the citation prints them in exactly the order sent. * **A DOI is stored canonically.** ``https://doi.org/10.1000/xyz``, ``doi:10.1000/xyz`` and ``10.1000/xyz`` are the same DOI, so the prefix is stripped on write and the column holds one spelling. * **A date is as precise as it is known.** Year, month and day are separate and independently optional, which is what CSL calls a partial date: a book has a year, a newspaper article a day, a patent its 公告日期. """ from datetime import date, datetime from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator from app.models.reference import ( REFERENCE_AUTHOR_ROLES, REFERENCE_LANGUAGES, REFERENCE_TYPES, ) from app.schemas.reference_tag import ReferenceTagRef #: Prefixes people paste along with a DOI. Stripped on write so the column has #: one spelling, and so a citation builder never has to test for them. _DOI_PREFIXES = ( "https://doi.org/", "http://doi.org/", "https://dx.doi.org/", "http://dx.doi.org/", "doi:", "DOI:", ) def normalize_doi(value: str | None) -> str | None: """Return the bare DOI, or ``None`` when nothing was given.""" if value is None: return None text = value.strip() for prefix in _DOI_PREFIXES: if text.lower().startswith(prefix.lower()): text = text[len(prefix) :] break return text.strip() or None class ReferenceAuthorInput(BaseModel): """One contributor as the client sends it. ``name`` is required — it is what prints. ``family_name`` / ``given_name`` are optional enrichment for styles that invert or initialise a name, and a ``sort`` that is left out is assigned from the position in the list. """ name: str = Field(min_length=1, max_length=255) family_name: str | None = Field(default=None, max_length=128) given_name: str | None = Field(default=None, max_length=128) role: str = Field(default="author", max_length=16) sort: int | None = Field(default=None, ge=-1_000_000, le=1_000_000) @field_validator("name") @classmethod def _require_name(cls, value: str) -> str: text = value.strip() if not text: raise ValueError("责任者姓名不能为空") return text @field_validator("family_name", "given_name") @classmethod def _strip_optional(cls, value: str | None) -> str | None: if value is None: return None return value.strip() or None @field_validator("role") @classmethod def _check_role(cls, value: str) -> str: if value not in REFERENCE_AUTHOR_ROLES: raise ValueError( "责任者角色只能是:" + "、".join(REFERENCE_AUTHOR_ROLES) ) return value class ReferenceAuthorRead(BaseModel): """A stored contributor.""" model_config = ConfigDict(from_attributes=True) id: int sort: int name: str family_name: str | None given_name: str | None role: str class ReferenceBase(BaseModel): """Every field a reference may carry, all optional but the title.""" type: str = Field(default="journal-article", max_length=32) title: str = Field(min_length=1, max_length=512) subtitle: str | None = Field(default=None, max_length=512) title_translated: str | None = Field(default=None, max_length=512) title_short: str | None = Field(default=None, max_length=255) container_title: str | None = Field(default=None, max_length=512) container_title_short: str | None = Field(default=None, max_length=255) series_title: str | None = Field(default=None, max_length=512) series_number: str | None = Field(default=None, max_length=32) edition: str | None = Field(default=None, max_length=64) volume: str | None = Field(default=None, max_length=32) issue: str | None = Field(default=None, max_length=32) pages: str | None = Field(default=None, max_length=64) article_number: str | None = Field(default=None, max_length=64) publisher: str | None = Field(default=None, max_length=255) publisher_place: str | None = Field(default=None, max_length=255) event_title: str | None = Field(default=None, max_length=512) event_place: str | None = Field(default=None, max_length=255) event_date: str | None = Field(default=None, max_length=64) publication_year: int | None = Field(default=None, ge=1, le=2999) publication_month: int | None = Field(default=None, ge=1, le=12) publication_day: int | None = Field(default=None, ge=1, le=31) accessed_date: date | None = None doi: str | None = Field(default=None, max_length=255) isbn: str | None = Field(default=None, max_length=32) issn: str | None = Field(default=None, max_length=32) url: str | None = Field(default=None, max_length=1024) patent_country: str | None = Field(default=None, max_length=64) patent_number: str | None = Field(default=None, max_length=64) standard_number: str | None = Field(default=None, max_length=64) report_number: str | None = Field(default=None, max_length=64) arxiv_id: str | None = Field(default=None, max_length=64) abstract: str | None = None keywords: str | None = Field(default=None, max_length=512) note: str | None = None citation_key: str | None = Field(default=None, max_length=64) language: str | None = Field(default=None, max_length=16) authors: list[ReferenceAuthorInput] = Field(default_factory=list) #: The tags to apply, by id. Tags are made first and applied second, so this #: names labels that already exist rather than carrying spellings that could #: invent new ones. Unknown ids are refused by name. tag_ids: list[int] = Field(default_factory=list) @field_validator("title") @classmethod def _require_title(cls, value: str) -> str: text = value.strip() if not text: raise ValueError("文献题名不能为空") return text @field_validator("type") @classmethod def _check_type(cls, value: str) -> str: if value not in REFERENCE_TYPES: raise ValueError("文献类型只能是:" + "、".join(REFERENCE_TYPES)) return value @field_validator("language") @classmethod def _check_language(cls, value: str | None) -> str | None: if value is None or value == "": return None if value not in REFERENCE_LANGUAGES: raise ValueError("语种只能是:" + "、".join(REFERENCE_LANGUAGES)) return value @field_validator("doi") @classmethod def _normalise_doi(cls, value: str | None) -> str | None: return normalize_doi(value) @field_validator( "subtitle", "title_translated", "title_short", "container_title", "container_title_short", "series_title", "series_number", "edition", "volume", "issue", "pages", "article_number", "publisher", "publisher_place", "event_title", "event_place", "event_date", "isbn", "issn", "url", "patent_country", "patent_number", "standard_number", "report_number", "arxiv_id", "keywords", "citation_key", ) @classmethod def _blank_to_none(cls, value: str | None) -> str | None: """Treat a whitespace-only string as "not set" rather than as a value.""" if value is None: return None return value.strip() or None @model_validator(mode="after") def _check_online_resource(self) -> "ReferenceBase": """An online resource must say where it is. GB/T 7714 prints a URL for ``[EB/OL]`` and nothing else identifies the document; a row typed as a web page or a dataset with no URL is a row that cannot be cited. """ if self.type in ("web-page", "dataset") and not (self.url or self.doi): raise ValueError("网页/数据集类型的文献必须至少给出 URL 或 DOI") return self class ReferenceCreate(ReferenceBase): """Payload for ``POST /references``.""" class ReferenceUpdate(BaseModel): """Payload for ``PATCH /references/{id}`` — every part optional. ``authors`` is a full replacement when present, like a template's placements: the citation prints the list in the order it arrives. """ type: str | None = Field(default=None, max_length=32) title: str | None = Field(default=None, min_length=1, max_length=512) subtitle: str | None = Field(default=None, max_length=512) title_translated: str | None = Field(default=None, max_length=512) title_short: str | None = Field(default=None, max_length=255) container_title: str | None = Field(default=None, max_length=512) container_title_short: str | None = Field(default=None, max_length=255) series_title: str | None = Field(default=None, max_length=512) series_number: str | None = Field(default=None, max_length=32) edition: str | None = Field(default=None, max_length=64) volume: str | None = Field(default=None, max_length=32) issue: str | None = Field(default=None, max_length=32) pages: str | None = Field(default=None, max_length=64) article_number: str | None = Field(default=None, max_length=64) publisher: str | None = Field(default=None, max_length=255) publisher_place: str | None = Field(default=None, max_length=255) event_title: str | None = Field(default=None, max_length=512) event_place: str | None = Field(default=None, max_length=255) event_date: str | None = Field(default=None, max_length=64) publication_year: int | None = Field(default=None, ge=1, le=2999) publication_month: int | None = Field(default=None, ge=1, le=12) publication_day: int | None = Field(default=None, ge=1, le=31) accessed_date: date | None = None doi: str | None = Field(default=None, max_length=255) isbn: str | None = Field(default=None, max_length=32) issn: str | None = Field(default=None, max_length=32) url: str | None = Field(default=None, max_length=1024) patent_country: str | None = Field(default=None, max_length=64) patent_number: str | None = Field(default=None, max_length=64) standard_number: str | None = Field(default=None, max_length=64) report_number: str | None = Field(default=None, max_length=64) arxiv_id: str | None = Field(default=None, max_length=64) abstract: str | None = None keywords: str | None = Field(default=None, max_length=512) note: str | None = None citation_key: str | None = Field(default=None, max_length=64) language: str | None = Field(default=None, max_length=16) authors: list[ReferenceAuthorInput] | None = None #: Full replacement when present, like ``authors``: the list is the set of #: labels on the row, so sending it means "these and no others" and ``[]`` #: clears every label. Omitting the key leaves the labels alone. tag_ids: list[int] | None = None @field_validator("title") @classmethod def _require_title(cls, value: str | None) -> str | None: if value is None: return None text = value.strip() if not text: raise ValueError("文献题名不能为空") return text @field_validator("type") @classmethod def _check_type(cls, value: str | None) -> str | None: if value is None: return None if value not in REFERENCE_TYPES: raise ValueError("文献类型只能是:" + "、".join(REFERENCE_TYPES)) return value @field_validator("language") @classmethod def _check_language(cls, value: str | None) -> str | None: if value is None or value == "": return None if value not in REFERENCE_LANGUAGES: raise ValueError("语种只能是:" + "、".join(REFERENCE_LANGUAGES)) return value @field_validator("doi") @classmethod def _normalise_doi(cls, value: str | None) -> str | None: return normalize_doi(value) class ReferenceListItem(BaseModel): """A reference as it appears in the library table.""" id: int type: str title: str subtitle: str | None container_title: str | None #: 出版者. Carried on the row because a book, a thesis and a report have no #: container to show and the publisher *is* their "where". publisher: str | None publication_year: int | None volume: str | None issue: str | None pages: str | None doi: str | None #: The printed author list, joined — a table row needs the line, not the #: rows behind it. authors_line: str author_count: int #: The labels the writer put on it, ready to paint. Loading them here rather #: than per row is what keeps a page of the library one query for the tags. tags: list[ReferenceTagRef] = Field(default_factory=list) #: How many sentences cite it. Drives the refusal message on delete, and #: tells the writer at a glance what is already used. citation_count: int created_at: datetime updated_at: datetime class ReferenceRead(BaseModel): """A reference with everything the table does not need.""" id: int type: str title: str subtitle: str | None title_translated: str | None title_short: str | None container_title: str | None container_title_short: str | None series_title: str | None series_number: str | None edition: str | None volume: str | None issue: str | None pages: str | None article_number: str | None publisher: str | None publisher_place: str | None event_title: str | None event_place: str | None event_date: str | None publication_year: int | None publication_month: int | None publication_day: int | None accessed_date: date | None doi: str | None isbn: str | None issn: str | None url: str | None patent_country: str | None patent_number: str | None standard_number: str | None report_number: str | None arxiv_id: str | None abstract: str | None keywords: str | None note: str | None citation_key: str | None language: str | None authors: list[ReferenceAuthorRead] tags: list[ReferenceTagRef] = Field(default_factory=list) citation_count: int created_at: datetime updated_at: datetime class ReferenceCitationRead(BaseModel): """One sentence that cites a reference — the reverse lookup. "Which of my sentences use this article?" is the question a reference library exists to answer, and it needs the sentence, the paragraph it sits in, and the paper it belongs to. """ citation_id: int sentence_id: int sentence_content: str quote: str paper_id: int paper_title: str paper_template_filed_sort: int paragraph_name: str | None = None __all__ = [ "ReferenceAuthorInput", "ReferenceAuthorRead", "ReferenceBase", "ReferenceCitationRead", "ReferenceCreate", "ReferenceListItem", "ReferenceRead", "ReferenceUpdate", "normalize_doi", ]