Open Stack

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 at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>