EventFilter#

class teamworksams.export_filter.EventFilter(user_key: str | None = None, user_value: str | List[str] | None = None, data_key: str | None = None, data_value: str | List[str] | None = None, data_condition: str | None = None, events_per_user: int | None = None)[source]#

Bases: object

Filter for selecting events in event data export.

Defines criteria for filtering events retrieved by get_event_data, allowing selection based on user attributes (e.g., username, group) or event data fields (e.g., intensity). Validates filter parameters to ensure compatibility with the AMS API.

Parameters:

  • user_key (Optional[str]) – User attribute to filter by, one of ‘username’, ‘email’, ‘group’, or ‘about’. If None, no user filtering is applied. Defaults to None.

  • user_value (Optional[Union[str, List[str]]]) – Value(s) to match for user_key (e.g., ‘TeamA’ for user_key="group"). Case-sensitive. If None, no user filtering is applied. Defaults to None.

  • data_key (Optional[str]) – Event data field to filter by (e.g., ‘intensity’). Must match a valid form field. If None, no data filtering is applied. Defaults to None.

  • data_value (Optional[str]) – Value to match for data_key (e.g., ‘High’). If None, no data filtering is applied. Defaults to None.

  • data_condition (Optional[str]) – Condition for data_key filtering, one of “>”, “>=”, “<”, “<=”, “=”, “!=”, “contains”. Defaults to None.

  • events_per_user (Optional[int]) – Maximum number of events per user. If None, retrieves all events. Defaults to None.

user_key#

The user filter key.

Type:

Optional[str]

user_value#

The user filter value(s).

Type:

Optional[Union[str, List[str]]]

data_key#

The data field key.

Type:

Optional[str]

data_value#

The data field value(s).

Type:

Optional[Union[str, List[str]]]

data_condition#

The data filter condition.

Type:

Optional[str]

events_per_user#

The maximum events per user.

Type:

Optional[int]

Raises:

ValueError – If any parameter is invalid, such as an unrecognized user_key, invalid data_condition, or negative events_per_user.

Examples

>>> from teamworksams import get_event_data, EventFilter
>>> filter = EventFilter(
...     user_key = "group",
...     user_value = "Example Group",
...     data_key = "Intensity",
...     data_value = "High",
...     data_condition = "=",
...     events_per_user = 10
... )
>>> df = get_event_data(
...     form = "Training Log",
...     start_date = "01/01/2025",
...     end_date = "31/01/2025",
...     url = "https://example.smartabase.com/site",
...     filter = filter
... )
__init__(user_key: str | None = None, user_value: str | List[str] | None = None, data_key: str | None = None, data_value: str | List[str] | None = None, data_condition: str | None = None, events_per_user: int | None = None)[source]#

Additional Notes#

  • The user_key must be one of ‘username’, ‘email’, ‘group’, or ‘about’; user_value is case-sensitive and can be a string or list (e.g., [‘TeamA’, ‘TeamB’]).

  • Use data_key and data_value to filter by event fields (e.g., data_key="intensity", data_value="High"), with data_condition like ‘equals’ or ‘contains’.

  • Set events_per_user to limit the number of events per user, reducing API load for large datasets.

See Also#