edit_user#

teamworksams.user_main.edit_user(mapping_df: pandas.DataFrame, user_key: str, url: str, username: str | None = None, password: str | None = None, option: UserOption | None = None, client: AMSClient | None = None) → pandas.DataFrame[source]#

Update user fields in an AMS instance.

Updates specified fields for existing users identified by a user key (e.g., username, email), using the AMS API’s /api/v2/person/save endpoint. The function retrieves complete user data to preserve unchanged fields, applies updates from the mapping_df DataFrame, and returns a DataFrame of failed updates with reasons. Supports interactive feedback, including status messages and confirmation prompts, and allows caching for performance. See User and Group Management for user account workflows.

Parameters:

  • mapping_df (pandas.DataFrame) – DataFrame containing a user_key column (e.g., ‘username’) and updatable columns (e.g., ‘first_name’, ‘email’, ‘dob’, ‘sex’, ‘username’, ‘known_as’, ‘active’, ‘uuid’). Empty values are sent as empty strings. Must not be empty.

  • user_key (str) – Identifier column in mapping_df. Must be one of ‘username’, ‘email’, ‘about’, or ‘uuid’. For example, ‘username’ matches users by their AMS username.

  • url (str) – AMS instance URL (e.g., ‘https://example.smartabase.com/site’). Must include a valid site name.

  • username (Optional[str]) – Username for authentication. If None, uses AMS_USERNAME environment variable or keyring credentials. Defaults to None.

  • password (Optional[str]) – Password for authentication. If None, uses AMS_PASSWORD environment variable or keyring credentials. Defaults to None.

  • option (UserOption, optional) – Configuration options, including interactive_mode for status messages and cache to reuse a client. The columns option is ignored. Defaults to None (uses default UserOption with interactive_mode=True).

  • client (AMSClient, optional) – Pre-authenticated client from teamworksams.utils.get_client. If None, a new client is created. Defaults to None.

Returns:

DataFrame of failed updates with columns ‘user_id’ (ID if matched or None), ‘user_key’ (identifier value), and ‘reason’ (failure reason). Empty if all updates succeed.

Return type:

pandas.DataFrame

Raises:

  • AMSError – If mapping_df is invalid, user_key is unsupported, no users are found, authentication fails, or the API request fails.

  • ValueError – If mapping_df is empty or lacks valid columns.

Examples

>>> import pandas as pd
>>> from teamworksams import edit_user, UserOption
>>> mapping_df = pd.DataFrame({
...     "username": ["john.doe", "jane.smith"],
...     "first_name": ["John", "Jane"],
...     "email": ["john.doe@new.com", "jane.smith@new.com"]
... })
>>> results = edit_user(
...     mapping_df = mapping_df,
...     user_key = "username",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     option = UserOption(interactive_mode = True)
... )
ℹ Fetching all user data...
ℹ Retrieved 30 users.
ℹ Attempting to map 2 users using about from provided dataframe...
ℹ Successfully mapped 2 users.
ℹ Updating 2 users...
Processing users: 100%|██████████| 2/2 [00:4<00:00, 3.46it/s]
✔ Successfully updated 2 users.
✔ No failed operations.

Additional Notes#

  • The mapping_df must include a column matching user_key (e.g., ‘username’) and at least one updatable field (e.g., ‘email’, ‘first_name’). Empty values are sent as empty strings to the AMS API, which may overwrite existing data.

  • The returned DataFrame lists failed updates with reasons like “User not found” or “API request failed,” enabling easy troubleshooting.

  • Use option.interactive_mode=True to display progress bars via tqdm for large updates, enhancing visibility in interactive scripts.

See Also#