Add python packaging approaches

[ninad-kamat]

Add some guidance or documentation about various approaches to python packaging that cover PEP517 and PEP518.

[da1910]

I've been working with the new PEP518 based project format for grantami-bomanalytics and openapi-common, and I've come across a few things that would be worth mentioning in this section:

File: and Attr: directives

New-style setup.cfg based projects have added limited support for statically extracting variables from other python files. This means that many of the existing ways to extract a version number into the package definition.

For example, if the version number is a module level variable that is defined somewhere as a literal you can do:
version = attr: ansys.<PRODUCT>.__version__

This extends to README files and LICENSE files for the setup.cfg description and long_description fields, you can include these directly by doing:
long_description = file: README.md, LICENSE

Dependabot and setup.cfg requirements

Dependabot is extremely helpful to automatically monitor package dependencies and suggest updates for security vulnerabilities, it supports a wide range of languages, including python. Unfortunately it does not currently support parsing the install_requires field of setup.cfg based projects.

For the openapi-common project I've put together a git hook and python script that scrapes these values and generates requirements.txt files that can be monitored, feel free to reuse them if they're helpful. In our case it makes sense to generate them, since we are exclusively a library, I imagine that applications would want to manually manage both the install_requires field and the requirements.txt file to pin specific tested dependency versions.

Tox

At the moment any tox configuration must be done as a string within the pyproject.toml file, this is a bit messy, and we are promised that there will be integration into setup.cfg soon.

[greschd]

New-style setup.cfg based projects have added limited support for statically extracting variables from other python files. This means that many of the existing ways to extract a version number into the package definition.

Just as a quick comment, the limitations of the attrs: command are discussed here: pypa/setuptools#1724
I'll have to re-read the discussion to condense it into advice we can put into the dev docs.

[greschd]

Short summary regarding the attr: directive:

If the module is importable during build time, the attr: <something>.__version__ directive should just work.

If it is not (for example, because import fails when some dependencies are not yet installed), there are two options:

• setuptools implements a "rudimentary AST analysis" to get the attribute without actually importing the module. This should work when the top-level __ini__.py contains a statement __version__ = "x.y.z". There is some confusion about other cases where this might or might not work.
• if the version is defined in a separate file (e.g. _version.py), and that is imported before any of the missing dependencies, the attr: directive will also work. However, this is more or less an accident of the implementation, as detailed here.

[jorgepiloto]

This was implemented in PR #44 and enhanced in PR #69.

Ideally, all build system backends should be compliant with PEP 621.

This topic is discussed in the Build System section. Templates for setup.py and pyproject.toml have been provided too.