On 08/20/2013 09:26 PM, Brant Knudson wrote: > > 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__.
I think, honestly, that we need to start using __all__ in all of the client libs. I agree with everything above. > 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 > _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev