telemetry¶

def get_consent_source() -> str:
    """Get the source of the telemetry consent decision.

    Returns:
        str: The source of consent (e.g., 'python method', 'environment variable', 'command line', 'none').
    """
    return _CONSENT_SOURCE

def get_user_config_dir_path() -> Path:
    """Get the user configuration directory path for the application.

    Creates the directory if it doesn't exist.

    Returns:
        Path: Path object pointing to the user's configuration directory.
    """
    return platformdirs.user_config_path(appname=_APP_NAME, appauthor=_APP_AUTHOR, roaming=True, ensure_exists=True)

def is_telemetry_allowed_by_env_var() -> ConsentStatus:
    """Check if telemetry is allowed via environment variable.

    Checks the SIMATICAI_TELEMETRY environment variable for consent.

    Returns:
        ConsentStatus: ALLOWED if env var is set to an affirmative value,
            DENIED if set to a negative value, UNDECIDED if not set.
    """
    if _CONSENT_ENV_VAR not in os.environ:
        return ConsentStatus.UNDECIDED
    choice = os.getenv(_CONSENT_ENV_VAR, "").lower() in _CONSENT_AFFIRMATIVE
    _logger.warning(f"Telemetry is {'allowed' if choice else 'denied'} by environment variable.")
    if choice:
        return ConsentStatus.ALLOWED
    return ConsentStatus.DENIED

def read_telemetry_consent_file() -> tuple[dict, Path]:
    """Read the telemetry consent configuration file.

    Returns:
        tuple[dict, Path]: A tuple containing the consent data dictionary and the path to the consent file.

    Raises:
        AssertionError: If the consent file exists but the user's choice is not readable.
    """
    consent_file = get_user_config_dir_path() / _CONSENT_FILE_NAME
    data = yaml_helper.read_yaml(consent_file)
    if CONSENT_KEY not in data:
        raise AssertionError("Consent file exists, but the user's choice is not readable.")
    return data, consent_file

def is_telemetry_allowed_by_config_file() -> bool:
    """Check if telemetry is allowed via configuration file.

    Reads the consent file and returns the user's telemetry choice.

    Returns:
        bool: True if telemetry is allowed, False otherwise.

    Raises:
        RuntimeError: If the consent file cannot be read or doesn't exist,
            prompting the user to make a consent decision.
    """
    try:
        data, _ = read_telemetry_consent_file()
        choice = data.get(CONSENT_KEY, False)
        if not isinstance(choice, bool):
            choice = str(choice).lower() in _CONSENT_AFFIRMATIVE
        _logger.warning(f"Telemetry is {'allowed' if choice else 'denied'} by configuration file.")
        return choice
    except BaseException as error:
        global _CONSENT_SOURCE
        _CONSENT_SOURCE = "none"
        raise RuntimeError(f"\n\n{CONSENT_EXCEPTION_TEXT}\n") from error

def is_telemetry_allowed() -> bool:
    """Check if telemetry is allowed based on all possible sources.

    Checks consent in order of precedence:
    1. Override set via allow_telemetry_once/deny_telemetry_once
    2. Environment variable (SIMATICAI_TELEMETRY)
    3. Configuration file

    Returns:
        bool: True if telemetry is allowed, False otherwise.

    Raises:
        RuntimeError: If no consent decision has been made and no configuration exists.
    """
    global _CONSENT_SOURCE
    _CONSENT_SOURCE = "python method"
    if ConsentStatus.UNDECIDED != _CONSENT_OVERRIDE:
        return ConsentStatus.ALLOWED == _CONSENT_OVERRIDE

    _CONSENT_SOURCE = "environment variable"
    choice_env = is_telemetry_allowed_by_env_var()
    if ConsentStatus.UNDECIDED != choice_env:
        return ConsentStatus.ALLOWED == choice_env

    _CONSENT_SOURCE = "command line"
    return is_telemetry_allowed_by_config_file()

def set_telemetry_consent(allow: bool) -> Path:
    """Set the telemetry consent decision in the configuration file.

    Creates or updates the consent file with the user's choice, timestamp,
    SDK version, and consent method.

    Args:
        allow (bool): True to allow telemetry, False to deny it.

    Returns:
        Path: Path to the consent file that was created or updated.

    Raises:
        RuntimeError: If the consent file cannot be written.
    """
    consent_file = get_user_config_dir_path() / _CONSENT_FILE_NAME
    try:
        with open(consent_file, "w") as f:
            # writing YAML manually to keep the file format as intended
            f.write(f"{CONSENT_KEY}: {'true' if allow else 'false'}\n")
            f.write(f"{CONSENT_KEY_TS}: '{datetime.now().isoformat()}'\n")
            f.write(f"{CONSENT_KEY_SDK}: '{version('simaticai')}'\n")
            f.write(f"{CONSENT_KEY_METHOD}: '{_CONSENT_SOURCE}'\n")
            f.write("information: |\n")
            for line in CONSENT_INFO.splitlines():
                f.write(f"    {line}\n")
    except BaseException as error:
        raise RuntimeError(f"Failed to save consent in '{consent_file}'.") from error
    return consent_file

def allow_telemetry() -> Path:
    """Allow telemetry and save the decision to the configuration file.

    Sets the consent source to 'python method' and saves the consent decision.

    Returns:
        Path: Path to the consent file that was updated.
    """
    global _CONSENT_SOURCE
    _CONSENT_SOURCE = "python method"
    return set_telemetry_consent(True)

def deny_telemetry() -> Path:
    """Deny telemetry and save the decision to the configuration file.

    Sets the consent source to 'python method' and saves the consent decision.

    Returns:
        Path: Path to the consent file that was updated.
    """
    global _CONSENT_SOURCE
    _CONSENT_SOURCE = "python method"
    return set_telemetry_consent(False)

def allow_telemetry_cli() -> Path:
    """Allow telemetry via command line interface and save the decision.

    Sets the consent source to 'command line' and saves the consent decision.

    Returns:
        Path: Path to the consent file that was updated.
    """
    global _CONSENT_SOURCE
    _CONSENT_SOURCE = "command line"
    return set_telemetry_consent(True)

def deny_telemetry_cli() -> Path:
    """Deny telemetry via command line interface and save the decision.

    Sets the consent source to 'command line' and saves the consent decision.

    Returns:
        Path: Path to the consent file that was updated.
    """
    global _CONSENT_SOURCE
    _CONSENT_SOURCE = "command line"
    return set_telemetry_consent(False)

def allow_telemetry_once():
    """Allow telemetry for the current session only without saving to file.

    Sets a temporary override that allows telemetry for this session.
    The decision is not persisted to the configuration file.
    """
    global _CONSENT_OVERRIDE, _CONSENT_SOURCE
    _CONSENT_SOURCE = "python method"
    _CONSENT_OVERRIDE = ConsentStatus.ALLOWED
    _logger.warning("Telemetry is enabled for this session.")

def deny_telemetry_once():
    """Deny telemetry for the current session only without saving to file.

    Sets a temporary override that denies telemetry for this session.
    The decision is not persisted to the configuration file.
    """
    global _CONSENT_OVERRIDE, _CONSENT_SOURCE
    _CONSENT_SOURCE = "python method"
    _CONSENT_OVERRIDE = ConsentStatus.DENIED
    _logger.warning("Telemetry is disabled for this session.")