# SPDX-License-Identifier: Apache-2.0 # Copyright 2026 Scienting # # Source Code: https://git.scient.ing/papers/paperspec # See the LICENSE.md file for full license terms. """Work keys and document keys (spec/02 §2.4).""" from typing import ClassVar import pytest from hypothesis import given, settings, strategies as st from helpers_lib1 import case_params, read_cases from paperspec import keys from paperspec.text import ALPHABET, sha256_hex PROPERTIES = settings(derandomize=True, max_examples=150, database=None, deadline=None) META = { "author": [{"family": "Vaswani", "given": "Ashish"}], "issued": {"date-parts": [[2017]]}, "title": "Attention is all you need", } @pytest.mark.parametrize( "case", case_params([c for c in read_cases("keys") if "version" not in c]) ) def test_key_vector(case): if "taken" in case: key = keys.unique_work_key(case["same_as"], case["meta"], set(case["taken"])) assert key == case["key"] assert len(key.rsplit("-", 1)[1]) == 6 return ident = keys.identity(case["same_as"], case["meta"]) assert ident == case["identity"] assert keys.scholar_part(case["meta"]) == case["scholar"] assert keys.SCHEME + ":" + ident == case["payload"] assert sha256_hex(case["payload"]) == case["sha256"] assert keys.suffix(ident) == case["suffix"] assert keys.suffix(ident, 8) == case["suffix_8"] assert case["suffix_8"].startswith(case["suffix"]) assert keys.work_key(case["same_as"], case["meta"]) == case["key"] assert keys.WORK_KEY_RE.match(case["key"]) assert case["key"] == case["scholar"] + "-" + case["suffix"] @pytest.mark.parametrize( "case", case_params([c for c in read_cases("keys") if "version" in c]) ) def test_document_key_vector(case): assert keys.document_key(case["work_key"], case["version"]) == case["document_key"] work, suffix = keys.split_key(case["document_key"]) assert work == case["work_key"] assert work + suffix == case["document_key"] @pytest.mark.parametrize( ("text", "folded"), [ ("Müller", "muller"), ("Ångström", "angstrom"), ("张伟", ""), ("ALL CAPS", "all caps"), ("fi", "fi"), ("", ""), (None, ""), (5, ""), ], ) def test_fold(text, folded): assert keys.fold(text) == folded @pytest.mark.parametrize( ("title", "words"), [ ("Don't stop", ["dont", "stop"]), ("Don\N{RIGHT SINGLE QUOTATION MARK}t stop", ["dont", "stop"]), ( "Self-assembly of 3D-printed bone", ["self", "assembly", "of", "3d", "printed", "bone"], ), (" ", []), (None, []), ("Étude: cafés", ["etude", "cafes"]), ], ) def test_title_words(title, words): assert keys.title_words(title) == words @pytest.mark.parametrize( ("name", "family"), [ ("Ada Lovelace", "Lovelace"), ("Lovelace, Ada", "Lovelace"), ("A. Smith Jr.", "Smith"), ("Smith III", "Smith"), ("John Smith, Jr.", "Smith"), ("Smith, Jr.", "Smith"), ("Smith, John", "Smith"), ("Madonna", "Madonna"), ("Jr.", "Jr."), ("", ""), (None, ""), (" Plato ", "Plato"), ], ) def test_family_name(name, family): assert keys.family_name(name) == family @pytest.mark.parametrize( ("meta", "family"), [ ({}, "anon"), ({"author": []}, "anon"), ({"author": [{"family": "O'Brien"}]}, "obrien"), ({"author": [{"literal": "Conan O'Brien"}]}, "obrien"), ({"author": [{"name": "Grace Hopper"}]}, "hopper"), ({"author": [{"family": "张伟"}]}, "anon"), ({"author": [{}]}, "anon"), ({"author": [{"family": "van der Waals"}]}, "vanderwaals"), ({"author": [{"family": "Kim"}, {"family": "Lee"}]}, "kim"), ], ) def test_first_family(meta, family): assert keys.first_family(meta) == family @pytest.mark.parametrize( ("meta", "year"), [ ({"issued": {"date-parts": [[2017, 3, 1]]}}, "2017"), ({"issued": {"date-parts": [["2017"]]}}, "2017"), ({"issued": {"date-parts": [[17]]}}, ""), ({"issued": {"date-parts": [[20170]]}}, ""), ({"issued": {"date-parts": [[True]]}}, ""), ({"issued": {"date-parts": [[None]]}}, ""), ({"issued": {"date-parts": [[]]}}, ""), ({"issued": {"date-parts": []}}, ""), ({"issued": {}}, ""), ({"issued": None}, ""), ({}, ""), ], ) def test_year_of(meta, year): assert keys.year_of(meta) == year @pytest.mark.parametrize( ("title", "scholar"), [ ("The theory of everything", "vaswani2017theory"), ("A of the", "vaswani2017"), ("", "vaswani2017"), ("Attention is all you need", "vaswani2017attention"), ("On the origin", "vaswani2017origin"), ], ) def test_scholar_part_skips_stop_words(title, scholar): assert keys.scholar_part(dict(META, title=title)) == scholar @pytest.mark.parametrize( ("value", "bare"), [ ("10.1000/ABC", "10.1000/abc"), ("doi:10.1000/ABC", "10.1000/abc"), ("DOI:10.1000/abc", "10.1000/abc"), ("https://doi.org/10.1000/abc", "10.1000/abc"), ("http://dx.doi.org/10.1000/abc", "10.1000/abc"), ("https://www.doi.org/10.1000/abc", "10.1000/abc"), (" doi:doi:10.1000/abc ", "10.1000/abc"), ("10.1000/É", "10.1000/É"), ], ) def test_norm_doi(value, bare): assert keys.norm_doi(value) == bare @pytest.mark.parametrize( ("same_as", "identity"), [ (["arxiv:1706.03762"], "arxiv:1706.03762"), (["isbn: 978-3-16 "], "isbn:978-3-16"), (["pmid:1", "arxiv:2"], "arxiv:2"), (["openalex:W1", "pmcid:PMC1"], "pmcid:PMC1"), (["doi:", "arxiv:1706.03762"], "arxiv:1706.03762"), (["doi:10.1/A", "doi:10.1/B"], "doi:10.1/a"), ( ["url:https://example.org", "title:x"], "meta:attention is all you need|2017|vaswani", ), (None, "meta:attention is all you need|2017|vaswani"), ([], "meta:attention is all you need|2017|vaswani"), (["noprefix"], "meta:attention is all you need|2017|vaswani"), ], ) def test_identity(same_as, identity): assert keys.identity(same_as, META) == identity @pytest.mark.parametrize("length", [1, 4, 8, 51]) def test_suffix_has_the_asked_length_and_alphabet(length): out = keys.suffix("doi:10.1/x", length) assert len(out) == length assert set(out) <= set(ALPHABET) @pytest.mark.parametrize("length", [0, -1, 52, 100]) def test_suffix_length_is_one_to_fifty_one(length): with pytest.raises(ValueError, match="a key suffix is 1 to 51 characters"): keys.suffix("doi:10.1/x", length) @given(st.text(max_size=40), st.integers(min_value=1, max_value=50)) @PROPERTIES def test_a_shorter_suffix_is_a_prefix_of_a_longer_one(ident, length): assert keys.suffix(ident, length + 1).startswith(keys.suffix(ident, length)) def test_unique_work_key_lengthens_by_two_while_taken(): same_as = ["doi:10.1/x"] first = keys.work_key(same_as, META, 4) second = keys.work_key(same_as, META, 6) third = keys.work_key(same_as, META, 8) assert keys.unique_work_key(same_as, META, set()) == first assert keys.unique_work_key(same_as, META, {first}) == second assert keys.unique_work_key(same_as, META, {first, second}) == third assert keys.unique_work_key(same_as, META, {second}) == first def test_unique_work_key_gives_up_when_every_length_is_taken(): same_as = ["doi:10.1/x"] taken = {keys.work_key(same_as, META, n) for n in range(4, 52, 2)} with pytest.raises(ValueError, match=r"no free key for doi:10\.1/x"): keys.unique_work_key(same_as, META, taken) @pytest.mark.parametrize( ("version", "suffix"), [ ({"type": "version-of-record"}, ""), ({"type": "supplement"}, ".si"), ({"type": "preprint", "seq": 2}, ".v2"), ({"type": "draft", "seq": 10}, ".v10"), ({"type": "submitted", "seq": 1}, ".v1"), ({"type": "accepted", "seq": 3}, ".v3"), ({"type": "accepted"}, ".accepted"), ({"type": "preprint", "seq": "2"}, ".preprint"), ({"type": "erratum", "seq": 4}, ".erratum"), ], ) def test_version_suffix(version, suffix): assert keys.version_suffix(version) == suffix assert keys.document_key("a2020b-abcd", version) == "a2020b-abcd" + suffix @pytest.mark.parametrize( ("dkey", "parts"), [ ("vaswani2017attention-a241", ("vaswani2017attention-a241", "")), ("vaswani2017attention-a241.v2", ("vaswani2017attention-a241", ".v2")), ("vaswani2017attention-a241.si.x-y", ("vaswani2017attention-a241", ".si.x-y")), ], ) def test_split_key(dkey, parts): assert keys.split_key(dkey) == parts @pytest.mark.parametrize( "dkey", [ "", "vaswani", "Vaswani2017-a241", "vaswani2017-a24", "vaswani2017-a24i", "vaswani2017-a241.", "vaswani2017-a241..v2", "vaswani2017-a241.V2", "2017vaswani-a241", "a-b-c0de", ], ) def test_split_key_refuses_what_is_not_a_document_key(dkey): with pytest.raises(ValueError, match="is not a document key"): keys.split_key(dkey) def test_suffix_of_takes_the_part_after_the_last_hyphen(): assert keys.suffix_of("vaswani2017attention-a241") == "a241" assert keys.suffix_of("a-b-c0de") == "c0de" class TestSuffixAgrees: DOI: ClassVar[list] = ["doi:10.5555/example"] def test_an_identifier_identity_is_held_to_the_key(self): key = keys.work_key(self.DOI, META) assert keys.suffix_agrees(key, self.DOI, META) long_key = keys.work_key(self.DOI, META, 8) assert keys.suffix_agrees(long_key, self.DOI, META) def test_a_different_hash_part_disagrees(self): key = keys.work_key(self.DOI, META) other = key[:-1] + ("0" if key[-1] != "0" else "1") assert not keys.suffix_agrees(other, self.DOI, META) def test_a_metadata_identity_is_not_held_to_the_key(self): assert keys.suffix_agrees("vaswani2017attention-zzzz", [], META) @given( st.text(max_size=30), st.text(max_size=20), st.one_of(st.none(), st.integers(min_value=0, max_value=99999)), ) @PROPERTIES def test_any_metadata_gives_a_valid_work_key_and_document_key(title, family, year): meta = {"title": title, "author": [{"family": family}]} if year is not None: meta["issued"] = {"date-parts": [[year]]} key = keys.work_key([], meta) assert keys.WORK_KEY_RE.match(key) document = keys.document_key(key, {"type": "preprint", "seq": 2}) assert keys.DOCUMENT_KEY_RE.match(document) assert keys.split_key(document) == (key, ".v2") assert keys.suffix_agrees(key, [], meta)