refactor: extract CSVImport._decompose_site_role, inverse of _evaluate_site_role

[jacalata]

Draft while stacked on #1811. Will be marked ready for review once #1811 merges.

Summary

Stacks on #1811.

Moves the ad-hoc site role → CSV columns logic from create_users_csv into UserItem.CSVImport._decompose_site_role, making it the explicit inverse of _evaluate_site_role. Both encode/decode functions now live together in CSVImport.

What changed

New method: UserItem.CSVImport._decompose_site_role(site_role) -> (license, admin_level, publish)

Replaces the if/elif block in create_users_csv with a lookup table. create_users_csv becomes:

license, admin_level, publish = UserItem.CSVImport._decompose_site_role(user.site_role or "Unlicensed")

Pre-existing bugs fixed in the decomposition:

• ExplorerCanPublish was emitted as license="ExplorerCanPublish" — not a valid CSV license value; now ("Explorer", "None", "1")
• SiteAdministrator (legacy role) was emitting license="" via str.replace("SiteAdministrator", ""); now maps to ("Explorer", "Site", "1")
• Non-admin roles now emit admin_level="None" (explicit CSV spec value) rather than "" — both accepted by the server but "None" is consistent with the spec and what _evaluate_site_role expects as input

Test updated: test_create_users_csv now asserts "None" for non-admin roles (previously asserted "") and verifies the auth column.

Test plan

• pytest test/test_user.py test/test_user_model.py — 46 passed
• Full suite — 848 passed, 1 skipped

🤖 Generated with Claude Code

[bcantoni]

Correctness: silent behavior change for several Roles values

The new _role_map lookup table doesn't faithfully preserve the old if/elif logic for every UserItem.Roles value. Diffing old vs. new decomposition for each role constant:

Role	Old CSV output (license, admin, publish)	New CSV output
Interactor	("Interactor", "", 1)	("Explorer", "None", "0")
Publisher	("Publisher", "", 1)	("Explorer", "None", "1")
ReadOnly	("ReadOnly", "", 0)	("Viewer", "None", "0")
UnlicensedWithPublish	("UnlicensedWithPublish", "", 1)	("Unlicensed", "None", "0") — falls into the .get() default, silently drops publish
ViewerWithPublish	("ViewerWithPublish", "", 1)	("Unlicensed", "None", "0") — same silent drop
Guest	("Guest", "", 0)	("Unlicensed", "None", "0")
SupportUser	("SupportUser", "", 0)	("Unlicensed", "None", "0")

Some of these (Interactor, Publisher, ReadOnly) look like reasonable improvements — their old outputs already emitted invalid license strings, so mapping them to real license values is a fix. But UnlicensedWithPublish and ViewerWithPublish look like a real regression: the old code at least preserved publish=1 even though license was garbage. The new _role_map.get(..., default) silently coerces both to Unlicensed/publish=0. Any caller using site_role = UserItem.Roles.ViewerWithPublish will now get a user provisioned as fully unlicensed instead of a licensed publisher, with no error or warning.

Suggestion: add explicit entries for Guest, SupportUser, UnlicensedWithPublish, and ViewerWithPublish to _role_map (matching whatever the CSV import spec actually expects for these), or if they're genuinely unsupported by CSV import, raise/log rather than silently defaulting to Unlicensed. At minimum, worth calling out in the PR description that these four roles' behavior is changing — two of them silently and detrimentally.

[bcantoni]

@jacalata take a look at the consistency check that claude called out - does that need to be fixed/improved?

[jacalata]

Good question. Several of the old values were actually broken already, and I was under the impression that the server was returning a new Unlicensed user. However it turns out it was throwing an error and not creating an account at all, so Claude was correct that we were changing from an error to a silent not-quite-as-expected success.

so, the old behavior: The server's parser (CsvLicenseRoleTypeConverter) accepts only creator / interactor / explorer / viewer / unlicensed / empty. Anything else throws USER_CSV_INVALID_LICENSE and the row is rejected.
However the roles 'Guest' and 'SupportUser' were accepted when calling the individual users.add method, just not in CSVs: that's a server-side asymmetry between the two endpoints, not a TSC bug. They will still work in users.add. We might try and clean that up as part of future work.

Fix: unmapped roles now emit license="Invalid", which the server rejects with the same USER_CSV_INVALID_LICENSE error you got before. Per-row failure semantics preserved for bulk_add callers who inspect the job result; batch resilience unaffected (bad rows fail, good rows succeed, no client-side throw takes down the whole call).

The legacy Roles values (UnlicensedWithPublish, ViewerWithPublish) didn't work at all. They've been in UserItem.Roles since the first commit of the library in 2016 and appear to have been fossilized dead code since Tableau Server moved off the old license model. Filed #1834 to formally deprecate them.