Introduce single module, e.g. watertap.api, from where all public objects should be imported

[lbianchi-lbl]

Just an idea following the discussions in #995. This would be similar to (AFAIK) pyomo.environ.

Some misc thoughts:

• This would also be a good and unambiguous way of defining what the "WaterTAP API" is, for things like e.g. checking backward-compatibility
• As this implies a flattening of the WaterTAP namespaces, we'd need to figure out how to handle cases where more than one objects among the ones we want to expose have the same name

[wigging]

I have many many many comments about this. But my main suggestion is stop looking at IDAES and Pyomo for inspiration on how to design a Python package. Please look at other packages in the Python ecosystem. The only import statement that should be in users Python programs or scripts is import watertap or import watertap as wt.

[lbianchi-lbl]

I don't see these as particularly different - isn't import pandas as pd essentially the same as import watertap.api as wt?

[wigging]

What do you mean by api? I consider the interface by which you access things in a package is the api. The package itself is the api. API is application programming interface where in this context the application is the Python package.

[lbianchi-lbl]

mypackage.api is just a convention (AFAIK fairly popular for Python projects, although it's a bit tricky to search for if you want to have concrete examples) for "having a submodule of the top-level package from where the code should be imported". The same can be accomplished with just using mypackage as the "one-stop module", but this has (mostly implementation-related) tradeoffs:

• Any code in mypackage is always executed when importing submodules, which can e.g. impact performance (the reason why import pandas as pd is noticeably slow)
• It precludes (modulo nonstandard import hacks) having mypackage as a namespace package, which is something we'd like to enable at some point for WaterTAP as this would allow us to have contributing packages be accessible from the watertap namespace even if they're distributed separately from the watertap Python distribution.

[wigging]

For any well designed package, you should be able to import mypackage as mp to import the package and access all of its modules, subpackages, etc. in that package. You should also be able to from mypackage import subpackage or from mypackage import module to access a particular component in that package that you want to use. Does the current version of watertap support both of these approaches?

[wigging]

Also, doing something like import package or from package import module or from package.module import obj will import the entire package even if you are only importing a single thing from that package. All of these approaches execute the entire package even if you only use one piece of the package.