The AiiDA public API has been defined in the documentation as every import that can be done from a secondary level. This is however not transparent to users and plugin developers as it is hidden in the doc resulting in a lot of misuse of private functionalities. The widespread use of these private functionalities blocks improvements in the code as we are more hesitant in changing functionalities for wrong backwards compatibility.
This PR marks clearly the internal functionalities with an underscore so a misuse only can happen intentionally. It only marks the third level of import with an underscore since any subsequent imports are automatically marked as internal. This gives us the opportunity to improve the public API as we can implement replacements for functionalities in the private API that are widely used.
from aiida import load_profile # OK, top-level import
from aiida.orm import QueryBuilder # OK, second-level import
from aiida.tools._importexport import Archive # NOT PUBLIC API
The AiiDA public API has been defined in the documentation as every import that can be done from a secondary level. This is however not transparent to users and plugin developers as it is hidden in the doc resulting in a lot of misuse of private functionalities. The widespread use of these private functionalities blocks improvements in the code as we are more hesitant in changing functionalities for wrong backwards compatibility.
This PR marks clearly the internal functionalities with an underscore so a misuse only can happen intentionally. It only marks the third level of import with an underscore since any subsequent imports are automatically marked as internal. This gives us the opportunity to improve the public API as we can implement replacements for functionalities in the private API that are widely used.
This means the public API example changes to
EDIT: Need to adapt imports in tests, and docs