Summary

Add users.bulk_add_from_file(filepath, strict=False) -> tuple[JobItem, list[SkippedLine]] as the modern file-based user import convenience. The existing users.create_from_file is deprecated (v0.41.0) in favor of bulk_add, but bulk_add takes Iterable[UserItem] and has no file-reading equivalent. Callers who want "read this CSV, import users, tell me what happened" today have to hand-roll validation + iteration + error accumulation.

Proposed shape

def bulk_add_from_file(
    self,
    filepath: str,
    strict: bool = False,
) -> tuple[JobItem, list[SkippedLine]]:
    """
    Import users from a CSV file.

    - Reads the file
    - Validates each line via UserItem.CSVImport.validate_file_for_import
    - If strict=True: raises ValueError on the first invalid line
    - If strict=False: skips invalid lines, returns them in the second tuple element
    - Calls POST /users/import (via bulk_add) with the valid users
    - Returns the JobItem plus any client-side-rejected lines
    """

SkippedLine would be a small dataclass carrying the raw line, line number, and validation error.

Motivation

• tabcmd (createsiteusers, createusers, addusers, etc.) currently duplicates ~100 lines of CSV parsing and validation logic client-side because there's no TSC method that spans file → server. UserItem.CSVImport: several bugs prevent reliable use and block tabcmd delegation #1809 tracks bringing tabcmd onto the shared TSC implementation; this method is what tabcmd would call.
• Direct TSC users get the same convenience.
• strict mode gives callers the choice between fail-fast and gather-errors, matching tabcmd's existing --complete / --no-complete CLI flag.