aedev.git_repo_manager.__main__

main module of git_repo_manager.

Module Attributes

ANY_PRJ_TYPE	tuple of available project types (including the pseudo-project-types: no-/incomplete-project and parent-folder)
ARG_MULTIPLES	mark multiple args in the _action() arg_names kwarg
ARG_ALL	all argument, used for lists e.g. of namespace portions.
ARGS_CHILDREN_DEFAULT	default arguments for children actions.
CMD_PIP	pip command using python venvs, especially on Windows
CMD_INSTALL	pip install command
COMMIT_MSG_FILE_NAME	name of the file containing the commit message
DJANGO_EXCLUDED_FROM_CLEANUP	set of file path masks/pattern to exclude essential files from to be cleaned-up on the server.
GIT_FOLDER_NAME	git sub-folder in project path root of local repository
NULL_VERSION	initial package version number for new project
LOCK_EXT	additional file extension to block updates from templates
MAIN_BRANCH	main/develop/default branch name
MOVE_TPL_TO_PKG_PATH_NAME_PREFIX	template file/folder name prefix, to move the templates to the package path (instead of the project path); has to be specified after SKIP_IF_PORTION_DST_NAME_PREFIX (if both prefixes are needed).
OUTSOURCED_MARKER	to mark an outsourced project file, maintained externally
OUTSOURCED_FILE_NAME_PREFIX	file name prefix of outsourced/externally maintained file
PROJECT_VERSION_SEP	separates package name and version in pip req files
PPF(object)
SKIP_IF_PORTION_DST_NAME_PREFIX	skip portion prj template dst root folder/file nam prefix
SKIP_PRJ_TYPE_FILE_NAME_PREFIX	file name prefix of skipped template if dst != prj type
TEMPLATE_PLACEHOLDER_ID_PREFIX	template id prefix marker
TEMPLATE_PLACEHOLDER_ID_SUFFIX	template id suffix marker
TEMPLATE_PLACEHOLDER_ARGS_SUFFIX	template args suffix marker
TEMPLATE_INCLUDE_FILE_PLACEHOLDER_ID	placeholder (func:replace_with_file_content_or_default)
TPL_FILE_NAME_PREFIX	file name prefix if template contains f-strings
TPL_IMPORT_NAME_PREFIX	package/import name prefix of template projects
TPL_STOP_CNV_PREFIX	file name prefix to support template of template
TPL_PACKAGES	import names of all possible template projects
TEMPLATES_FILE_NAME_PREFIXES	supported template file name prefixes (in the order they have to specified, apart from TPL_STOP_CNV_PREFIX which can be specified anywhere, to deploy template files to other template projects).
VERSION_MATCHER	pre-compiled regular expression to detect and bump the app/portion file version numbers of a version string.
ActionArgs	action arguments specified on grm command line
ActionFlags	action flags/kwargs specified on grm command line
RegisteredTemplateProject	registered template project info (tpl_projects item)
PdvType	project development variables type
ChildrenType	children pdv of a project parent or a namespace root
RepoType	repo host libs repo object (PyGithub, python-gitlab)
REGISTERED_ACTIONS	implemented actions registered via _action() deco
REGISTERED_HOSTS_CLASS_NAMES	class names of all supported remote host domains
REGISTERED_TPL_PROJECTS	projects providing templates and outsourced files
TEMP_CONTEXT	temp patch folder context (optional/lazy/late created)
cae	main app instance of this grm tool, initialized out of __name__ == '__main__' to be used for unit tests

Functions

activate_venv([name])	ensure to activate a virtual environment if it is different to the current one (the one on Python/app start).
active_venv()	determine the virtual environment that is currently active.
add_children_file(ini_pdv, file_name, ...)	add a file, template of outsourced text file to the working trees of parent/root and children/portions.
add_file(ini_pdv, file_name, rel_path)	add file, template or outsourced text file into the project working tree.
bump_file_version(file_name[, increment_part])	increment part of version number of module/script file, also removing any pre/alpha version sub-part/suffix.
bump_version(ini_pdv)	increment project version.
bytes_file_diff(file_content, file_path[, ...])	return the differences between the content of a file against a bytes array.
check_children_integrity(parent_pdv, ...)	run integrity checks for the specified children of a parent or portions of a namespace.
check_integrity(ini_pdv)	integrity check of files/folders completeness, outsourced/template files update-state and CI tests.
clone_children(parent_or_root_pdv, ...)	clone specified namespace-portion/parent-child repos to the local machine.
clone_project(ini_pdv[, package_or_portion])	clone remote repo to the local machine.
commit_children(ini_pdv, *children_pdv)	commit changes to children of a namespace/parent using the individually prepared commit message files.
commit_project(ini_pdv)	commit changes of a single project to the local repo using the prepared commit message file.
delete_children_file(ini_pdv, file_name, ...)	delete file or empty folder from parent/root and children/portions working trees.
delete_file(ini_pdv, file_name)	delete file or empty folder from project working tree.
deploy_template(tpl_file_path, dst_path, ...)	create/update outsourced project file content from a template.
editable_project_path(project_name)	determine the project path of a project package installed as editable.
find_extra_modules(project_path[, ...])	determine additional modules of a local (namespace portion) project.
find_git_branch_files(project_path[, ...])	find all added/changed/deleted/renamed/unstaged worktree files that are not merged into the main branch.
find_project_files(project_path, root_path_masks)	find all files of a python package including the .py modules.
in_venv([name])	ensure the virtual environment gets activated within the context.
increment_version(version[, increment_part])	increment version number.
install_children_editable(ini_pdv, *children_pdv)	install parent children or namespace portions as editable on local machine.
install_editable(ini_pdv)	install project as editable from source/project root folder.
install_requirements(req_file[, project_path])	install requirements from requirements*.txt file with pip
main()	main app script
main_file_path(project_path, project_type, ...)	return the file path of the main/version type for the specified project type.
new_app(ini_pdv)	create or complete/renew a gui app project.
new_children(ini_pdv, *children_pdv)	initialize or renew parent folder children or namespace portions.
new_django(ini_pdv)	create or complete/renew a django project.
new_module(ini_pdv)	create or complete/renew module project.
new_namespace_root(ini_pdv)	create or complete/renew namespace root package.
new_package(ini_pdv)	create or complete/renew package project.
new_project(ini_pdv)	complete/renew an existing project.
on_ci_host()	check and return True if this tool is running on the GitLab/GitHub CI host/server.
patch_string(content, pdv, **replacer)	replace f-string / dynamic placeholders in content with variable values / return values of replacer callables.
pdv_str(pdv, var_name)	string value of project development variable var_name of pdv.
pdv_val(pdv, var_name)	determine value of project development variable from passed pdv or aedev_setup_project module constant.
prepare_and_run_main()	prepare and run app
prepare_children_commit(ini_pdv, title, ...)	run code checks and prepare/overwrite the commit message file for a bulk-commit of children projects.
prepare_commit(ini_pdv[, title])	run code checks and prepare/overwrite the commit message file for the commit of a single project/package.
project_dev_vars([project_path])	analyse and map an extended project development environment, including template/root projects and git status.
project_version(imp_or_pkg_name, ...)	determine package name and version in list of package/version strings.
pypi_versions(pip_name)	determine all the available release versions of a package hosted at the PyPI 'Cheese Shop'.
refresh_children_outsourced(ini_pdv, ...)	refresh outsourced files from templates in namespace/project-parent children projects.
refresh_outsourced(ini_pdv)	refresh/renew all the outsourced files in the specified project.
refresh_templates(pdv[, logger])	convert ae namespace package templates found in the cwd or underneath (except excluded) to the final files.
rename_children_file(ini_pdv, old_file_name, ...)	rename file or folder in parent/root and children/portions working trees.
rename_file(ini_pdv, old_file_name, ...)	rename file or folder in project working tree.
replace_file_version(file_name[, ...])	replace version number of module/script file.
replace_with_file_content_or_default(args_str)	return file content if file name specified in first string arg exists, else return empty string or 2nd arg str.
root_packages_masks(pdv)	determine root sub packages from the passed project packages and add them glob path wildcards.
run_children_command(ini_pdv, command, ...)	run console command for the specified portions/children of a namespace/parent.
show_actions(ini_pdv)	get info of available/registered/implemented actions of the specified/current project and remote.
show_children_status(ini_pdv, *children_pdv)	run integrity checks for the specified portions/children of a namespace/parent.
show_children_versions(ini_pdv, *children_pdv)	show package versions (local, remote and on pypi) for the specified children of a namespace/parent.
show_status(ini_pdv)	show git status of the specified/current project and remote.
show_versions(ini_pdv)	display package versions of worktree, remote/origin repo, latest PyPI release and default app/web host.
skip_files_lean_web(file_path)	file exclude callback to reduce the deployed files on the web server to the minimum.
skip_files_migrations(file_path)	file exclude callback for the files under the django migrations folders.
update_children(ini_pdv, *children_pdv)	fetch and rebase the MAIN_BRANCH to the local children repos of the parent/namespace-root(also updated).
update_project(ini_pdv)	fetch and rebase the MAIN_BRANCH of the specified project in the local repo.
venv_bin_path([name])	determine the absolute path of the bin/executables folder of a virtual pyenv environment.

Classes

GithubCom()	remote connection and actions on remote repo in gitHub.com.
GitlabCom()	remote connection and actions on gitlab.com.
PythonanywhereCom()	remote actions on remote web host pythonanywhere.com (to be specified by --domain option).
RemoteHost()	base class registering subclasses as remote host repo class in REGISTERED_HOSTS_CLASS_NAMES.

ANY_PRJ_TYPE = ('app', 'django', 'module', 'package', 'namespace-root')

tuple of available project types (including the pseudo-project-types: no-/incomplete-project and parent-folder)

ARG_MULTIPLES = ' ...'

mark multiple args in the _action() arg_names kwarg

ARG_ALL = 'all'

all argument, used for lists e.g. of namespace portions

ARGS_CHILDREN_DEFAULT = (('all',), ('children-sets-expr',), ('children-names ...',))

default arguments for children actions.

CMD_PIP = 'python -m pip'

pip command using python venvs, especially on Windows

CMD_INSTALL = 'python -m pip install'

pip install command

COMMIT_MSG_FILE_NAME = '.commit_msg.txt'

name of the file containing the commit message

DJANGO_EXCLUDED_FROM_CLEANUP = {'**/django.mo', 'db.sqlite', 'media/**/*', 'project.db', 'static/**/*'}

set of file path masks/pattern to exclude essential files from to be cleaned-up on the server.

GIT_FOLDER_NAME = '.git'

git sub-folder in project path root of local repository

NULL_VERSION = '0.0.0'

initial package version number for new project

LOCK_EXT = '.locked'

additional file extension to block updates from templates

MAIN_BRANCH = 'develop'

main/develop/default branch name

MOVE_TPL_TO_PKG_PATH_NAME_PREFIX = 'de_mtp_'

template file/folder name prefix, to move the templates to the package path (instead of the project path); has to be specified after SKIP_IF_PORTION_DST_NAME_PREFIX (if both prefixes are needed).

OUTSOURCED_MARKER = 'THIS FILE IS EXCLUSIVELY MAINTAINED'

to mark an outsourced project file, maintained externally

OUTSOURCED_FILE_NAME_PREFIX = 'de_otf_'

file name prefix of outsourced/externally maintained file

PROJECT_VERSION_SEP = '=='

separates package name and version in pip req files

PPF(object)

formatter for console printouts

SKIP_IF_PORTION_DST_NAME_PREFIX = 'de_sfp_'

skip portion prj template dst root folder/file nam prefix

SKIP_PRJ_TYPE_FILE_NAME_PREFIX = 'de_spt_'

file name prefix of skipped template if dst != prj type

TEMPLATE_PLACEHOLDER_ID_PREFIX = '# '

template id prefix marker

TEMPLATE_PLACEHOLDER_ID_SUFFIX = '#('

template id suffix marker

TEMPLATE_PLACEHOLDER_ARGS_SUFFIX = ')#'

template args suffix marker

TEMPLATE_INCLUDE_FILE_PLACEHOLDER_ID = 'IncludeFile'

placeholder (func:replace_with_file_content_or_default)

TPL_FILE_NAME_PREFIX = 'de_tpl_'

file name prefix if template contains f-strings

TPL_IMPORT_NAME_PREFIX = 'aedev.tpl_'

package/import name prefix of template projects

TPL_STOP_CNV_PREFIX = '_z_'

file name prefix to support template of template

TPL_PACKAGES = ['aedev.tpl_app', 'aedev.tpl_django', 'aedev.tpl_module', 'aedev.tpl_package', 'aedev.tpl_namespace_root', 'aedev.tpl_project']

import names of all possible template projects

TEMPLATES_FILE_NAME_PREFIXES = ('de_sfp_', 'de_spt_', 'de_otf_', 'de_tpl_', '_z_')

supported template file name prefixes (in the order they have to specified, apart from TPL_STOP_CNV_PREFIX which can be specified anywhere, to deploy template files to other template projects).

Hint

SKIP_IF_PORTION_DST_NAME_PREFIX can also be path name prefix, like MOVE_TPL_TO_PKG_PATH_NAME_PREFIX.

VERSION_MATCHER = re.compile("^__version__ = '(\\d+)[.](\\d+)[.](\\d+)[a-z\\d]*'", re.MULTILINE)

pre-compiled regular expression to detect and bump the app/portion file version numbers of a version string.

The version number format has to be conform to PEP396 and the sub-part to Pythons distutils (trailing version information indicating sub-releases, are either “a1,a2,…,aN” (for alpha releases), “b1,b2,…,bN” (for beta releases) or “pr1,pr2,…,prN” (for pre-releases). Note that distutils got deprecated in Python 3.12 (see package packaging.version as replacement)).

ActionArgs

action arguments specified on grm command line

alias of List[str]

ActionFlags

action flags/kwargs specified on grm command line

alias of Dict[str, Any]

RegisteredTemplateProject

registered template project info (tpl_projects item)

alias of Dict[str, str]

PdvType

project development variables type

alias of Dict[str, Any]

ChildrenType

children pdv of a project parent or a namespace root

alias of OrderedDict[str, Dict[str, Any]]

RepoType

repo host libs repo object (PyGithub, python-gitlab)

alias of Repository | Project

REGISTERED_ACTIONS: Dict[str, Dict[str, Any]] = {'GithubCom.fork_project': {'annotations': {'forked_usr_repo': <class 'str'>, 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('forked-user-slash-repo',),), 'docstring': ' create/renew fork of a remote repo specified via the 1st argument, into our user/group namespace. ', 'local_action': False, 'project_types': ('projects-parent-dir', 'app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'fork'}, 'GithubCom.push_project': {'annotations': {'branch_name': <class 'str'>, 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': ((), ('branch-name',)), 'docstring': ' push current/specified branch of project/package to remote host domain, version-tagged if release is True.\n\n        :param branch_name:         optional branch name to push (alternatively specified by the ``branch`` command line\n                                    option).\n        ', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'push'}, 'GithubCom.release_project': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'version_tag': <class 'str'>}, 'arg_names': (('version-tag',), ('LATEST',)), 'docstring': ' update local MAIN_BRANCH from origin and if pip_name is set then also release the latest/specified version.\n\n        :param version_tag:     push version tag in the format ``v<version-number>`` to release or ``LATEST`` to use\n                                the version tag of the latest git repository version.\n        ', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'release'}, 'GithubCom.request_merge': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' request merge of the origin=fork repository into the main branch at remote/upstream=forked. ', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'request'}, 'GitlabCom.clean_releases': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'return': typing.List[str]}, 'docstring': ' delete local+remote release tags and branches of the specified project that got not published to PYPI. ', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root')}, 'GitlabCom.fork_children': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' fork children of a namespace root project or of a parent folder. ', 'local_action': False, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'GitlabCom.fork_project': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' create/renew fork of a remote repo specified via the ``package`` option, into our user/group namespace. ', 'local_action': False, 'project_types': ('projects-parent-dir', 'app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'fork'}, 'GitlabCom.push_children': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' push specified children projects to remotes/origin. ', 'local_action': False, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'push'}, 'GitlabCom.push_project': {'annotations': {'branch_name': <class 'str'>, 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': ((), ('branch-name',)), 'docstring': ' push current/specified branch of project/package to remote host domain, version-tagged if release is True.\n\n        :param branch_name:         optional branch name to push (alternatively specified by the ``branch`` command line\n                                    option).\n        ', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'push'}, 'GitlabCom.release_children': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' release the latest versions of the specified parent/root children projects to remotes/origin. ', 'local_action': False, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'release'}, 'GitlabCom.release_project': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'version_tag': <class 'str'>}, 'arg_names': (('version-tag',), ('LATEST',)), 'docstring': ' update local MAIN_BRANCH from origin and if pip_name is set then also release the latest/specified version.\n\n        :param version_tag:     push version tag in the format ``v<version-number>`` to release or ``LATEST`` to use\n                                the version tag of the latest git repository version.\n        ', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'release'}, 'GitlabCom.request_children_merge': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' request the merge of the specified children of a parent/namespace on remote/upstream. ', 'local_action': False, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'request'}, 'GitlabCom.request_merge': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' request merge of the origin=fork repository into the main branch at remote/upstream=forked. ', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'request'}, 'GitlabCom.search_repos': {'annotations': {'fragment': <class 'str'>, 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': ((), ('fragment',)), 'docstring': ' search remote repositories via a text fragment in its project name/description. ', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root')}, 'GitlabCom.show_children_repos': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' display remote properties of parent/root children repos. ', 'local_action': False, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'GitlabCom.show_repo': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' display properties of remote repository. ', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root')}, 'PythonanywhereCom.check_deploy': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'version_tag': <class 'str'>}, 'arg_names': (('version-tag',), ('LATEST',), ('WORKTREE',)), 'docstring': ' check all project package files at the app/web server against the specified package version.\n\n\n        :param version_tag:     version tag in the format ``v<version-number>`` to check or ``LATEST`` to check against\n                                the latest repository version or ``WORKTREE`` to check directly against\n                                the local work tree (with the locally added, unstaged and changed files).\n\n        :param optional_flags:  additional/optionally supported command line arguments:\n\n                                * ``ALL`` is including all deployable package files, instead of only the new, changed or\n                                  deleted files in the specified repository.\n                                * ``CLEANUP`` is checking for deletable files on the web server/host, e.g. after\n                                  they got removed from the specified repository or work tree.\n                                * ``LEAN`` is reducing the deployable files sets to the minimum (using e.g. the function\n                                  :func:`skip_files_lean_web`), like e.g. the gettext ``.po`` files,\n                                  the ``media_ini`` root folder, and the ``static`` sub-folder with the initial static\n                                  files of the web project.\n                                * ``MASKS`` specifies a list of file paths masks/pattern to be included in the\n                                  repository files to check/deploy. to include e.g. the files of the static root folder\n                                  specify this argument as ``MASKS="[\'static/**/*\']"``. single files can be included\n                                  too, by adding their possible file names to the list - only the found ones will be\n                                  included. for example to include the django database you could add some possible DB\n                                  file names to the list like in ``"MASKS=[\'static/**/*\', \'db.sqlite\', \'project.db\']"``\n\n        ', 'flags': {'ALL': False, 'CLEANUP': False, 'LEAN': False, 'MASKS': []}, 'local_action': False, 'project_types': ('app', 'django')}, 'PythonanywhereCom.deploy_project': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'version_tag': <class 'str'>}, 'arg_names': (('version-tag',), ('LATEST',), ('WORKTREE',)), 'docstring': ' deploy code files of django/app project version to the web-/app-server.\n\n        :param version_tag:     version tag in the format ``v<version-number>`` to deploy or ``LATEST`` to use\n                                the tag of the latest repository version or ``WORKTREE`` to deploy directly\n                                from the local work tree (including locally added, unstaged and changed files).\n        :param optional_flags:  optional command line arguments, documented in the :meth:`.check_deploy` action.\n        ', 'flags': {'ALL': False, 'CLEANUP': False, 'LEAN': False, 'MASKS': []}, 'local_action': False, 'project_types': ('app', 'django'), 'shortcut': 'deploy'}, 'add_children_file': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'file_name': <class 'str'>, 'ini_pdv': typing.Dict[str, typing.Any], 'rel_path': <class 'str'>, 'return': <class 'bool'>}, 'arg_names': (('source-name', 'rel-path', 'all'), ('source-name', 'rel-path', 'children-sets-expr'), ('source-name', 'rel-path', 'children-names ...')), 'docstring': ' add a file, template of outsourced text file to the working trees of parent/root and children/portions.\n\n    :param file_name:           source (template) file name (optional with path).\n    :param rel_path:            relative destination path within the working tree.\n    :param children_pdv:        project dev vars of the children to process.\n    ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'add_file': {'annotations': {'file_name': <class 'str'>, 'ini_pdv': typing.Dict[str, typing.Any], 'rel_path': <class 'str'>, 'return': <class 'bool'>}, 'arg_names': (('source-name', 'rel-path'),), 'docstring': ' add file, template or outsourced text file into the project working tree.\n\n    :param file_name:           file name to add (optional with abs. path, else relative to working tree root folder).\n    :param rel_path:            relative path in destination project working tree.\n    ', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root')}, 'bump_version': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' increment project version. ', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root')}, 'check_children_integrity': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'parent_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' run integrity checks for the specified children of a parent or portions of a namespace. ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'check'}, 'check_integrity': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' integrity check of files/folders completeness, outsourced/template files update-state and CI tests. ', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'check'}, 'clone_children': {'annotations': {'parent_or_root_pdv': typing.Dict[str, typing.Any], 'project_versions': <class 'str'>, 'return': typing.List[str]}, 'arg_names': (('package-versions ...',),), 'docstring': ' clone specified namespace-portion/parent-child repos to the local machine.\n\n    :param parent_or_root_pdv:  vars of the parent/namespace-root project.\n    :param project_versions:    package/project names with optional version of the children to be cloned.\n    ', 'local_action': True, 'pre_action': <function _check_children_not_exist>, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'clone'}, 'clone_project': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'package_or_portion': <class 'str'>, 'return': <class 'str'>}, 'arg_names': (('--project',), ('--path',), ('package-name',), ('portion-name',)), 'docstring': ' clone remote repo to the local machine.\n\n    :param package_or_portion:  name of the package/portion to clone, optionally with version number.\n    ', 'local_action': True, 'pre_action': <function _check_children_not_exist>, 'project_types': ('namespace-root', 'projects-parent-dir'), 'shortcut': 'clone'}, 'commit_children': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' commit changes to children of a namespace/parent using the individually prepared commit message files. ', 'local_action': True, 'pre_action': <function check_children_integrity>, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'commit'}, 'commit_project': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' commit changes of a single project to the local repo using the prepared commit message file. ', 'local_action': True, 'pre_action': <function check_integrity>, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'commit'}, 'delete_children_file': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'file_name': <class 'str'>, 'ini_pdv': typing.Dict[str, typing.Any], 'return': <class 'bool'>}, 'arg_names': (('file-or-folder-name', 'all'), ('file-or-folder-name', 'children-sets-expr'), ('file-or-folder-name', 'children-names ...')), 'docstring': ' delete file or empty folder from parent/root and children/portions working trees.\n\n    :param file_name:           file/folder name to delete (optional with path, relative to working tree root folder).\n    :param children_pdv:        tuple of children project dev vars.\n    ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'delete_file': {'annotations': {'file_name': <class 'str'>, 'ini_pdv': typing.Dict[str, typing.Any], 'return': <class 'bool'>}, 'arg_names': (('file-or-folder-name',),), 'docstring': ' delete file or empty folder from project working tree.\n\n    :param file_name:           file/folder name to delete (optional with path, relative to working tree root folder).\n    ', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root')}, 'install_children_editable': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' install parent children or namespace portions as editable on local machine. ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'editable'}, 'install_editable': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' install project as editable from source/project root folder. ', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'editable'}, 'new_app': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'return': typing.Dict[str, typing.Any]}, 'docstring': ' create or complete/renew a gui app project. ', 'local_action': True, 'project_types': ('', 'projects-parent-dir', 'app', 'django', 'module', 'package', 'namespace-root')}, 'new_children': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any], 'return': typing.List[typing.Dict[str, typing.Any]]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' initialize or renew parent folder children or namespace portions. ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'renew'}, 'new_django': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'return': typing.Dict[str, typing.Any]}, 'docstring': ' create or complete/renew a django project. ', 'local_action': True, 'project_types': ('', 'projects-parent-dir', 'app', 'django', 'module', 'package', 'namespace-root')}, 'new_module': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'return': typing.Dict[str, typing.Any]}, 'docstring': ' create or complete/renew module project. ', 'local_action': True, 'project_types': ('', 'projects-parent-dir', 'app', 'django', 'module', 'package', 'namespace-root')}, 'new_namespace_root': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'return': typing.Dict[str, typing.Any]}, 'docstring': ' create or complete/renew namespace root package. ', 'local_action': True, 'project_types': ('', 'projects-parent-dir', 'app', 'django', 'module', 'package', 'namespace-root')}, 'new_package': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'return': typing.Dict[str, typing.Any]}, 'docstring': ' create or complete/renew package project. ', 'local_action': True, 'project_types': ('', 'projects-parent-dir', 'app', 'django', 'module', 'package', 'namespace-root')}, 'new_project': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'return': typing.Dict[str, typing.Any]}, 'docstring': ' complete/renew an existing project. ', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'renew'}, 'prepare_children_commit': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any], 'title': <class 'str'>}, 'arg_names': (('commit-message-title', 'all'), ('commit-message-title', 'children-sets-expr'), ('commit-message-title', 'children-names ...')), 'docstring': ' run code checks and prepare/overwrite the commit message file for a bulk-commit of children projects.\n\n    :param title:               optional commit message title.\n    :param children_pdv:        tuple of project dev vars of the children to process.\n    ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'prepare'}, 'prepare_commit': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'title': <class 'str'>}, 'arg_names': ((), ('commit-message-title',)), 'docstring': ' run code checks and prepare/overwrite the commit message file for the commit of a single project/package.\n\n    :param title:               optional commit message title.\n    ', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'prepare'}, 'refresh_children_outsourced': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' refresh outsourced files from templates in namespace/project-parent children projects. ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'refresh'}, 'refresh_outsourced': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' refresh/renew all the outsourced files in the specified project. ', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'refresh'}, 'rename_children_file': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any], 'new_file_name': <class 'str'>, 'old_file_name': <class 'str'>, 'return': <class 'bool'>}, 'arg_names': (('old-name', 'new-name', 'all'), ('old-name', 'new-name', 'children-sets-expr'), ('old-name', 'new-name', 'children-names ...')), 'docstring': ' rename file or folder in parent/root and children/portions working trees.\n\n    :param old_file_name:       file/folder name to rename (optional with path, relative to working tree root folder).\n    :param new_file_name:       new name of file/folder (optional with path, relative to working tree root folder).\n    :param children_pdv:        tuple of project dev vars of the children to process.\n    ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'rename_file': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'new_file_name': <class 'str'>, 'old_file_name': <class 'str'>, 'return': <class 'bool'>}, 'arg_names': (('old-file-or-folder-name', 'new-file-or-folder-name'),), 'docstring': ' rename file or folder in project working tree.\n\n    :param old_file_name:       source file/folder (optional with path, absolute or relative to project working tree).\n    :param new_file_name:       destination file/folder (optional path, absolute or relative to project working tree).\n    ', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root')}, 'run_children_command': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'command': <class 'str'>, 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('command', 'all'), ('command', 'children-sets-expr'), ('command', 'children-names ...')), 'docstring': ' run console command for the specified portions/children of a namespace/parent.\n\n    :param command:             console command string (including all command arguments).\n    :param children_pdv:        tuple of children project dev vars.\n    ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'run'}, 'show_actions': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' get info of available/registered/implemented actions of the specified/current project and remote. ', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'actions'}, 'show_children_status': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' run integrity checks for the specified portions/children of a namespace/parent. ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'status'}, 'show_children_versions': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' show package versions (local, remote and on pypi) for the specified children of a namespace/parent. ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'versions'}, 'show_status': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' show git status of the specified/current project and remote. ', 'local_action': True, 'project_types': ('projects-parent-dir', 'app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'status'}, 'show_versions': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any]}, 'docstring': ' display package versions of worktree, remote/origin repo, latest PyPI release and default app/web host. ', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'versions'}, 'update_children': {'annotations': {'children_pdv': typing.Dict[str, typing.Any], 'ini_pdv': typing.Dict[str, typing.Any]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' fetch and rebase the MAIN_BRANCH to the local children repos of the parent/namespace-root(also updated). ', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'update'}, 'update_project': {'annotations': {'ini_pdv': typing.Dict[str, typing.Any], 'return': typing.List[str]}, 'docstring': ' fetch and rebase the MAIN_BRANCH of the specified project in the local repo. ', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'namespace-root'), 'shortcut': 'update'}}

implemented actions registered via _action() deco

_RCS: Dict[str, Callable] = {'_git_add': <function _git_add>, 'module.makedirs': <function makedirs>, 'module.write_file': <function write_file>}

registered recordable callees, for check* actions, using other actions with temporary redirected callees.

REGISTERED_HOSTS_CLASS_NAMES: Dict[str, str] = {'github.com': 'GithubCom', 'gitlab.com': 'GitlabCom', 'pythonanywhere.com': 'PythonanywhereCom'}

class names of all supported remote host domains

REGISTERED_TPL_PROJECTS: Dict[str, Dict[str, str]] = {}

projects providing templates and outsourced files

TEMP_CONTEXT: TemporaryDirectory | None = None

temp patch folder context (optional/lazy/late created)

TEMP_PARENT_FOLDER: str

temporary parent folder for to clone git repos into

cae = <ae.console.ConsoleApp object>

main app instance of this grm tool, initialized out of __name__ == ‘__main__’ to be used for unit tests

_action(*project_types, **deco_kwargs)

parametrized decorator to declare functions and RemoteHost methods as grm actions.

Return type:

Callable

_recordable_function(callee)

decorator to register function as recordable (to be replaced/redirected in protocol mode).

Return type:

Callable

_rc_id(instance, method_name)

compile recordable callee id of object method or module instance attribute/function.

Return type:

str

_record_calls(*recordable_methods, **recordable_functions)

Return type:

Iterator[None]

activate_venv(name='')

ensure to activate a virtual environment if it is different to the current one (the one on Python/app start).

Parameters:

name (str) – the name of the venv to activate. if this arg is empty or not specified then the venv of the project in the current working directory tree will be activated.

Return type:

str

Returns:

the name of the previously active venv or an empty string if the requested or no venv was active, or if venv is not supported.

active_venv()

determine the virtual environment that is currently active.

Note

the current venv gets set via data:`os.environ on start of this Python app or by activate_venv().

Return type:

str

Returns:

the name of the currently active venv.

bump_file_version(file_name, increment_part=3)

increment part of version number of module/script file, also removing any pre/alpha version sub-part/suffix.

Parameters:

• file_name (str) – module/script file name to be patched/version-bumped.

• increment_part (int) – version number part to increment: 1=mayor, 2=minor, 3=build/revision (default=3).

Return type:

str

Returns:

empty string on success, else error string.

bytes_file_diff(file_content, file_path, line_sep='\\n')

return the differences between the content of a file against a bytes array.

Parameters:

• file_content (bytes) – older file bytes to be compared against the file content of the file specified by the file_path argument.

• file_path (str) – path to the file of which newer content gets compared against the file bytes specified by the file_content argument.

• line_sep (str) – string used to prefix, separate and indent the lines in the returned output string.

Return type:

str

Returns:

differences between the two file contents, compiled with the git diff command.

deploy_template(tpl_file_path, dst_path, patcher, pdv, logger=<built-in function print>, replacer=None, dst_files=None)

create/update outsourced project file content from a template.

Parameters:

• tpl_file_path (str) – template file path/name.ext (absolute or relative to current working directory).

• dst_path (str) – absolute or relative destination path without the destination file name. relative paths are relative to the project root path (the project_path item in the pdv argument).

• patcher (str) – patching template project or function (to be added into the outsourced project file).

• pdv (Dict[str, Any]) – project env/dev variables dict of the destination project to patch/refresh, providing values for (1) f-string template replacements, and (2) to specify the project type, and root or package data folder (in the project_type, and project_path or package_path items).

• logger (Callable) – print()-like callable for logging.

• replacer (Optional[Dict[str, Callable[[str], str]]]) – optional dict with multiple replacer: key=placeholder-id and value=replacer callable.

• dst_files (Optional[Set[str]]) – optional set of project file paths to be excluded from to be created/updated. if the project file got created/updated by this function then the destination file path will be added to this set.

Return type:

bool

Returns:

True if template got deployed/written to the destination, else False.

Note

the project file will be kept unchanged if either:

• the absolute file path is in the set specified by the dst_files argument,

• there exists a lock-file with the additional LOCK_EXT file extension, or

• the outsourced project text does not contain the OUTSOURCED_MARKER string.

editable_project_path(project_name)

determine the project path of a project package installed as editable.

Parameters:

project_name (str) – project package name to search for.

Return type:

str

Returns:

project source root path of an editable installed package or empty string if not found as editable installed package.

find_extra_modules(project_path, namespace_name='', portion_name='')

determine additional modules of a local (namespace portion) project.

Parameters:

• project_path (str) – file path of the local namespace project root directory/folder. passing an empty string will search in the current working directory.

• namespace_name (str) – namespace name or pass an empty string for non-namespace-portion projects.

• portion_name (str) – name of the portion (folder). pass an empty string for non-namespace-portion projects.

Return type:

List[str]

Returns:

list of module import name strings (without file extension and path separators as dots). modules in the TEMPLATES_FOLDER and any PY_INIT modules are excluded.

find_git_branch_files(project_path, branch_or_tag='develop', untracked=False, skip_file_path=<function <lambda>>)

find all added/changed/deleted/renamed/unstaged worktree files that are not merged into the main branch.

Parameters:

• project_path (str) – path of the project root folder. pass empty string to use the current working directory.

• branch_or_tag (str) – branch(es)/tag(s)/commit(s) passed to git diff to specify the changed files between version(s).

• skip_file_path (Callable[[str], bool]) – called for each found file passing the file path relative to the project root folder (specified by the project_path argument), returning True to exclude/skip the file with passed file path.

• untracked (bool) – pass True to include untracked files from the returned result set.

Return type:

Set[str]

Returns:

set of file paths relative to worktree root specified by the project root path specified by the project_path argument.

find_project_files(project_path, root_path_masks, skip_file_path=<function <lambda>>)

find all files of a python package including the .py modules.

Parameters:

• project_path (str) – path of the project root folder. pass empty string to use the current working directory.

• root_path_masks (List[str]) – list of folder or sub-package path masks with wildcards, relative to the project root.

• skip_file_path (Callable[[str], bool]) – called for each found file with their file path (relative to project root folder in project_path) as argument, returning True to exclude/skip the specified file.

Return type:

set[str]

Returns:

set of file paths relative to the project root folder specified by the argument project_path.

increment_version(version, increment_part=3)

increment version number.

Parameters:

• version (Union[str, Iterable[str]]) – version number string or an iterable of version string parts.

• increment_part (int) – part of the version number to increment (1=mayor, 2=minor, 3=patch).

Return type:

str

Returns:

incremented version number.

install_requirements(req_file, project_path='')

install requirements from requirements*.txt file with pip

Parameters:

• req_file (str) – pip requirements.txt file path.

• project_path (str) – project root folder path.

Returns:

0/zero on installation without errors, else pip error return code.

in_venv(name='')

ensure the virtual environment gets activated within the context.

Parameters:

name (str) – the name of the venv to activate. if not specified then the venv of the project in the current working directory tree will be activated.

Return type:

Iterator[None]

main_file_path(project_path, project_type, namespace_name)

return the file path of the main/version type for the specified project type.

Parameters:

• project_path (str) – project path, including the package name as basename.

• project_type (str) – project type to determine the main/version file path for.

• namespace_name (str) – namespace name if for namespace portion or root projects, else pass empty string.

Return type:

str

Returns:

main file path and name.

on_ci_host()

check and return True if this tool is running on the GitLab/GitHub CI host/server.

Return type:

bool

Returns:

True if running on CI host, else False

project_version(imp_or_pkg_name, packages_versions)

determine package name and version in list of package/version strings.

Parameters:

• imp_or_pkg_name (str) – import or package name to search.

• packages_versions (List[str]) – project package versions string: <project_name>[<PROJECT_VERSION_SEP><project_version>].

Return type:

Sequence[str]

Returns:

sequence of package name and version number. the package name is an empty string if it is not in packages_versions. the version number is an empty string if no package version is specified in packages_versions.

patch_string(content, pdv, **replacer)

replace f-string / dynamic placeholders in content with variable values / return values of replacer callables.

Parameters:

• content (str) – f-string to patch (e.g. a template file’s content).

• pdv (Dict[str, Any]) – project env/dev vars dict with variables used as globals for f-string replacements.

• replacer (Callable[[str], str]) – optional kwargs dict with key/name=placeholder-id and value=replacer-callable. if not passed then the replacer with id TEMPLATE_INCLUDE_FILE_PLACEHOLDER_ID will be searched and if found the callable replace_with_file_content_or_default() will be executed.

Return type:

str

Returns:

string extended with include snippets found in the same directory.

Raises:

Exception – if evaluation of :paramref;`~patch_string.content` f-string failed (because of missing-globals-NameError/SyntaxError/ValueError/…).

pdv_str(pdv, var_name)

string value of project development variable var_name of pdv.

Parameters:

• pdv (Dict[str, Any]) – project development variables dict.

• var_name (str) – name of variable.

Return type:

str

Returns:

variable value or if not exists in pdv then the constant/default value of the module aedev_setup_project or if no constant with this name exists then an empty string.

Raises:

AssertionError – if the specified variable value is not of type str. in this case use the function pdv_val() instead.

pdv_val(pdv, var_name)

determine value of project development variable from passed pdv or aedev_setup_project module constant.

Parameters:

• pdv (Dict[str, Any]) – project environment variables dict.

• var_name (str) – name of the variable to determine the value of.

Return type:

Any

Returns:

project env var or module constant value. empty string if variable is not defined.

project_dev_vars(project_path='')

analyse and map an extended project development environment, including template/root projects and git status.

Parameters:

project_path (str) – optional rel/abs path of the package/app/project root directory of a new and existing project (defaults to the current working directory if empty or not passed).

Return type:

Dict[str, Any]

Returns:

dict/mapping with the determined project development variable values.

pypi_versions(pip_name)

determine all the available release versions of a package hosted at the PyPI ‘Cheese Shop’.

Parameters:

pip_name (str) – pip/package name to get release versions from.

Return type:

List[str]

Returns:

list of released versions (the latest last) or on error a list with a single empty string item.

refresh_templates(pdv, logger=<built-in function print>, **replacer)

convert ae namespace package templates found in the cwd or underneath (except excluded) to the final files.

Parameters:

• pdv (Dict[str, Any]) –

  project env/dev variables dict of the destination project to patch/refresh, providing values for (1) f-string template replacements, and (2) to control the template registering, patching and deployment via the variables:

  • namespace_name: namespace of the destination project.

  • package_path: path to package data root of the destination project.

  • project_path: path to working tree root of the destination project.

  • ’project_name’: pypi name of the package/portion/app/.. project.

  • project_type: type of the destination project.

  • repo_url: remote/upstream repository url of the destination project.

  • tpl_projects: template projects data (import name, project path and version).

  Hint

  use the function project_dev_vars() to create this dict.

• logger (Callable) – print()-like callable for logging.

• replacer (Callable[[str], str]) – dict of optional replacer with key=placeholder-id and value=callable. if not passed then only the replacer with id TEMPLATE_INCLUDE_FILE_PLACEHOLDER_ID and its callable/func replace_with_file_content_or_default() will be executed.

Return type:

Set[str]

Returns:

set of patched destination file names.

replace_file_version(file_name, increment_part=0, new_version='')

replace version number of module/script file.

Parameters:

• file_name (str) – module/script file name to be patched/version-bumped.

• increment_part (int) – version number part to increment: 1=mayor, 2=minor, 3=build/revision, default 0=nothing.

• new_version (str) – if passed replaces the original version in the file.

Return type:

str

Returns:

empty string on success, else error string.

replace_with_file_content_or_default(args_str)

return file content if file name specified in first string arg exists, else return empty string or 2nd arg str.

Parameters:

args_str (str) – pass either file name, or file name and default literal separated by a comma character. spaces, tabs and newline characters get removed from the start and end of the file name. a default literal gets parsed like a config variable, the literal value gets return.

Return type:

str

Returns:

file content or default literal value or empty string (if file not exists and there is no comma character in args_str).

root_packages_masks(pdv)

determine root sub packages from the passed project packages and add them glob path wildcards.

Parameters:

pdv (Dict[str, Any]) – project environment variables dict.

Return type:

list[str]

Returns:

list of project root packages extended with glob path wildcards.

skip_files_migrations(file_path)

file exclude callback for the files under the django migrations folders.

Parameters:

file_path (str) – path to file to check for exclusion, relative to the project root folder.

Return type:

bool

Returns:

True if the file specified in file_path has to excluded, else False.

skip_files_lean_web(file_path)

file exclude callback to reduce the deployed files on the web server to the minimum.

Parameters:

file_path (str) – path to file to check for exclusion, relative to the project root folder.

Return type:

bool

Returns:

True if the file specified in file_path has to excluded, else False.

venv_bin_path(name='')

determine the absolute path of the bin/executables folder of a virtual pyenv environment.

Parameters:

name (str) – the name of the venv. if not specified then the venv name will be determined from the first found .python-version file, starting in the current working directory (cwd) and up to 3 parent directories above.

Return type:

str

Returns:

absolute path of the bin folder of the projects local pyenv virtual environment

_act_callable(ini_pdv, act_name)

Return type:

Optional[Callable]

_act_spec(pdv, act_name)

Return type:

Tuple[Dict[str, Any], str]

_available_actions(project_type=<ae.base.UnsetType object>)

Return type:

Set[str]

_chk_if(error_code, check_result, error_message)

exit/quit this console app if the check_result argument is False and the force app option is False.

_check_commit_msg_file(pdv)

Return type:

str

_check_folders_files_completeness(pdv)

_check_children_not_exist(parent_or_root_pdv, *project_versions)

_check_resources_img(pdv)

check images, message texts and sounds of the specified project.

Return type:

List[str]

_check_resources_i18n_ae(file_name, content)

check a translation text file with ae_i18n portion message texts.

Parameters:

• file_name (str) – message texts file name.

• content (str) – message texts file content.

_check_resources_i18n_po(file_name, content)

check a translation text file with GNU gettext message texts.

Parameters:

• file_name (str) – message texts file name (.po file).

• content (str) – message texts file content.

_check_resources_i18n_texts(pdv)

Return type:

List[str]

_check_resources_snd(pdv)

Return type:

List[str]

_check_resources(pdv)

check images, message texts and sounds of the specified project.

_check_templates(pdv)

_check_types_linting_tests(pdv)

_children_desc(pdv, children_pdv=())

Return type:

str

_children_project_names(ini_pdv, names, chi_vars)

Return type:

List[str]

_children_path_package_option_reset()

_cl(err_code, command_line, extra_args=(), lines_output=None, exit_on_err=True, exit_msg='', shell=False)

execute command in the current working directory of the OS console/shell, dump error and exit app if needed.

Parameters:

• err_code (int) – error code to pass to console as exit code (if exit_on_err is True).

• command_line (str) – command line string to execute on the console/shell. could contain command line args separated by whitespace characters (alternatively use extra_args).

• extra_args (Sequence) – optional sequence of extra command line arguments.

• lines_output (Optional[List[str]]) – optional list to return the lines printed to stdout/stderr on execution.

• exit_on_err (bool) – pass False to not exit the app on error (exit_msg has then to be empty).

• exit_msg (str) – additional text to print on stdout/console if error and exit_on_err is True.

• shell (bool) – pass True to execute command in the default OS shell (see subprocess.run()).

Return type:

int

Returns:

0 on success or the error number if an error occurred.

_clone_template_project(import_name, version)

Return type:

str

_debug_or_verbose()

determine if verbose or debug option got specified (preventing on app init early call of cae.get_option()).

Return type:

bool

_exit_error(error_code, error_message='')

quit this shell script, optionally displaying an error message.

_expected_args(act_spec)

Return type:

str

_get_branch(pdv)

Return type:

str

_get_host_class_name(host_domain)

Return type:

str

_get_host_config_val(host_domain, option_name, host_user='', name_prefix='repo')

determine host domain, group, user and credential values.

Parameters:

• host_domain (str) – domain name of the host. pass empty string to skip search for host-specific variable.

• option_name (str) – host option name and config variable name part (‘domain’, ‘group’, ‘user’, ‘token’), resulting in e.g. user, repo_user, repo_user_at_xxx, web_user, web_user_at…

• host_user (str) – username at the host. if not passed or host_domain is empty then skip the search for a user-specific variable value.

• name_prefix (str) – config variable name prefix. pass ‘web’ to get web server host config values.

Return type:

Optional[str]

Returns:

config variable value or None if not found.

_get_host_domain(pdv, name_prefix='repo')

determine domain name of repository|web host from –domain option, repo_domain or web_domain config variable.

Parameters:

name_prefix (str) – config variable name prefix. pass ‘web’ to get web server host config values.

Return type:

str

Returns:

domain name of repository|web host.

_get_host_group(pdv, host_domain)

determine user group name from –group option or repo_group config variable.

Parameters:

host_domain (str) – domain to get user token for.

Return type:

str

Returns:

user group name or if not found the default username STK_AUTHOR.

_get_host_user_name(pdv, host_domain, name_prefix='repo')

determine username from –user option, repo_user or web_user config variable.

Parameters:

• host_domain (str) – domain to get user token for.

• name_prefix (str) – config variable name prefix. pass ‘web’ to get web server host config values.

Return type:

str

Returns:

username or if not found the user group name.

_get_host_user_token(host_domain, host_user='', name_prefix='repo')

determine token or password of user from –token option, repo_token or web_token config variable.

Parameters:

• host_domain (str) – domain to get user token for.

• host_user (str) – host user to get token for.

• name_prefix (str) – config variable name prefix. pass ‘web’ to get web server host config values.

Return type:

str

Returns:

token string for domain and user on repository|web host.

_get_namespace(pdv, project_type)

Return type:

str

_get_parent_path(pdv)

Return type:

str

_get_parent_packageversion(pdv, package_or_portion)

Return type:

Tuple[str, str]

_get_path_package(pdv, project_type='')

Return type:

Tuple[str, str, str]

_get_prj_name(pdv, project_type='')

Return type:

str

_get_renamed_path_package(pdv, namespace_name, project_type)

Return type:

Tuple[str, str]

_git_add(pdv)

_git_branches(pdv)

Return type:

List[str]

_git_checkout(pdv, *extra_args, branch='', from_branch='')

_git_clone(repo_root, project_name, branch_or_tag='', parent_path='', extra_args=())

Return type:

str

_git_commit(pdv, extra_options=())

execute the command ‘git commit’ for the specified project.

Parameters:

• pdv (Dict[str, Any]) – providing project-name and -path in which this git command gets executed.

• extra_options (Iterable[str]) – additional options passed to git commit command line, e.g. [”–patch”, “–dry-run”].

Note

ensure the commit message in the file COMMIT_MSG_FILE_NAME is uptodate.

_git_current_branch(pdv)

Return type:

str

_git_diff(pdv, *extra_opt_and_ref_specs)

Return type:

List[str]

_git_fetch(pdv, *extra_args)

Return type:

List[str]

_git_init_if_needed(pdv)

Return type:

bool

_git_merge(pdv, from_branch)

Return type:

bool

_git_project_version(pdv, increment_part=3)

determine latest or the next free package git repository version or the project specified via the pdv argument.

Parameters:

• pdv (Dict[str, Any]) – project dev vars to identify the package.

• increment_part (int) – part of the version number to be incremented (1=mayor, 2=minor/namespace, 3=patch). pass zero/0 to return the latest published package version.

Return type:

str

Returns:

latest published repository package version as string or the first version (increment_version(NULL_VERSION, increment_part) or “0.0.1”) if project never published a version tag to remotes/origin or an empty string on error.

_git_push(pdv, *branches_and_tags, exit_on_error=True, extra_args=())

push portion in the current working directory to the specified branch.

Return type:

int

_git_remotes(pdv)

Return type:

Dict[str, str]

_git_renew_remotes(pdv)

_git_status(pdv)

Return type:

List[str]

_git_tag_add(pdv, tag)

_git_tag_in_branch(pdv, tag, branch='origin/develop')

check if tag/ref is in the specified or in the remote origin main branch.

Parameters:

• pdv (Dict[str, Any]) – project vars.

• tag (str) – any ref like a tag or another branch, to be searched within branch.

• branch (str) – branch to be searched in for tag.

Return type:

bool

Returns:

True if ref got found in branch, else False.

_git_tag_list(pdv, tag_pattern='v*')

Return type:

List[str]

_git_uncommitted(pdv)

Return type:

List[str]

_hint(act_fun, run_grm_message_suffix='')

Return type:

str

_in_prj_dir_venv(project_path, venv_name='')

Return type:

Iterator[None]

_init_act_args_check(ini_pdv, act_spec, act_name, act_args, act_flags)

check and possibly complete the command line arguments, and split optional action flags from action args.

called after _init_act_exec_args/INI_PDV-initialization.

_init_act_args_shortcut(ini_pdv, ini_act_name)

Return type:

str

_init_act_exec_args()

prepare execution of action requested via command line arguments and options.

• init project dev vars

• check if action is implemented

• check action arguments

• run optional pre_action.

Return type:

Tuple[Dict[str, Any], str, tuple, Dict[str, Any]]

Returns:

tuple of project pdv, action name to execute, a tuple with additional action arguments, and a dict of optional action flag arguments.

_init_children_pdv_args(ini_pdv, act_args)

get package names of the portions specified as command line args, optionally filtered by –branch option.

Return type:

List[Dict[str, Any]]

_init_children_presets(chi_vars)

Return type:

Dict[str, Set[str]]

_patch_outsourced(file_name, content, patcher)

Return type:

str

_pp(output)

Return type:

str

_print_pdv(pdv)

_register_template(import_name, dev_require, add_req, tpl_projects)

Return type:

Dict[str, str]

_renew_prj_dir(new_pdv)

_renew_project(ini_pdv, project_type)

Return type:

Dict[str, Any]

_renew_local_root_req_file(pdv)

_required_package(import_or_package_name, packages_versions)

Return type:

bool

_template_projects(pdv)

determine template projects of namespace, project type and generic project (the highest priority first).

Return type:

List[Dict[str, str]]

_template_version_option(import_name)

Return type:

str

_wait()

_write_commit_message(pdv, pkg_version='{project_version}', title='')

class RemoteHost

Bases: object

base class registering subclasses as remote host repo class in REGISTERED_HOSTS_CLASS_NAMES.

name_prefix: str = 'repo'

create_branch: Callable

release_project: Callable

repo_obj: Callable

request_merge: Callable

classmethod __init_subclass__(**kwargs)

register remote host class name; called on declaration of a subclass of RemoteHost.

_repo_merge_src_dst_fork_branch(ini_pdv)

Return type:

Tuple[Union[Repository, Project], Union[Repository, Project], bool, str]

_release_project(ini_pdv, version_tag)

class GithubCom

Bases: RemoteHost

remote connection and actions on remote repo in gitHub.com.

connection: Github

connection to GitHub host

connect(ini_pdv)

connect to gitHub.com remote host.

Parameters:

ini_pdv (Dict[str, Any]) – project dev vars (host_token).

Return type:

bool

Returns:

True on successful authentication else False.

create_branch(group_repo, branch_name, tag_name)

create new remote branch onto/from tag name.

Parameters:

• group_repo (str) – string with owner-user-name/repo-name of the repository, e.g. “UserName/RepositoryName”.

• branch_name (str) – name of the branch to create.

• tag_name (str) – name of the tag/ref to create branch from.

init_new_repo(group_repo, project_desc)

config new project repo.

Parameters:

• group_repo (str) – project owner user and repository names in the format “user-name/repo-name”.

• project_desc (str) – project description.

repo_obj(err_code, err_msg, group_repo)

convert user repo names to a repository instance of the remote api.

Parameters:

• err_code (int) – error code, pass 0 to not quit if project not found.

• err_msg (str) – error message to display on error with optional {name} to be automatically substituted with the project name from the group_repo_names argument.

• group_repo (str) – string with owner-user-name/repo-name of the repository, e.g. “UserName/RepositoryName”.

Return type:

Repository

Returns:

python-github repository if found, else return None if err_code is zero else quit.

static _protect_branches(project_repo, branch_masks)

fork_project(ini_pdv, forked_usr_repo)

create/renew fork of a remote repo specified via the 1st argument, into our user/group namespace.

push_project(ini_pdv, branch_name='')

push current/specified branch of project/package to remote host domain, version-tagged if release is True.

Parameters:

• ini_pdv (Dict[str, Any]) – project dev vars.

• branch_name (str) – optional branch name to push (alternatively specified by the branch command line option).

release_project(ini_pdv, version_tag)

update local MAIN_BRANCH from origin and if pip_name is set then also release the latest/specified version.

Parameters:

• ini_pdv (Dict[str, Any]) – project dev vars.

• version_tag (str) – push version tag in the format v<version-number> to release or LATEST to use the version tag of the latest git repository version.

request_merge(ini_pdv)

request merge of the origin=fork repository into the main branch at remote/upstream=forked.

class GitlabCom

Bases: RemoteHost

remote connection and actions on gitlab.com.

connection: Gitlab

connection to Gitlab host

connect(ini_pdv)

connect to gitlab.com remote host.

Parameters:

ini_pdv (Dict[str, Any]) – project dev vars (REPO_HOST_PROTOCOL, host_domain, host_token).

Return type:

bool

Returns:

True on successful authentication else False.

create_branch(group_repo, branch_name, tag_name)

create new remote branch onto/from tag name.

Parameters:

• group_repo (str) – string with owner-user-name/repo-name of the repository, e.g. “UserName/RepositoryName”.

• branch_name (str) – name of the branch to create.

• tag_name (str) – name of the tag/ref to create branch from.

init_new_repo(ini_pdv)

create group/user project specified in ini_pdv or quit with error if group/user not found.

Parameters:

ini_pdv (Dict[str, Any]) – project dev vars.

repo_obj(err_code, err_msg, group_repo)

convert group/project_name or an endswith-fragment of it to a Project instance of the remote repo api.

Parameters:

• err_code (int) – error code, pass 0 to not quit if project not found.

• err_msg (str) – error message to display on error with optional {name} to be automatically substituted with the project name from the group_repo argument.

• group_repo (str) – group/project-name to search for.

Return type:

Project

Returns:

python-gitlab project instance if found, else return None if err_code is zero else quit.

project_owner(ini_pdv)

determine owner (group|user) of the project specified by ini_pdv or quit with error if group/user not found.

Parameters:

ini_pdv (Dict[str, Any]) – project dev vars.

Return type:

Union[Group, User]

Returns:

instance of Group or User, determined via the user-/group-names specified by ini_pdv.

clean_releases(ini_pdv)

delete local+remote release tags and branches of the specified project that got not published to PYPI.

Return type:

List[str]

fork_children(ini_pdv, *children_pdv)

fork children of a namespace root project or of a parent folder.

fork_project(ini_pdv)

create/renew fork of a remote repo specified via the package option, into our user/group namespace.

push_children(ini_pdv, *children_pdv)

push specified children projects to remotes/origin.

push_project(ini_pdv, branch_name='')

push current/specified branch of project/package to remote host domain, version-tagged if release is True.

Parameters:

• ini_pdv (Dict[str, Any]) – project dev vars.

• branch_name (str) – optional branch name to push (alternatively specified by the branch command line option).

release_children(ini_pdv, *children_pdv)

release the latest versions of the specified parent/root children projects to remotes/origin.

release_project(ini_pdv, version_tag)

update local MAIN_BRANCH from origin and if pip_name is set then also release the latest/specified version.

Parameters:

• ini_pdv (Dict[str, Any]) – project dev vars.

• version_tag (str) – push version tag in the format v<version-number> to release or LATEST to use the version tag of the latest git repository version.

request_children_merge(ini_pdv, *children_pdv)

request the merge of the specified children of a parent/namespace on remote/upstream.

request_merge(ini_pdv)

request merge of the origin=fork repository into the main branch at remote/upstream=forked.

search_repos(ini_pdv, fragment='')

search remote repositories via a text fragment in its project name/description.

show_children_repos(ini_pdv, *children_pdv)

display remote properties of parent/root children repos.

show_repo(ini_pdv)

display properties of remote repository.

class PythonanywhereCom

Bases: RemoteHost

remote actions on remote web host pythonanywhere.com (to be specified by –domain option).

connection: PythonanywhereApi

requests http connection

name_prefix: str = 'web'

config variable name prefix

connect(ini_pdv)

connect to www. and eu.pythonanywhere.com web host.

Parameters:

ini_pdv (Dict[str, Any]) – parent/root project dev vars.

Return type:

bool

Returns:

True on successful authentication else False.

deploy_flags = {'ALL': False, 'CLEANUP': False, 'LEAN': False, 'MASKS': []}

optional flag names and default values for the actions check_deploy() and deploy_project()

deploy_differences(ini_pdv, action, version_tag, **optional_flags)

determine differences between the specified repository and web host/server (deployable and deletable files).

Parameters:

• ini_pdv (Dict[str, Any]) – project dev vars.

• action (str) – pass ‘check’ to only check the differences between the specified repository and the web server/host, or ‘deploy’ to prepare the deployment of these differences.

• version_tag (str) – project package version to deploy. pass LATEST to use the version tag of the latest repository version (PyPI release), or WORKTREE to deploy the actual working tree package version (including unstaged/untracked files).

• optional_flags – optional command line arguments, documented in detail in the declaration of the action method parameter check_deploy.optional_flags.

Return type:

tuple[str, str, set[str], set[str]]

Returns:

tuple of 2 strings and 2 sets. the first string contains a description of the project and the server to check/deploy-to, and the second the path to the project root folder. the two sets containing project file paths, relative to the local/temporary project root folder, the first one with the deployable files, and the 2nd one with the removable files.

check_deploy(ini_pdv, version_tag, **optional_flags)

check all project package files at the app/web server against the specified package version.

Parameters:

• ini_pdv (Dict[str, Any]) – project dev vars.

• version_tag (str) – version tag in the format v<version-number> to check or LATEST to check against the latest repository version or WORKTREE to check directly against the local work tree (with the locally added, unstaged and changed files).

• optional_flags –

  additional/optionally supported command line arguments:

  • ALL is including all deployable package files, instead of only the new, changed or deleted files in the specified repository.

  • CLEANUP is checking for deletable files on the web server/host, e.g. after they got removed from the specified repository or work tree.

  • LEAN is reducing the deployable files sets to the minimum (using e.g. the function skip_files_lean_web()), like e.g. the gettext .po files, the media_ini root folder, and the static sub-folder with the initial static files of the web project.

  • MASKS specifies a list of file paths masks/pattern to be included in the repository files to check/deploy. to include e.g. the files of the static root folder specify this argument as MASKS="['static/**/*']". single files can be included too, by adding their possible file names to the list - only the found ones will be included. for example to include the django database you could add some possible DB file names to the list like in "MASKS=['static/**/*', 'db.sqlite', 'project.db']"

deploy_project(ini_pdv, version_tag, **optional_flags)

deploy code files of django/app project version to the web-/app-server.

Parameters:

• ini_pdv (Dict[str, Any]) – project dev vars.

• version_tag (str) – version tag in the format v<version-number> to deploy or LATEST to use the tag of the latest repository version or WORKTREE to deploy directly from the local work tree (including locally added, unstaged and changed files).

• optional_flags – optional command line arguments, documented in the check_deploy() action.

add_children_file(ini_pdv, file_name, rel_path, *children_pdv)

add a file, template of outsourced text file to the working trees of parent/root and children/portions.

Parameters:

• ini_pdv (Dict[str, Any]) – parent/root project dev vars.

• file_name (str) – source (template) file name (optional with path).

• rel_path (str) – relative destination path within the working tree.

• children_pdv (Dict[str, Any]) – project dev vars of the children to process.

Return type:

bool

Returns:

True if the file got added to the parent/root and to all children, else False.

add_file(ini_pdv, file_name, rel_path)

add file, template or outsourced text file into the project working tree.

Parameters:

• ini_pdv (Dict[str, Any]) – project dev vars.

• file_name (str) – file name to add (optional with abs. path, else relative to working tree root folder).

• rel_path (str) – relative path in destination project working tree.

Return type:

bool

Returns:

True if the file got added to the specified project, else False.

bump_version(ini_pdv)

increment project version.

check_children_integrity(parent_pdv, *children_pdv)

run integrity checks for the specified children of a parent or portions of a namespace.

check_integrity(ini_pdv)

integrity check of files/folders completeness, outsourced/template files update-state and CI tests.

clone_children(parent_or_root_pdv, *project_versions)

clone specified namespace-portion/parent-child repos to the local machine.

Parameters:

• parent_or_root_pdv (Dict[str, Any]) – vars of the parent/namespace-root project.

• project_versions (str) – package/project names with optional version of the children to be cloned.

Return type:

List[str]

Returns:

list of project paths of the cloned children projects (for unit testing).

clone_project(ini_pdv, package_or_portion='')

clone remote repo to the local machine.

Parameters:

• ini_pdv (Dict[str, Any]) – vars of the project to clone.

• package_or_portion (str) – name of the package/portion to clone, optionally with version number.

Return type:

str

Returns:

project path of the cloned project (used for unit tests).

commit_children(ini_pdv, *children_pdv)

commit changes to children of a namespace/parent using the individually prepared commit message files.

commit_project(ini_pdv)

commit changes of a single project to the local repo using the prepared commit message file.

delete_children_file(ini_pdv, file_name, *children_pdv)

delete file or empty folder from parent/root and children/portions working trees.

Parameters:

• ini_pdv (Dict[str, Any]) – parent/root project dev vars.

• file_name (str) – file/folder name to delete (optional with path, relative to working tree root folder).

• children_pdv (Dict[str, Any]) – tuple of children project dev vars.

Return type:

bool

Returns:

True if file got found & deleted from the parent and all children projects, else False.

delete_file(ini_pdv, file_name)

delete file or empty folder from project working tree.

Parameters:

• ini_pdv (Dict[str, Any]) – project dev vars.

• file_name (str) – file/folder name to delete (optional with path, relative to working tree root folder).

Return type:

bool

Returns:

True if the file got found and delete from the specified project, else False.

install_children_editable(ini_pdv, *children_pdv)

install parent children or namespace portions as editable on local machine.

install_editable(ini_pdv)

install project as editable from source/project root folder.

new_app(ini_pdv)

create or complete/renew a gui app project.

Return type:

Dict[str, Any]

new_children(ini_pdv, *children_pdv)

initialize or renew parent folder children or namespace portions.

Return type:

List[Dict[str, Any]]

new_django(ini_pdv)

create or complete/renew a django project.

Return type:

Dict[str, Any]

new_module(ini_pdv)

create or complete/renew module project.

Return type:

Dict[str, Any]

new_namespace_root(ini_pdv)

create or complete/renew namespace root package.

Return type:

Dict[str, Any]

new_package(ini_pdv)

create or complete/renew package project.

Return type:

Dict[str, Any]

new_project(ini_pdv)

complete/renew an existing project.

Return type:

Dict[str, Any]

prepare_children_commit(ini_pdv, title, *children_pdv)

run code checks and prepare/overwrite the commit message file for a bulk-commit of children projects.

Parameters:

• ini_pdv (Dict[str, Any]) – parent/root project dev vars.

• title (str) – optional commit message title.

• children_pdv (Dict[str, Any]) – tuple of project dev vars of the children to process.

prepare_commit(ini_pdv, title='')

run code checks and prepare/overwrite the commit message file for the commit of a single project/package.

Parameters:

• ini_pdv (Dict[str, Any]) – project dev vars.

• title (str) – optional commit message title.

refresh_children_outsourced(ini_pdv, *children_pdv)

refresh outsourced files from templates in namespace/project-parent children projects.

refresh_outsourced(ini_pdv)

refresh/renew all the outsourced files in the specified project.

rename_children_file(ini_pdv, old_file_name, new_file_name, *children_pdv)

rename file or folder in parent/root and children/portions working trees.

Parameters:

• ini_pdv (Dict[str, Any]) – parent/root project dev vars.

• old_file_name (str) – file/folder name to rename (optional with path, relative to working tree root folder).

• new_file_name (str) – new name of file/folder (optional with path, relative to working tree root folder).

• children_pdv (Dict[str, Any]) – tuple of project dev vars of the children to process.

Return type:

bool

Returns:

True if the file got renamed in the parent and all children projects, else False.

rename_file(ini_pdv, old_file_name, new_file_name)

rename file or folder in project working tree.

Parameters:

• ini_pdv (Dict[str, Any]) – project dev vars.

• old_file_name (str) – source file/folder (optional with path, absolute or relative to project working tree).

• new_file_name (str) – destination file/folder (optional path, absolute or relative to project working tree).

Return type:

bool

Returns:

True if file/folder got renamed, else False.

run_children_command(ini_pdv, command, *children_pdv)

run console command for the specified portions/children of a namespace/parent.

Parameters:

• ini_pdv (Dict[str, Any]) – parent/root project dev vars.

• command (str) – console command string (including all command arguments).

• children_pdv (Dict[str, Any]) – tuple of children project dev vars.

show_actions(ini_pdv)

get info of available/registered/implemented actions of the specified/current project and remote.

show_children_status(ini_pdv, *children_pdv)

run integrity checks for the specified portions/children of a namespace/parent.

show_children_versions(ini_pdv, *children_pdv)

show package versions (local, remote and on pypi) for the specified children of a namespace/parent.

show_status(ini_pdv)

show git status of the specified/current project and remote.

show_versions(ini_pdv)

display package versions of worktree, remote/origin repo, latest PyPI release and default app/web host.

update_children(ini_pdv, *children_pdv)

fetch and rebase the MAIN_BRANCH to the local children repos of the parent/namespace-root(also updated).

update_project(ini_pdv)

fetch and rebase the MAIN_BRANCH of the specified project in the local repo.

Return type:

List[str]

prepare_and_run_main()

prepare and run app

main()

main app script