Method function signatures changing in v1.0

[jwodder]

In versioningit, the methods for carrying out steps are implemented as functions — potentially user-defined — that take a step-specific set of arguments plus a collection of parameters supplied in the user configuration (usually the respective table in pyproject.toml). In the current v0.x series, these user parameters are passed as keyword arguments to the functions; e.g., the arguments signature for VCS methods is of the form:

(*, project_dir: Union[str, pathlib.Path], **params: Any)

I have since realized that passing user parameters this way is silly and creates more problems than it solves. As a result, the way that user parameters are passed to method functions will change in the upcoming v1.0.0 release. Parameters will now be passed as a dict supplied as a single params keyword argument; e.g., for VCS methods, the arguments signature becomes:

(*, project_dir: Union[str, pathlib.Path], params: Dict[str, Any])

Reasons for this change include:

• With the v0.x signatures, it was impossible for user parameters to include fields with the same names as step-specific arguments; e.g., if a [tool.versioningit.vcs] table contained a project_dir key, that key had to be discarded. With the upcoming signature change, this restriction is lifted.

• As far as I can recall/determine, the only benefit of the v0.x signatures was that they allowed method functions to receive select user parameters as direct function arguments, but this can't work for all parameters, as TOML keys with hyphens in them (a common usecase) are invalid as Python identifiers.

This change affects the following types of Python projects:

• Projects that define their own custom versioningit methods

• Extension packages that provide custom versioningit methods

• Projects that use custom extension packages that provide custom versioningit methods

Searching for such projects on GitHub and elsewhere turns up no results, which suggests that no one will notice this change, but I cannot rule out the possibility of private repositories using this feature. As long as such projects put a <1.0 or similar restriction on their versioningit dependencies and consult the CHANGELOG before updating for v1.0, nothing should break.