Skip to content

Commit 5e40525

Browse files
committed
feat(user-sync): add orcid public api client
1 parent 90bf3da commit 5e40525

2 files changed

Lines changed: 294 additions & 0 deletions

File tree

‎src/osw/tools/user_sync/sources.py‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,14 @@
77
from __future__ import annotations
88

99
import re
10+
import time
1011
from dataclasses import dataclass, field
1112
from typing import Any, Dict, Iterable, Iterator, List, Optional, Sequence
1213

14+
import requests
15+
16+
from .config import ORCID_API_BASE_DEFAULT
17+
1318
# An ORCID iD is 16 digits in groups of four; the last character may be an X.
1419
ORCID_RE = re.compile(r"^\d{4}-\d{4}-\d{4}-\d{3}[\dX]$")
1520

@@ -106,3 +111,145 @@ def partition_by_orcid(users: Iterable[MwUser]) -> Dict[str, List[MwUser]]:
106111
for user in users:
107112
(orcid if user.is_orcid else other).append(user)
108113
return {"orcid": orcid, "other": other}
114+
115+
116+
class OrcidRateLimitError(RuntimeError):
117+
"""Raised when the ORCID public API keeps returning HTTP 429."""
118+
119+
120+
@dataclass
121+
class OrcidAffiliation:
122+
"""An employment entry from an ORCID record."""
123+
124+
organization: str
125+
ror_id: Optional[str] = None
126+
department: Optional[str] = None
127+
role: Optional[str] = None
128+
129+
130+
@dataclass
131+
class OrcidProfile:
132+
"""The subset of a public ORCID record that maps to an OSW User item."""
133+
134+
orcid_id: str
135+
given_names: Optional[str] = None
136+
family_name: Optional[str] = None
137+
credit_name: Optional[str] = None
138+
other_names: List[str] = field(default_factory=list)
139+
emails: List[str] = field(default_factory=list)
140+
urls: List[str] = field(default_factory=list)
141+
affiliations: List[OrcidAffiliation] = field(default_factory=list)
142+
143+
@property
144+
def orcid_uri(self) -> str:
145+
return f"https://orcid.org/{self.orcid_id}"
146+
147+
@property
148+
def display_name(self) -> Optional[str]:
149+
"""Best full name: credit name, else given + family, else None."""
150+
if self.credit_name:
151+
return self.credit_name
152+
parts = [p for p in (self.given_names, self.family_name) if p]
153+
return " ".join(parts) or None
154+
155+
156+
def _value(node: Any, *keys: str) -> Optional[Any]:
157+
"""Safely walk nested dicts, returning None on any missing key."""
158+
cur = node
159+
for key in keys:
160+
if not isinstance(cur, dict):
161+
return None
162+
cur = cur.get(key)
163+
return cur
164+
165+
166+
def _parse_affiliations(activities: Any) -> List[OrcidAffiliation]:
167+
affiliations: List[OrcidAffiliation] = []
168+
groups = _value(activities, "employments", "affiliation-group") or []
169+
for group in groups:
170+
for summary in group.get("summaries") or []:
171+
emp = summary.get("employment-summary") or {}
172+
org = emp.get("organization") or {}
173+
name = org.get("name")
174+
if not name:
175+
continue
176+
ror = None
177+
disamb = org.get("disambiguated-organization") or {}
178+
if (disamb.get("disambiguation-source") or "").upper() == "ROR":
179+
ror = disamb.get("disambiguated-organization-identifier")
180+
affiliations.append(
181+
OrcidAffiliation(
182+
organization=name,
183+
ror_id=ror,
184+
department=emp.get("department-name"),
185+
role=emp.get("role-title"),
186+
)
187+
)
188+
return affiliations
189+
190+
191+
def parse_orcid_record(data: Dict[str, Any], orcid_id: str) -> OrcidProfile:
192+
"""Parse an ORCID ``/record`` JSON payload into an OrcidProfile (pure)."""
193+
person = data.get("person") or {}
194+
other_names = [
195+
n.get("content")
196+
for n in _value(person, "other-names", "other-name") or []
197+
if n.get("content")
198+
]
199+
emails = [
200+
e.get("email")
201+
for e in _value(person, "emails", "email") or []
202+
if e.get("email")
203+
]
204+
urls = [
205+
_value(u, "url", "value")
206+
for u in _value(person, "researcher-urls", "researcher-url") or []
207+
if _value(u, "url", "value")
208+
]
209+
return OrcidProfile(
210+
orcid_id=orcid_id,
211+
given_names=_value(person, "name", "given-names", "value"),
212+
family_name=_value(person, "name", "family-name", "value"),
213+
credit_name=_value(person, "name", "credit-name", "value"),
214+
other_names=other_names,
215+
emails=emails,
216+
urls=urls,
217+
affiliations=_parse_affiliations(data.get("activities-summary") or {}),
218+
)
219+
220+
221+
def fetch_orcid_record(
222+
orcid_id: str,
223+
session: Optional[requests.Session] = None,
224+
base: str = ORCID_API_BASE_DEFAULT,
225+
timeout: float = 30.0,
226+
max_retries: int = 2,
227+
cache: Optional[Dict[str, Optional[OrcidProfile]]] = None,
228+
) -> Optional[OrcidProfile]:
229+
"""Fetch and parse a public ORCID record.
230+
231+
Returns None when the record does not exist (HTTP 404). Retries on HTTP 429
232+
honoring ``Retry-After`` and raises OrcidRateLimitError if still limited.
233+
"""
234+
if cache is not None and orcid_id in cache:
235+
return cache[orcid_id]
236+
sess = session or requests.Session()
237+
url = f"{base}/{orcid_id}/record"
238+
headers = {"Accept": "application/json"}
239+
result: Optional[OrcidProfile] = None
240+
for attempt in range(max_retries + 1):
241+
resp = sess.get(url, headers=headers, timeout=timeout)
242+
if resp.status_code == 404:
243+
result = None
244+
break
245+
if resp.status_code == 429:
246+
if attempt >= max_retries:
247+
raise OrcidRateLimitError(f"ORCID rate limit for {orcid_id}")
248+
time.sleep(float(resp.headers.get("Retry-After", 1)))
249+
continue
250+
resp.raise_for_status()
251+
result = parse_orcid_record(resp.json(), orcid_id)
252+
break
253+
if cache is not None:
254+
cache[orcid_id] = result
255+
return result
Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
"""Unit tests for the ORCID public-API client."""
2+
3+
import pytest
4+
import requests
5+
6+
from osw.tools.user_sync import sources
7+
from osw.tools.user_sync.sources import (
8+
OrcidProfile,
9+
OrcidRateLimitError,
10+
fetch_orcid_record,
11+
parse_orcid_record,
12+
)
13+
14+
ORCID_ID = "0000-0002-1825-0097"
15+
16+
RECORD = {
17+
"person": {
18+
"name": {
19+
"given-names": {"value": "Jane"},
20+
"family-name": {"value": "Doe"},
21+
"credit-name": {"value": "Jane A. Doe"},
22+
},
23+
"other-names": {"other-name": [{"content": "J. Doe"}]},
24+
"emails": {"email": [{"email": "jane@example.org"}]},
25+
"researcher-urls": {
26+
"researcher-url": [{"url": {"value": "https://jane.example.org"}}]
27+
},
28+
},
29+
"activities-summary": {
30+
"employments": {
31+
"affiliation-group": [
32+
{
33+
"summaries": [
34+
{
35+
"employment-summary": {
36+
"department-name": "Physics",
37+
"role-title": "Researcher",
38+
"organization": {
39+
"name": "Example University",
40+
"disambiguated-organization": {
41+
"disambiguated-organization-identifier": (
42+
"https://ror.org/01abc2345"
43+
),
44+
"disambiguation-source": "ROR",
45+
},
46+
},
47+
}
48+
}
49+
]
50+
}
51+
]
52+
}
53+
},
54+
}
55+
56+
57+
class FakeResponse:
58+
def __init__(self, status_code=200, json_data=None, headers=None):
59+
self.status_code = status_code
60+
self._json = json_data
61+
self.headers = headers or {}
62+
63+
def json(self):
64+
return self._json
65+
66+
def raise_for_status(self):
67+
if self.status_code >= 400:
68+
raise requests.HTTPError(f"status {self.status_code}")
69+
70+
71+
class FakeSession:
72+
def __init__(self, responses):
73+
self._responses = list(responses)
74+
self.calls = 0
75+
76+
def get(self, url, headers=None, timeout=None):
77+
self.calls += 1
78+
return self._responses.pop(0)
79+
80+
81+
def test_parse_record_full():
82+
p = parse_orcid_record(RECORD, ORCID_ID)
83+
assert p.given_names == "Jane"
84+
assert p.family_name == "Doe"
85+
assert p.credit_name == "Jane A. Doe"
86+
assert p.display_name == "Jane A. Doe"
87+
assert p.other_names == ["J. Doe"]
88+
assert p.emails == ["jane@example.org"]
89+
assert p.urls == ["https://jane.example.org"]
90+
assert p.orcid_uri == f"https://orcid.org/{ORCID_ID}"
91+
assert len(p.affiliations) == 1
92+
aff = p.affiliations[0]
93+
assert aff.organization == "Example University"
94+
assert aff.ror_id == "https://ror.org/01abc2345"
95+
assert aff.department == "Physics"
96+
assert aff.role == "Researcher"
97+
98+
99+
def test_parse_record_sparse():
100+
p = parse_orcid_record({"person": {}}, ORCID_ID)
101+
assert p.given_names is None
102+
assert p.display_name is None
103+
assert p.emails == []
104+
assert p.affiliations == []
105+
106+
107+
def test_display_name_falls_back_to_given_family():
108+
p = OrcidProfile(orcid_id=ORCID_ID, given_names="Jane", family_name="Doe")
109+
assert p.display_name == "Jane Doe"
110+
111+
112+
def test_fetch_404_returns_none():
113+
session = FakeSession([FakeResponse(status_code=404)])
114+
assert fetch_orcid_record(ORCID_ID, session=session) is None
115+
116+
117+
def test_fetch_200_parses():
118+
session = FakeSession([FakeResponse(status_code=200, json_data=RECORD)])
119+
p = fetch_orcid_record(ORCID_ID, session=session)
120+
assert p.family_name == "Doe"
121+
122+
123+
def test_fetch_retries_on_429(monkeypatch):
124+
monkeypatch.setattr(sources.time, "sleep", lambda *_: None)
125+
session = FakeSession([
126+
FakeResponse(status_code=429, headers={"Retry-After": "0"}),
127+
FakeResponse(status_code=200, json_data=RECORD),
128+
])
129+
p = fetch_orcid_record(ORCID_ID, session=session)
130+
assert p.given_names == "Jane"
131+
assert session.calls == 2
132+
133+
134+
def test_fetch_raises_when_rate_limited(monkeypatch):
135+
monkeypatch.setattr(sources.time, "sleep", lambda *_: None)
136+
session = FakeSession([FakeResponse(status_code=429) for _ in range(3)])
137+
with pytest.raises(OrcidRateLimitError):
138+
fetch_orcid_record(ORCID_ID, session=session, max_retries=2)
139+
140+
141+
def test_fetch_uses_cache():
142+
session = FakeSession([FakeResponse(status_code=200, json_data=RECORD)])
143+
cache = {}
144+
first = fetch_orcid_record(ORCID_ID, session=session, cache=cache)
145+
second = fetch_orcid_record(ORCID_ID, session=session, cache=cache)
146+
assert first is second
147+
assert session.calls == 1

0 commit comments

Comments
 (0)