pycrossword
0.4
Pure-Python implementation of a crossword puzzle generator and editor
|
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... | |
Class responsible for application updating and checking new available releases.
It allows for two checking / updating methods:
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 |
|||
) |
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:
|
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:
str
the current app version, e.g. '2.0'dict
the new app version, e.g. ‘{'version’: '2.1', 'hash': '', 'branch': '', 'description': '', 'date': ''}` Returns:bool
True
to continue update; False
to abort 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) |
|
private |
Compares two version strings and checks if one is later than the other.
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) |
str
comparison result:v1
is later than v2
v1
is older than v2
v1
is the same as v2
|
private |
Converts a Python datetime
object to a string.
|
private |
bool
True
if Git is installed (is accessible via Updater::git_exe); False
otherwise
|
private |
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)
|
private |
Retrieves information on the latest app version available on Github.
dict
latest version info with the following items:str
app version string (e.g. '3.0')str
Git commit hash corresponding to the versionstr
Git branch name corresponding to the versionstr
optional description of the latest releasestr
date and time of the Git commit
|
private |
Retrieves the list of remote branches for the current Git repo.
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 |
dict
remote branches found as a dictionary in the following format: 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
|
private |
Runs a Git command with or without arguments and returns the result.
args | positional arguments positional arguments passed to Git |
kwargs | keyword arguments keyword arguments passed to _run_exe() |
|
private |
Updates the app from a remote Git branch or commit.
branch_or_commit | str remote branch name or commit hash |
|
private |
Initializes Updater::update_info from the update.log file or creates that file.
|
private |
Converts a version string into a tuple of version numbers.
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. |
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)
|
private |
bool
True
if the pycrossword Python package is installed in the current Python environment (including virtualenv installation)
|
private |
Gets the latest app version on PyPi with pip.
str
app version string (e.g. '3.0')str
(EMPTY: see get_recent_version())str
(EMPTY: see get_recent_version())str
(EMPTY: see get_recent_version())str
(EMPTY: see get_recent_version())
|
private |
Gets the list of installed Python packages with pip.
outdated_only | bool if True , only outdated packages will be included in the search result |
list
Python packages as a list of dictionaries: 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'
|
private |
Runs pip and returns the result.
args | positional arguments positional arguments passed to pip |
kwargs | keyword arguments keyword arguments passed to _run_exe() |
|
private |
Updates the app from PyPi with pip.
|
private |
Runs an executable and optionally returns the result.
See utils::run_exe()
|
private |
Converts a string to a Python datetime
object.
|
private |
Strips unacceptable characters from a version string.
version_str | str the version string to sanitize |
str
sanitized version string (containing only numbers and dots)
|
private |
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)
|
private |
Writes the update info from Updater::update_info to the update.log file.
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.
force | bool check regardless of the update check interval |
dict
| None
latest version info or None
on failure. The version info dict contains the following items:str
app version string (e.g. '3.0')str
Git commit hash corresponding to the version (only for Github updates)str
Git branch name corresponding to the version (only for Github updates)str
optional description of the latest release (only for Github updates)str
date and time of the Git commit (only for Github updates) def pycross.utils.update.Updater.get_recent_version | ( | self | ) |
Retrieves information on the latest app version available on Github or PyPi.
dict
latest version info. The version info dict contains the following items:str
app version string (e.g. '3.0')str
Git commit hash corresponding to the version (only for Github updates)str
Git branch name corresponding to the version (only for Github updates)str
optional description of the latest release (only for Github updates)str
date and time of the Git commit (only for Github updates) If an error occurs the resulting dictionary contains a single item:str
the error message def pycross.utils.update.Updater.update | ( | self, | |
force = False |
|||
) |
Updates the application to the most recent version.
force | bool if set to True , the update will proceed regardless of the update check interval |
bool
False
on failure, None
on success pycross.utils.update.Updater.app_name |
str
this application name (see globalvars::APP_NAME
)
pycross.utils.update.Updater.app_version |
str
this application version (see globalvars::APP_VERSION
)
pycross.utils.update.Updater.check_every |
int
interval in days to check for updates
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
pycross.utils.update.Updater.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 pycross.utils.update.Updater.git_installed |
bool
True
if Git is installed in the current system
pycross.utils.update.Updater.git_repo |
str
the Git host (see globalvars::GIT_REPO
)
pycross.utils.update.Updater.log_file |
str
full path to the debug log file (to output messages)
pycross.utils.update.Updater.on_before_update |
callable
callback fired before the app updating process starts
pycross.utils.update.Updater.on_get_recent |
callable
callback fired when a new release is detected
pycross.utils.update.Updater.on_norecent |
callable
callback fired when no updates are available
pycross.utils.update.Updater.pkg_installed |
bool
True
if the app is currently installed via pip (from PyPi)
pycross.utils.update.Updater.print_to |
file
file-like object to output messages to
pycross.utils.update.Updater.update_file |
str
full path to the update log file (see globalvars::UPDATE_FILE
)
pycross.utils.update.Updater.update_info |
dict
update info stored in the update file The items are as follows:
str
date and time of the last update (as a string)str
date and time of the last update check (as a string)dict
info on the latest available release:str
app version string (e.g. '3.0')str
Git commit hash corresponding to the version (only for Github updates)str
Git branch name corresponding to the version (only for Github updates)str
optional description of the latest release (only for Github updates)str
date and time of the Git commit (only for Github updates)