EventOption#

class teamworksams.export_option.EventOption(interactive_mode: bool = True, guess_col_type: bool = True, convert_dates: bool = False, clean_names: bool = False, cache: bool = True, include_missing_users: bool = False, download_attachment: bool = False, attachment_directory: str | None = None)[source]#

Bases: object

Options for configuring event data export.

Defines customization options for the get_event_data() function, controlling aspects such as downloading attachments, cleaning column names, caching API responses, and enabling interactive feedback. These options allow users to tailor the event data retrieval process, including data formatting, performance optimization, and user experience. See Exporting Data for usage examples.

Parameters:

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

  • guess_col_type (bool) – Whether to infer column data types (e.g., numeric, datetime) in the resulting DataFrame. Defaults to True.

  • convert_dates (bool) – Whether to convert date columns to pandas datetime objects. Defaults to False.

  • clean_names (bool) – Whether to clean column names by converting to lowercase and replacing spaces with underscores. Defaults to False.

  • cache (bool) – Whether to cache API responses to improve performance for repeated requests. Defaults to True.

  • include_missing_users (bool) – Whether to include events for users not found in user data, ensuring all events are represented. Defaults to False.

  • download_attachment (bool) – Whether to download attachments associated with events. Defaults to False.

  • attachment_directory (Optional[str]) – Directory path to save downloaded attachments. If None, uses the current working directory. Can be either an absolute path or a relative path. Ignored if download_attachment is False. Defaults to None.

interactive_mode#

Indicates whether interactive mode is enabled.

Type:

bool

guess_col_type#

Indicates whether column type inference is enabled.

Type:

bool

convert_dates#

Indicates whether date conversion is enabled.

Type:

bool

clean_names#

Indicates whether column name cleaning is enabled.

Type:

bool

cache#

Indicates whether caching is enabled.

Type:

bool

include_missing_users#

Indicates whether missing users are included.

Type:

bool

download_attachment#

Indicates whether attachment downloading is enabled.

Type:

bool

attachment_directory#

The directory for saving attachments.

Type:

Optional[str]

attachment_count#

The number of attachments downloaded (set during processing).

Type:

int

Examples

>>> from teamworksams import get_event_data, EventOption
>>> option = EventOption(
...     interactive_mode = True,
...     clean_names = True,
...     download_attachment = True,
...     attachment_directory = "/path/to/attachments"
... )
>>> df = get_event_data(
...     form = "Training Log",
...     start_date = "01/01/2025",
...     end_date = "31/01/2025",
...     url = "https://example.smartabase.com/site",
...     option = option
... )
__init__(interactive_mode: bool = True, guess_col_type: bool = True, convert_dates: bool = False, clean_names: bool = False, cache: bool = True, include_missing_users: bool = False, download_attachment: bool = False, attachment_directory: str | None = None)[source]#

Additional Notes#

  • Set download_attachment=True to save event attachments, ensuring attachment_directory is a valid path to avoid errors.

  • Use clean_names=True to standardize column names (e.g., ‘Training Log’ to ‘training_log’) for consistency in analysis.

  • Enable interactive_mode=True for tqdm progress bars and status messages, ideal for interactive environments like Jupyter notebooks.

See Also#