aedev.base

base development constants and helpers

this module portion in the aedev namespace provides the following base constants, types and helper functions, used for development operations (DevOps) and tools:

• APP_PRJ – gui application project type.

• DJANGO_PRJ – django web application project type.

• MODULE_PRJ – standalone module project type.

• NO_PRJ – marker for invalid or no project (type) detected.

• PACKAGE_PRJ – python package project type.

• PARENT_PRJ – pseudo-type for parent-directory initialization.

• PLAYGROUND_PRJ – playground or scratch project type.

• ROOT_PRJ – namespace root project type.

• ANY_PRJ_TYPE – tuple of all real project types.

• ALL_PRJ_TYPES – tuple of all project types, including NO_PRJ and PARENT_PRJ.

• COMMIT_MSG_FILE_NAME: the default filename for commit messages.

• DEF_MAIN_BRANCH: the name of the default/main branch.

• PIP_CMD: the pip command.

• PIP_INSTALL_CMD: the pip install command.

• PYPI_ROOT_URL: the production PyPI URL.

• PYPI_ROOT_URL_TEST: the test PyPI URL.

• PROJECT_VERSION_SEP: the separator used in Pip requirements files to ty/fix a project to a version.

• VERSION_QUOTE: the quote character used for the __version__ variable value (typically ‘).

• VERSION_PREFIX: the search string used to find the __version__ variable (e.g., __version__ = ‘).

• VERSION_MATCHER: a pre-compiled regular expression to detect and manage version numbers conforming to pep396 and python’s distutils standards.

• TemplateProjectType: project template register info (project_templates item type).

• TemplateProjectsType: project_templates var type (added by pjm/project_manager).

• CachedTemplates: cache mapping of registered project templates.

• code_file_title(): determines the docstring title of a Python code file.

• code_file_version(): reads the version number of a Python code file from the __version__ module variable.

• code_version(): determines a version number from a specified content string (e.g., file content) using a configurable prefix and suffix.

• get_pypi_versions(): determines all available release versions of a package on PyPI.

• project_name_version(): determine package name and version in the specified list of package/version strings.

Module Attributes

APP_PRJ	gui application project
DJANGO_PRJ	django website project
MODULE_PRJ	module portion/project
NO_PRJ	no project detected
PACKAGE_PRJ	package portion/project
PARENT_PRJ	pseudo project type for new project started in parent-dir
PLAYGROUND_PRJ	playground project
ROOT_PRJ	namespace root project
ANY_PRJ_TYPE	tuple of real project types (not including the pseudo-project-types: no-/incomplete-project and parent-folder)
ALL_PRJ_TYPES	all project types (including no/parent project)
COMMIT_MSG_FILE_NAME	name of the file containing the commit message
DEF_MAIN_BRANCH	main/develop/default branch name
PIP_CMD	pip command using python venvs, especially on Windows
PROJECT_VERSION_SEP	separates package name and version in pip req files
PYPI_ROOT_URL	PyPI cheeseshop production domain with service
PYPI_ROOT_URL_TEST	PyPI cheeseshop test domain with service
TEST_PROJECTS_PARENT_FOLDER	integration/unit tests projects local machine parent folder
TEST_PROJECTS_NAMESPACE	integration/unit tests namespace
TEST_PROJECTS_REMOTE	git remote domain of integration/unit tests projects
VERSION_QUOTE	quote character of the __version__ number variable value
VERSION_PREFIX	search string to find the __version__ variable
VERSION_MATCHER	pre-compiled regular expression to detect and change/bump the app/portion file version numbers of a version string.
TemplateProjectType	project template register info (project_templates item type)
TemplateProjectsType	project_templates var type (added by pjm/project_manager)
CachedTemplates	cache mapping of registered project templates

Functions

code_file_title(file_name)	determine docstring title of a Python code file.
code_file_version(file_name)	read version of Python code file - from __version__ module variable initialization.
code_version(content[, prefix, suffix])	determine a version number from the specified content string.
get_pypi_versions(pip_name[, pypi_test])	determine all the available release versions of a package hosted at the PyPI 'Cheese Shop'.
project_name_version(imp_or_pkg_name, ...)	determine package name and version in the specified list of package/version strings.

APP_PRJ = 'app'

gui application project

DJANGO_PRJ = 'django'

django website project

MODULE_PRJ = 'module'

module portion/project

NO_PRJ = ''

no project detected

PACKAGE_PRJ = 'package'

package portion/project

PARENT_PRJ = 'projects-parent-dir'

pseudo project type for new project started in parent-dir

PLAYGROUND_PRJ = 'playground'

playground project

ROOT_PRJ = 'namespace-root'

namespace root project

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

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

ALL_PRJ_TYPES = ('app', 'django', 'module', 'package', 'playground', 'namespace-root', '', 'projects-parent-dir')

all project types (including no/parent project)

COMMIT_MSG_FILE_NAME = '.commit_msg.txt'

name of the file containing the commit message

DEF_MAIN_BRANCH = 'develop'

main/develop/default branch name

PIP_CMD = 'pip'

pip command using python venvs, especially on Windows

PROJECT_VERSION_SEP = '=='

separates package name and version in pip req files

PYPI_ROOT_URL = 'https://pypi.org'

PyPI cheeseshop production domain with service

PYPI_ROOT_URL_TEST = 'https://test.pypi.org'

PyPI cheeseshop test domain with service

TEST_PROJECTS_PARENT_FOLDER = 'TsT'

integration/unit tests projects local machine parent folder

TEST_PROJECTS_NAMESPACE = 'aetst'

integration/unit tests namespace

TEST_PROJECTS_REMOTE = 'gitlab.com'

git remote domain of integration/unit tests projects

VERSION_QUOTE = "'"

quote character of the __version__ number variable value

VERSION_PREFIX = "__version__ = '"

search string to find the __version__ variable

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

pre-compiled regular expression to detect and change/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)).

TemplateProjectType

project template register info (project_templates item type)

alias of dict[str, str]

TemplateProjectsType

project_templates var type (added by pjm/project_manager)

alias of list[dict[str, str]]

CachedTemplates

cache mapping of registered project templates

alias of dict[str, dict[str, str]]

code_file_title(file_name)

determine docstring title of a Python code file.

Parameters:

file_name (str) – name (and optional path) of module/script file to read the docstring title number from.

Return type:

str

Returns:

docstring title string or empty string if file|docstring-title not found.

code_file_version(file_name)

read version of Python code file - from __version__ module variable initialization.

Parameters:

file_name (str) – name (and optional path) of module/script file to read the version number from.

Return type:

str

Returns:

version number string or empty string if file or version-in-file not found.

code_version(content, prefix="^__version__ = '", suffix="'")

determine a version number from the specified content string.

Parameters:

• content (Union[str, bytes]) – content of type str or bytes to be searched for the definition/declaration of a version.

• prefix (str) – version string prefix (directly before the veesion number).

• suffix (str) – version string suffix char/string (directly after the version number string). passing an empty is not allowed, and will always return an empty string.

Return type:

str

Returns:

version number string or empty string if version could not be not found in content.

get_pypi_versions(pip_name, pypi_test=None)

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

Parameters:

• pip_name (str) – pip|package|project name to get release versions from.

• pypi_test (Optional[bool]) – pass True to use the test version of PyPI (at test.pypi.org). if not specified or None then the test version of PyPI will be used if pip_name starts with the projects namespace (:data:`~aedev.base.TEST_PROJECTS_NAMESPACE), used for the pjm integration tests.

Return type:

list[str]

Returns:

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

Note

if the OS environment variable PIP_INDEX_URL is set, then its value is used instead of pypi.org.

project_name_version(imp_or_pkg_name, packages_versions)

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

Parameters:

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

• packages_versions (Iterable[str]) – an Iterable with project package name and optional version strings, like specified in requirements.txt files (format: <project_name>[<PROJECT_VERSION_SEP><project_version>]).

Return type:

tuple[str, str]

Returns:

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