get_profile_data#

teamworksams.export_main.get_profile_data(form: str, url: str, username: str | None = None, password: str | None = None, filter: ProfileFilter | None = None, option: ProfileOption | None = None, client: AMSClient | None = None) → pandas.DataFrame[source]#

Retrieve profile data from an AMS Profile Form.

Fetches profile data from the specified AMS Profile Form, returning a pandas.DataFrame with columns like ‘profile_id’, ‘user_id’, and form fields. Supports optional filtering by user attributes (e.g., group) and customization like column name standardization. Provides interactive feedback when option.interactive_mode=True.

Parameters:

  • form (str) – Name of the AMS Profile Form (e.g., ‘Athlete Profile’). Must be a non-empty string and correspond to a valid form.

  • 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.

  • filter (ProfileFilter, optional) – Filter object to narrow results by user attributes (e.g., ‘group’). If None, includes all profiles. Defaults to None.

  • option (ProfileOption, optional) – Configuration options, including interactive_mode for status messages, clean_names to standardize column names, guess_col_type to infer data types, cache to reuse a client, and include_missing_users to include users without profiles. Defaults to None (uses default ProfileOption).

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

Returns:

Profile data with columns like ‘profile_id’, ‘user_id’,

’form’, and form fields (e.g., ‘ID’). Empty with columns [‘user_id’, ‘profile_id’, ‘form’] if no profiles are found.

Return type:

pandas.DataFrame

Raises:

  • AMSError – If form is empty, no profiles/users are found, authentication fails, or the API request fails.

  • ValueError – If filter parameters are invalid.

Examples

>>> import pandas as pd
>>> from teamworksams import get_profile_data, ProfileFilter, ProfileOption
>>> df = get_profile_data(
...     form = "Athlete Profile",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     filter = ProfileFilter(user_key = "group", user_value = "Example Group"),
...     option = ProfileOption(interactive_mode = True, clean_names = True)
... )
ℹ Requesting profile data for form 'Athlete Profile'
ℹ Processing 5 profiles...
>>> print(df.head())
   about  user_id  profile_id  form              ID
0  John Doe    12345      54321  Athlete Profile    2435t4yrgfddeqwret12
1  Jane Smith  12346      54322  Athlete Profile    2435t4yrgfddeqwret6

Additional Notes#

  • The form parameter must match an existing AMS Profile Form exactly (case-sensitive).

  • Use option.clean_names=True to standardize column names (e.g., ‘Athlete Profile’ to ‘athlete_profile’) for consistency in analysis.

  • The filter parameter with ProfileFilter() limits profiles to specific users, reducing API load for large datasets.

See Also#