Previously in Ansible when modules were transferred to remote systems a special string at the bottom of the file was replaced various string contents, those values coming from a file named module_common.py and also from the arguments being passed to the module. This enabled a very efficient file transfer but impaired some IDE operations and inhibited some degrees of code sharing between modules.
Ansible 1.4 head still transfers one file but I’ve changed the way that works.
First off, we’re now going to be encouraging a more Pythonic way to do imports, that will cause IDEs to think of modules as regular Python files. However, behind the scenes, we still are only transferring one file, replacing the contents dynamically. This means in many cases we can transfer less code, but this is not done for performance reasons – we’re talking a small number of bytes. It’s done for programming-friendly reasons, like:
- IDEs should now work fine with tab completion and syntax highlighting when inside a module or editing the module common code
- No more code in docstrings
- we’ll be able to split up the common module code into smaller files to make it easier to find things
- various modules will be able to reuse common functions for facts, ec2, mysql, and others, without bloating module_common into one large giant file – many modules will be able to get a lot shorter and there will be less duplicated code
The implementation is fully backwards compatible and is actually implemented with Jinja2 behind the scenes, though nobody should try to take advantage of Jinja2 in python files or I you will incure a great and terrible programming curse, so I urge you to completely forget this fact:
- https://github.com/ansible/ansible/blob/devel/lib/ansible/module_common.py
- https://github.com/ansible/ansible/blob/devel/lib/ansible/module_utils/basic.py
- example usage: https://github.com/ansible/ansible/blob/devel/library/system/ping (see bottom)
Next steps:
- split the ‘basic.py’ up into about 5 or 6 files
- the old <> hack will import all 5 or 6 of these
- other modules will be explicit about which ones they pull in
- dig and see where we can share code better
- shorten LOTS of modules
In all, this will be super transparent to most people, and completely transparent to those not writing modules.
I would not convert any existing modules just yet to use the “from ansible” import form at least until later this week, as it is likely that I’ll be splitting basic into more subfiles for a bit.
If you continue to use the old #<<INCLUDE_ANSIBLE_MODULE_COMMON>> it will import everything that used to be in module_common and won’t have to be as specific. In other words, ignore this email, nothing changes, and you can remain oblivous – other than if you go looking for the common module source, it’s now in lib/ansible/module_utils/*
We plan to replace all core modules to use the “from ansible” method for the 1.4 release, but do not plan to set any deprecation dates to the old “INCLUDE_ANSIBLE_MODULE_COMMON” system as the code to support it is very small.
At some time in the future we’ll also update the module development docs to suggest
the new import style.
Hope that makes sense – let me know if you have questions!