We've been too lax about delineating public and internal interfaces in python-keystoneclient. This makes changes and reviews difficult because we don't know what we can change without breaking applications. For example, we thought we could rename a part, but then it broke somebody (Horizon?)[0].
We've got a lot of changes we'd like to make to the python-keystoneclient to share authentication, so this problem is only going to get worse if we don't get it under control. We don't have to come up with a convention for public/internal because PEP8 defines it for us[1], and we're supposedly enforcing PEP8. If we were to strictly interpret python-keystoneclient against PEP8 then everything would be internal because the keystoneclient package and everything in it is internal since it has no docs. If we consider the usage doc in doc/source[2] as public documentation, then there's a few classes and packages that could be considered public, too. Since we're in undefined territory here, I think we need to be more conservative. A very conservative approach would be to just consider everything in keystoneclient to be public unless it's explicitly internal (prefixed with _ or it's documentation says it's internal). This essentially makes everything but a few internal methods public. We don't want everything to be public because changes will be more difficult to make than it should be. I propose that we bring keystoneclient into compliance with PEP8. Let's start assuming everything is public unless it's explicitly internal. Then make the following changes: 0) Rename all those things that should be internal to prefix with _, while preserving backwards compatibility by leaving the old symbol there marked as deprecated. 1) Document public APIs with docstrings. 2) Change modules to explicitly declare public APIs in __all__. This will be in a point release. Then in the next major release we yank out the deprecated function. [0] https://bugs.launchpad.net/python-keystoneclient/+bug/1211998 [1] http://www.python.org/dev/peps/pep-0008/#public-and-internal-interfaces [2] https://github.com/openstack/python-keystoneclient/blob/master/doc/source/using-api.rst - Brant
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
