upload_and_attach_to_avatars#

teamworksams.file_main.upload_and_attach_to_avatars(mapping_df: pandas.DataFrame | None = None, file_dir: str = None, user_key: str = None, url: str = None, username: str | None = None, password: str | None = None, option: FileUploadOption | None = None, client: AMSClient | None = None) → pandas.DataFrame[source]#

Upload files and attach them as avatars to user profiles in an AMS instance.

Matches the provided or auto-generated pandas.DataFrame to users using user_key, uploads valid image files from file_dir, and updates the avatarId field in user profiles. If mapping_df is None, generates it from image filenames in file_dir (without extension) as user_key values. Preserves other profile fields during updates. Returns a pandas.DataFrame with results. See Uploading Files for detailed workflows.

Parameters:

  • mapping_df (Optional[pandas.DataFrame]) – DataFrame with columns: - user_key (str): User identifier (e.g., ‘username’, ‘email’, ‘about’, ‘uuid’). - file_name (str): Image file name in file_dir (e.g., ‘avatar1.png’). If None, generates from file_dir filenames. Defaults to None.

  • file_dir (str) – Directory path containing image files (e.g., ‘/path/to/avatars’). Must be a valid directory.

  • user_key (str) – Column name for user identification (‘username’, ‘email’, ‘about’, ‘uuid’). Required if mapping_df is None or provided.

  • 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 or keyring credentials. Defaults to None.

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

  • option (FileUploadOption, optional) – Configuration options for interactive feedback, caching, and saving results to a CSV. Defaults to None (uses default FileUploadOption with interactive_mode=True).

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

Returns:

Results with columns:

  • user_key (str): The user identifier from mapping_df.

  • file_name (str): The file name from mapping_df.

  • user_id (str): Matched user ID (None if failed).

  • file_id (str): Uploaded file ID (None if failed).

  • server_file_name (str): Server-assigned file name (None if failed).

  • status (str): ‘SUCCESS’ or ‘FAILED’.

  • reason (str): Failure reason (None if successful).

Return type:

pandas.DataFrame

Raises:

  • AMSError – If: - file_dir is invalid or empty. - mapping_df is None and no valid images are found. - User data retrieval fails. - No users are found. - File validation fails (e.g., non-image files). - File upload or profile update fails.

  • ValueError – If user_key is invalid or mapping_df is malformed.

Examples

>>> import pandas as pd
>>> from teamworksams import upload_and_attach_to_avatars, FileUploadOption
>>> mapping_df = DataFrame({
...     "username": ["user1", "user2"],
...     "file_name": ["avatar1.png", "avatar2.jpg"]
... })
>>> results = upload_and_attach_to_avatars(
...     mapping_df = mapping_df,
...     file_dir = "/path/to/avatars",
...     user_key = "username",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "password",
...     option = FileUploadOption(
...         interactive_mode = True,
...         save_to_file = "avatar_results.csv"
...     )
... )
ℹ Fetching all user data from site to match provided files...
ℹ Retrieved 50 users.
ℹ Found 2 valid avatar files in directory for 2 matching users on the site.
ℹ Uploading 2 avatar files...
Uploading files: 100%|██████████| 2/2 [00:02<00:00,  1.00s/it]
Preparing to update avatars for 2 users with 2 avatar files.
Updating avatars: 100%|██████████| 2/2 [00:02<00:00,  1.00s/it]
✔ Successfully updated 2 avatar files to 2 users.
ℹ Saved results to 'avatar_results.csv'
>>> print(results)
   username  file_name user_id file_id server_file_name status reason
0   user1  avatar1.png 78901   94196 avatar1_1747654002120.png SUCCESS None
1   user2  avatar2.jpg 78902   94197 avatar2_1747654003484.jpg SUCCESS None

Additional Notes#

  • If mapping_df is None, the function generates it from image filenames in file_dir, using names (without extension) as user_key values, simplifying batch avatar uploads.

  • Valid image types include .png, .jpg, .jpeg, .gif, and .heic; non-image files are skipped with failure reasons.

  • Ensure users exist in the AMS instance (verify with get_user()) to avoid “User not found” errors.

  • Use option.interactive_mode=True to monitor progress, as the function involves user mapping, file validation, and profile updates.

See Also#