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.
__all__
Background: Commit 2da9088 moved configure_nsswitch_database to another module. This caused ansible-freeipa to break very late in the current release cycle.
configure_nsswitch_database
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:
ipaclient.install.client ipaclient.install.ipachangeconf ipalib ipalib.config ipalib.constants ipalib.install.kinit ipalib.krb_utils ipalib.rpc ipalib.util ipaplatform.debian.paths ipaplatform.debian.tasks ipaplatform.fedora.paths ipaplatform.fedora.tasks ipaplatform.rhel.paths ipaplatform.rhel.tasks ipapython.admintool ipapython.certdb ipapython.dn ipapython.dnsutil ipapython.ipa_log_manager ipapython.ipautil ipapython.version ipaserver.install.dogtaginstance ipaserver.install.installutils ipaserver.install.replication ipaserver.install.server.install ipaserver.install.server.replicainstall ipaserver.install.service ipaserver.masters
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.
Login to comment on this ticket.