Skip to content

Commit 217b101

Browse files
committed
chore(user-sync): scaffold module, example and tracking
1 parent 848615c commit 217b101

6 files changed

Lines changed: 243 additions & 0 deletions

File tree

‎examples/user_sync.py‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
"""Create or update OSW User items from MediaWiki accounts and ORCID.
2+
3+
Usage:
4+
uv run python examples/user_sync.py --domain llm4eln.semos.dev --dry-run
5+
"""
6+
7+
import dotenv
8+
9+
from osw.express import OswExpress
10+
from osw.tools.user_sync import config_from_args, run_user_sync
11+
12+
13+
def main() -> None:
14+
dotenv.load_dotenv()
15+
config = config_from_args()
16+
osw = OswExpress(domain=config.domain, cred_filepath=config.cred_filepath)
17+
report = run_user_sync(config, osw=osw)
18+
print(report.summary())
19+
20+
21+
if __name__ == "__main__":
22+
main()

‎src/osw/tools/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
"""Maintenance and automation tools built on top of the osw core library."""
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
"""Sync OSW User items from MediaWiki accounts and public ORCID data."""
2+
3+
from __future__ import annotations
4+
5+
from .config import (
6+
ORGANIZATION_CATEGORY,
7+
USER_CATEGORY,
8+
SyncConfig,
9+
build_arg_parser,
10+
config_from_args,
11+
)
12+
from .sync import SyncReport, run_user_sync
13+
14+
__all__ = [
15+
"ORGANIZATION_CATEGORY",
16+
"USER_CATEGORY",
17+
"SyncConfig",
18+
"SyncReport",
19+
"build_arg_parser",
20+
"config_from_args",
21+
"run_user_sync",
22+
]

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

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
"""Configuration for the user-item sync tool."""
2+
3+
from __future__ import annotations
4+
5+
import argparse
6+
from dataclasses import dataclass, field
7+
from typing import List, Optional
8+
9+
# Category page titles of the target item types (see opensemantic.base.v1).
10+
USER_CATEGORY = "Category:OSWd9aa0bca9b0040d8af6f5c091bf9eec7"
11+
ORGANIZATION_CATEGORY = "Category:OSW1969007d5acf40539642877659a02c23"
12+
13+
# Public ORCID API used to enrich ORCID users.
14+
ORCID_API_BASE_DEFAULT = "https://pub.orcid.org/v3.0"
15+
16+
# MediaWiki group whose members are excluded from the sync (bots).
17+
BOT_GROUP = "bot"
18+
19+
20+
@dataclass
21+
class SyncConfig:
22+
"""Runtime options for a single sync run."""
23+
24+
domain: Optional[str] = None
25+
cred_filepath: Optional[str] = None
26+
dry_run: bool = False
27+
assume_yes: bool = False
28+
limit: Optional[int] = None
29+
include_non_orcid: bool = True
30+
exclude_bot_group: bool = True
31+
create_redirects: bool = True
32+
link_organizations: bool = True
33+
orcid_api_base: str = ORCID_API_BASE_DEFAULT
34+
excluded_groups: List[str] = field(default_factory=lambda: [BOT_GROUP])
35+
36+
37+
def build_arg_parser() -> argparse.ArgumentParser:
38+
"""Build the argument parser used by the example wrapper."""
39+
parser = argparse.ArgumentParser(
40+
description="Create or update OSW User items from MediaWiki and ORCID.",
41+
)
42+
parser.add_argument("--domain", help="Target OSL domain, e.g. llm4eln.semos.dev.")
43+
parser.add_argument(
44+
"--cred-filepath",
45+
dest="cred_filepath",
46+
help="Path to accounts.pwd.yaml (defaults to the working directory).",
47+
)
48+
parser.add_argument(
49+
"--dry-run",
50+
action="store_true",
51+
help="Show the preview only; do not write anything.",
52+
)
53+
parser.add_argument(
54+
"--yes",
55+
dest="assume_yes",
56+
action="store_true",
57+
help="Non-interactive: apply new items and gap-fills, keep existing on conflicts.",
58+
)
59+
parser.add_argument(
60+
"--limit",
61+
type=int,
62+
help="Process at most this many MediaWiki users (for testing).",
63+
)
64+
parser.add_argument(
65+
"--no-redirects",
66+
dest="create_redirects",
67+
action="store_false",
68+
help="Do not create User: redirect pages.",
69+
)
70+
parser.add_argument(
71+
"--no-organizations",
72+
dest="link_organizations",
73+
action="store_false",
74+
help="Do not resolve or link ORCID affiliations to Organization items.",
75+
)
76+
parser.add_argument(
77+
"--include-non-orcid",
78+
dest="include_non_orcid",
79+
action="store_true",
80+
default=True,
81+
help="Also sync non-bot accounts without an ORCID username (default).",
82+
)
83+
parser.add_argument(
84+
"--orcid-only",
85+
dest="include_non_orcid",
86+
action="store_false",
87+
help="Sync only accounts whose username is an ORCID iD.",
88+
)
89+
return parser
90+
91+
92+
def config_from_args(argv: Optional[List[str]] = None) -> SyncConfig:
93+
"""Parse command-line arguments into a SyncConfig."""
94+
args = build_arg_parser().parse_args(argv)
95+
return SyncConfig(
96+
domain=args.domain,
97+
cred_filepath=args.cred_filepath,
98+
dry_run=args.dry_run,
99+
assume_yes=args.assume_yes,
100+
limit=args.limit,
101+
include_non_orcid=args.include_non_orcid,
102+
create_redirects=args.create_redirects,
103+
link_organizations=args.link_organizations,
104+
)

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

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
"""Orchestrator for the user-item sync tool.
2+
3+
Later phases implement enumeration, ORCID enrichment, reconciliation, the
4+
interactive layer and the store step. This module currently defines the report
5+
type and the public entry point.
6+
"""
7+
8+
from __future__ import annotations
9+
10+
from dataclasses import dataclass, field
11+
from typing import Dict, List, Optional
12+
13+
from osw.core import OSW
14+
15+
from .config import SyncConfig
16+
17+
18+
@dataclass
19+
class SyncReport:
20+
"""Outcome of a sync run."""
21+
22+
created: List[str] = field(default_factory=list)
23+
updated: List[str] = field(default_factory=list)
24+
skipped: List[str] = field(default_factory=list)
25+
failed: Dict[str, str] = field(default_factory=dict)
26+
redirects_created: List[str] = field(default_factory=list)
27+
organizations: List[str] = field(default_factory=list)
28+
29+
def summary(self) -> str:
30+
"""One-line human-readable summary of the run."""
31+
return (
32+
f"created={len(self.created)} updated={len(self.updated)} "
33+
f"skipped={len(self.skipped)} failed={len(self.failed)} "
34+
f"redirects={len(self.redirects_created)} orgs={len(self.organizations)}"
35+
)
36+
37+
38+
def run_user_sync(config: SyncConfig, osw: Optional[OSW] = None) -> SyncReport:
39+
"""Create or update OSW User items from MediaWiki accounts and ORCID data.
40+
41+
Args:
42+
config: Runtime options for the run.
43+
osw: An authenticated OSW/OswExpress connection. Required for any wiki
44+
access; the example wrapper builds one from ``config``.
45+
"""
46+
raise NotImplementedError("Implemented incrementally in phases 1 to 6.")
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
"""Unit tests for the user-sync configuration and public surface."""
2+
3+
from osw.tools.user_sync import (
4+
ORGANIZATION_CATEGORY,
5+
USER_CATEGORY,
6+
SyncConfig,
7+
SyncReport,
8+
config_from_args,
9+
run_user_sync,
10+
)
11+
12+
13+
def test_defaults():
14+
cfg = SyncConfig()
15+
assert cfg.include_non_orcid is True
16+
assert cfg.create_redirects is True
17+
assert cfg.link_organizations is True
18+
assert cfg.excluded_groups == ["bot"]
19+
assert USER_CATEGORY.startswith("Category:OSW")
20+
assert ORGANIZATION_CATEGORY.startswith("Category:OSW")
21+
22+
23+
def test_config_from_args_parses_flags():
24+
cfg = config_from_args([
25+
"--domain",
26+
"llm4eln.semos.dev",
27+
"--dry-run",
28+
"--limit",
29+
"5",
30+
"--orcid-only",
31+
])
32+
assert cfg.domain == "llm4eln.semos.dev"
33+
assert cfg.dry_run is True
34+
assert cfg.limit == 5
35+
assert cfg.include_non_orcid is False
36+
37+
38+
def test_report_summary():
39+
report = SyncReport(created=["Item:OSW1"], updated=["Item:OSW2"])
40+
assert "created=1" in report.summary()
41+
assert "updated=1" in report.summary()
42+
43+
44+
def test_run_user_sync_is_stub():
45+
import pytest
46+
47+
with pytest.raises(NotImplementedError):
48+
run_user_sync(SyncConfig())

0 commit comments

Comments
 (0)