pycrossword  0.4
Pure-Python implementation of a crossword puzzle generator and editor
Public Member Functions | Public Attributes | Private Member Functions | List of all members
pycross.utils.update.Updater Class Reference

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:

  1. From the Gihub repository using git.
  2. 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_namestr this application name (see globalvars::APP_NAME)
app_versionstr this application version (see globalvars::APP_VERSION)
git_repostr the Git host (see globalvars::GIT_REPO)
update_filestr path to the update log file (see globalvars::UPDATE_FILE)
log_filestr path to the debug log file (to output messages)
check_everyint interval in days to check for updates
check_major_versionsbool whether to check only for major releases (e.g. 1.0... 2.0...) or all (including minor) releases
git_exestr 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_recentcallable callback fired when a new release is detected. The callback takes one argument:
on_before_updatecallable 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_norecentcallable callback fired when no updates are available; the callbacks takes no arguments and returns nothing
    print_tofile 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
v1str the first (left) version string
v2str the second (right) version string
max_versionsint max version depth to parse (see _parse_version())
major_onlybool 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_withtuple starting strings for branch names that must be excluded from the result; if None or empty, no branches will be excluded
include_starting_withtuple 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
argspositional arguments positional arguments passed to Git
kwargskeyword 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_commitstr 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_strstr the version string to convert
max_versionsint 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:

◆ _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_onlybool 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
argspositional arguments positional arguments passed to pip
kwargskeyword 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_strstr 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
forcebool 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
forcebool 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: