Proposal: move iris.cube.Cube to iris.Cube

[shoyer]

I find myself constructing a lot of cubes and cubelists manually when I implement new functions to manipulate cubes.

Since these are core API objects, I suggest they should be moved from iris.cube.Cube and iris.cube.CubeList to iris.Cube and iris.CubeList (via an import statement in /lib/iris/__init__.py). This would be consistent with many other Python libraries (e.g., Pandas), for which the core API is also usually exposed at the top level.

As a library user, it's just easier not to need to know about the structure of Iris's code to find a class or function. I can see a case for consolidating other functions into a broader namespace as well, but Cube and CubeList are the worse offenders (in my view). In my view, exposing submodules in a library's API should be done with caution, and only when it is clearly easier for library users.

[pelson]

I can see the benefit of doing this, but the real problem for me is documenting it. Perhaps if iris.Cube existed in our documentation and simply linked to the iris.cube.Cube documentation then that might be a way to go.

Other than that, nice suggestion - it is something that has crossed my mind more than once.

[esc24]

It's crossed my mind too. iris.Constraint comes to mind as an example where we've done it. I know shapely does this kind of thing (e.g. shapely.geometry.Polygon and shapely.geometry.polygon.Polygon). However, I find this confusing and I like namespaces. I'm wary of there not being one and only one obvious way to do it. That said, if we keep the list of top level objects to an absolute minimum I can see why it's appealing.

[shoyer]

I think the multiple paths is pretty common and unlikely to be confusing as long as the documentation keeps things straight. For example, you can also find np.array in np.core.multiarray.array.

I agree that the main challenge here is documentation, so perhaps I will leave this to those more familiar with Iris's documentation generator. It should definitely be possible to document iris.Cube and not iris.cube.Cube, since so many other packages manage to do it. The code patch will simply be adding from iris.cube import Cube, CubeList, CubeMetadata to /lib/iris/__init__.py (and adding them to the __all__ list).

[rhattersley]

The code patch will simply be adding from iris.cube import Cube, CubeList, CubeMetadata to /lib/iris/init.py (and adding them to the all list).

I was concerned about circular imports (they've bitten us before!) but I gave it a quick go and it was fine.

[bblay]

:+1: nicer code

[rcomer]

Do we still want to do this? Intuitively, it would undo some of the import speed gains from #4174.

[trexfeathers]

Do we still want to do this? Intuitively, it would undo some of the import speed gains from #4174.

It seems unlikely that this desire is limited to Cube. We've previously discussed making all commonly used API available at the top level, taking inspiration from Numpy (https://github.com/SciTools/iris/issues/3429#issuecomment-537064862).

So I don't think this can be easily dismissed, nor can it be easily completed!

[pp-mo]

@trexfeathers it would undo some of the import speed gains from #4174.

I don't think this is a practical issue in itself : If you're using Iris at all, you will be using cubes, so the additional cost of "import iris.cube" is one that every reasonable usage will get anyway. The only difference is in the "headline figure" import time : for me, that goes from ~0.1 secs to ~0.6secs.

Test timings on my machine :	imports	timing
import iris	0.1 secs
import iris.coords	0.4 secs
import iris.cube	0.7 secs
import iris.cube; import iris.coords	0.7 secs

[trexfeathers]

Part of a larger conversation:

• 4710

• 4798

[github-actions[bot]]

In order to maintain a backlog of relevant issues, we automatically label them as stale after 500 days of inactivity.

If this issue is still important to you, then please comment on this issue and the stale label will be removed.

Otherwise this issue will be automatically closed in 28 days time.