get_group#

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

Retrieve group data from an AMS instance.

Fetches a list of groups accessible to the authenticated user, such as teams or departments, and processes the API response into a pandas DataFrame with group names. Provides interactive feedback on the number of groups retrieved if enabled. Supports caching and data type inference for the output DataFrame. 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 (e.g., ‘/site’).

  • 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 (GroupOption, optional) – Configuration options, including guess_col_type to infer column data types (e.g., string for group names) and interactive_mode to print status messages (e.g., “Retrieved 3 groups”). Defaults to None (uses default GroupOption).

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

Returns:

A pandas DataFrame containing group data with a ‘name’ column listing

group names. Returns an empty DataFrame if no groups are accessible.

Return type:

DataFrame

Raises:

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

Examples

>>> import pandas as pd
>>> from teamworksams import get_group, GroupOption
>>> df = get_group(
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     option = GroupOption(interactive_mode = True)
... )
ℹ Fetching group data...
✔ Retrieved 3 groups.
>>> print(df)
      name
0    Example Group A
1    Example Group B
2    Example Group C

Additional Notes#

  • Set option.guess_col_type=True to ensure group names are treated as strings, avoiding type mismatches in pandas.DataFrame operations.

  • Use with get_user() to map users to groups, as shown in User and Group Management.

  • Enable option.interactive_mode=True for feedback like “Retrieved 3 groups,” useful in interactive environments.

See Also#