FreeIPA should use __all__ to mark objects that are considered exported and used by ansible-freeipa. This will make it more obvious which functions and attributes are used by ansible-freeipa and reduce the likelihood of breaking ansible-freeipa.
Background: Commit 2da9088 moved configure_nsswitch_database to another module. This caused ansible-freeipa to break very late in the current release cycle.
The module global variable __all__ is used for * imports and as a marker for attributes that can be considered as exported. __all__ makes it more obvious which module members are used outside of FreeIPA and by ansible-freeipa. The variable a tuple of attribute names, e.g. __all__ = ('api', ). If an attribute is not define pylint will complain with an error like ipalib/__init__.py:885: [E0603(undefined-all-variable), ] Undefined variable name 'foo' in __all__).
__all__ = ('api', )
ipalib/__init__.py:885: [E0603(undefined-all-variable), ] Undefined variable name 'foo' in __all__)
A quick search over ansible-freeipa code base revealed imports of these modules:
The task is to identify all used members and to add them to __all__ of these modules.
The __all__ approach doesn't help when a function signature is changed. The next step after __all__ is to record all function signatures and object attributes and write a checker for that. Perhaps it is possible to utilize mypy and type checkers?
@cheimes writing down the types and checking them would be a great start. But if the goal is to not break the API used by ansible-freeipa (or whatever else), we also need some processes around that.
But yeah, step 1 is __all__, step 2 is mypy, step 3 is rules about how and when types may be changed.
to comment on this ticket.