Re: [openstack-dev] [TripleO] Defining a public API for tripleo-common
On 09/30/2015 10: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. 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. Cheers, Dougal Hi, my preference would be to follow the same approach which is used in oslo libraries (I think these libs should be take as a best practice example if possible). And oslo libs AFAIK use the last of your options. But if there is a plan to build some thin REST API layer on top if it, I think that versioning will be necessary. So I would lean to the default underscore convention in versioned directory structure :). Jan __ 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
Re: [openstack-dev] [TripleO] Defining a public API for tripleo-common
On 2015-09-30 01:08, 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. > > 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. The last is the accepted Python convention: https://docs.python.org/2/tutorial/classes.html#private-variables-and-class-local-references and is in common use in other OpenStack libraries. It also integrates properly with things like automatic api docs from sphinx. I'd be -1 on pretty much any other approach. __ 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
Re: [openstack-dev] [TripleO] Defining a public API for tripleo-common
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
Re: [openstack-dev] [TripleO] Defining a public API for tripleo-common
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. 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. -- Ryan Brown / Senior Software Engineer, Openstack / Red Hat, Inc. __ 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
[openstack-dev] [TripleO] Defining a public API for tripleo-common
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. 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. Cheers, Dougal __ 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
