aedev.project_manager.utils

util/helper functions needed by __main__.py and templates.py.

Module Attributes

ARG_MULTIPLES	mark multiple args in the _action() arg_names kwarg
ARG_ALL	all argument, for lists, e.g., of namespace portions
ARGS_CHILDREN_DEFAULT	default arguments for children actions.
DJANGO_EXCLUDED_FROM_CLEANUP	set of file path masks/pattern to exclude essential files from to be cleaned-up on the server.
PIP_FREEZE_COMMENT	console output line of pip freeze command, separating the listed from the additional/unlisted packages.
ActionArgs	action arguments specified on pjm command line
ActionFlags	action flags/kwargs specified on pjm command line
RepoType	repo host libs repo object (PyGithub, python-gitlab)
PPF(object)
REGISTERED_ACTIONS	implemented actions registered via _action() deco
REGISTERED_HOSTS_CLASS_NAMES	class names of all supported remote host domains

Functions

children_desc(pdv[, children_pdv])	printable message describing a single child of a namespace root (portion) or of a project parent folder.
children_project_names(ini_pdv, names, chi_vars)	check and compile a list of package names of the children of a namespace root or a projects parent folder.
expected_args(act_spec)	return a printable message explaining the expected arguments of the specified pjm action.
get_app_option(pdv, option_name)	determine command line option value from pdv object.
get_branch(pdv)	determine name of the branch of the project of the specified pdv object.
get_host_class_name(host_domain)	determine the class name for the specified host domain.
get_host_config_val(pdv, option_name[, ...])	determine host/user-specific domain, group, user and token values.
get_host_domain(pdv[, var_prefix])	determine domain name of repository|web host from the repo_domain or web_domain option or config variable.
get_host_group(pdv, host_domain)	determine the upstream user|group name from the --repo_group option or config variable.
get_host_user_name(pdv, host_domain[, ...])	determine username from --repo_user/--web_user options, PDV_repo_user or PDV_web_user config variable.
get_host_user_token(pdv, host_domain[, ...])	determine token or password of user from --repo_token or --web_token option or config variable.
get_mirror_urls(pdv)	determine the configured mirrors remote names/urls for the project specified by the pdv argument.
git_init_add(pdv)	run git add for the project specified by the pdv argument (after running git init if git repo is not created).
git_push_url(pdv[, authenticate, remote_urls])	determine the origin url of the repository, to push onto.
guess_next_action(pdv)	guess the next action to be done locally.
ppp(output)	pretty printing formatter function.
project_topics(pdv)	extracts the project topics of a project.
refresh_pdv(pdv)	refresh pdv in-place to reflect the current state of the project working tree.
update_frozen_req_file(project_pip_name, ...)	update frozen requirements file
update_frozen_req_files(pdv)	update the four possible frozen requirements files of a project.
write_commit_message(pdv[, pkg_version, title])	write the commit message file used by git commands.

ARG_MULTIPLES = ' ...'

mark multiple args in the _action() arg_names kwarg

ARG_ALL = 'all'

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

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

default arguments for children actions.

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.

PIP_FREEZE_COMMENT = '## The following requirements were added by pip freeze:'

console output line of pip freeze command, separating the listed from the additional/unlisted packages.

ActionArgs

action arguments specified on pjm command line

alias of list[str]

ActionFlags

action flags/kwargs specified on pjm command line

alias of dict[str, Any]

RepoType

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

alias of Repository | Project

PPF(object)

formatter for console printouts

REGISTERED_ACTIONS: dict[str, dict[str, Any]] = {'GithubCom.fork_project': {'annotations': {'fork_repo_path': <class 'str'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'arg_names': (('group|user-slash-repo-to-fork-from',),), 'docstring': ' create/renew a fork of a remote repo specified via the 1st argument, into our user namespace. ', 'full_name': 'GithubCom.fork_project', 'local_action': False, 'project_types': ('projects-parent-dir', 'app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'fork'}, 'GithubCom.push_project': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' push the current/specified branch of project/package version-tagged to the remote repository host.', 'full_name': 'GithubCom.push_project', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'push'}, 'GithubCom.release_project': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'version_tag': <class 'str'>}, 'arg_names': (('version-tag',), ('LATEST',)), 'docstring': ' update local main branch from origin, and if pip_name is set, then release the latest/specified version too.\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.', 'full_name': 'GithubCom.release_project', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'release'}, 'GithubCom.request_merge': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' request merge of the origin=fork repository into the main branch at remote/upstream=forked. ', 'full_name': 'GithubCom.request_merge', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'request'}, 'GithubCom.show_status': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' show git status of the specified/current project locally and on remote. ', 'full_name': 'GithubCom.show_status', 'local_action': False, 'project_types': ('projects-parent-dir', 'app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'status'}, 'GitlabCom.clean_releases': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'return': list[str]}, 'docstring': ' delete local+remote release tags and branches of the specified project that got not published to PYPI. ', 'full_name': 'GitlabCom.clean_releases', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root')}, 'GitlabCom.fork_project': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'owner_project_path': <class 'str'>}, 'arg_names': (('group|user-slash-project-to-fork-from',),), 'docstring': ' create or renew a fork of a remote repo, specified via the 1st argument, into our user namespace. ', 'full_name': 'GitlabCom.fork_project', 'local_action': False, 'project_types': ('projects-parent-dir', 'app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'fork'}, 'GitlabCom.push_children': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' push specified children projects to the origin remote. ', 'full_name': 'GitlabCom.push_children', 'local_action': False, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'GitlabCom.push_project': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' push current/specified branch of project/package version-tagged to the remote host domain.', 'full_name': 'GitlabCom.push_project', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'push'}, 'GitlabCom.release_children': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' release the latest versions of the specified parent/root children projects to the origin remote. ', 'full_name': 'GitlabCom.release_children', 'local_action': False, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'GitlabCom.release_project': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'version_tag': <class 'str'>}, 'arg_names': (('version-tag',), ('LATEST',)), 'docstring': ' update local main branch from origin, optionally release (to PyPI if pip_name is set) and mirror to GitHub.\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.', 'full_name': 'GitlabCom.release_project', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'release'}, 'GitlabCom.request_children_merge': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' request specified children merge of a parent/namespace on the upstream/forked remote. ', 'full_name': 'GitlabCom.request_children_merge', 'local_action': False, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'GitlabCom.request_merge': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' request merge of the origin=fork repository into the main branch at the upstream/forked remote. ', 'full_name': 'GitlabCom.request_merge', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'request'}, 'GitlabCom.search_repos': {'annotations': {'fragment': <class 'str'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'arg_names': ((), ('fragment',)), 'docstring': ' search remote repositories via a text fragment in its project name/description. ', 'full_name': 'GitlabCom.search_repos', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root')}, 'GitlabCom.show_children_status': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' display the local and remote status of parent/root children repos. ', 'full_name': 'GitlabCom.show_children_status', 'local_action': False, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'GitlabCom.show_remote': {'annotations': {'_ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'owner_project_path': <class 'str'>}, 'arg_names': (('owner|group|user/project_name',),), 'docstring': ' display properties of any remote repository, specified via the owner (user|group) and project name path. ', 'full_name': 'GitlabCom.show_remote', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root', '', 'projects-parent-dir'), 'shortcut': 'remote'}, 'GitlabCom.show_status': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' show git status of the specified/current project locally and on remote. ', 'full_name': 'GitlabCom.show_status', 'local_action': False, 'project_types': ('projects-parent-dir', 'app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'status'}, 'PythonanywhereCom.check_deploy': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, '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        :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        :param optional_flags:  additional/optionally supported command line arguments:\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\n                                  function :func:`skip_files_lean_web`), like e.g., the gettext ``.po`` files,\n                                  the ``media_ini`` root folder and the ``static`` subfolder 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\']"``', 'flags': {'ALL': False, 'CLEANUP': False, 'LEAN': False, 'MASKS': []}, 'full_name': 'PythonanywhereCom.check_deploy', 'local_action': False, 'project_types': ('app', 'django')}, 'PythonanywhereCom.deploy_project': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'version_tag': <class 'str'>}, 'arg_names': (('version-tag',), ('LATEST',), ('WORKTREE',)), 'docstring': ' deploy code files of a django/app project version to the web-/app-server.\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.', 'flags': {'ALL': False, 'CLEANUP': False, 'LEAN': False, 'MASKS': []}, 'full_name': 'PythonanywhereCom.deploy_project', 'local_action': False, 'project_types': ('app', 'django'), 'shortcut': 'deploy'}, 'add_children_file': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'file_name': <class 'str'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, '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 any file to the project working trees of parent/root and children/portions.\n    :param file_name:           source (template) file name (optional with a path).\n    :param rel_path:            destination path relative to the project root.\n    :param children_pdv:        project dev vars of the children to process.', 'full_name': 'add_children_file', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'add_file': {'annotations': {'file_name': <class 'str'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'rel_path': <class 'str'>, 'return': <class 'bool'>}, 'arg_names': (('source-name', 'rel-path'), ('source-name',)), 'docstring': ' add any file into the project working tree.\n    :param file_name:           file name to add (either with an absolut path, or relative to the project root).\n                                if the source is a template file, then the path prefixes of the base file name will be\n                                processed (with the project dev vars as template vars).\n    :param rel_path:            optional relative folder/dir path in the destination project working tree, defaults\n                                to the project root folder.', 'full_name': 'add_file', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root')}, 'build_gui_app': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' build gui app with buildozer, add LIBS to make a clean/full build and EMBED to include APK to share. ', 'flags': {'EMBED': False, 'LIBS': False}, 'full_name': 'build_gui_app', 'local_action': True, 'project_types': ('app',), 'shortcut': 'build'}, 'check_children_integrity': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'parent_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' run integrity checks for the specified children of a parent or portions of a namespace. ', 'full_name': 'check_children_integrity', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'check_integrity': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' integrity check of files/folders completeness, managed/template files update-state, and CI tests. ', 'full_name': 'check_integrity', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'check'}, 'clone_children': {'annotations': {'owner_name_versions': <class 'str'>, 'parent_or_root_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'return': list[str]}, 'arg_names': (('children-owner-name-versions ...',),), 'docstring': ' clone specified namespace-portion/parent-child repositories to the local machine.\n    .. hint:: the supported command line options are documented in the :func:`clone_project` action.\n    :param parent_or_root_pdv:  parent/namespace-root project to clone from.\n    :param owner_name_versions: the projects/packages/portions to be cloned, identified by their repository owner\n                                user|group, the project/portion name and an optional version::\n                                    group-name/project_name1==v3.6.9 project_name2 ...\n                                running in namespace root/sister project allows to only specify the portion names::\n                                    portion_name1 portion_name2 ...\n                                the user|group name is only obligatory when this action got started from a parent folder\n                                (else it defaults to owner of the namespace root|sister project).', 'full_name': 'clone_children', 'local_action': True, 'pre_action': <function _check_children_to_clone>, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'clone_project': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'owner_name_version': <class 'str'>, 'return': <class 'str'>}, 'arg_names': (('project-owner-name[==version]',),), 'docstring': ' clone remote repo to the local machine.\n    the origin host domain can be specified with the --repo_domain option.\n    the owner user|group name can alternatively be specified via the --repo_group option.\n    if the --branch option is specified, then only this branch/tag will be cloned (quicker!) and directly checked-out.\n    extra checks on the correct portion/project name can be activated by specifying the --namespace_name option.\n                                project to clone or use the local parent or namespace root/sister project.\n    :param owner_name_version:  name of the project to clone, optionally prefixed with the owner name (and a slash)\n                                and suffixed with (the :data:`PROJECT_VERSION_SEP` seperator and) a version number.\n                                needed/used by :func:`clone_children` and unit tests.', 'full_name': 'clone_project', 'local_action': True, 'pre_action': <function _check_children_to_clone>, 'project_types': ('namespace-root', 'projects-parent-dir'), 'shortcut': 'clone'}, 'commit_children': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' commit changes to children of a namespace/parent using the individually prepared commit message files. ', 'full_name': 'commit_children', 'local_action': True, 'pre_action': <function check_children_integrity>, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'commit_project': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' commit changes of a single project to the local repo using the prepared commit message file. ', 'full_name': 'commit_project', 'local_action': True, 'pre_action': <function check_integrity>, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'commit'}, 'delete_children_file': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'file_name': <class 'str'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, '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 a file or an empty folder from parent/root and children/portions project roots.\n    :param file_name:           file/folder name to delete (optional with a path, relative to the project root).\n    :param children_pdv:        tuple of children project dev vars.\n                                projects, else False.', 'full_name': 'delete_children_file', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'delete_file': {'annotations': {'file_or_dir': <class 'str'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'return': <class 'bool'>}, 'arg_names': (('file-or-folder-name',),), 'docstring': ' delete a file or an empty folder from the project.\n    :param file_or_dir:         file/folder name to delete (optional with a path, relative to the project root).', 'full_name': 'delete_file', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root')}, 'install_children_editable': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' install parent children or namespace portions as editable on the local machine. ', 'full_name': 'install_children_editable', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'install_editable': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' install the project as editable from the source/project root folder. ', 'full_name': 'install_editable', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'editable'}, 'new_app': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'return': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' create or complete/renew a gui app project. ', 'full_name': 'new_app', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root', '', 'projects-parent-dir')}, 'new_children': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'return': list[aedev.project_vars.ProjectDevVars]}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' initialize or renew parent folder children or namespace portions. ', 'full_name': 'new_children', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'new_django': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'return': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' create or complete/renew a django project. ', 'full_name': 'new_django', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root', '', 'projects-parent-dir')}, 'new_module': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'return': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' create or complete/renew a module project. ', 'full_name': 'new_module', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root', '', 'projects-parent-dir')}, 'new_namespace_root': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'return': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' create or complete/renew a namespace root package. ', 'full_name': 'new_namespace_root', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root', '', 'projects-parent-dir')}, 'new_package': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'return': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' create or complete/renew a package project. ', 'full_name': 'new_package', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root', '', 'projects-parent-dir')}, 'new_playground': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'return': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' create or complete/renew a playground project. ', 'full_name': 'new_playground', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root', '', 'projects-parent-dir')}, 'prepare_children_commit': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, '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    :param title:               optional commit message title.\n    :param children_pdv:        project dev var args tuple of the children to process.', 'full_name': 'prepare_children_commit', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'prepare_commit': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, '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    :param title:               optional commit message title (with the f-string placeholder `{project_version}`).', 'full_name': 'prepare_commit', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'prepare'}, 'refresh_children_managed': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' refresh frozen requirements and managed files from templates in all the children projects. ', 'full_name': 'refresh_children_managed', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'refresh_project': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' refresh/renew all the *requirements_frozen.txt files and all the managed files of the specified project. ', 'full_name': 'refresh_project', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'refresh'}, 'rename_children_file': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, '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 a file or folder in parent/root and children/portions projects.\n    :param old_file_name:       file/folder name to rename (optional with a path, relative to the project root).\n    :param new_file_name:       new name of file/folder (optional with a path, relative to the project root).\n    :param children_pdv:        project dev vars tuple of the children to process.\n                                else False.', 'full_name': 'rename_children_file', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'rename_file': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, '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 a file or folder in the project tree.\n    :param old_file_name:       source file/folder (optional with a path, absolute or relative to the project root).\n    :param new_file_name:       destination file/folder (optional path, absolute or relative to the project root).', 'full_name': 'rename_file', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root')}, 'renew_children': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'arg_names': (('all',), ('children-sets-expr',), ('children-names ...',)), 'docstring': ' complete/renew/update the local children projects of the specified parent/namespace-root. ', 'full_name': 'renew_children', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'renew_project': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'return': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' complete/renew/update an existing project. ', 'full_name': 'renew_project', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'renew'}, 'run_children_command': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'command': <class 'str'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, '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    :param command:             console command string (including all command arguments).\n    :param children_pdv:        tuple of children project dev vars.', 'full_name': 'run_children_command', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root'), 'shortcut': 'run'}, 'show_actions': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' get available/registered/implemented actions info of the specified/current project and remote. ', 'full_name': 'show_actions', 'local_action': False, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root', '', 'projects-parent-dir'), 'shortcut': 'actions'}, 'show_children_versions': {'annotations': {'children_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, '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. ', 'full_name': 'show_children_versions', 'local_action': True, 'project_types': ('projects-parent-dir', 'namespace-root')}, 'show_versions': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' display package versions of worktree, remote repo(s), latest PyPI release and default app/web host. ', 'full_name': 'show_versions', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'versions'}, 'update_mirror': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>, 'mirror_remote': <class 'str'>}, 'arg_names': (('mirror-url-or-remote-name',),), 'docstring': ' create or update a mirror of the actual repo onto the specified remote/host.\n    :param mirror_remote:       mirror remote name or server/host url (optionally with authentication) to push to.\n    .. note::\n        there are three more pushable (but currently not implemented) git ref namespaces: pull, pipelines and lfs.\n        other git ref namespaces are stash and remotes (remotes cannot be pushed - therefore the git push option\n        --mirror cannot be used to create&update a mirror at GitHub/GitLab).', 'full_name': 'update_mirror', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'mirror'}, 'upgrade_requirements': {'annotations': {'ini_pdv': <class 'aedev.project_vars.ProjectDevVars'>}, 'docstring': ' upgrade project requirements|dependencies, optionally as editable package.\n    :param optional_flags:      additional/optional command line arguments:\n                                * ``EDITABLE``: requirements available as sister packager (under the same project parent\n                                  folder) will be installed/upgraded as editable (via the -e option of `pip`).\n                                * ``MASKS``: list of package name masks/pattern strings to restrict the upgraded\n                                  packages. if not specified then all packages required by the project will be upgraded.', 'flags': {'EDITABLE': False, 'MASKS': []}, 'full_name': 'upgrade_requirements', 'local_action': True, 'project_types': ('app', 'django', 'module', 'package', 'playground', 'namespace-root'), 'shortcut': 'upgrade'}}

implemented actions registered via _action() deco

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

class names of all supported remote host domains

children_desc(pdv, children_pdv=())

printable message describing a single child of a namespace root (portion) or of a project parent folder.

Parameters:

• pdv (ProjectDevVars) – project dev vars of the root/parent project.

• children_pdv (Collection[ProjectDevVars]) – project dev vars of the child to get the description for.

Return type:

str

Returns:

description message of the specified namespace-root/parent-folder child.

children_project_names(ini_pdv, names, chi_vars)

check and compile a list of package names of the children of a namespace root or a projects parent folder.

Parameters:

• ini_pdv (ProjectDevVars) – project dev variables of a root project or projects parent folder.

• names (Sequence[str]) – names of the children.

• chi_vars (OrderedDict[str, ProjectDevVars]) – children project dev variables to double-check and to determine returned list order.

Return type:

list[str]

Returns:

children package names list (ordered in the same order as the specified child pdvs).

expected_args(act_spec)

return a printable message explaining the expected arguments of the specified pjm action.

Parameters:

act_spec (dict[str, Any]) – specification of the action to determine the expected arguments for.

Return type:

str

Returns:

printable message with the expected arguments of the specified action.

get_app_option(pdv, option_name)

determine command line option value from pdv object.

Parameters:

• pdv (ProjectDevVars) – project dev variables.

• option_name (str) – name of the command line option to determine.

Return type:

Optional[Any]

Returns:

command line option value or None if not found.

get_branch(pdv)

determine name of the branch of the project of the specified pdv object.

Parameters:

pdv (ProjectDevVars) – project dev variables.

Return type:

str

Returns:

name of the branch specified in the --branch command line option. if no branch got specified as command line option then return the currently checked-out branch.

get_host_class_name(host_domain)

determine the class name for the specified host domain.

Parameters:

host_domain (str) – host domain name to determine the corresponding class name.

Return type:

str

Returns:

class name of the specified host domain name or an empty string if no class is found.

get_host_config_val(pdv, option_name, host_domain='', host_user='')

determine host/user-specific domain, group, user and token values.

Parameters:

• pdv (ProjectDevVars) – project dev vars with app options and project_path (to include env var values from dotenv files in prj/parent dirs).

• option_name (str) – app option name.

• host_domain (str) – domain name of the host. if not specified or as empty string then the domain specified as command line option (via –repo_domain, –web_domain) will be used. if no option got specified then the search for a host-specific variable will be skipped.

• 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.

Return type:

Optional[str]

Returns:

config variable value or None if not found.

get_host_domain(pdv, var_prefix='repo_')

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

Parameters:

• pdv (ProjectDevVars) – project dev vars.

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

Return type:

str

Returns:

domain name of the host, or an empty string if ‘{var_prefix}domain’ is not set.

get_host_group(pdv, host_domain)

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

Parameters:

• pdv (ProjectDevVars) – project dev vars.

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

Return type:

str

Returns:

upstream user|group name or, if not found, then the default username PDV_AUTHOR, and if neither ‘repo_group’ nor ‘AUTHOR’ exists then an empty string..

get_host_user_name(pdv, host_domain, var_prefix='repo_')

determine username from –repo_user/–web_user options, PDV_repo_user or PDV_web_user config variable.

Parameters:

• pdv (ProjectDevVars) – project dev vars.

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

• var_prefix (str) – config var name prefix. pass ‘web_’ to get web server username. ‘repo_user’ | ‘web_user’

Return type:

str

Returns:

username or if not found the user group name.

get_host_user_token(pdv, host_domain, host_user='', var_prefix='repo_')

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

Parameters:

• pdv (ProjectDevVars) – project development variables.

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

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

• var_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_mirror_urls(pdv)

determine the configured mirrors remote names/urls for the project specified by the pdv argument.

Parameters:

pdv (ProjectDevVars) – project dev vars of the project to determine the mirrors remote-names/urls for.

Return type:

list[str]

Returns:

list of remote-names/urls of the configured mirror urls. the urls that are evaluated to an empty string are not included in this returned list. an empty list will be returned if there are no mirrors configured for the specified project.

git_init_add(pdv)

run git add for the project specified by the pdv argument (after running git init if git repo is not created).

Parameters:

pdv (ProjectDevVars) – project dev vars.

git_push_url(pdv, authenticate=False, remote_urls=None)

determine the origin url of the repository, to push onto.

Return type:

str

guess_next_action(pdv)

guess the next action to be done locally.

Parameters:

pdv (ProjectDevVars) – dev vars of the project.

Return type:

str

Returns:

error message with a ‘¡’ as the first char or one of the action names: ‘new_project’, ‘renew_project’, ‘prepare_commit’, ‘commit_project’, ‘push_project’, ‘request_merge’, ‘release_project’.

ppp(output)

pretty printing formatter function.

Parameters:

output (Iterable[str]) – output iterable to format for pretty printing.

Return type:

str

Returns:

pretty printing formatted string.

project_topics(pdv)

extracts the project topics of a project.

Parameters:

pdv (ProjectDevVars) – project development variables.

Return type:

list[str]

Returns:

list of the project topics.

refresh_pdv(pdv)

refresh pdv in-place to reflect the current state of the project working tree.

Parameters:

pdv (ProjectDevVars) – project development variables.

update_frozen_req_file(project_pip_name, req_file_path, all_packages=False, integrate_pip_errors=False)

update frozen requirements file

Parameters:

• project_pip_name (str) – pip name of the project with this requirements file.

• req_file_path (str) – file path of the requirements file.

• all_packages (bool) – pass True to include also not explicitly requested packages (added by pip freeze).

• integrate_pip_errors (bool) – pass True to integrate errors into the resulting frozen requirements file.

Return type:

list[str]

Returns:

an empty list (if update_rozen_req_file.integrate_pip_errors is True) or a list of pip error output lines.

update_frozen_req_files(pdv)

update the four possible frozen requirements files of a project.

Parameters:

pdv (ProjectDevVars) – project dev variables of the project to update.

Return type:

list[str]

Returns:

list of errors or an empty list.

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

write the commit message file used by git commands.

Parameters:

• pdv (ProjectDevVars) – project dev variables.

• pkg_version (str) – package/project version placeholder.

• title (str) – commit message title.