Repository navigation
[pyos][code structure] Matching functional structure with code structure #427
Description
I see that the operator module was split up! nice!
In reading the docs, it seems like there are further ways the structure of the package could match the structure of the docs and the types of objects in the package. For example there seems to be a relatively straightforward structure from the docs that would look something like
- collections
- matrix
- vector
- scalar
- operators
- unary
- binary
- monoid
- semiring
- indexunary
- select
but currently that looks like
- binary
- indexunary
- monoid
- op
- select
- semiring
- unary
- core
- matrix
- scalar
- vector
- operator
- agg
- base
- binary
- indexunary
- monoid
- select
- semiring
- unary
where the operators are both at the package root and also beneath core.operator, and the collections are also within the core module.
Wondering what the barriers are to refactoring here so that the code structure more closely matches the structure of what the code is doing?
part of: pyOpenSci/software-submission#81
Activity
eriknw commentedon Apr 10, 2023
Interesting perspective. I'm curious to hear what other people think. I think I'll need more time to digest this.
The modules in
graphblas.coreare useful for implementingpython-graphblasitself. Although not technically hidden/private (so we still need to have deprecations cycles such as here), they are tucked away under.core, which is common practice for scientific Python packages. Seenumpy.core,pandas.core,xarray.core,numba.core,sympy.core, andbokeh.corejust to name a few.In other words, users shouldn't need to use or understand
graphblas.coreunder normal circumstances. We've thought carefully about how to structure the package and what to expose to the user. We want the non-core modules (and objects) to be easily explorable via tab-completion such thatgb.<tab>,gb.unary.<tab>,A.<tab>, etc. show only what is relevant and are not messy (btw, don't use ipython 8.12.0, which has a bug that ruins tab-completion). After all, I believe the best way to use (and learn) most packages is to play with them in a REPL.As you've noted, there is a gap between between what is user-facing and understanding how things are implemented. I expect experimenting with objects would typically be more edifying than diving into the code for most things for most people, but we should still strive for making the code more comprehendible.