aedev.setup_project

project setup helper functions

this portion of the aedev namespace is providing constants and helper functions to install/setup Python projects of applications, modules, packages, namespace portions and their root packages via the setuptools.setup() function.

the function project_env_vars() is analyzing a Python project and is providing the project properties as a dict of project environment variable values.

the main goal of this project analysis is to:

ease the setup process of Python projects,

replace additional setup tools like e.g. pipx or poetry and

eliminate or at least minimize redundancies of the project properties, stored in the project files like setup.py, setup.cfg, pyproject.toml, …

e.g. if you have to change the short description/title or the version number of a project you only need to edit them in one single place of your project. after that, the changed project property value will be automatically propagated/used in the next setup process.

basic helper functions

while code_file_version() determines the current version of any type of Python code file, code_file_title() does the same for the title of the code file’s docstring.

package data resources of a project can be determined by calling the function find_package_data(). the return value can directly be passed to the package_data item of the kwargs passed to setuptools.setup().

an optional namespace of a package gets determined and returned as string by the function namespace_guess().

determine project environment variable values

the function project_env_vars() inspects the folder of a Python project to generate a complete mapping of environment variables representing project properties like e.g. names, ids, urls, file paths, versions or the content of the readme file.

if the current working directory is the root directory of a Python project to analyze then it can be called without specifying any arguments:

pev = project_env_vars()

to analyze a project in any other directory specify the path in the project_path argument:

pev = project_env_vars(project_path='path/to/project_or_parent')

..note::: if project_env_vars() gets called from within of your setup.py file, then a True value has to be passed to the keyword argument from_setup.

the project property values can be retrieved from the returned dictionary (the pev variable) either via the function pev_str() (only for string values), the function pev_val() or directly via getitem. the following example is retrieving a string reflecting the name of the project package:

project_name = pev_str(pev, 'project_name')

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

if the current or specified directory to analyze is the parent directory of your projects (and is defined in PARENT_FOLDERS) then the mapped project type key will contain the special pseudo value PARENT_PRJ, which gets recognized by the aedev.git_repo_manager development tools e.g. for the creation of a new projects and the bulk processing of multiple projects or the portions of a namespace.

other useful properties in the pev mapping dictionary for real projects are e.g. ‘project_version’ (determined e.g. from the __version__ module variable), ‘repo_root’ (the url prefix to the remote/origin repositories host), or ‘setup_kwargs’ (the keyword arguments passed to the setuptools.setup() function).

Hint

for a complete list of all available project environment variables check either the code of this module or the content of the returned pev variable (the latter can be done alternatively e.g. by running the grm tool with the command line options -v, -D and the command line argument show-status).

configure individual project environment variable values

the default values of project environment variables provided by this module are optimized for an easy maintenance of namespace portions like e.g. aedev and ae.

individual project environment variable values can be configured via the two files pev.defaults and pev.updates, which are situated in the working tree root folder of a project. the content of these files will be parsed by the built-in function ast.literal_eval() and has to result in a dict value. only the project environment variables that differ from the pev variable value have to be specified.

an existing pev.defaults is changing project environment variable default values which may affect other pev variables. e.g. to change the value of the author’s name project environment variable STK_AUTHOR, the content of the file pev.defaults would look like:

{'STK_AUTHOR': "My Author Name"}

changing the default value of the STK_AUTHOR variable results that the variable setup_kwargs['author'] will also have the value "My Author Name".

in contrary the file pev.updates gets processed at the very end of the initialization of the project environment variables and the specified values get merged into the project environment variables with the help of the function ae.base.deep_dict_update(). therefore, putting the content from the last example into pev.updates will only affect the variable STK_AUTHOR, whereas setup_kwargs['author'] will be left unchanged.

Hint

if code has to be executed to calculate an individual value of a project environment variable you have to modify the variable pev directly in your project’s setup.py file. this can be achieved by either, providing a setup-hook module or by directly patching the pev variable, like shown in the following example:

from aedev.setup_project import project_env_vars

pev = project_env_vars(from_setup=True)
pev['STK_AUTHOR'] = "My Author Name"
...

Module Attributes

`APP_PRJ`	gui application project
`DJANGO_PRJ`	django website project
`MODULE_PRJ`	module portion/project
`PACKAGE_PRJ`	package portion/project
`PARENT_PRJ`	pseudo project type for new project started in parent-dir
`ROOT_PRJ`	namespace root project
`NO_PRJ`	no project detected
`DOCS_HOST_PROTOCOL`	documentation host connection protocol
`DOCS_DOMAIN`	documentation dns domain
`DOCS_SUB_DOMAIN`	doc sub domain; def: namespace\|package+REPO_GROUP_SUFFIX
`PARENT_FOLDERS`	names of parent folders containing Python project directories
`PYPI_PROJECT_ROOT`	PYPI projects root url
`MINIMUM_PYTHON_VERSION`	minimum version of the Python/CPython runtime
`REPO_HOST_PROTOCOL`	repo host connection protocol
`REPO_CODE_DOMAIN`	code repository dns domain (gitlab.com\|github.com)
`REPO_PAGES_DOMAIN`	repository pages internet/dns domain
`REPO_GROUP`	repo users group name; def=namespace\|package+REPO_GROUP_SUFFIX
`REPO_GROUP_SUFFIX`	repo users group name suffix (only used if REPO_GROUP is empty)
`REQ_FILE_NAME`	requirements default file name
`REQ_DEV_FILE_NAME`	default file name for development/template requirements
`STK_AUTHOR`	project author name default
`STK_AUTHOR_EMAIL`	project author email default
`STK_LICENSE`	project license default
`STK_CLASSIFIERS`	project classifiers defaults
`STK_PYTHON_REQUIRES`	default required Python version of project
`VERSION_QUOTE`	quote character of the __version__ number variable value
`VERSION_PREFIX`	search string to find the __version__ variable
`DataFilesType`	setup_kwargs['data_files']
`PackageDataType`	setup_kwargs['package_data']
`SetupKwargsType`	setuptools.setup()-kwargs
`PevVarType`	single project environment variable
`PevType`	project env vars mapping

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)	read version of content string of a Python code file.
`find_package_data`(package_path)	find doc, template, kv, i18n translation text, image and sound files of an app or (namespace portion) package.
`namespace_guess`(project_path)	guess name of namespace name from the package/app/project root directory path.
`pev_str`(pev, var_name)	string value of project environment variable `var_name` of `pev`.
`pev_val`(pev, var_name)	determine value of project environment variable from passed pev or use module constant value as default.
`project_env_vars`([project_path, from_setup])	analyse and map the development environment of a package-/app-project into a dict of project property values.

APP_PRJ = 'app': gui application project

DJANGO_PRJ = 'django': django website project

MODULE_PRJ = 'module': module portion/project

PACKAGE_PRJ = 'package': package portion/project

PARENT_PRJ = 'projects-parent-dir': pseudo project type for new project started in parent-dir

ROOT_PRJ = 'namespace-root': namespace root project

NO_PRJ = '': no project detected

DOCS_HOST_PROTOCOL = 'https://': documentation host connection protocol

DOCS_DOMAIN = 'readthedocs.io': documentation dns domain

DOCS_SUB_DOMAIN = '': doc sub domain; def: namespace|package+REPO_GROUP_SUFFIX

PARENT_FOLDERS = ('Projects', 'PycharmProjects', 'esc', 'old_src', 'projects', 'repo', 'repos', 'source', 'src', 'docs'): names of parent folders containing Python project directories

PYPI_PROJECT_ROOT = 'https://pypi.org/project': PYPI projects root url

MINIMUM_PYTHON_VERSION = '3.9': minimum version of the Python/CPython runtime

REPO_HOST_PROTOCOL = 'https://': repo host connection protocol

REPO_CODE_DOMAIN = 'gitlab.com': code repository dns domain (gitlab.com|github.com)

REPO_PAGES_DOMAIN = 'gitlab.io': repository pages internet/dns domain

REPO_GROUP = '': repo users group name; def=namespace|package+REPO_GROUP_SUFFIX

REPO_GROUP_SUFFIX = '-group': repo users group name suffix (only used if REPO_GROUP is empty)

REQ_FILE_NAME = 'requirements.txt': requirements default file name

REQ_DEV_FILE_NAME = 'dev_requirements.txt': default file name for development/template requirements

STK_AUTHOR = 'AndiEcker': project author name default

STK_AUTHOR_EMAIL = 'aecker2@gmail.com': project author email default

STK_LICENSE = 'OSI Approved :: GNU General Public License v3 or later (GPLv3+)': project license default

STK_CLASSIFIERS = ['Development Status :: 3 - Alpha', 'License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)', 'Natural Language :: English', 'Operating System :: OS Independent', 'Programming Language :: Python', 'Programming Language :: Python :: 3', 'Programming Language :: Python :: 3.9', 'Topic :: Software Development :: Libraries :: Python Modules']: project classifiers defaults

STK_PYTHON_REQUIRES = '>=3.9': default required Python version of project

VERSION_QUOTE = "'": quote character of the __version__ number variable value

VERSION_PREFIX = "__version__ = '": search string to find the __version__ variable

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]

PevVarType

single project environment variable

alias of str | Sequence[str] | List[Tuple[str, Tuple[str, …]]] | Dict[str, Any]

PevType

project env vars mapping

alias of Dict[str, str | Sequence[str] | List[Tuple[str, Tuple[str, …]]] | Dict[str, Any]]

_compile_remote_vars(pev)[source]

_compile_setup_kwargs(pev)[source]

add setup kwargs from pev values, if not set in setup.cfg.

Parameters:: pev¶ (Dict[str, Union[str, Sequence[str], List[Tuple[str, Tuple[str, ...]]], Dict[str, Any]]]) – dict of project environment variables with a ‘setup_kwargs’ dict to update/complete.

optional setup_kwargs for native/implicit namespace packages are e.g. namespace_packages. adding to setup_kwargs include_package_data=True results in NOT including package resources into sdist (if no MANIFEST.in file is used).

_init_defaults(project_path)[source]

Return type:: Dict[str, Union[str, Sequence[str], List[Tuple[str, Tuple[str, ...]]], Dict[str, Any]]]

_init_pev(project_path)[source]

Return type:: Dict[str, Union[str, Sequence[str], List[Tuple[str, Tuple[str, ...]]], Dict[str, Any]]]

_load_descriptions(pev)[source]

load long description from the README file of the project.

Parameters:: pev¶ (Dict[str, Union[str, Sequence[str], List[Tuple[str, Tuple[str, ...]]], Dict[str, Any]]]) – dict of project environment variables with a ‘project_path’ key.

_load_requirements(pev)[source]

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

Parameters:

pev¶ (Dict[str, Union[str, Sequence[str], List[Tuple[str, Tuple[str, ...]]], Dict[str, Any]]]) –

dict of project environment variables with the following required project env 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_require, docs_require, install_require, portions_packages, setup_require, tests_require.

code_file_title(file_name)[source]

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)[source]

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)[source]

read version of content string of a Python code file.

Parameters:: content¶ (Union[str, bytes]) – content of a code file, possibly containing the declaration of a __version__ variable.
Return type:: str
Returns:: version number string or empty string if file or version-in-file not found.

find_package_data(package_path)[source]

find doc, template, kv, i18n translation text, image and sound files of an app or (namespace portion) package.

Parameters:: package_path¶ (str) – path of the root folder to collect from: project root for most projects or the package subdir (project_path/namespace_name(s)…/portion_name) for namespace projects.
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 BUILD_CONFIG_FILE 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.

namespace_guess(project_path)[source]

guess name of namespace name from the package/app/project root directory path.

Parameters:: project_path¶ (str) – path to project root folder.
Return type:: str
Returns:: namespace import name of the project specified via the project root directory path.

pev_str(pev, var_name)[source]

string value of project environment variable var_name of pev.

Parameters:

pev¶ (Dict[str, Union[str, Sequence[str], List[Tuple[str, Tuple[str, ...]]], Dict[str, Any]]]) – project environment variables dict.
var_name¶ (str) – name of variable.

Return type:

str

Returns:

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

Raises:

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

Hint

the str type annotation of the return value makes mypy happy. additional the constant’s values of this module will be taken into account. replaces cast(str, pev.get(‘namespace_name’, globals().get(var_name, “”))).

pev_val(pev, var_name)[source]

determine value of project environment variable from passed pev or use module constant value as default.

Parameters:

pev¶ (Dict[str, Union[str, Sequence[str], List[Tuple[str, Tuple[str, ...]]], Dict[str, Any]]]) – project environment variables dict.
var_name¶ (str) – name of the variable to determine the value of.

Return type:

Union[str, Sequence[str], List[Tuple[str, Tuple[str, ...]]], Dict[str, Any]]

Returns:

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

project_env_vars(project_path='', from_setup=False)[source]

analyse and map the development environment of a package-/app-project into a dict of project property values.

Parameters:

project_path¶ (str) – optional rel/abs path of the package/app/project working tree root directory of a new or an existing project (default=current working directory).
from_setup¶ (bool) – pass True if this function get called from within the setup.py module of your project.

Return type:

Dict[str, Union[str, Sequence[str], List[Tuple[str, Tuple[str, ...]]], Dict[str, Any]]]

Returns:

dict/mapping with the determined project environment variable values.