get_user#

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

Retrieve user data from an AMS instance.

Fetches user data for all accessible users or a filtered subset based on attributes like username, email, group, or about field. The function queries the AMS API, processes the response into a pandas DataFrame with columns such as user ID, name, email, and group affiliations, and provides interactive feedback on the number of users retrieved if enabled. Supports caching and column selection for customized output. See User and Group Management for user account workflows.

Parameters:

  • url (str) – The 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 (UserFilter, optional) – Filter users by attributes like ‘username’, ‘email’, ‘group’, or ‘about’. For example, UserFilter(user_key = "group", user_value = "TeamA") retrieves users in “TeamA”. Defaults to None (all users).

  • option (UserOption, optional) – Configuration options, including columns (list of output columns, e.g., ["user_id", "email"]) and interactive_mode (print status messages). Defaults to None (default UserOption).

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

Returns:

A pandas DataFrame containing user data with columns such as ‘user_id’,

’first_name’, ‘last_name’, ‘email’, ‘groups’, and others, depending on the API response and option.columns. Returns an empty DataFrame if no users are found or no users match the filter.

Return type:

DataFrame

Raises:

AMSError – If authentication fails, the API request returns an invalid response, or no users are accessible.

Examples

>>> import pandas as pd
>>> from teamworksams import get_user, UserFilter, UserOption
>>> df = get_user(
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     filter = UserFilter(user_key = "group", user_value = "TeamA"),
...     option = UserOption(columns = ["user_id", "first_name", "groups"], interactive_mode = True)
... )
ℹ Fetching user data...
✔ Retrieved 2 users.
>>> print(df)
   user_id first_name groups
0    12345   John Doe  TeamA
1    12346 Jane Smith  TeamA