Cantera needlessly exports external/built-in modules and functions

[ischoegl]

Cantera version

2.4.0 / 2.5.0a

Operating System

all

Python/MATLAB version

all Python

Expected Behavior

External (and built-in) modules should not be added to the cantera package as they are not part of cantera, e.g. numpy, math, os, sys, weakref, erf, warnings, appdelete, ...
While they are obviously required internally, they should not necessarily be exposed (can be avoided by defining __all__ in modules where cantera objects/functions are defined, so the from <> import * in __init__.py will only include what needs to be exposed).

Actual Behavior

cantera.np is numpy (external project), cantera.math is math (built-in), etc.
While this is admittedly a minor issue, it conflicts with PEP 423 as it obfuscates the origin of modules (np), and needlessly creates an additional level.

Steps to reproduce

1. import cantera as ct
2. dir(ct) includes both cantera and non-cantera modules

[speth]

The referenced PEP has a status of "deferred" and depends on another PEP (426) whose status is "withdrawn", so I don't think adherence to this PEP has much weight.

Furthermore, this behavior is also seen in plenty of other modules. For example, numpy imports math, sys, and warnings. It also occurs within the standard library, e.g. pickle imports io, re, and sys.

[ischoegl]

It only involves a couple of lines of code and would create a cleaner interface. I can fork, implement and create a pull request if the effort is supported.

[bryanwweber]

@ischg I don't actually see where PEP 423 recommends against the behavior that Cantera is doing here. Can you provide a link to the section? As @speth said, many other much bigger libraries (and things from the standard library!) do exactly what Cantera does.

The problem with this change (and I was a bit hasty in adding the "help-wanted" tag) is that now we have to add a line to the __all__ object any time something new is added so that it is exported properly. That's an extra burden for people modifying the code who may not be that familiar with how Python works and just want to test their modification.

[ischoegl]

@bryanwweber ok. not a problem. PEP 423 advocates against deep nesting, where in this case there isn't even a real reason. The PEP also recommends the use of standard patterns for community projects, which implies that they shouldn't be renamed using an alias. This admittedly does not affect the performance of the code in any way, but ultimately falls back to PEP 20 ... which at the same time could be interpreted as a reason to close this issue ;)

[speth]

Right, the issue that Bryan mentions of needing to maintain __all__ is part of what I would like to avoid. The other issues with PEP 423 notwithstanding, I think the interpretation of its guidance about nesting is not about how and where we import packages that we use, but how the contents of the Cantera package itself are structured. For example, this is a recommendation against putting things in nested namespaces like cantera.kinetics.reactions.Arrhenius rather than just cantera.Arrhenius.

There are certainly things to be said for keeping an interface clean, but at the same time, I don't really expect dir(cantera) to be the way that people usually learn about what functionality Cantera provides.