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