Open Stack

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130820/4f8e5ae8/attachment.html>