Class responsible for application updating and checking new available releases. More...

Public Member Functions
def	__init__ (self, app_name, app_version, git_repo, update_file, log_file, check_every=1, check_major_versions=True, git_exe=None, on_get_recent=None, on_before_update=None, on_norecent=None, print_to=sys.stdout)

def	update (self, force=False)
	Updates the application to the most recent version. More...

def	check_update (self, force=False)
	Checks for the latest app version available on Github or PyPi. More...

def	get_recent_version (self)
	Retrieves information on the latest app version available on Github or PyPi. More...

Public Attributes
	app_name
	`str` this application name (see `globalvars::APP_NAME`) More...

	app_version
	`str` this application version (see `globalvars::APP_VERSION`) More...

	git_repo
	`str` the Git host (see `globalvars::GIT_REPO`) More...

	update_file
	`str` full path to the update log file (see `globalvars::UPDATE_FILE`) More...

	log_file
	`str` full path to the debug log file (to output messages) More...

	print_to
	`file` file-like object to output messages to More...

	check_every
	`int` interval in days to check for updates More...

	check_major_versions
	`bool` whether to check only for major releases (e.g. More...

	on_get_recent
	`callable` callback fired when a new release is detected More...

	on_before_update
	`callable` callback fired before the app updating process starts More...

	on_norecent
	`callable` callback fired when no updates are available More...

	update_info
	`dict` update info stored in the update file The items are as follows: More...

	git_exe
	`str` path to the Git executable More...

	git_installed
	`bool` `True` if Git is installed in the current system More...

	pkg_installed
	`bool` `True` if the app is currently installed via pip (from PyPi) More...

Private Member Functions
def	_update_check_required (self)

def	_git_check_installed (self)

def	_git_check_repo (self)

def	_git_run (self, args, *kwargs)
	Runs a Git command with or without arguments and returns the result. More...

def	_git_update_from_branch (self, branch_or_commit)
	Updates the app from a remote Git branch or commit. More...

def	_git_get_remote_branches (self, exclude_starting_with=('master',), include_starting_with=('release',))
	Retrieves the list of remote branches for the current Git repo. More...

def	_git_get_recent_version (self)
	Retrieves information on the latest app version available on Github. More...

def	_pip_run (self, args, *kwargs)
	Runs pip and returns the result. More...

def	_pip_list_packages (self, outdated_only=False)
	Gets the list of installed Python packages with pip. More...

def	_pip_check_pkg_installed (self)

def	_pip_update (self)
	Updates the app from PyPi with pip. More...

def	_pip_get_recent_version (self)
	Gets the latest app version on PyPi with pip. More...

def	_run_exe (self, args, external=False, capture_output=True, stdout=subprocess.PIPE, encoding=ENCODING, timeout=None, shell=False, **kwargs)
	Runs an executable and optionally returns the result. More...

def	_datetime_to_str (self, dt=None, strformat='%Y-%m-%d %H-%M-%S')
	Converts a Python `datetime` object to a string. More...

def	_str_to_datetime (self, text, strformat='%Y-%m-%d %H-%M-%S')
	Converts a string to a Python `datetime` object. More...

def	_init_update_info (self)
	Initializes Updater::update_info from the update.log file or creates that file. More...

def	_write_update_info (self)
	Writes the update info from Updater::update_info to the update.log file. More...

def	_strip_version_az (self, version_str)
	Strips unacceptable characters from a version string. More...

def	_parse_version (self, version_str, max_versions=-1)
	Converts a version string into a tuple of version numbers. More...

def	_compare_versions (self, v1, v2, max_versions=-1, major_only=False)
	Compares two version strings and checks if one is later than the other. More...

Detailed Description

Class responsible for application updating and checking new available releases.

It allows for two checking / updating methods:

From the Gihub repository using git.
From the PyPi repository using pip. The method is chosen automatically, depending on whether the app has been installed with pip as a Python package or is contained in a local Git repo.

Constructor & Destructor Documentation

◆ init()

def pycross.utils.update.Updater.__init__	(	self,
		app_name,
		app_version,
		git_repo,
		update_file,
		log_file,
		check_every = `1`,
		check_major_versions = `True`,
		git_exe = `None`,
		on_get_recent = `None`,
		on_before_update = `None`,
		on_norecent = `None`,
		print_to = `sys.stdout`
	)

Parameters

app_name	`str` this application name (see `globalvars::APP_NAME`)
app_version	`str` this application version (see `globalvars::APP_VERSION`)
git_repo	`str` the Git host (see `globalvars::GIT_REPO`)
update_file	`str` path to the update log file (see `globalvars::UPDATE_FILE`)
log_file	`str` path to the debug log file (to output messages)
check_every	`int` interval in days to check for updates
check_major_versions	`bool` whether to check only for major releases (e.g. 1.0... 2.0...) or all (including minor) releases
git_exe	`str` path to the Git executable (`None` means the simple string 'git' will be used, i.e. Git must be in the system path)
on_get_recent	`callable` callback fired when a new release is detected. The callback takes one argument: `dict` the new version info (see check_update() return value)
on_before_update	`callable` callback fired before the app updating process starts. Its prototype is as follows: (current_version: str, new_version: dict) -> bool

Args:

current_version str the current app version, e.g. '2.0'
new_version dict the new app version, e.g. ‘{'version’: '2.1', 'hash': '', 'branch': '', 'description': '', 'date': ''}` Returns:

bool True to continue update; False to abort

Parameters

on_norecent	`callable` callback fired when no updates are available; the callbacks takes no arguments and returns nothing
print_to	`file` file-like object to output messages to (default = `sys.stdout`, the system console output)

Member Function Documentation

◆ _compare_versions()

def pycross.utils.update.Updater._compare_versions	(	self,
		v1,
		v2,
		max_versions = `-1`,
		major_only = `False`
	)

private

Compares two version strings and checks if one is later than the other.

Parameters

v1	`str` the first (left) version string
v2	`str` the second (right) version string
max_versions	`int` max version depth to parse (see _parse_version())
major_only	`bool` compare only major versions (first version number in each version string)

Returns

str comparison result:

'>' if v1 is later than v2
'<' if v1 is older than v2
'=' if v1 is the same as v2

◆ _datetime_to_str()

def pycross.utils.update.Updater._datetime_to_str	(	self,
		dt = `None`,
		strformat = `'%Y-%m-%d %H-%M-%S'`
	)

private

Converts a Python datetime object to a string.

See utils::datetime_to_str()

◆ _git_check_installed()

def pycross.utils.update.Updater._git_check_installed ( self )

private

Returns: bool True if Git is installed (is accessible via Updater::git_exe); False otherwise

◆ _git_check_repo()

def pycross.utils.update.Updater._git_check_repo ( self )

private

Returns: bool True if the current directory is in a Git local repository (this way we check that Git updates are possible by pulling from Github)

◆ _git_get_recent_version()

def pycross.utils.update.Updater._git_get_recent_version ( self )

private

Retrieves information on the latest app version available on Github.

Returns

dict latest version info with the following items:

version str app version string (e.g. '3.0')
hash str Git commit hash corresponding to the version
branch str Git branch name corresponding to the version
description str optional description of the latest release
date str date and time of the Git commit

◆ _git_get_remote_branches()

def pycross.utils.update.Updater._git_get_remote_branches	(	self,
		exclude_starting_with = `('master',)`,
		include_starting_with = `('release',)`
	)

private

Retrieves the list of remote branches for the current Git repo.

Parameters

exclude_starting_with	`tuple` starting strings for branch names that must be excluded from the result; if `None` or empty, no branches will be excluded
include_starting_with	`tuple` starting strings for branch names that must be included in the result; if `None` or empty, no branches will be included

Returns: dict remote branches found as a dictionary in the following format:
{parsed_version: (branch_name, commit_hash), ...}

where parsed_version is a tuple returned by _parse_version(), branch_name is the branch name and commit_hash is the commit hash to which the branch is attached

◆ _git_run()

def pycross.utils.update.Updater._git_run	(		self,
		*	args,
		**	kwargs
	)

private

Runs a Git command with or without arguments and returns the result.

Parameters

args	`positional arguments` positional arguments passed to Git
kwargs	`keyword arguments` keyword arguments passed to _run_exe()

Returns: subprocess.CompletedProcess process result

◆ _git_update_from_branch()

def pycross.utils.update.Updater._git_update_from_branch	(	self,
		branch_or_commit
	)

private

Updates the app from a remote Git branch or commit.

Parameters

branch_or_commit str remote branch name or commit hash

Returns: subprocess.Popen process result

◆ _init_update_info()

def pycross.utils.update.Updater._init_update_info ( self )

private

Initializes Updater::update_info from the update.log file or creates that file.

◆ _parse_version()

def pycross.utils.update.Updater._parse_version	(	self,
		version_str,
		max_versions = `-1`
	)

private

Converts a version string into a tuple of version numbers.

Parameters

version_str	`str` the version string to convert
max_versions	`int` max version depth to convert. For example, if `version_str` == '3.0.1.2' and `max_versions` == 2, the resulting tuple will be `(3, 0)` – only 2 version sections. The value of -1 (default) lifts this limitation.

Returns: tuple | None tuple containing the version sections in their original order, e.g. '3.0.1.2' -> (3, 0, 1, 2); None on failure (incorrect input version string)

◆ _pip_check_pkg_installed()

def pycross.utils.update.Updater._pip_check_pkg_installed ( self )

private

Returns: bool True if the pycrossword Python package is installed in the current Python environment (including virtualenv installation)

◆ _pip_get_recent_version()

def pycross.utils.update.Updater._pip_get_recent_version ( self )

private

Gets the latest app version on PyPi with pip.

Returns

latest version info. The version info dict contains the following items:

version str app version string (e.g. '3.0')
hash str (EMPTY: see get_recent_version())
branch str (EMPTY: see get_recent_version())
description str (EMPTY: see get_recent_version())
date str (EMPTY: see get_recent_version())

◆ _pip_list_packages()

def pycross.utils.update.Updater._pip_list_packages	(	self,
		outdated_only = `False`
	)

private

Gets the list of installed Python packages with pip.

Parameters

outdated_only bool if True, only outdated packages will be included in the search result

Returns: list Python packages as a list of dictionaries:
[{'name': pk_name, 'version': pk_version}, ...]

if outdated_only == False, each dict contains 2 elements: 'name' and 'version' if outdated_only == True, 2 additional keys are present: 'latest_version' and 'latest_filetype'

◆ _pip_run()

def pycross.utils.update.Updater._pip_run	(		self,
		*	args,
		**	kwargs
	)

private

Runs pip and returns the result.

Parameters

args	`positional arguments` positional arguments passed to pip
kwargs	`keyword arguments` keyword arguments passed to _run_exe()

Returns: subprocess.CompletedProcess process result

◆ _pip_update()

def pycross.utils.update.Updater._pip_update ( self )

private

Updates the app from PyPi with pip.

Returns: subprocess.Popen process result

◆ _run_exe()

def pycross.utils.update.Updater._run_exe	(		self,
			args,
			external = `False`,
			capture_output = `True`,
			stdout = `subprocess.PIPE`,
			encoding = `ENCODING`,
			timeout = `None`,
			shell = `False`,
		**	kwargs
	)

private

Runs an executable and optionally returns the result.

See utils::run_exe()

◆ _str_to_datetime()

def pycross.utils.update.Updater._str_to_datetime	(	self,
		text,
		strformat = `'%Y-%m-%d %H-%M-%S'`
	)

private

Converts a string to a Python datetime object.

See utils::str_to_datetime()

◆ _strip_version_az()

def pycross.utils.update.Updater._strip_version_az	(	self,
		version_str
	)

private

Strips unacceptable characters from a version string.

Parameters

version_str str the version string to sanitize

Returns: str sanitized version string (containing only numbers and dots)

◆ _update_check_required()

def pycross.utils.update.Updater._update_check_required ( self )

private

Returns: bool True if update checking is required (based on the update check interval stored in the app settings); False if not required (the app has been updated recently and the check interval hasn't yet elapsed since the last update)

◆ _write_update_info()

def pycross.utils.update.Updater._write_update_info ( self )

private

Writes the update info from Updater::update_info to the update.log file.

◆ check_update()

def pycross.utils.update.Updater.check_update	(	self,
		force = `False`
	)

Checks for the latest app version available on Github or PyPi.

This method also updates the update.log file so the application can read the release info on next startup.

Parameters

force bool check regardless of the update check interval

Returns

dict | None latest version info or None on failure. The version info dict contains the following items:

version str app version string (e.g. '3.0')
hash str Git commit hash corresponding to the version (only for Github updates)
branch str Git branch name corresponding to the version (only for Github updates)
description str optional description of the latest release (only for Github updates)
date str date and time of the Git commit (only for Github updates)

◆ get_recent_version()

def pycross.utils.update.Updater.get_recent_version ( self )

Retrieves information on the latest app version available on Github or PyPi.

Returns

dict latest version info. The version info dict contains the following items:

version str app version string (e.g. '3.0')
hash str Git commit hash corresponding to the version (only for Github updates)
branch str Git branch name corresponding to the version (only for Github updates)
description str optional description of the latest release (only for Github updates)
date str date and time of the Git commit (only for Github updates) If an error occurs the resulting dictionary contains a single item:
error str the error message

◆ update()

def pycross.utils.update.Updater.update	(	self,
		force = `False`
	)

Updates the application to the most recent version.

Parameters

force bool if set to True, the update will proceed regardless of the update check interval

Returns: bool False on failure, None on success

Member Data Documentation

◆ app_name

pycross.utils.update.Updater.app_name

str this application name (see globalvars::APP_NAME)

◆ app_version

pycross.utils.update.Updater.app_version

str this application version (see globalvars::APP_VERSION)

◆ check_every

pycross.utils.update.Updater.check_every

int interval in days to check for updates

◆ check_major_versions

pycross.utils.update.Updater.check_major_versions

bool whether to check only for major releases (e.g.

1.0... 2.0...) or all (including minor) releases

◆ git_exe

pycross.utils.update.Updater.git_exe

str path to the Git executable

Warning: None means the simple string 'git' will be used, i.e. Git must be in the system path

◆ git_installed

pycross.utils.update.Updater.git_installed

bool True if Git is installed in the current system

◆ git_repo

pycross.utils.update.Updater.git_repo

str the Git host (see globalvars::GIT_REPO)

◆ log_file

pycross.utils.update.Updater.log_file

str full path to the debug log file (to output messages)

◆ on_before_update

pycross.utils.update.Updater.on_before_update

callable callback fired before the app updating process starts

◆ on_get_recent

pycross.utils.update.Updater.on_get_recent

callable callback fired when a new release is detected

◆ on_norecent

pycross.utils.update.Updater.on_norecent

callable callback fired when no updates are available

◆ pkg_installed

pycross.utils.update.Updater.pkg_installed

bool True if the app is currently installed via pip (from PyPi)

◆ print_to

pycross.utils.update.Updater.print_to

file file-like object to output messages to

◆ update_file

pycross.utils.update.Updater.update_file

str full path to the update log file (see globalvars::UPDATE_FILE)

◆ update_info

pycross.utils.update.Updater.update_info

dict update info stored in the update file The items are as follows:

last_update str date and time of the last update (as a string)
last_check str date and time of the last update check (as a string)
recent_version dict info on the latest available release:
- version str app version string (e.g. '3.0')
- hash str Git commit hash corresponding to the version (only for Github updates)
- branch str Git branch name corresponding to the version (only for Github updates)
- description str optional description of the latest release (only for Github updates)
- date str date and time of the Git commit (only for Github updates)

The documentation for this class was generated from the following file:

pycross/utils/update.py

Public Member Functions

Public Attributes

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ _compare_versions()

◆ _datetime_to_str()

◆ _git_check_installed()

◆ _git_check_repo()

◆ _git_get_recent_version()

◆ _git_get_remote_branches()

◆ _git_run()

◆ _git_update_from_branch()

◆ _init_update_info()

◆ _parse_version()

◆ _pip_check_pkg_installed()

◆ _pip_get_recent_version()

◆ _pip_list_packages()

◆ _pip_run()

◆ _pip_update()

◆ _run_exe()

◆ _str_to_datetime()

◆ _strip_version_az()

◆ _update_check_required()

◆ _write_update_info()

◆ check_update()

◆ get_recent_version()

◆ update()

Member Data Documentation

◆ app_name

◆ app_version

◆ check_every

◆ check_major_versions

◆ git_exe

◆ git_installed

◆ git_repo

◆ log_file

◆ on_before_update

◆ on_get_recent

◆ on_norecent

◆ pkg_installed

◆ print_to

◆ update_file

◆ update_info

◆ init()