Use __all__ in every public module to control which names are exported

[federicobond]

[gruebel]

Question regarding the expectations here. Do you just want to expose all the current files/modules as is or hide in which file they actually reside.

Ex.

from openfeature import api
from openfeature.client import OpenFeatureClient
from openfeature.provider.in_memory_provider import InMemoryFlag, InMemoryProvider

or this

from openfeature import api
from openfeature import OpenFeatureClient
from openfeature.provider import InMemoryFlag, InMemoryProvider

[federicobond]

There is room to keep improving the public module hierarchy. The only thing we should avoid is making multiple releases with breaking changes. If we are going to make changes on this then we should bundle all of them together in a single release so that users only have to migrate once.

My current thinking is that we should use __all__ to control visibility within public modules, to avoid re-exporting imports and such; and we should use underscore-prefixed modules for hiding internal structure, either using _internal modules or splitting files into multiple internal prefixed modules that get imported by a single public one.

For a good reference on this check out how the opentelemetry-python SDK does it.

As for your specific question, I don't have a strong preference either way for the OpenFeatureClient import, but the InMemoryProvider one is probably more idiomatic as openfeature.provider.in_memory. It makes sense to separate providers into multiple modules to avoid parsing/loading unused providers.

[federicobond]

What I have said is not established convention, just my own curated best practices from years of working with Python. Feel free to suggest alternatives.

[federicobond]

One big issue with the current module hierarchy is that the API is commonly imported as:

from openfeature import api

Or worse:

from openfeature.api import set_provider

Neither of these names (api, set_provider) give any indication as to what they belong to, if you find them in the middle of a long file. A more pythonic approach would be to be able to import them like this:

import openfeature

openfeature.set_provider(provider)

Or, if you want:

import openfeature as of

of.set_provider()

[gruebel]

Typically I prefer to expose the most important ones directly at the root level of the package and less frequent used ones through the their sub namespace. But I think your suggestion can't be implemented, because openfeature is a namespace package and therefore you can't set __all__ in the __init__.py. For the sub namespaces it is no problem, but the root won't work sadly.

[federicobond]

Yeah, I remember now that's the reason we didn't do it before.

I think a good step forward would be to compile a list of suggestions for improving the public package structure and then do these changes all in one go.

[beeme1mr]

Hey @federicobond, can this be closed now?

[gruebel]

Yeah, this is done 😄