sci-protocol 0.2.0__py3-none-any.whl

pysci/citations.py

@@ -0,0 +1,233 @@
+"""Citation targets (protocol §4.4): validation and comparison keys.
+
+Three target forms are permitted:
+
+* ``sci:sha256:<digest>`` -- an SCI publication;
+* ``doi:<name>`` -- a DOI URI (DOI names compare case-insensitively for ASCII
+  after percent-decoding);
+* an ``http``/``https`` URI (RFC 9110 §4.2) with an optional fragment.
+
+:func:`citation_target_key` derives a normalized key so that equivalent
+spellings of the same DOI or URL can be grouped, e.g. by an indexer.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Final
+
+from .ids import is_digest
+
+__all__ = [
+    "CITATION_RELATIONS",
+    "CitationTarget",
+    "TargetKind",
+    "citation_target_key",
+    "is_http_uri",
+    "parse_citation_target",
+]
+
+CITATION_RELATIONS: Final = frozenset({"uses", "reviews", "supports", "challenges", "supersedes"})
+
+_UNRESERVED: Final = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~")
+_SUB_DELIMS: Final = frozenset("!$&'()*+,;=")
+_PCHAR: Final = _UNRESERVED | _SUB_DELIMS | frozenset(":@")
+_PATH_CHARS: Final = _PCHAR | frozenset("/")
+_QUERY_CHARS: Final = _PCHAR | frozenset("/?")
+_REG_NAME_CHARS: Final = _UNRESERVED | _SUB_DELIMS
+_HEX: Final = frozenset("0123456789abcdefABCDEF")
+
+_HTTP_URI: Final = re.compile(
+    r"(?P<scheme>[A-Za-z][A-Za-z0-9+.-]*)://(?P<authority>[^/?#]*)(?P<path>[^?#]*)"
+    r"(?:\?(?P<query>[^#]*))?(?:#(?P<fragment>.*))?",
+    re.DOTALL,
+)
+_DOI: Final = re.compile(r"doi:(?P<prefix>10\.[0-9]+(?:\.[0-9]+)*)/(?P<suffix>.+)", re.DOTALL)
+
+
+class TargetKind(StrEnum):
+    SCI = "sci"
+    DOI = "doi"
+    URL = "url"
+
+
+@dataclass(frozen=True, slots=True)
+class CitationTarget:
+    """A validated citation target and its comparison key."""
+
+    kind: TargetKind
+    target: str
+    key: str
+
+
+def _valid_chars(value: str, allowed: frozenset[str]) -> bool:
+    """True if ``value`` uses only ``allowed`` characters and valid %HH escapes."""
+    index = 0
+    length = len(value)
+    while index < length:
+        ch = value[index]
+        if ch == "%":
+            if index + 2 >= length:
+                return False
+            if value[index + 1] not in _HEX or value[index + 2] not in _HEX:
+                return False
+            index += 3
+            continue
+        if ch not in allowed:
+            return False
+        index += 1
+    return True
+
+
+def _valid_authority(authority: str) -> bool:
+    if not authority or "@" in authority:
+        # RFC 9110 §4.2.1: an empty host is invalid; userinfo is deprecated
+        # and treated as an error by recipients (§4.2.4).
+        return False
+    if authority.startswith("["):
+        end = authority.find("]")
+        if end < 0:
+            return False
+        literal, rest = authority[1:end], authority[end + 1 :]
+        try:
+            ipaddress.IPv6Address(literal)
+        except ValueError:
+            return False
+        port = rest[1:] if rest.startswith(":") else None
+        if rest and port is None:
+            return False
+    else:
+        host, sep, port_text = authority.partition(":")
+        port = port_text if sep else None
+        if not host or not _valid_chars(host, _REG_NAME_CHARS):
+            return False
+    return port is None or port.isdigit() or port == ""
+
+
+def is_http_uri(value: str) -> bool:
+    """True for an absolute ``http``/``https`` URI with an optional fragment."""
+    match = _HTTP_URI.fullmatch(value)
+    if match is None or match["scheme"].lower() not in ("http", "https"):
+        return False
+    if not value.isascii():
+        return False
+    if not _valid_authority(match["authority"]):
+        return False
+    if not _valid_chars(match["path"], _PATH_CHARS):
+        return False
+    query = match["query"]
+    if query is not None and not _valid_chars(query, _QUERY_CHARS):
+        return False
+    fragment = match["fragment"]
+    return fragment is None or _valid_chars(fragment, _QUERY_CHARS)
+
+
+def _percent_normalize(value: str, keep: frozenset[str], *, fold_case: bool = False) -> str:
+    """Decode %HH into bytes, optionally ASCII-lowercase, and re-encode canonically.
+
+    Characters in ``keep`` (and unreserved characters) are written literally;
+    every other byte becomes an uppercase %HH escape.
+    """
+    raw = bytearray()
+    index = 0
+    while index < len(value):
+        ch = value[index]
+        if ch == "%":
+            raw.append(int(value[index + 1 : index + 3], 16))
+            index += 3
+        else:
+            raw.extend(ch.encode("utf-8"))
+            index += 1
+    if fold_case:
+        raw = bytearray(raw.lower())  # bytes.lower() affects ASCII letters only
+    out = []
+    literal = keep | _UNRESERVED
+    for byte in raw:
+        ch = chr(byte)
+        out.append(ch if byte < 0x80 and ch in literal else f"%{byte:02X}")
+    return "".join(out)
+
+
+def _normalize_escapes(value: str, *, lower: bool = False) -> str:
+    """RFC 3986 §6.2.2: uppercase %HH, decode escaped unreserved characters only."""
+    out: list[str] = []
+    index = 0
+    while index < len(value):
+        ch = value[index]
+        if ch == "%":
+            byte = int(value[index + 1 : index + 3], 16)
+            decoded = chr(byte)
+            if decoded in _UNRESERVED:
+                out.append(decoded.lower() if lower else decoded)
+            else:
+                out.append(f"%{byte:02X}")
+            index += 3
+        else:
+            out.append(ch.lower() if lower else ch)
+            index += 1
+    return "".join(out)
+
+
+def _url_key(value: str) -> str:
+    match = _HTTP_URI.fullmatch(value)
+    if match is None:  # pragma: no cover - validated before
+        raise ValueError("not an HTTP URI")
+    scheme = match["scheme"].lower()
+    authority = match["authority"]
+    if authority.startswith("["):
+        end = authority.index("]")
+        host = "[" + str(ipaddress.IPv6Address(authority[1:end])) + "]"
+        port = authority[end + 2 :] if authority[end + 1 :].startswith(":") else ""
+    else:
+        host_text, _, port = authority.partition(":")
+        host = _normalize_escapes(host_text, lower=True)
+    if port and port.lstrip("0") == ("80" if scheme == "http" else "443"):
+        port = ""
+    port = port.lstrip("0") or ("0" if port else "")
+    path = _normalize_escapes(match["path"]) or "/"
+    key = f"{scheme}://{host}{':' + port if port else ''}{path}"
+    if match["query"] is not None:
+        key += "?" + _normalize_escapes(match["query"])
+    if match["fragment"] is not None:
+        key += "#" + _normalize_escapes(match["fragment"])
+    return key
+
+
+def parse_citation_target(target: str) -> CitationTarget | None:
+    """Validate a §4.4 target; None if it uses none of the permitted forms."""
+    if target.startswith("sci:"):
+        digest = target[len("sci:sha256:") :] if target.startswith("sci:sha256:") else ""
+        if not is_digest(digest):
+            return None
+        return CitationTarget(TargetKind.SCI, target, target)
+    if target.startswith("doi:"):
+        match = _DOI.fullmatch(target)
+        if match is None or not target.isascii() or not _valid_chars(match["suffix"], _PATH_CHARS):
+            return None
+        suffix = _percent_normalize(match["suffix"], _PATH_CHARS - _UNRESERVED, fold_case=True)
+        return CitationTarget(TargetKind.DOI, target, f"doi:{match['prefix']}/{suffix}")
+    if is_http_uri(target):
+        return CitationTarget(TargetKind.URL, target, _url_key(target))
+    return None
+
+
+def citation_target_key(target: str) -> str:
+    """Normalized comparison key for a citation target.
+
+    * SCI targets are returned unchanged (they are already canonical).
+    * DOI targets are percent-decoded, ASCII-lowercased, and re-encoded with
+      uppercase escapes for every byte outside RFC 3986 ``pchar``/``/``.
+    * URLs get RFC 3986 §6.2.2-6.2.3 normalization: lowercase scheme and host,
+      default port removed, empty path as ``/``, percent-encoding normalized.
+      The fragment is retained.
+
+    Raises:
+        ValueError: ``target`` is not a valid citation target.
+    """
+    parsed = parse_citation_target(target)
+    if parsed is None:
+        raise ValueError("not a valid SCI, DOI, or HTTP(S) citation target")
+    return parsed.key

pysci/data/freetsa-cacert.pem

@@ -0,0 +1,45 @@
+-----BEGIN CERTIFICATE-----
+MIIH/zCCBeegAwIBAgIJAMHphhYNqOmAMA0GCSqGSIb3DQEBDQUAMIGVMREwDwYD
+VQQKEwhGcmVlIFRTQTEQMA4GA1UECxMHUm9vdCBDQTEYMBYGA1UEAxMPd3d3LmZy
+ZWV0c2Eub3JnMSIwIAYJKoZIhvcNAQkBFhNidXNpbGV6YXNAZ21haWwuY29tMRIw
+EAYDVQQHEwlXdWVyemJ1cmcxDzANBgNVBAgTBkJheWVybjELMAkGA1UEBhMCREUw
+HhcNMTYwMzEzMDE1MjEzWhcNNDEwMzA3MDE1MjEzWjCBlTERMA8GA1UEChMIRnJl
+ZSBUU0ExEDAOBgNVBAsTB1Jvb3QgQ0ExGDAWBgNVBAMTD3d3dy5mcmVldHNhLm9y
+ZzEiMCAGCSqGSIb3DQEJARYTYnVzaWxlemFzQGdtYWlsLmNvbTESMBAGA1UEBxMJ
+V3VlcnpidXJnMQ8wDQYDVQQIEwZCYXllcm4xCzAJBgNVBAYTAkRFMIICIjANBgkq
+hkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAtgKODjAy8REQ2WTNqUudAnjhlCrpE6ql
+mQfNppeTmVvZrH4zutn+NwTaHAGpjSGv4/WRpZ1wZ3BRZ5mPUBZyLgq0YrIfQ5Fx
+0s/MRZPzc1r3lKWrMR9sAQx4mN4z11xFEO529L0dFJjPF9MD8Gpd2feWzGyptlel
+b+PqT+++fOa2oY0+NaMM7l/xcNHPOaMz0/2olk0i22hbKeVhvokPCqhFhzsuhKsm
+q4Of/o+t6dI7sx5h0nPMm4gGSRhfq+z6BTRgCrqQG2FOLoVFgt6iIm/BnNffUr7V
+DYd3zZmIwFOj/H3DKHoGik/xK3E82YA2ZulVOFRW/zj4ApjPa5OFbpIkd0pmzxzd
+EcL479hSA9dFiyVmSxPtY5ze1P+BE9bMU1PScpRzw8MHFXxyKqW13Qv7LWw4sbk3
+SciB7GACbQiVGzgkvXG6y85HOuvWNvC5GLSiyP9GlPB0V68tbxz4JVTRdw/Xn/XT
+FNzRBM3cq8lBOAVt/PAX5+uFcv1S9wFE8YjaBfWCP1jdBil+c4e+0tdywT2oJmYB
+BF/kEt1wmGwMmHunNEuQNzh1FtJY54hbUfiWi38mASE7xMtMhfj/C4SvapiDN837
+gYaPfs8x3KZxbX7C3YAsFnJinlwAUss1fdKar8Q/YVs7H/nU4c4Ixxxz4f67fcVq
+M2ITKentbCMCAwEAAaOCAk4wggJKMAwGA1UdEwQFMAMBAf8wDgYDVR0PAQH/BAQD
+AgHGMB0GA1UdDgQWBBT6VQ2MNGZRQ0z357OnbJWveuaklzCBygYDVR0jBIHCMIG/
+gBT6VQ2MNGZRQ0z357OnbJWveuakl6GBm6SBmDCBlTERMA8GA1UEChMIRnJlZSBU
+U0ExEDAOBgNVBAsTB1Jvb3QgQ0ExGDAWBgNVBAMTD3d3dy5mcmVldHNhLm9yZzEi
+MCAGCSqGSIb3DQEJARYTYnVzaWxlemFzQGdtYWlsLmNvbTESMBAGA1UEBxMJV3Vl
+cnpidXJnMQ8wDQYDVQQIEwZCYXllcm4xCzAJBgNVBAYTAkRFggkAwemGFg2o6YAw
+MwYDVR0fBCwwKjAooCagJIYiaHR0cDovL3d3dy5mcmVldHNhLm9yZy9yb290X2Nh
+LmNybDCBzwYDVR0gBIHHMIHEMIHBBgorBgEEAYHyJAEBMIGyMDMGCCsGAQUFBwIB
+FidodHRwOi8vd3d3LmZyZWV0c2Eub3JnL2ZyZWV0c2FfY3BzLmh0bWwwMgYIKwYB
+BQUHAgEWJmh0dHA6Ly93d3cuZnJlZXRzYS5vcmcvZnJlZXRzYV9jcHMucGRmMEcG
+CCsGAQUFBwICMDsaOUZyZWVUU0EgdHJ1c3RlZCB0aW1lc3RhbXBpbmcgU29mdHdh
+cmUgYXMgYSBTZXJ2aWNlIChTYWFTKTA3BggrBgEFBQcBAQQrMCkwJwYIKwYBBQUH
+MAGGG2h0dHA6Ly93d3cuZnJlZXRzYS5vcmc6MjU2MDANBgkqhkiG9w0BAQ0FAAOC
+AgEAaK9+v5OFYu9M6ztYC+L69sw1omdyli89lZAfpWMMh9CRmJhM6KBqM/ipwoLt
+nxyxGsbCPhcQjuTvzm+ylN6VwTMmIlVyVSLKYZcdSjt/eCUN+41K7sD7GVmxZBAF
+ILnBDmTGJmLkrU0KuuIpj8lI/E6Z6NnmuP2+RAQSHsfBQi6sssnXMo4HOW5gtPO7
+gDrUpVXID++1P4XndkoKn7Svw5n0zS9fv1hxBcYIHPPQUze2u30bAQt0n0iIyRLz
+aWuhtpAtd7ffwEbASgzB7E+NGF4tpV37e8KiA2xiGSRqT5ndu28fgpOY87gD3ArZ
+DctZvvTCfHdAS5kEO3gnGGeZEVLDmfEsv8TGJa3AljVa5E40IQDsUXpQLi8G+UC4
+1DWZu8EVT4rnYaCw1VX7ShOR1PNCCvjb8S8tfdudd9zhU3gEB0rxdeTy1tVbNLXW
+99y90xcwr1ZIDUwM/xQ/noO8FRhm0LoPC73Ef+J4ZBdrvWwauF3zJe33d4ibxEcb
+8/pz5WzFkeixYM2nsHhqHsBKw7JPouKNXRnl5IAE1eFmqDyC7G/VT7OF669xM6hb
+Ut5G21JE4cNK6NNucS+fzg1JPX0+3VhsYZjj7D5uljRvQXrJ8iHgr/M6j2oLHvTA
+I2MLdq2qjZFDOCXsxBxJpbmLGBx9ow6ZerlUxzws2AWv2pk=
+-----END CERTIFICATE-----