Description

sneakers-the-rat

opened on Apr 10, 2023

Issue body actions

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

1. eriknw commented on Apr 10, 2023

   

   eriknw

   on Apr 10, 2023

   Member

   More actions

   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.core are useful for implementing python-graphblas itself. 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. See numpy.core, pandas.core, xarray.core, numba.core, sympy.core, and bokeh.core just to name a few.

   In other words, users shouldn't need to use or understand graphblas.core under 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 that gb.<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.
2. eriknw

   added

   documentationImprove or add to documentationImprove or add to documentation

   discussionDiscussing a topic with no specific actions yetDiscussing a topic with no specific actions yet

   hygieneImprove code quality and reduce maintenance overheadImprove code quality and reduce maintenance overhead

   on Apr 12, 2023

Issue actions