UpsertEventOption#

class teamworksams.import_option.UpsertEventOption(interactive_mode: bool = True, cache: bool = True, id_col: str = 'user_id', table_fields: List[str] | None = None)[source]#

Bases: object

Options for configuring the upsert_event_data function.

Customizes the behavior of upsert_event_data(), controlling user identifier mapping, caching, interactive feedback, and table fields. Optimizes performance for inserting new events and updating existing ones in an AMS Event Form. See Importing Data for upsert workflows.

Parameters:

  • interactive_mode (bool) – If True, prints status messages (e.g., “Upserted 2 events”) and tqdm progress bars during execution, ideal for interactive environments like Jupyter notebooks. Set to False for silent execution. Defaults to True.

  • cache (bool) – If True, reuses an existing AMSClient via get_client(), reducing API calls for multi-function workflows. Set to False for independent sessions. Defaults to True.

  • id_col (str) – Column name in the input pandas.DataFrame for user identifiers. Must be one of ‘user_id’, ‘about’, ‘username’, or ‘email’. Used to map identifiers to AMS user IDs. Defaults to ‘user_id’.

  • table_fields (Optional[List[str]]) – List of table field names in the AMS form (e.g., [‘session_details’]). Must match DataFrame columns if specified. If None, assumes no table fields. Defaults to None.

interactive_mode#

Boolean indicating if interactive feedback is enabled.

cache#

Boolean indicating if caching is enabled.

id_col#

The column name used for mapping user identifiers.

table_fields#

List of table field names, or an empty list if None.

Raises:

ValueError – If id_col is not one of the allowed values.

Examples

>>> from teamworksams import UpsertEventOption, upsert_event_data
>>> import pandas as pd
>>> df = pd.DataFrame({
...     "event_id": [67890, None],
...     "username": ["john.doe", "jane.smith"],
...     "start_date": ["01/01/2025", "02/01/2025"],
...     "duration": [65, 45]
... })
>>> option = UpsertEventOption(id_col = "username", interactive_mode = True)
>>> upsert_event_data(
...     df = df,
...     form = "Training Log",
...     url = "https://example.smartabase.com/site",
...     option = option
... )
ℹ Updating 1 existing events for 'Training Log'
ℹ Inserting 1 new events for 'Training Log'
✔ Processed 2 events for 'Training Log'
__init__(interactive_mode: bool = True, cache: bool = True, id_col: str = 'user_id', table_fields: List[str] | None = None)[source]#

Additional Notes#

  • The id_col must be one of ‘user_id’, ‘about’, ‘username’, or ‘email’ and present in the input pandas.DataFrame to map user identifiers correctly.

  • Use cache=True to optimize performance when upserting large datasets, reusing a AMSClient() for both inserts and updates.

  • Specify table_fields for table fields (e.g., [‘session_details’]), ensuring DataFrame columns match the AMS form exactly.

See Also#