Skip to content

Commit 90bf3da

Browse files
committed
feat(user-sync): enumerate and classify mediawiki users
1 parent 217b101 commit 90bf3da

2 files changed

Lines changed: 212 additions & 0 deletions

File tree

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

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
"""External data sources for the user-item sync tool.
2+
3+
This module wraps the MediaWiki ``allusers`` API. The ORCID public-API client is
4+
added in a later phase.
5+
"""
6+
7+
from __future__ import annotations
8+
9+
import re
10+
from dataclasses import dataclass, field
11+
from typing import Any, Dict, Iterable, Iterator, List, Optional, Sequence
12+
13+
# An ORCID iD is 16 digits in groups of four; the last character may be an X.
14+
ORCID_RE = re.compile(r"^\d{4}-\d{4}-\d{4}-\d{3}[\dX]$")
15+
16+
_ALLUSERS_PROPS = "registration|editcount|groups|centralids|blockinfo"
17+
18+
19+
def is_orcid_username(name: str) -> bool:
20+
"""True if a MediaWiki username is an ORCID iD (whitelisted ORCID login)."""
21+
return bool(ORCID_RE.match(name or ""))
22+
23+
24+
@dataclass
25+
class MwUser:
26+
"""A MediaWiki account and the metadata exposed by the ``allusers`` API."""
27+
28+
name: str
29+
userid: Optional[int] = None
30+
registration: Optional[str] = None
31+
editcount: int = 0
32+
groups: List[str] = field(default_factory=list)
33+
blocked: bool = False
34+
35+
@property
36+
def is_orcid(self) -> bool:
37+
return is_orcid_username(self.name)
38+
39+
@property
40+
def orcid_id(self) -> Optional[str]:
41+
"""The bare ORCID iD when the username is one, else None."""
42+
return self.name if self.is_orcid else None
43+
44+
@classmethod
45+
def from_api(cls, raw: Dict[str, Any]) -> MwUser:
46+
return cls(
47+
name=raw["name"],
48+
userid=raw.get("userid"),
49+
registration=raw.get("registration") or None,
50+
editcount=int(raw.get("editcount") or 0),
51+
groups=list(raw.get("groups") or []),
52+
blocked="blockid" in raw,
53+
)
54+
55+
56+
def _iter_allusers(site: Any, batch: Any = "max") -> Iterator[Dict[str, Any]]:
57+
"""Yield raw ``allusers`` records, following API continuation."""
58+
params: Dict[str, Any] = {
59+
"list": "allusers",
60+
"auprop": _ALLUSERS_PROPS,
61+
"aulimit": batch,
62+
}
63+
while True:
64+
resp = site.api("query", **params)
65+
yield from resp.get("query", {}).get("allusers", [])
66+
cont = resp.get("continue")
67+
if not cont:
68+
break
69+
params.update(cont)
70+
71+
72+
def enumerate_mw_users(
73+
site: Any,
74+
excluded_groups: Sequence[str] = ("bot",),
75+
include_non_orcid: bool = True,
76+
limit: Optional[int] = None,
77+
batch: Any = "max",
78+
) -> List[MwUser]:
79+
"""List MediaWiki accounts to sync.
80+
81+
Args:
82+
site: An object exposing ``api("query", ...)`` (an mwclient Site).
83+
excluded_groups: Accounts in any of these groups are skipped (bots).
84+
include_non_orcid: If False, keep only ORCID-username accounts.
85+
limit: Keep at most this many accounts after filtering.
86+
batch: ``aulimit`` value passed to the API.
87+
"""
88+
excluded = set(excluded_groups)
89+
users: List[MwUser] = []
90+
for raw in _iter_allusers(site, batch=batch):
91+
user = MwUser.from_api(raw)
92+
if excluded.intersection(user.groups):
93+
continue
94+
if not include_non_orcid and not user.is_orcid:
95+
continue
96+
users.append(user)
97+
if limit is not None and len(users) >= limit:
98+
break
99+
return users
100+
101+
102+
def partition_by_orcid(users: Iterable[MwUser]) -> Dict[str, List[MwUser]]:
103+
"""Split users into ``{"orcid": [...], "other": [...]}``."""
104+
orcid: List[MwUser] = []
105+
other: List[MwUser] = []
106+
for user in users:
107+
(orcid if user.is_orcid else other).append(user)
108+
return {"orcid": orcid, "other": other}
Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
"""Unit tests for MediaWiki user enumeration and classification."""
2+
3+
from osw.tools.user_sync.sources import (
4+
MwUser,
5+
enumerate_mw_users,
6+
is_orcid_username,
7+
partition_by_orcid,
8+
)
9+
10+
11+
class FakeSite:
12+
"""Mimics mwclient Site.api for list=allusers, with continuation."""
13+
14+
def __init__(self, pages):
15+
self._pages = pages
16+
self.calls = 0
17+
18+
def api(self, action, **params):
19+
assert action == "query"
20+
assert params["list"] == "allusers"
21+
page = self._pages[self.calls]
22+
self.calls += 1
23+
return page
24+
25+
26+
def _page(users, cont=None):
27+
resp = {"query": {"allusers": users}}
28+
if cont is not None:
29+
resp["continue"] = cont
30+
return resp
31+
32+
33+
def test_is_orcid_username():
34+
assert is_orcid_username("0000-0002-6374-9831")
35+
assert is_orcid_username("0000-0003-0930-082X")
36+
assert not is_orcid_username("Alice")
37+
assert not is_orcid_username("")
38+
39+
40+
def test_from_api_classifies_orcid_and_blocked():
41+
u = MwUser.from_api({
42+
"name": "0000-0002-6374-9831",
43+
"userid": 16,
44+
"registration": "2026-01-21T08:31:14Z",
45+
"editcount": 37,
46+
"groups": ["*", "user", "autoconfirmed"],
47+
})
48+
assert u.is_orcid is True
49+
assert u.orcid_id == "0000-0002-6374-9831"
50+
assert u.editcount == 37
51+
assert u.blocked is False
52+
53+
54+
def test_enumerate_follows_continuation_and_excludes_bots():
55+
site = FakeSite([
56+
_page(
57+
[
58+
{"name": "0000-0002-6374-9831", "userid": 16, "groups": ["user"]},
59+
{"name": "SyncBot", "userid": 2, "groups": ["user", "bot"]},
60+
],
61+
cont={"aufrom": "M"},
62+
),
63+
_page([
64+
{"name": "Maintainer", "userid": 3, "groups": ["sysop"]},
65+
]),
66+
])
67+
users = enumerate_mw_users(site)
68+
names = [u.name for u in users]
69+
assert names == ["0000-0002-6374-9831", "Maintainer"] # bot dropped
70+
assert site.calls == 2 # continuation followed
71+
72+
73+
def test_enumerate_orcid_only_and_limit():
74+
site = FakeSite([
75+
_page([
76+
{"name": "0000-0002-6374-9831", "groups": ["user"]},
77+
{"name": "Alice", "groups": ["user"]},
78+
{"name": "0000-0003-0930-082X", "groups": ["user"]},
79+
])
80+
])
81+
orcid_only = enumerate_mw_users(site, include_non_orcid=False)
82+
assert [u.name for u in orcid_only] == [
83+
"0000-0002-6374-9831",
84+
"0000-0003-0930-082X",
85+
]
86+
87+
site2 = FakeSite([
88+
_page([
89+
{"name": "0000-0002-6374-9831", "groups": ["user"]},
90+
{"name": "Alice", "groups": ["user"]},
91+
])
92+
])
93+
limited = enumerate_mw_users(site2, limit=1)
94+
assert len(limited) == 1
95+
96+
97+
def test_partition_by_orcid():
98+
users = [
99+
MwUser(name="0000-0002-6374-9831"),
100+
MwUser(name="Alice"),
101+
]
102+
parts = partition_by_orcid(users)
103+
assert [u.name for u in parts["orcid"]] == ["0000-0002-6374-9831"]
104+
assert [u.name for u in parts["other"]] == ["Alice"]

0 commit comments

Comments
 (0)