Welcome to PyWinSparkle’s documentation!

A wrapper for the WinSparkle project

pywinsparkle.win_sparkle_check_update_with_ui()

Checks if an update is available, showing progress UI to the user.

Normally, WinSparkle checks for updates on startup and only shows its UI when it finds an update. If the application disables this behavior, it can hook this function to “Check for updates...” menu item.

When called, background thread is started to check for updates. A small window is shown to let the user know the progress. If no update is found, the user is told so. If there is an update, the usual “update available” window is shown.

This function returns immediately.

pywinsparkle.win_sparkle_check_update_with_ui_and_install()

Checks if an update is available, showing progress UI to the user and immediately installing the update if one is available.

This is useful for the case when users should almost always use the newest version of your software. When called, WinSparkle will check for updates showing a progress UI to the user. If an update is found the update prompt will be skipped and the update will be installed immediately.

If your application expects to do something after checking for updates you may wish to use win_sparkle_set_did_not_find_update_callback() and win_sparkle_set_update_cancelled_callback().

pywinsparkle.win_sparkle_check_update_without_ui()

Checks if an update is available.

No progress UI is shown to the user when checking. If an update is available, the usual “update available” window is shown; this function is not completely UI-less.

Use with caution, it usually makes more sense to use the automatic update checks on interval option or manual check with visible UI.

This function returns immediately.

pywinsparkle.win_sparkle_cleanup()

Cleans up after WinSparkle.

Should be called by the app when it’s shutting down. Cancels any pending Sparkle operations and shuts down its helper threads.

pywinsparkle.win_sparkle_get_last_check_time()

Gets the time for the last update check.

Default value is -1, indicating that the update check has never run.

Returns:Time in seconds since unix epoch
pywinsparkle.win_sparkle_get_update_check_interval()

Gets the time for the last update check.

Default value is -1, indicating that the update check has never run.

pywinsparkle.win_sparkle_init()

Starts WinSparkle.

If WinSparkle is configured to check for updates on startup, proceeds to perform the check. You should only call this function when your app is initialized and shows its main window.

@note This call doesn’t block and returns almost immediately. If an
update is available, the respective UI is shown later from a separate thread.
pywinsparkle.win_sparkle_set_app_build_version(build_number)

Sets application build version number.

This is the internal version number that is not normally shown to the user. It can be used for finer granularity that official release versions, e.g. for interim builds.

If this function is called, then the provided build number is used for comparing versions; it is compared to the “version” attribute in the appcast and corresponds to OS X Sparkle’s CFBundleVersion handling. If used, then the appcast must also contain the “shortVersionString” attribute with human-readable display version string. The version passed to win_sparkle_set_app_details() corresponds to this and is used for display.

Parameters:build_number – the build number (as string)
pywinsparkle.win_sparkle_set_app_details(company_name, app_name, app_version)

Sets application metadata.

Normally, these are taken from VERSIONINFO/StringFileInfo resources, but if your application doesn’t use them for some reason, using this function is an alternative.

note company_name and app_name are used to determine the location
of WinSparkle settings in registry. (HKCUSoftware<company_name><app_name>WinSparkle is used.)
Parameters:
  • company_name – Company name of the vendor.
  • app_name – Application name. This is both shown to the user and used in HTTP User-Agent header
  • app_version – Version of the app, as string (e.g. “1.2” or “1.2rc1”).
pywinsparkle.win_sparkle_set_appcast_url(url)

Sets URL for the app’s appcast. Only http and https schemes are supported.

If this function isn’t called by the app, the URL is obtained from Windows resource named “FeedURL” of type “APPCAST”.

note: Always use HTTPS feeds, do not use unencrypted HTTP! This is
necessary to prevent both leaking user information and preventing various MITM attacks.
Parameters:url – URL of the appcast.
pywinsparkle.win_sparkle_set_automatic_check_for_updates(update_state)

Sets whether updates are checked automatically or only through a manual call. If disabled, win_sparkle_check_update_with_ui() must be used explicitly.

Parameters:update_state – 1 to have updates checked automatically, 0 otherwise
pywinsparkle.win_sparkle_set_can_shutdown_callback(app_callback)

Set callback for querying the application if it can be closed.

This callback will be called to ask the host if it’s ready to shut down, before attempting to launch the installer. The callback returns TRUE if the host application can be safely shut down or FALSE if not (e.g. because the user has unsaved documents).

Note: There’s no guarantee about the thread from which the callback is called,
except that it certainly won’t be called from the app’s main thread. Make sure the callback is thread-safe.
Parameters:app_callback – The function name that should called
pywinsparkle.win_sparkle_set_did_find_update_callback(app_callback)

Set callback to be called when the updater did find an update.

This is useful in combination with win_sparkle_check_update_with_ui_and_install() as it allows you to perform some action after WinSparkle checks for updates.

Parameters:app_callback – The function name that should called
pywinsparkle.win_sparkle_set_did_not_find_update_callback(app_callback)

Set callback to be called when the updater did not find an update.

This is useful in combination with win_sparkle_check_update_with_ui_and_install() as it allows you to perform some action after WinSparkle checks for updates.

Parameters:app_callback – The function name that should called
pywinsparkle.win_sparkle_set_error_callback(app_callback)

Set callback to be called when the updater encounters an error.

Parameters:app_callback – The function name that should called
pywinsparkle.win_sparkle_set_lang(language)

Sets UI language from its Win32 LANGID code.

This function must be called before win_sparkle_init(). :param language: An int, Language code (LANGID) as created by the MAKELANGID macro or returned by e.g. ::GetThreadUILanguage()

pywinsparkle.win_sparkle_set_registry_path(registry_path)

Set the registry path where settings will be stored.

Normally, these are stored in “HKCUSoftware<company_name><app_name>WinSparkle” but if your application needs to store the data elsewhere for some reason, using this function is an alternative.

Note that @a path is relative to HKCU/HKLM root and the root is not part of it. For example: example: win_sparkle_set_registry_path(“SoftwareMy AppUpdates”);

Parameters:registry_path – Registry path where settings will be stored.
pywinsparkle.win_sparkle_set_shutdown_request_callback(app_callback)

Set callback for shutting down the application.

This callback will be called to ask the host to shut down immediately after launching the installer. Its implementation should gracefully terminate the application.

It will only be called if the call to the callback set with win_sparkle_set_can_shutdown_callback() returns TRUE.

@note There’s no guarantee about the thread from which the callback is called,
except that it certainly won’t be called from the app’s main thread. Make sure the callback is thread-safe.
Parameters:app_callback – The function name that should called
pywinsparkle.win_sparkle_set_update_cancelled_callback(app_callback)

Set callback to be called when the user cancels a download.

This is useful in combination with win_sparkle_check_update_with_ui_and_install() as it allows you to perform some action when the installation is interrupted.

Parameters:app_callback – The function name that should called
pywinsparkle.win_sparkle_set_update_check_interval(interval)

Sets the automatic update interval.

Parameters:interval – interval The interval in seconds between checks for updates. The minimum update interval is 3600 seconds (1 hour).

Indices and tables