aedev.project_vars

project development variables

this portion of the aedev namespace is providing constants and helper functions to keep your projects DRY. this is done by bundling all development environment properties and settings of your project without any redundancies. e.g. the short description/title or the version number of a project is maintained and can be changed in one (!) single place.

the following Python project types are supported:

• GUI applications

• Django web applications

• console app and library modules

• console app and library packages

• namespace library portions

• namespace roots

• source code parent folders

• playgrounds

project development variables data includes:

• project name, version, title and description

• virtual environment (pyenv)

• contributing author name and email

• project documentation (README, manuals, contribution docs, license)

• external dependencies/requirements

• project file templates

• repository status, branches and tags (git)

• repository remote urls and CI (GitLab or GitHub)

• deployment remotes (web servers, cloud storage, PyPi-release of project and its namespace children|portions)

• setup (pip and setuptools)

determine project development variables

the ProjectDevVars class provided by this portion is a dictionary subclass that represents the project development variables. On instantiation, it is analyzing the project folder, collecting defaults, merging environment variables, and compiles values suitable for packaging and publishing.

to collect the data of a project, create a new instance of this class:

pdv = ProjectDevVars()

for existing projects no arguments are needed if the current working directory is the project root folder. in order to analyze a project in any other directory specify the path via the project_path keyword argument:

pdv = ProjectDevVars(project_path='path/to/project_or_parent')

the project property values can be retrieved from the returned dictionary-like instance, either via the method pdv_val() (used mainly for non-string values), or directly via getitem. the following example is retrieving a string reflecting the name of the project:

project_name = pdv['project_name']

the type of project gets mapped by the ‘project_type’ project development variable. recognized project types are e.g. a module, a package, a namespace root, or an gui application.

determining the project development variables of projects with the types PARENT_PRJ or ROOT_PRJ will gather also the project dev vars of their containing children projects. these children dev variables are stored as list in the parent project development variable children_project_vars, where each item is an instance of the ProjectDevVars class, representing a child project.

key methods of a ProjectDevVars instance

• ProjectDevVars.as_dict() – export pdv values as a plain dict.

• ProjectDevVars.copy() – create a new ProjectDevVars with copied values.

• ProjectDevVars.errors() – validate pdv values and return a list of errors/warnings.

• ProjectDevVars.pdv_val() – fetch a variable’s value, falling back to defaults.

project introspection helpers and constants

these standalone functions provide utilities for inspecting Python source code files and project environments.

• editable_project_root_path(): determines the project path of a package installed in an editable mode

(e.g., via pip install -e). * find_extra_modules(): determines a list of additional module names within a local package, excluding templates and __init__.py files. * increment_version(): increments a semantic version string (e.g., major, minor, or patch part). * latest_remote_version() – determine the latest or next available version tag from git remotes. * main_file_path() – compute the expected main/version file path for a project type. * pdv_default_values() – collect default pdv values from module globals. * pdv_env_values() – load pdv values from environment variables. * project_owner_name_version() – split a project string into owner, name, and version. * root_packages_masks() – return package glob masks for root packages. * skip_files_migrations() – filter callback to exclude django migrations. * skip_files_lean_web() – filter callback to minimize files for web deployment. * replace_file_version() – update a file’s version string in place.

project development variable value constants

• PDV_APP_BUILD_CFG_FILENAME: the name of the application building configuration file (e.g. buildozer.spec).

• PDV_COMMIT_MSG_FILE_NAME: the default file name for a git commit message.

• PDV_DOCS_FOLDER: the default folder name for documentation (e.g., docs).

• PDV_DOCS_HOST_PROTOCOL: the default protocol for the documentation host (e.g., https://).

• PDV_docs_domain: the default dns domain for documentation (e.g., readthedocs.io).

• PDV_KEYWORDS: a list of default keywords for :pypi:`pypi` release metadata.

• PDV_LICENSE: the default license for the project (e.g., gpl-3.0-or-later, PEP 639).

• PDV_MAIN_BRANCH: the default name for the main branch in a git repository.

• PDV_MIN_PYTHON_VERSION: the minimum version of the python runtime required for the project (e.g., 3.9).

• PDV_NULL_VERSION: the initial package version, chosen to meet :pypi:`pypi` classifier requirements.

• PDV_PARENT_FOLDERS: a tuple of common names for parent folders that contain python project directories.

• PDV_PYTHON_REQUIRES: the default required python version string for setup files (e.g., >=3.9).

• PDV_RELEASE_REF_PREFIX: the prefix for project release branch names or references.

• PDV_REMOTE_ORIGIN: the name of the git remote from which the local repository was cloned.

• PDV_REMOTE_UPSTREAM: the name of the git remote for the fork’s source repository.

• PDV_REPO_HOST_PROTOCOL: the default protocol for the code repository host (e.g., https://).

• PDV_repo_domain: the default dns domain for the code repository (e.g., gitlab.com).

• PDV_REPO_PAGES_DOMAIN: the internet/dns domain for repository pages (e.g., gitlab.io).

• PDV_REPO_GROUP_SUFFIX: the suffix used for the default repository users group name.

• PDV_REPO_ISSUES_SUFFIX: the url suffix for the repository’s issues page (e.g., /-/issues).

• PDV_REQ_FILE_NAME: the default filename for the main project dependencies (e.g., requirements.txt).

• PDV_REQ_DEV_FILE_NAME: the default filename for development or template-specific requirements.

• PDV_TEMPLATES_FOLDER: the default folder name for file templates (e.g., templates).

• PDV_TESTS_FOLDER: the default folder name for unit tests (e.g., tests).

• PDV_VERSION_TAG_PREFIX: the prefix for git version tags.

configure individual project development variable values

this portion is providing default values for most of the project development variables. individual default values can be configured as OS/shell/console environment variables.

for projects released at PyPI at least the author name and a contact email address should be configured, because their default values (in PDV_AUTHOR and PDV_AUTHOR_EMAIL) are empty strings.

the package data resources of a project gets determined by the method _find_package_data(). the return value gets directly passed to the package_data development variable, which will be used to create the setup.py file of your project (as kwarg passed to setuptools.setup()).

Module Attributes

ENV_VAR_NAME_PREFIX	used for env var names and the constant names declared in this module
PDV_COMMIT_MSG_FILE_NAME	name of the git commit message file
PDV_APP_BUILD_CFG_FILENAME	app building config file
PDV_DOCS_FOLDER	docs folder name
PDV_DOCS_HOST_PROTOCOL	documentation host connection protocol
PDV_docs_domain	documentation dns domain
PDV_KEYWORDS	PyPi release keywords
PDV_LICENSE	project license default (PEP 639)
PDV_MAIN_BRANCH	default main branch name
PDV_MIN_PYTHON_VERSION	minimum version of the Python/CPython runtime
PDV_NULL_VERSION	initial package version (3==min classifier accepted by PyPI)
PDV_PARENT_FOLDERS	names of parent folders containing Python project directories
PDV_REPO_HOST_PROTOCOL	repo host connection protocol
PDV_repo_domain	code repository dns domain (gitlab.com|github.com)
PDV_REPO_PAGES_DOMAIN	repository pages internet/dns domain
PDV_REPO_GROUP_SUFFIX	repo users group name suffix (used for 'repo_group' default)
PDV_REPO_ISSUES_SUFFIX	repo host URL suffix to the issues page (GitHub=="/issues")
PDV_REQ_FILE_NAME	requirements default file name
PDV_REQ_DEV_FILE_NAME	default file name for development/template requirements
PDV_TEMPLATES_FOLDER	templates folder name
PDV_TESTS_FOLDER	unit tests folder name
PDV_RELEASE_REF_PREFIX	project release branch-name/ref prefix
PDV_VERSION_TAG_PREFIX	project version tag prefix
PDV_REMOTE_ORIGIN	name of git remote from where the local repo get cloned from
PDV_REMOTE_UPSTREAM	name of git remote from where the fork repo get forked from
ChildrenType	children pdv of a project parent or a namespace root
DataFilesType	setup_kwargs['data_files']
PackageDataType	setup_kwargs['package_data']
SetupKwargsType	setuptools.setup()-kwargs
PdvVarValType	project development variable value types, including also types of later/externally added vars by pjm, like e.g. 'TemplateProjectsType' for the 'project_templates' variable, or 'RemoteHost' for the 'host_api' variable, or dict[str, str] for the 'main_app_options' variable (already covered via SetupKwargsType/dict[str, Any].

Functions

find_extra_modules(package_path, tpls_folder)	determine additional modules of a local (namespace portion) package/project.
frozen_req_file_path([req_file_path, strict])	check if a frozen requirements.txt file exists (with version numbers).
increment_version(version[, increment_part])	increment version number.
latest_remote_version(pdv[, increment_part])	determine the latest or the next free origin remote repository version of the specified project.
main_file_path(project_path, project_type[, ...])	return the file path of the main/version type for the specified project type.
pdv_default_values()	collect the ProjectDevVars defaults from the globals of this module.
pdv_env_values()	read pdv default values from environment variables.
project_name_guess(project_path[, stripped_name])	guess name of project name from project root directory path (also for backups under old_src parent directory).
project_owner_name_version(project_string[, ...])	split the specified project string into its owner user|group name, the project name, and the project version.
replace_file_version(file_name[, version, ...])	replace version number in specified project main/version file, removing any pre/alpha version subpart/suffix.
root_packages_masks(project_packages)	determine root sub packages from the passed project packages and add them glob path wildcards.
skip_files_lean_web(file_path)	file exclusion callback to reduce the deployed files on the web server to the minimum.
skip_files_migrations(file_path)	file exclusion callback for the files under the django migrations folders.

Classes

ProjectDevVars(**var_values)

project development variables mapping.

ENV_VAR_NAME_PREFIX = 'PDV_'

used for env var names and the constant names declared in this module

PDV_COMMIT_MSG_FILE_NAME = '.commit_msg.txt'

name of the git commit message file

PDV_APP_BUILD_CFG_FILENAME = 'buildozer.spec'

app building config file

PDV_DOCS_FOLDER = 'docs'

docs folder name

PDV_DOCS_HOST_PROTOCOL = 'https://'

documentation host connection protocol

PDV_docs_domain = 'readthedocs.io'

documentation dns domain

PDV_KEYWORDS = ['configuration', 'development', 'environment', 'productivity']

PyPi release keywords

PDV_LICENSE = 'GPL-3.0-or-later'

project license default (PEP 639)

PDV_MAIN_BRANCH = 'develop'

default main branch name

PDV_MIN_PYTHON_VERSION = '3.12'

minimum version of the Python/CPython runtime

PDV_NULL_VERSION = '0.3.0'

initial package version (3==min classifier accepted by PyPI)

PDV_PARENT_FOLDERS = ('Projects', 'PycharmProjects', 'ae-group', 'aedev-group', 'code', 'dev', 'esc', 'old_src', 'projects', 'python', 'repos', 'source', 'src', 'TsT', 'docs')

names of parent folders containing Python project directories

PDV_REPO_HOST_PROTOCOL = 'https://'

repo host connection protocol

PDV_repo_domain = 'gitlab.com'

code repository dns domain (gitlab.com|github.com)

PDV_REPO_PAGES_DOMAIN = 'gitlab.io'

repository pages internet/dns domain

PDV_REPO_GROUP_SUFFIX = '-group'

repo users group name suffix (used for ‘repo_group’ default)

PDV_REPO_ISSUES_SUFFIX = '/-/issues'

repo host URL suffix to the issues page (GitHub==”/issues”)

PDV_REQ_FILE_NAME = 'requirements.txt'

requirements default file name

PDV_REQ_DEV_FILE_NAME = 'dev_requirements.txt'

default file name for development/template requirements

PDV_TEMPLATES_FOLDER = 'templates'

templates folder name

PDV_TESTS_FOLDER = 'tests'

unit tests folder name

PDV_RELEASE_REF_PREFIX = 'release'

project release branch-name/ref prefix

PDV_VERSION_TAG_PREFIX = 'v'

project version tag prefix

PDV_REMOTE_ORIGIN = 'origin'

name of git remote from where the local repo get cloned from

PDV_REMOTE_UPSTREAM = 'upstream'

name of git remote from where the fork repo get forked from

ChildrenType

children pdv of a project parent or a namespace root

alias of OrderedDict[str, ProjectDevVars]

DataFilesType

setup_kwargs[‘data_files’]

alias of list[tuple[str, tuple[str, …]]]

PackageDataType

setup_kwargs[‘package_data’]

alias of dict[str, list[str]]

SetupKwargsType

setuptools.setup()-kwargs

alias of dict[str, Any]

PdvVarValType

project development variable value types, including also types of later/externally added vars by pjm, like e.g. ‘TemplateProjectsType’ for the ‘project_templates’ variable, or ‘RemoteHost’ for the ‘host_api’ variable, or dict[str, str] for the ‘main_app_options’ variable (already covered via SetupKwargsType/dict[str, Any].

alias of str | Sequence[str] | list[tuple[str, tuple[str, …]]] | dict[str, str] | dict[str, Any] | list[dict[str, str]] | RemoteHost

find_extra_modules(package_path, tpls_folder)

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

Parameters:

• package_path (str) – path to the package folder, mostly underneath the project root folder.

• tpls_folder (str) – name of the templates folder (situated in the package folder) to exclude template files.

Return type:

list[str]

Returns:

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

frozen_req_file_path(req_file_path='requirements.txt', strict=False)

check if a frozen requirements.txt file exists (with version numbers).

Parameters:

• req_file_path (str) – requirements-file-path (the not frozen version of it).

• strict (bool) – pass True to return an empty string if no frozen version exists.

Return type:

str

Returns:

path of the frozen version of the specified *requirements.txt file (in the same folder) or if no frozen version exists: an empty string (if strict got specified as True), or (if strict is False) the specified path of the (normal|un-frozen) requirements-file.

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.

latest_remote_version(pdv, increment_part=3)

determine the latest or the next free origin remote repository version of the specified project.

Parameters:

• pdv (ProjectDevVars) – project development variables (project_path, project_version, VERSION_TAG_PREFIX).

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

the incremented latest published repository package version as a string or the first version accepted by PyPI (increment_version(PDV_NULL_VERSION, increment_part) | “0.3.1”) if the project never published a version tag to the git origin remote.

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 root folder path, including the package name as basename.

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

• namespace_name (str) – pass namespace name for namespace portion or root projects.

Return type:

str

Returns:

main file path and name.

Note

in contrary to project_main_file() this function will also work for new projects where neither exists the main file nor the project root folder.

pdv_default_values()

collect the ProjectDevVars defaults from the globals of this module.

Return type:

dict[str, Any]

Returns:

dict with the pdv variable names as keys and its default values.

pdv_env_values()

read pdv default values from environment variables.

Return type:

dict[str, Any]

Returns:

dict with the pdv names as keys and its values loaded from the os environment variables.

project_name_guess(project_path, stripped_name='')

guess name of project name from project root directory path (also for backups under old_src parent directory).

Parameters:

• project_path (str) – project root directory path (absolute or relative to the current working directory).

• stripped_name (str) – optional stripped project name (w/o any old-project-backup-idx-number+comments suffix).

Return type:

str

Returns:

guessed project name.

project_owner_name_version(project_string, owner_default='', namespace_default='', version_default='')

split the specified project string into its owner user|group name, the project name, and the project version.

Parameters:

• project_string (str) – the string to parse and split.

• owner_default (str) – default value of the owner user|group name if not specified.

• namespace_default (str) – namespace default value, used if only portion name is specified.

• version_default (str) – default value of the version number if not specified.

Return type:

tuple[str, str, str]

Returns:

tuple with owner name, project name and project version

replace_file_version(file_name, version='', increment_part=3)

replace version number in specified project main/version file, removing any pre/alpha version subpart/suffix.

Parameters:

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

• version (str) – version number to increment/bump (if the argument increment_part is not 0) and to replace/put into the version file. defaults to the version number in the version file, if not specified.

• increment_part (int) – part of the version number to be incremented: 1=mayor, 2=minor, 3=build/revision. specify 0 to not increment the version number. defaults to 3 (build) if not specified.

Return type:

str

Returns:

empty string on success, else error string.

root_packages_masks(project_packages)

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

Parameters:

project_packages (Iterable[str]) – iterable with package import names, like returned from the setuptools helper functions find_packages()/find_namespace_packages().

Return type:

list[str]

Returns:

list of project root packages extended with glob path wildcards.

skip_files_lean_web(file_path)

file exclusion 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:

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

skip_files_migrations(file_path)

file exclusion 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:

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

class ProjectDevVars(**var_values)

Bases: dict[str, str | Sequence[str] | list[tuple[str, tuple[str, …]]] | dict[str, str] | dict[str, Any] | list[dict[str, str]] | RemoteHost]

project development variables mapping.

__init__(**var_values)

analyze and map the environment and status of a code project into project development variables.

Parameters:

var_values – fixed dev var values, overwriting OS environment variables and defaults. to get the project dev variable values from an existing project pass the project_path kwarg with the path of the project root folder. the project root path defaults to the current working directory, if the kwargs project_path and project_name are not specified; if only project_name is specified then it defaults to the folder with the project name situated underneath the current working directory.

Raises:

AssertionError if both kwargs project_path and project_name are specified.

Returns:

special mapping with all the determinable project development variable values.

disable_non_string_fetch_warning

set to True to disable warning on access to non-str-item-value

__getitem__(var_name)

get the string value of the project development variable with the specified var name.

Parameters:

var_name (str) – project development variable name.

Return type:

str

Returns:

string value of the specified pdv (other types are returned too, but a warning will be displayed in this case). or if not exists in pdv then the global constant/default value of this module, or any empty string if no constant with this name exists.

_compile_dev_vars()

_compile_namespace_children()

_compile_remote_vars()

_compile_setup_kwargs()

add setup kwargs from pdv values.

_find_package_data()

find doc, template, kv, i18n translation text, image and sound files of an app/package.

Return type:

dict[str, list[str]]

Returns:

setuptools package_data dict, where the key is an empty string (to be included for all sub-packages) and the dict item is a list of all found resource files with a relative path to the package_path directory. folder names with a leading underscore (like e.g. the docs _build, the PY_CACHE_FOLDER`|`__pycache__ and the __enamlcache__ folders) get excluded. explicitly included will be any PDV_APP_BUILD_CFG_FILENAME file, as well as any folder name starting with PACKAGE_INCLUDE_FILES_PREFIX (used e.g. by ae.updater), situated directly in the directory specified by package_path.

_init_from_env(project_path)

_init_pdv(var_values)

_init_project_type()

determine project type from project_path, project_name, namespace_name, portion_name and version_file.

Return type:

str

_load_descriptions()

load long description from the README file of the project.

Parameters:

self – dict of project development variables with a ‘project_path’ key.

_load_requirements()

load requirements from the available requirements.txt file(s) of this project.

Parameters:

self –

project development variables instance with the following required project dev vars: DOCS_FOLDER, REQ_FILE_NAME, REQ_DEV_FILE_NAME, TESTS_FOLDER, namespace_name, project_name, project_path.

the project env vars overwritten in this argument by this function are: dev_requires, docs_requires, install_requires, portions_packages, tests_requires.

as_dict()

extract project development variable values as a dictionary.

Return type:

dict[str, Any]

children_app_options()

determine the main app options needed for to initialize its children w/o ‘project_name’ and ‘project_path’.

Return type:

dict[str, str]

Returns:

dict with valid main app options for the children of this root/parent package/project.

copy()

create a copy of this ProjectDevVars instance.

Return type:

ProjectDevVars

__orig_bases__ = (dict[str, typing.Union[str, typing.Sequence[str], list[tuple[str, tuple[str, ...]]], dict[str, str], dict[str, typing.Any], list[dict[str, str]], ForwardRef('RemoteHost')]],)

errors(warnings_as_error=False)

checks the completeness and integrity of the project development variable values.

Parameters:

warnings_as_error (bool) – pass True to interpret all warnings as an error (e.g., if no AUTHOR/_EMAIL is configured, or if the projects parent folder is not registered as such).

Return type:

list[str]

Returns:

a list of error/warning messages.

pdv_val(var_name)

determine the project development variable value from this instance of their default value.

Parameters:

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

Return type:

Any

Returns:

project dev var value (mostly not of type str) or an empty string if variable is not defined.