Explicitly declare supported public APIs with '__all__'

[sungwy]

Feature Request / Improvement

Currently, we rely on the informal naming conventions (with or without underscore) to distinguish between a public or private API.

It will be helpful to declare the names of public APIs in the __all__ attribute on all our public API supporting modules as it will:

• control what APIs we expose to wildcard imports
• enhance discoverability of public APIs (when reading the source code as users or developers)
• and allow tools like Griffe to detect the correct public APIs for backwards compatibility analysis in our CI

[ndrluis]

@sungwy I created a document with the idea to discuss and make it easier for other contributors to help us with this task. I added an example of the table module/class, but before we start defining it, I believe we need to discuss more about the mix of code styles we currently have. Sometimes we expose functions, and in other cases, we expose classes. It would be nice for us to define a "specification" to maintain consistency, and then we can start designing the API.

What do you think?

[sungwy]

Hey, thank you so much for starting the document! That's a great suggestion. I think reviewing our classes, functions and constants and their 'public' status by encapsulating the user workflows against specific entrypoints is the right way to move forward with this work. I left a comment on what you have worked on so far, and I'll keep reviewing the document as you continue to work on it @ndrluis