Guidelines for python requirements

[LecrisUT]

Summary

When packaging an ansible collection/role, there currently is no standard way of specifying python requirements, primarily the hard requirements of plugins. Some people use requirements.txt, but there is no standard guidelines for role and collection authors that I could find. It would be nice to have this documented and discussed somewhere.

Issue Type

Documentation Report

Component Name

N/A

Ansible Version

N/A

Configuration

N/A

OS / Environment

N/A

Additional Information

Here is my consideration of possible standards

Using requirements.txt

Pros

• Currently a popular approach
• Does not leave a python footprint, e.g. a package name with .egg files

Cons

• It is not standardized what are build/test/module requirements
• Only python dependencies

Using python metadata

Pros

• Current standard for python projects
• Can specify separate build/test/module requirements, e.g.:
  • build-system.requires for any build requirements, e.g. in ansible-galaxy collection build and equivalents
  • project.dependenceis for local runtime requirements, i.e. plugin requirements
  • project.optional-dependencies.test, etc. for ansible test. Naming not standardized, but it is not that much of an issue
  • project.optional-dependencies.local-runner, project.optional-dependencies.moduleA, or some other format. For dependencies of running a particular runner or module. Does not have to be standardized, just mentioned as a good practice

Cons

• Python footprint, e.g. must avoid name-clash. Not that severe since some projects already have a setup.py configuration and they use sensible namespacing
• Only python dependencies

galaxy.yaml

Pros

• Already standardized

Cons

• Only handles ansible dependencies

This could be expanded though to include:

• system_requirements: for system, packages, library and executable requirements
• python_requirements: for python package requirements

Maybe we could use a similar format like PEP621 to separate them logically by usage

In documentation

Pros

• Widely used for system requirements

Cons

• Not standardized
• Hard to separate system/python requirements and logical

Code of Conduct

• I agree to follow the Ansible Code of Conduct

[ansibot]

Files identified in the description:

• lib/ansible/cli/__init__.py

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

[bcoca]

yes, this is something we have been debating for a long time, ansible-builder has such a feature

[sivel]

ansible-builder info: https://ansible-builder.readthedocs.io/en/stable/collection_metadata/

ansible-core will never provide a means for automatically installing deps from a file like the above, because the variations are too extensive, but when including a collection in an execution environment, ansible-builder allows for a collection to indicate these deps.

[LecrisUT]

Thanks, I was not considering automatically installing deps, I was just considering making the ansible collections more accessible to modern Fedora packaging guidelines. The tools for packaging python have come a long way that it has become trivial to maintain them due to PEP621 and such. I just hope we can make ansible collection just as accessible with such a guideline.

[LecrisUT]

Also, just so that we are on the same page, this refers to dependencies of the controller, not of the environments where the modules are executed on.

[sivel]

That is correct, packaging of a collection wouldn't want to install target deps anyway, since the collection is installed on a controller, and not on a target.

One thing we've talked about before is that collection authors could create a bootstrapping playbook, that could be used to install target deps, if it aligns with the means that the user wants to install said deps. But that would not help with packaging.

Target deps, being so disconnected from controller deps, as targets do not even have to be the same OS or OS version, cannot reasonably be handled with an OS package of a collection.

[bcoca]

Controller deps would be only guaranteed for plugins. Modules really should not for 2 reasons, they might/might not execute on the controller and they might/might not be written in python or have non python deps.

[samccann]

Thanks @LecrisUT and others for the details here.The discussion is happening at ansible-community/community-topics#224 as it's bigger than just a docs update. Closing this issue in favor of the broader discussion issue. Once that discussion comes to consensus, we can open another docs issue with the exact docs needed.