aedev.project_manager.templates

templates for managed files of Python projects

this module extends the template processing engine of the ae.managed_files portion with code project management functionality.

Module Attributes

CACHED_TPL_PROJECTS	map to temporarily cache registered/cloned template projects.
MOVE_INTO_PACKAGE_PATH_PFX	template path prefix, to move the templates into the package path (underneath/instead of the project path).
SKIP_FOR_PORTIONS_PATH_PFX	template file/path prefix to skip deployment of templates to a namespace portion.
SKIP_PRJ_TYPE_PATH_PFX	template file name prefix followed by a project type id arg (see *_PRJ constants). file creation/update from template will be skipped if it the project type id in the template file name matches the destination project type.
TPL_IMPORT_NAME_PREFIX	package/import name prefix of project type template packages
TPL_IMPORT_NAME_SUFFIX	package/import name suffix of project type template packages
TPL_PATH_OPTION_SUFFIX	option name suffix to specify template project root folder
TPL_VERSION_OPTION_SUFFIX	option name suffix to specify template package version
TPL_IMPORT_NAMES	import names of the generic project-type-related (aedev) template projects
PATH_PREFIXES_PARSERS	mapping of path prefix parser markers (keys) to their corresponding parser functions (value)

Functions

check_templates(cae, pdv[, fail_on_outdated])	check the project files that are outdated or missing from the registered namespace/project templates.
clone_template_project(import_name, version_tag)	clone template package project from gitlab.com
path_pfx_place_into_package_path(mf)	path prefix callee for the MOVE_INTO_PACKAGE_PATH_PFX prefix.
path_pfx_skip_for_portions(mf)	callee for the SKIP_FOR_PORTIONS_PATH_PFX path prefix.
path_pfx_skip_if_project_type(mf, project_type)	path prefix callback for the SKIP_PRJ_TYPE_PATH_PFX prefix.
project_templates(project_type, ...[, ...])	get template packages (optionally clone and register) of a project with the specified project type&namespace.
register_template(import_name, ...[, ...])	add/update the template register and the template packages list for the specified template package and version.
setup_kwargs_literal(setup_kwargs)	literal string of the setuptools.setup() kwargs dict, to be used by the setup.py template (aedev.project_tpls).
template_options_prefix(import_name)	unique key of a template package import name usable for command line options and to specify a template path.
template_path_option(import_name)	unique key of a template package import name usable for command line options and to specify a template path.
template_version_option(import_name)	unique key of a template package import name usable for command line options and to specify a template version.

CACHED_TPL_PROJECTS: dict[str, dict[str, str]] = {}

map to temporarily cache registered/cloned template projects. not used directly by this module, but declared globally here to be used as argument value for project_templates.cached_templates and register_template.cached_templates.

MOVE_INTO_PACKAGE_PATH_PFX = 'MovPkg-'

template path prefix, to move the templates into the package path (underneath/instead of the project path).

SKIP_FOR_PORTIONS_PATH_PFX = 'SkpPor-'

template file/path prefix to skip deployment of templates to a namespace portion.

SKIP_PRJ_TYPE_PATH_PFX = 'SkpTyp-'

template file name prefix followed by a project type id arg (see *_PRJ constants). file creation/update from template will be skipped if it the project type id in the template file name matches the destination project type.

TPL_IMPORT_NAME_PREFIX = 'aedev.'

package/import name prefix of project type template packages

TPL_IMPORT_NAME_SUFFIX = '_tpls'

package/import name suffix of project type template packages

TPL_PATH_OPTION_SUFFIX = '_project_path'

option name suffix to specify template project root folder

TPL_VERSION_OPTION_SUFFIX = '_project_version'

option name suffix to specify template package version

TPL_IMPORT_NAMES = ['aedev.app_tpls', 'aedev.django_tpls', 'aedev.module_tpls', 'aedev.package_tpls', 'aedev.playground_tpls', 'aedev.namespace_root_tpls', 'aedev.project_tpls']

import names of the generic project-type-related (aedev) template projects

_get_and_log_project_templates(cae, pdv)

Return type:

list[dict[str, str]]

_get_app_tpl_options(cae, pdv)

Return type:

dict[str, str]

_get_template_files(project_tpls, version_tag_prefix)

Return type:

list[tuple[str, str, str]]

_get_template_vars(pdv)

Return type:

TypeAliasType

_log_check_outdated(cae, outdated, verbose)

_log_check_summary(cae, man, subject, fail_on_outdated=False)

check_templates(cae, pdv, fail_on_outdated=False)

check the project files that are outdated or missing from the registered namespace/project templates.

Parameters:

• cae (ConsoleApp) – ConsoleApp instance.

• pdv (ProjectDevVars) – 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.

• fail_on_outdated (bool) – pass True to quit app if there are missing/outdated managed files (skip-able with -f).

Return type:

TemplateMngr | None

Returns:

TemplateMngr instance with the current state of the project files generated and synced from templates. e.g. to retrieve a set of the destination project file paths that would be created/updated use set(<this return value>.deploy_files.keys()). None will be returned if no project type gets specified by the argument pdv.

Note

ensure the CWD is on the destination project root folder (missing/outdated_files paths are relative).

clone_template_project(import_name, version_tag)

clone template package project from gitlab.com

Parameters:

• import_name (str) – template package import name.

• version_tag (str) – version tag of the template package to clone.

Return type:

str

Returns:

path to the templates folder within the template package project or an empty string if an error occurred..

path_pfx_place_into_package_path(mf)

path prefix callee for the MOVE_INTO_PACKAGE_PATH_PFX prefix.

Parameters:

mf (ManagedFile) – ManagedFile instance.

path_pfx_skip_for_portions(mf)

callee for the SKIP_FOR_PORTIONS_PATH_PFX path prefix.

Parameters:

mf (ManagedFile) – ManagedFile instance.

path_pfx_skip_if_project_type(mf, project_type)

path prefix callback for the SKIP_PRJ_TYPE_PATH_PFX prefix.

Parameters:

• mf (ManagedFile) – ManagedFile instance.

• project_type (str) – project type prefix arg.

PATH_PREFIXES_PARSERS = {'MovPkg-': (0, <function path_pfx_place_into_package_path>), 'Obi-': (0, <function path_pfx_overwritable_binary_content>), 'Ovw-': (0, <function path_pfx_overwritable_content>), 'PutMar-': (0, <function path_pfx_puttable_content>), 'SkpPor-': (0, <function path_pfx_skip_for_portions>), 'SkpTyp-': (1, <function path_pfx_skip_if_project_type>), 'UpdMar-': (0, <function path_pfx_updatable_content>), 'fSt-': (0, <function path_pfx_parametrize_with_context>)}

mapping of path prefix parser markers (keys) to their corresponding parser functions (value)

project_templates(project_type, namespace_name, requested_options, cached_templates, dev_requires, version_tag_prefix='v')

get template packages (optionally clone and register) of a project with the specified project type&namespace.

Parameters:

• project_type (str) – type of the project (declared as *_PRJ constants in aedev.base).

• namespace_name (str) – name of the namespace if the project is a portion, else an empty string.

• requested_options (dict[str, str]) – dict with explicitly requested template packages via their version or their local path. if not specified for a template package then the version specified by the project_templates.dev_requires will be used. the keys of this dict are created with the helper functions template_path_option() or template_version_option(). the values are accordingly either local file paths or version strings of the template packages to use/register.

• cached_templates (dict[str, dict[str, str]]) – map of the cached/registered template projects (e.g. CACHED_TPL_PROJECTS). unregistered templates packages needed by the specified project type/name-space will be automatically added to this register/map.

• dev_requires (Union[list[str], tuple[str, ...]]) – list/tuple of packages required by the project (from the projects dev_requirements.txt file) which can contain template packages with their version number. if the versions of the needed template packages are not specified, then the latest versions will be used. when specified as list type and the registered template package version got cloned then it will be appended as new list entry.

• version_tag_prefix (str) – version tag prefix.

Return type:

list[dict[str, str]]

Returns:

list of the template packages needed by the specified project type/namespace.

register_template(import_name, requested_options, cached_templates, dev_requires, template_packages, version_tag_prefix='v')

add/update the template register and the template packages list for the specified template package and version.

Parameters:

• import_name (str) – import name of the template package.

• requested_options (dict[str, str]) – see description of the parameter project_template.requested_options.

• cached_templates (dict[str, dict[str, str]]) – see description of the parameter project_template.cached_templates.

• dev_requires (Union[list[str], tuple[str, ...]]) – see description of the parameter project_template.dev_requires.

• template_packages (list[dict[str, str]]) – list of template packages, to be extended with the specified template package/version.

• version_tag_prefix (str) – version tag prefix.

Raises:

AssertionError – if both, the local path and the version option is specified.

setup_kwargs_literal(setup_kwargs)

literal string of the setuptools.setup() kwargs dict, to be used by the setup.py template (aedev.project_tpls).

Parameters:

setup_kwargs (dict[str, Any]) – kwargs passed to call of _func:setuptools.setup in setup.py. in order to prevent errors if the template-generated file README.md get created after setup.py and to have a nicer code formatting in the resulting setup.py file, the value of the long_description item will be replaced by a dynamic-loading expression.

Return type:

str

Returns:

literal of specified setup kwargs formatted for column 1.

Note

the setup.py template has to include/provide the statement: import pathlib.

template_options_prefix(import_name)

unique key of a template package import name usable for command line options and to specify a template path.

Parameters:

import_name (str) – import name of the template package.

Return type:

str

Returns:

command line option prefix of the specified template package.

template_path_option(import_name)

unique key of a template package import name usable for command line options and to specify a template path.

Parameters:

import_name (str) – template package import name.

Return type:

str

Returns:

template package version option key/name.

template_version_option(import_name)

unique key of a template package import name usable for command line options and to specify a template version.

Parameters:

import_name (str) – template package import name.

Return type:

str

Returns:

template package path option key/name.