Open Stack

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.

++

>