citesync 0.1.0__py3-none-any.whl

citesync/mapping-local.json

@@ -0,0 +1,408 @@
+{
+  "schema_version": "1.0",
+  "codemeta_tag": "3.1",
+  "generator": {
+    "name": "codemeta-drift",
+    "version": "0.1.0"
+  },
+  "rows": [
+    {
+      "format": "cff-1.2.0",
+      "term": "name",
+      "path": "title",
+      "source": "crosswalk:crosswalks/Citation File Format 1.2.0.csv@3.1"
+    },
+    {
+      "format": "cff-1.2.0",
+      "term": "version",
+      "path": "version",
+      "source": "crosswalk:crosswalks/Citation File Format 1.2.0.csv@3.1"
+    },
+    {
+      "format": "cff-1.2.0",
+      "term": "author",
+      "path": "authors[]",
+      "source": "crosswalk:crosswalks/Citation File Format 1.2.0.csv@3.1"
+    },
+    {
+      "format": "cff-1.2.0",
+      "term": "author.givenName",
+      "path": "authors[].given-names",
+      "source": "crosswalk:crosswalks/Citation File Format 1.2.0.csv@3.1"
+    },
+    {
+      "format": "cff-1.2.0",
+      "term": "author.familyName",
+      "path": "authors[].family-names",
+      "source": "crosswalk:crosswalks/Citation File Format 1.2.0.csv@3.1"
+    },
+    {
+      "format": "cff-1.2.0",
+      "term": "author.@id",
+      "path": "authors[].orcid",
+      "source": "curated:the cell lists person.orcid / identifiers / doi; a person's ORCID is orcid"
+    },
+    {
+      "format": "cff-1.2.0",
+      "term": "license",
+      "path": "license",
+      "source": "curated:the cell lists license / license-url; license-url holds a licence URL, not an SPDX id"
+    },
+    {
+      "format": "cff-1.2.0",
+      "term": "identifier",
+      "path": "doi | identifiers[type=doi].value",
+      "source": "curated:the cell lists identifiers / person.orcid / doi; the software DOI is doi, or the doi entry of identifiers"
+    },
+    {
+      "format": "cff-1.2.0",
+      "term": "codeRepository",
+      "path": "repository-code",
+      "source": "crosswalk:crosswalks/Citation File Format 1.2.0.csv@3.1"
+    },
+    {
+      "format": "cff-1.2.0",
+      "term": "description",
+      "path": "abstract",
+      "source": "crosswalk:crosswalks/Citation File Format 1.2.0.csv@3.1"
+    },
+    {
+      "format": "cff-1.2.0",
+      "term": "keywords",
+      "path": "keywords",
+      "source": "crosswalk:crosswalks/Citation File Format 1.2.0.csv@3.1"
+    },
+    {
+      "format": "codemeta",
+      "term": "name",
+      "path": "name",
+      "source": "curated:codemeta's own term"
+    },
+    {
+      "format": "codemeta",
+      "term": "version",
+      "path": "version",
+      "source": "curated:codemeta's own term"
+    },
+    {
+      "format": "codemeta",
+      "term": "author",
+      "path": "author[]",
+      "source": "curated:codemeta's own term"
+    },
+    {
+      "format": "codemeta",
+      "term": "author.givenName",
+      "path": "author[].givenName",
+      "source": "curated:codemeta's own term"
+    },
+    {
+      "format": "codemeta",
+      "term": "author.familyName",
+      "path": "author[].familyName",
+      "source": "curated:codemeta's own term"
+    },
+    {
+      "format": "codemeta",
+      "term": "author.@id",
+      "path": "author[].@id",
+      "source": "curated:codemeta's own term"
+    },
+    {
+      "format": "codemeta",
+      "term": "license",
+      "path": "license",
+      "source": "curated:codemeta's own term"
+    },
+    {
+      "format": "codemeta",
+      "term": "identifier",
+      "path": "identifier",
+      "source": "curated:codemeta's own term"
+    },
+    {
+      "format": "codemeta",
+      "term": "codeRepository",
+      "path": "codeRepository",
+      "source": "curated:codemeta's own term"
+    },
+    {
+      "format": "codemeta",
+      "term": "description",
+      "path": "description",
+      "source": "curated:codemeta's own term"
+    },
+    {
+      "format": "codemeta",
+      "term": "keywords",
+      "path": "keywords",
+      "source": "curated:codemeta's own term"
+    },
+    {
+      "format": "zenodo",
+      "term": "name",
+      "path": "title",
+      "source": "crosswalk:crosswalks/Zenodo.csv@3.1"
+    },
+    {
+      "format": "zenodo",
+      "term": "version",
+      "path": "version",
+      "source": "crosswalk:crosswalks/Zenodo.csv@3.1"
+    },
+    {
+      "format": "zenodo",
+      "term": "author",
+      "path": "creators[]",
+      "source": "crosswalk:crosswalks/Zenodo.csv@3.1"
+    },
+    {
+      "format": "zenodo",
+      "term": "author.givenName",
+      "path": "creators[].name",
+      "source": "curated:no cell; Zenodo keeps one name string per creator, written 'Family, Given'"
+    },
+    {
+      "format": "zenodo",
+      "term": "author.familyName",
+      "path": "creators[].name",
+      "source": "curated:no cell; Zenodo keeps one name string per creator, written 'Family, Given'"
+    },
+    {
+      "format": "zenodo",
+      "term": "author.@id",
+      "path": "creators[].orcid",
+      "source": "curated:the cell says ORCID; the .zenodo.json key is orcid"
+    },
+    {
+      "format": "zenodo",
+      "term": "license",
+      "path": "license",
+      "source": "crosswalk:crosswalks/Zenodo.csv@3.1"
+    },
+    {
+      "format": "zenodo",
+      "term": "identifier",
+      "path": "doi",
+      "source": "curated:the cell says id, the Zenodo record id; the DOI field is doi",
+      "comment": "The GitHub integration mints the DOI and normally leaves doi unset in .zenodo.json."
+    },
+    {
+      "format": "zenodo",
+      "term": "codeRepository",
+      "path": "related_identifiers[relation=isSupplementTo].identifier",
+      "source": "curated:the cell says related_identifiers.isSupplementTo, a relation, not a key; the URL is the identifier of the entry with that relation"
+    },
+    {
+      "format": "zenodo",
+      "term": "description",
+      "path": "description",
+      "source": "crosswalk:crosswalks/Zenodo.csv@3.1"
+    },
+    {
+      "format": "zenodo",
+      "term": "keywords",
+      "path": "keywords",
+      "source": "crosswalk:crosswalks/Zenodo.csv@3.1"
+    },
+    {
+      "format": "pep621",
+      "term": "name",
+      "path": "project.name",
+      "source": "curated:no PEP 621 crosswalk upstream"
+    },
+    {
+      "format": "pep621",
+      "term": "version",
+      "path": "project.version",
+      "source": "curated:no PEP 621 crosswalk upstream"
+    },
+    {
+      "format": "pep621",
+      "term": "author",
+      "path": "project.authors[]",
+      "source": "curated:no PEP 621 crosswalk upstream"
+    },
+    {
+      "format": "pep621",
+      "term": "author.givenName",
+      "path": "project.authors[].name",
+      "source": "curated:no PEP 621 crosswalk upstream; an author has one name string"
+    },
+    {
+      "format": "pep621",
+      "term": "author.familyName",
+      "path": "project.authors[].name",
+      "source": "curated:no PEP 621 crosswalk upstream; an author has one name string"
+    },
+    {
+      "format": "pep621",
+      "term": "author.@id",
+      "path": null,
+      "source": "curated:no PEP 621 crosswalk upstream; PEP 621 has no person identifier"
+    },
+    {
+      "format": "pep621",
+      "term": "license",
+      "path": "project.license",
+      "source": "curated:no PEP 621 crosswalk upstream",
+      "comment": "An SPDX expression string since PEP 639. The legacy {text = ...} or {file = ...} table is the same key in an older shape."
+    },
+    {
+      "format": "pep621",
+      "term": "identifier",
+      "path": null,
+      "source": "curated:no PEP 621 crosswalk upstream; PEP 621 has no DOI field"
+    },
+    {
+      "format": "pep621",
+      "term": "codeRepository",
+      "path": "project.urls.Source | project.urls.Repository | project.urls.Homepage",
+      "source": "curated:no PEP 621 crosswalk upstream"
+    },
+    {
+      "format": "pep621",
+      "term": "description",
+      "path": "project.description",
+      "source": "curated:no PEP 621 crosswalk upstream"
+    },
+    {
+      "format": "pep621",
+      "term": "keywords",
+      "path": "project.keywords",
+      "source": "curated:no PEP 621 crosswalk upstream"
+    },
+    {
+      "format": "cargo",
+      "term": "name",
+      "path": "package.name",
+      "source": "curated:the cell says package.authors; the crate name is package.name"
+    },
+    {
+      "format": "cargo",
+      "term": "version",
+      "path": "package.version",
+      "source": "crosswalk:crosswalks/Cargo.csv@3.1"
+    },
+    {
+      "format": "cargo",
+      "term": "author",
+      "path": "package.authors[]",
+      "source": "crosswalk:crosswalks/Cargo.csv@3.1"
+    },
+    {
+      "format": "cargo",
+      "term": "author.givenName",
+      "path": "package.authors[]",
+      "source": "curated:no cell; Cargo keeps one 'Name <email>' string per author"
+    },
+    {
+      "format": "cargo",
+      "term": "author.familyName",
+      "path": "package.authors[]",
+      "source": "curated:no cell; Cargo keeps one 'Name <email>' string per author"
+    },
+    {
+      "format": "cargo",
+      "term": "author.@id",
+      "path": null,
+      "source": "curated:no cell; Cargo has no person identifier"
+    },
+    {
+      "format": "cargo",
+      "term": "license",
+      "path": "package.license",
+      "source": "crosswalk:crosswalks/Cargo.csv@3.1"
+    },
+    {
+      "format": "cargo",
+      "term": "identifier",
+      "path": null,
+      "source": "curated:no cell; Cargo has no DOI field"
+    },
+    {
+      "format": "cargo",
+      "term": "codeRepository",
+      "path": "package.repository",
+      "source": "crosswalk:crosswalks/Cargo.csv@3.1"
+    },
+    {
+      "format": "cargo",
+      "term": "description",
+      "path": "package.description",
+      "source": "curated:no cell; Cargo has package.description"
+    },
+    {
+      "format": "cargo",
+      "term": "keywords",
+      "path": "package.keywords",
+      "source": "curated:the cell says package.keyword; Cargo's key is package.keywords"
+    },
+    {
+      "format": "npm",
+      "term": "name",
+      "path": "name",
+      "source": "crosswalk:crosswalks/NodeJS.csv@3.1"
+    },
+    {
+      "format": "npm",
+      "term": "version",
+      "path": "version",
+      "source": "crosswalk:crosswalks/NodeJS.csv@3.1"
+    },
+    {
+      "format": "npm",
+      "term": "author",
+      "path": "author",
+      "source": "crosswalk:crosswalks/NodeJS.csv@3.1"
+    },
+    {
+      "format": "npm",
+      "term": "author.givenName",
+      "path": "author.name",
+      "source": "curated:no cell; the crosswalk's person name row says author.name, one name string"
+    },
+    {
+      "format": "npm",
+      "term": "author.familyName",
+      "path": "author.name",
+      "source": "curated:no cell; the crosswalk's person name row says author.name, one name string"
+    },
+    {
+      "format": "npm",
+      "term": "author.@id",
+      "path": null,
+      "source": "curated:no cell; package.json has no person identifier"
+    },
+    {
+      "format": "npm",
+      "term": "license",
+      "path": "license",
+      "source": "crosswalk:crosswalks/NodeJS.csv@3.1"
+    },
+    {
+      "format": "npm",
+      "term": "identifier",
+      "path": null,
+      "source": "curated:the cell says name, the package name; package.json has no DOI field"
+    },
+    {
+      "format": "npm",
+      "term": "codeRepository",
+      "path": "repository",
+      "source": "crosswalk:crosswalks/NodeJS.csv@3.1"
+    },
+    {
+      "format": "npm",
+      "term": "description",
+      "path": "description",
+      "source": "crosswalk:crosswalks/NodeJS.csv@3.1"
+    },
+    {
+      "format": "npm",
+      "term": "keywords",
+      "path": "keywords",
+      "source": "crosswalk:crosswalks/NodeJS.csv@3.1"
+    }
+  ]
+}

citesync/mapping.py

@@ -0,0 +1,118 @@
+"""The vendored field mapping, and the path grammar its rows use.
+
+The mapping says where each CodeMeta term sits in each format. Its contract is
+docs/mapping-export.md in codemeta-drift, and MAPPING_SOURCE names the
+codemeta-drift release and commit it was copied from.
+"""
+
+import json
+import re
+from functools import cache
+from importlib.resources import files
+from typing import Any
+
+from citesync.errors import CheckError
+
+SCHEMA_MAJOR = "1"
+FORMATS = ("cff-1.2.0", "codemeta", "zenodo", "pep621", "cargo", "npm")
+TERMS = ("name", "version", "author", "license", "identifier", "codeRepository", "description", "keywords")
+PERSON_TERMS = ("author.givenName", "author.familyName", "author.@id")
+
+_STEP = re.compile(r"^(@?[A-Za-z_][A-Za-z0-9_-]*)(?:\[\]|\[(@?[A-Za-z_][A-Za-z0-9_-]*)=([A-Za-z0-9_.-]+)\])?$")
+
+type Mapping = dict[tuple[str, str], str | None]
+"""(format, term) to path, or None when the format has no place for the term."""
+
+
+@cache
+def load_mapping() -> Mapping:
+    """Read the vendored mapping and check what citesync needs from it.
+
+    Raises:
+        CheckError: on an unknown schema major, a duplicate row, or a missing row
+            for a term citesync reads.
+    """
+    name = "mapping-local.json"
+    data = json.loads(files("citesync").joinpath(name).read_text(encoding="utf-8"))
+    return check_mapping(data, name)
+
+
+def check_mapping(data: dict[str, Any], name: str) -> Mapping:
+    """Turn a parsed mapping export into a lookup table, refusing what citesync can't use."""
+    major = str(data.get("schema_version", "")).split(".")[0]
+    if major != SCHEMA_MAJOR:
+        msg = f"{name}: schema_version {data.get('schema_version')!r}, this build reads {SCHEMA_MAJOR}.x"
+        raise CheckError(msg)
+    rows: Mapping = {}
+    for row in data["rows"]:
+        key = (row["format"], row["term"])
+        if key in rows:
+            msg = f"{name}: two rows for {key[0]} {key[1]}"
+            raise CheckError(msg)
+        rows[key] = row["path"]
+    missing = [f"{fmt} {term}" for fmt in FORMATS for term in TERMS + PERSON_TERMS if (fmt, term) not in rows]
+    if missing:
+        msg = f"{name}: no row for {', '.join(missing)}"
+        raise CheckError(msg)
+    for (fmt, term), path in rows.items():
+        if path is not None and fmt in FORMATS:
+            _parse(path)  # fail on load, not on the first file that uses the row
+        if term in PERSON_TERMS and path is not None and rows.get((fmt, "author")) is None:
+            msg = f"{name}: {fmt} {term} has a path but {fmt} author has none"
+            raise CheckError(msg)
+    return rows
+
+
+def _parse(path: str) -> list[list[tuple[str, str | None, str | None, bool]]]:
+    """Split a path into alternatives of steps: (key, filter key, filter value, is a list step)."""
+    alternatives = []
+    for alternative in path.split(" | "):
+        steps = []
+        for step in alternative.split("."):
+            match = _STEP.match(step)
+            if not match:
+                msg = f"mapping path {path!r}: bad step {step!r}"
+                raise CheckError(msg)
+            steps.append((match[1], match[2], match[3], step.endswith("]")))
+        alternatives.append(steps)
+    return alternatives
+
+
+def resolve(doc: Any, path: str) -> list[Any]:  # noqa: ANN401 - parsed JSON, TOML or YAML
+    """Every value at ``path`` in ``doc``, from the first alternative that has any.
+
+    A plain step reads a key of a mapping; ``key[]`` reads each element of a list;
+    ``key[k=v]`` reads the elements whose ``k`` equals ``v``. An empty list means the
+    path does not exist in ``doc``.
+    """
+    for steps in _parse(path):
+        nodes = [doc]
+        for key, fkey, fvalue, is_list in steps:
+            found = [node[key] for node in nodes if isinstance(node, dict) and key in node]
+            if is_list:
+                elements = [el for value in found if isinstance(value, list) for el in value]
+                if fkey is not None:
+                    elements = [el for el in elements if isinstance(el, dict) and str(el.get(fkey)) == fvalue]
+                found = elements
+            nodes = found
+        if nodes:
+            return nodes
+    return []
+
+
+def relative(path: str, parent: str) -> str:
+    """A person sub-term path relative to its term's path: ``authors[].orcid`` under ``authors[]`` is ``orcid``.
+
+    Each alternative of ``path`` must start with ``parent``. The result is ``""``
+    when the sub-term is the element itself (Cargo's one ``Name <email>`` string).
+    """
+    parts = []
+    for alternative in path.split(" | "):
+        if alternative == parent:
+            parts.append("")
+        elif alternative.startswith(parent + "."):
+            parts.append(alternative.removeprefix(parent + "."))
+        else:
+            msg = f"mapping path {path!r} does not start with its term's path {parent!r}"
+            raise CheckError(msg)
+    return " | ".join(parts)

citesync/mapping.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "codemeta-drift mapping export",
+  "description": "Where each CodeMeta term sits in each metadata format, read from one CodeMeta release (mapping-<codemeta_tag>.json). A row says where a value is, never how it is spelled: SPDX URL or id, ORCID URL or bare iD, 'Family, Given' and DOI forms are the consumer's business. Fields this schema does not define are allowed, so a reader that knows an older minor accepts a newer file. Contract and compatibility rules: https://github.com/simonvanlierde/codemeta-drift/blob/main/docs/mapping-export.md.",
+  "type": "object",
+  "required": ["schema_version", "codemeta_tag", "generator", "rows"],
+  "properties": {
+    "schema_version": {
+      "description": "'MAJOR.MINOR' of this schema. A consumer reads the major before anything else and stops on one it does not know. A minor adds optional fields, formats or terms and never changes what an existing field means.",
+      "type": "string",
+      "pattern": "^1\\.(0|[1-9][0-9]*)$"
+    },
+    "codemeta_tag": {
+      "description": "The codemeta/codemeta tag the crosswalk rows were read from, such as '3.1'.",
+      "type": "string",
+      "minLength": 1
+    },
+    "generator": {
+      "description": "The tool that wrote the file and its version. A hand-written file says so in a local version label, such as '0.1.0+hand'.",
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "rows": {
+      "description": "One row per (format, term). A pair appears at most once; JSON Schema cannot say that, so consumers check it.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/row" }
+    }
+  },
+  "$defs": {
+    "row": {
+      "type": "object",
+      "required": ["format", "term", "path", "source"],
+      "properties": {
+        "format": {
+          "description": "Stable format id: cff-1.2.0, codemeta, zenodo, pep621, cargo, npm. A versioned format puts its version in the id.",
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(-[a-z0-9.]+)*$"
+        },
+        "term": {
+          "description": "A CodeMeta term (name, version, author, license, identifier, codeRepository, description, keywords), or a person sub-term qualified by the term it sits under: author.givenName, author.familyName, author.@id (ORCID).",
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9]*(\\.@?[A-Za-z][A-Za-z0-9]*)?$"
+        },
+        "path": {
+          "description": "Where the value sits in the format's file, or null when the format has no place for it. Grammar: steps joined by '.'; a step is a key, a key followed by '[]' (each element of a list), or a key followed by '[k=v]' (each element whose k equals v). A key may contain letters, digits, '_' and '-', and may start with '@'. ' | ' separates alternatives, read left to right: the first that exists wins. A sub-term path is absolute and starts with its parent term's path. Examples: package.keywords, authors[].given-names, identifiers[type=doi].value, project.urls.Source | project.urls.Repository.",
+          "type": ["string", "null"],
+          "pattern": "^@?[A-Za-z_][A-Za-z0-9_-]*(\\[\\]|\\[@?[A-Za-z_][A-Za-z0-9_-]*=[A-Za-z0-9_.-]+\\])?(\\.@?[A-Za-z_][A-Za-z0-9_-]*(\\[\\]|\\[@?[A-Za-z_][A-Za-z0-9_-]*=[A-Za-z0-9_.-]+\\])?)*( \\| @?[A-Za-z_][A-Za-z0-9_-]*(\\[\\]|\\[@?[A-Za-z_][A-Za-z0-9_-]*=[A-Za-z0-9_.-]+\\])?(\\.@?[A-Za-z_][A-Za-z0-9_-]*(\\[\\]|\\[@?[A-Za-z_][A-Za-z0-9_-]*=[A-Za-z0-9_.-]+\\])?)*)*$"
+        },
+        "source": {
+          "description": "Why the row says what it says. 'crosswalk:<file>@<tag>' when the path reads the cell of that CodeMeta crosswalk; 'curated:<reason>' when the row departs from the crosswalk or the crosswalk has no cell.",
+          "type": "string",
+          "pattern": "^(crosswalk:crosswalks/[^@]+\\.csv@[^@\\s]+|curated:\\S.*)$"
+        },
+        "see_also": {
+          "description": "Upstream issue or pull request that reports the crosswalk cell this row departs from.",
+          "type": "string",
+          "pattern": "^https://"
+        },
+        "comment": {
+          "description": "Free text for a human reader. Never machine-read.",
+          "type": "string"
+        }
+      }
+    }
+  }
+}