On 09/30/2015 03:15 PM, Ryan Brown wrote:
On 09/30/2015 04:08 AM, Dougal Matthews wrote:
Hi,
What is the standard practice for defining public API's for OpenStack
libraries? As I am working on refactoring and updating tripleo-common
I have
to grep through the projects I know that use it to make sure I don't
break
anything.
The API working group exists, but they focus on REST APIs so they don't
have any guidelines on library APIs.
Personally I would choose to have a policy of "If it is documented, it is
public" because that is very clear and it still allows us to do internal
refactoring.
Otherwise we could use __all__ to define what is public in each file, or
assume everything that doesn't start with an underscore is public.
I think assuming that anything without a leading underscore is public
might be too broad. For example, that would make all of libutils
ostensibly a "stable" interface. I don't think that's what we want,
especially this early in the lifecycle.
In heatclient, we present "heatclient.client" and "heatclient.exc"
modules as the main public API, and put versioned implementations in
modules.
I'd recommend to avoid things like 'heatclient.client', as in a big
application it would lead to imports like
from heatclient import client as heatclient
:)
What I did for ironic-inspector-client was to make a couple of most
important things available directly on ironic_inspector_client top-level
module, everything else - under ironic_inspector_client.v1 (modulo some
legacy).
heatclient
|- client
|- exc
\- v1
|- client
|- resources
|- events
|- services
I think versioning the public API is the way to go, since it will make
it easier to maintain backwards compatibility while new needs/uses evolve.
++
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
