InsertEventOption#

class teamworksams.import_option.InsertEventOption(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 insert_event_data function.

Customizes the behavior of insert_event_data(), controlling user identifier mapping, caching, interactive feedback, and table fields. Optimizes performance and user experience for inserting new events into an AMS Event Form. See Importing Data for import workflows.

Parameters:

  • interactive_mode (bool) – Whether to print status messages during execution, such as the number of events being inserted and the result. Defaults to True.

  • cache (bool) – If True, reuses an existing AMSClient via get_client(), reducing API calls for multi-function workflows (e.g., inserting multiple batches). 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#

Indicates whether interactive mode is enabled.

Type:

bool

cache#

Indicates whether caching is enabled.

Type:

bool

id_col#

The column name used for mapping user identifiers.

Type:

str

table_fields#

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

Type:

List[str]

Raises:

  • ValueError – If id_col is not one of ‘user_id’, ‘about’, ‘username’, or

  • 'email'. –

Examples

>>> from teamworksams import InsertEventOption, insert_event_data
>>> import pandas as pd
>>> df = pd.DataFrame({
...     "username": ["john.doe"],
...     "start_date": ["01/01/2025"],
...     "duration": [60]
... })
>>> option = InsertEventOption(id_col = "username", interactive_mode = True)
>>> insert_event_data(
...     df = df,
...     form = "Training Log",
...     url = "https://example.smartabase.com/site",
...     option = option
... )
__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 a valid column in the input pandas.DataFrame (e.g., ‘username’, ‘user_id’) and one of ‘user_id’, ‘about’, ‘username’, or ‘email’; invalid values raise ValueError.

  • Specify table_fields for AMS forms with table data (e.g., [‘session_details’]), ensuring column names match exactly to avoid AMSError.

  • Enable interactive_mode=True for feedback like “Inserted 2 events,” ideal for interactive environments like Jupyter notebooks.

See Also#