Prefix matrix/vector/scalar helper functions with module name

The metadata/utility helpers in matrix.py, vector.py, and scalar.py
were named after generic concepts (`new`, `free`, `type`, `format`,
`shape`, `size`, etc.). Several of those names shadow Python builtins
(`type`, `format`) or collide with common variables, making bare
imports awkward (`from suitesparse_graphblas.matrix import type` is
asking for trouble). Prefix every helper with its module name so each
function is unambiguous on import:

  matrix.py (16 helpers):
    free / new / type / nrows / ncols / nvals / shape / format /
    set_format / sparsity_status / sparsity_control /
    set_sparsity_control / hyper_switch / set_hyper_switch /
    bitmap_switch / set_bitmap_switch
      -> matrix_free, matrix_new, matrix_type, ...,
         matrix_set_bitmap_switch

  vector.py (5 helpers):
    free / new / type / size / nvals
      -> vector_free, vector_new, vector_type, vector_size, vector_nvals

  scalar.py (3 helpers):
    free / new / type
      -> scalar_free, scalar_new, scalar_type

The element setters/getters (set_bool, get_bool, set_int8, get_int8,
..., set_fc64, get_fc64) are NOT renamed -- they already have a clear
set_*/get_* naming convention.

Internal cross-references updated:

- `def matrix_new(T, ..., *, free=matrix_free)` -- the default value of
  the `free` keyword argument now references the renamed module-level
  function. The kwarg parameter name itself stays as `free` so existing
  callers passing `free=None` or `free=my_func` still work.
- `matrix_shape()` body now calls `matrix_nrows(A)` and `matrix_ncols(A)`.
- All in-module doctests updated: `>>> A = new(...)` -> `>>> A = matrix_new(...)`,
  `>>> nrows(A)` -> `>>> matrix_nrows(A)`, etc. Element setter/getter
  doctests that call `new(...)` to construct test instances are also
  updated to use the prefixed name.
- Local variable shadows (e.g. `format = ffi.new(...)` inside
  `matrix_format()`) and kwarg parameter names (e.g. `format` in
  `matrix_set_format(A, format)`) are intentionally left alone -- they
  are local and don't reference the renamed functions.
- `ffi.new(...)` (cffi calls) is preserved -- distinguished from the
  renamed `new(...)` via a negative lookbehind in the rename pattern.

External call sites updated:

- `suitesparse_graphblas/__init__.py`: `burble` class doctest
  references `matrix.matrix_new(...)` and `matrix.matrix_nvals(...)`.
- `suitesparse_graphblas/io/binary.py`: 13 `matrix.X(...)` call sites
  in the binread/binwrite serialization paths now call
  `matrix.matrix_X(...)`.
- `suitesparse_graphblas/io/serialize.py`: 2 docstring prose mentions
  plus 2 attribute references (`matrix.free` -> `matrix.matrix_free`,
  `vector.free` -> `vector.vector_free`) used as the default GC
  callback in `deserialize_matrix` / `deserialize_vector`.
- `suitesparse_graphblas/tests/test_io.py`: 17 external call sites
  updated to the prefixed names.

Verified by rebuilding the Docker test image and running both the full
doctest suite and the pytest suite inside the container:

  matrix:  97 attempted, 0 failed
  vector:  90 attempted, 0 failed
  scalar:  81 attempted, 0 failed
  TOTAL doctest: 268 attempted, 0 failed

  pytest: 9 passed
    test_doctest, test_exceptions, test_io (matrix and vector
    serialization round-trip), test_jit, test_package, test_scalar

Author: michelp

suitesparse_graphblas/__init__.py

@@ -228,7 +228,7 @@ class burble:
 
     >>> from suitesparse_graphblas import burble, lib, matrix
     >>>
-    >>> A = matrix.new(lib.GrB_BOOL, 3, 3)
+    >>> A = matrix.matrix_new(lib.GrB_BOOL, 3, 3)
     >>> burble.is_enabled
     False
     >>> burble.enable()
@@ -239,15 +239,15 @@ class burble:
     Example with explicit enable and disable:
 
     >>> burble.enable()
-    >>> n = matrix.nvals(A)
+    >>> n = matrix.matrix_nvals(A)
       [ GrB_Matrix_nvals
          1.91e-06 sec ]
     >>> burble.disable()
 
     Example as a context manager:
 
     >>> with burble():
-    >>>     n = matrix.nvals(A)
+    >>>     n = matrix.matrix_nvals(A)
       [ GrB_Matrix_nvals
          1.91e-06 sec ]
 

suitesparse_graphblas/io/binary.py

@@ -123,19 +123,19 @@ def binwrite(A, filename, comments=None, opener=Path.open):
     typecode = ffinew("int32_t*")
     matrix_type = ffi.new("GrB_Type*")
 
-    nrows[0] = matrix.nrows(A)
-    ncols[0] = matrix.ncols(A)
-    nvals[0] = matrix.nvals(A)
-    matrix_type[0] = matrix.type(A)
+    nrows[0] = matrix.matrix_nrows(A)
+    ncols[0] = matrix.matrix_ncols(A)
+    nvals[0] = matrix.matrix_nvals(A)
+    matrix_type[0] = matrix.matrix_type(A)
 
     check_status(A, lib.GxB_Type_size(typesize, matrix_type[0]))
     typecode[0] = _ss_typecodes[matrix_type[0]]
 
-    format[0] = matrix.format(A)
-    hyper_switch[0] = matrix.hyper_switch(A)
-    bitmap_switch[0] = matrix.bitmap_switch(A)
-    sparsity_status[0] = matrix.sparsity_status(A)
-    sparsity_control[0] = matrix.sparsity_control(A)
+    format[0] = matrix.matrix_format(A)
+    hyper_switch[0] = matrix.matrix_hyper_switch(A)
+    bitmap_switch[0] = matrix.matrix_bitmap_switch(A)
+    sparsity_status[0] = matrix.matrix_sparsity_status(A)
+    sparsity_control[0] = matrix.matrix_sparsity_control(A)
 
     by_row = format[0] == lib.GxB_BY_ROW
     by_col = format[0] == lib.GxB_BY_COL
@@ -446,7 +446,7 @@ def binread(filename, opener=Path.open):
 
         Ax[0] = readinto_new_buffer(f, "uint8_t*", typesize[0] if is_iso[0] else Ax_size[0])
 
-        A = matrix.new(atype, nrows[0], ncols[0])
+        A = matrix.matrix_new(atype, nrows[0], ncols[0])
 
         if by_col and is_hyper:
             check_status(
@@ -546,7 +546,7 @@ def binread(filename, opener=Path.open):
         else:
             raise TypeError("Unknown format {format[0]}")
 
-        matrix.set_sparsity_control(A, sparsity_control[0])
-        matrix.set_hyper_switch(A, hyper_switch[0])
-        matrix.set_bitmap_switch(A, bitmap_switch[0])
+        matrix.matrix_set_sparsity_control(A, sparsity_control[0])
+        matrix.matrix_set_hyper_switch(A, hyper_switch[0])
+        matrix.matrix_set_bitmap_switch(A, bitmap_switch[0])
         return A

suitesparse_graphblas/io/serialize.py

@@ -88,7 +88,7 @@ def deserialize_matrix(data, *, free=True, nthreads=None):
     """Deserialize a Matrix from bytes.
 
     The `free` argument is called when the object is garbage
-    collected, the default is `matrix.free()`.  If `free` is None then
+    collected, the default is `matrix.matrix_free()`.  If `free` is None then
     there is no automatic garbage collection and it is up to the user
     to free the matrix.
     """
@@ -108,15 +108,15 @@ def deserialize_matrix(data, *, free=True, nthreads=None):
     if free:
         if callable(free):
             return ffi.gc(A, free)
-        return ffi.gc(A, matrix.free)
+        return ffi.gc(A, matrix.matrix_free)
     return A
 
 
 def deserialize_vector(data, *, free=True, nthreads=None):
     """Deserialize a Vector from bytes.
 
     The `free` argument is called when the object is garbage
-    collected, the default is `vector.free()`.  If `free` is None then
+    collected, the default is `vector.vector_free()`.  If `free` is None then
     there is no automatic garbage collection and it is up to the user
     to free the vector.
     """
@@ -136,7 +136,7 @@ def deserialize_vector(data, *, free=True, nthreads=None):
     if free:
         if callable(free):
             return ffi.gc(v, free)
-        return ffi.gc(v, vector.free)
+        return ffi.gc(v, vector.vector_free)
     return v