diff --git a/.github/workflows/test_and_build.yml b/.github/workflows/test_and_build.yml index c20530fbe..064dd93d8 100644 --- a/.github/workflows/test_and_build.yml +++ b/.github/workflows/test_and_build.yml @@ -171,22 +171,22 @@ jobs: npver=$(python -c 'import random ; print(random.choice(["=1.21", "=1.22", "=1.23", "=1.24", ""]))') spver=$(python -c 'import random ; print(random.choice(["=1.8", "=1.9", "=1.10", ""]))') pdver=$(python -c 'import random ; print(random.choice(["=1.2", "=1.3", "=1.4", "=1.5", "=2.0", ""]))') - akver=$(python -c 'import random ; print(random.choice(["=1.9", "=1.10", "=2.0", "=2.1", ""]))') + akver=$(python -c 'import random ; print(random.choice(["=1.9", "=1.10", "=2.0", "=2.1", "=2.2", ""]))') elif [[ ${{ startsWith(steps.pyver.outputs.selected, '3.9') }} == true ]]; then npver=$(python -c 'import random ; print(random.choice(["=1.21", "=1.22", "=1.23", "=1.24", ""]))') spver=$(python -c 'import random ; print(random.choice(["=1.8", "=1.9", "=1.10", ""]))') pdver=$(python -c 'import random ; print(random.choice(["=1.2", "=1.3", "=1.4", "=1.5", "=2.0", ""]))') - akver=$(python -c 'import random ; print(random.choice(["=1.9", "=1.10", "=2.0", "=2.1", ""]))') + akver=$(python -c 'import random ; print(random.choice(["=1.9", "=1.10", "=2.0", "=2.1", "=2.2", ""]))') elif [[ ${{ startsWith(steps.pyver.outputs.selected, '3.10') }} == true ]]; then npver=$(python -c 'import random ; print(random.choice(["=1.21", "=1.22", "=1.23", "=1.24", ""]))') spver=$(python -c 'import random ; print(random.choice(["=1.8", "=1.9", "=1.10", ""]))') pdver=$(python -c 'import random ; print(random.choice(["=1.3", "=1.4", "=1.5", "=2.0", ""]))') - akver=$(python -c 'import random ; print(random.choice(["=1.9", "=1.10", "=2.0", "=2.1", ""]))') + akver=$(python -c 'import random ; print(random.choice(["=1.9", "=1.10", "=2.0", "=2.1", "=2.2", ""]))') else # Python 3.11 npver=$(python -c 'import random ; print(random.choice(["=1.23", "=1.24", ""]))') spver=$(python -c 'import random ; print(random.choice(["=1.9", "=1.10", ""]))') pdver=$(python -c 'import random ; print(random.choice(["=1.5", "=2.0", ""]))') - akver=$(python -c 'import random ; print(random.choice(["=1.10", "=2.0", "=2.1", ""]))') + akver=$(python -c 'import random ; print(random.choice(["=1.10", "=2.0", "=2.1", "=2.2", ""]))') fi if [[ ${{ steps.sourcetype.outputs.selected }} == "source" || ${{ steps.sourcetype.outputs.selected }} == "upstream" ]]; then # TODO: there are currently issues with some numpy versions when diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d995f4253..10fcca649 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -43,7 +43,7 @@ repos: - id: isort # Let's keep `pyupgrade` even though `ruff --fix` probably does most of it - repo: https://github.com/asottile/pyupgrade - rev: v3.3.2 + rev: v3.4.0 hooks: - id: pyupgrade args: [--py38-plus] @@ -58,7 +58,7 @@ repos: - id: black - id: black-jupyter - repo: https://github.com/charliermarsh/ruff-pre-commit - rev: v0.0.265 + rev: v0.0.267 hooks: - id: ruff args: [--fix-only, --show-fixes] @@ -71,7 +71,7 @@ repos: additional_dependencies: &flake8_dependencies # These versions need updated manually - flake8==6.0.0 - - flake8-bugbear==23.3.23 + - flake8-bugbear==23.5.9 - flake8-simplify==0.20.0 - repo: https://github.com/asottile/yesqa rev: v1.4.0 @@ -86,7 +86,7 @@ repos: additional_dependencies: [tomli] files: ^(graphblas|docs)/ - repo: https://github.com/charliermarsh/ruff-pre-commit - rev: v0.0.265 + rev: v0.0.267 hooks: - id: ruff - repo: https://github.com/sphinx-contrib/sphinx-lint diff --git a/environment.yml b/environment.yml index 875ec5cbd..1a7fb6fa8 100644 --- a/environment.yml +++ b/environment.yml @@ -94,8 +94,10 @@ dependencies: # - python-igraph # - python-louvain # - pyupgrade + # - rich # - ruff # - scalene + # - scikit-network # - setuptools-git-versioning # - snakeviz # - sphinx-lint diff --git a/graphblas/agg/__init__.py b/graphblas/agg/__init__.py index c1319facb..9f6ead0b5 100644 --- a/graphblas/agg/__init__.py +++ b/graphblas/agg/__init__.py @@ -1,4 +1,4 @@ -"""`graphblas.agg` is an experimental module for exploring Aggregators. +"""``graphblas.agg`` is an experimental module for exploring Aggregators. Aggregators may be used in reduce methods: - Matrix.reduce_rowwise @@ -59,9 +59,9 @@ - ss.argmax .. deprecated:: 2023.1.0 - Aggregators `first`, `last`, `first_index`, `last_index`, `argmin`, and `argmax` are - deprecated in the `agg` namespace such as `agg.first`. Use them from `agg.ss` namespace - instead such as `agg.ss.first`. Will be removed in version 2023.9.0 or later. + Aggregators ``first``, ``last``, ``first_index``, ``last_index``, ``argmin``, and ``argmax`` + are deprecated in the ``agg`` namespace such as ``agg.first``. Use them from ``agg.ss`` + namespace instead such as ``agg.ss.first``. Will be removed in version 2023.9.0 or later. # Possible aggregators: # - absolute_deviation, sum(abs(x - mean(x))), sum_absminus(x, mean(x)) diff --git a/graphblas/core/agg.py b/graphblas/core/agg.py index b9f1977ab..23848d3b9 100644 --- a/graphblas/core/agg.py +++ b/graphblas/core/agg.py @@ -1,8 +1,8 @@ """graphblas.core.agg namespace is deprecated; please use graphblas.core.operator.agg instead. .. deprecated:: 2023.3.0 -`graphblas.core.agg` will be removed in a future release. -Use `graphblas.core.operator.agg` instead. +``graphblas.core.agg`` will be removed in a future release. +Use ``graphblas.core.operator.agg`` instead. Will be removed in version 2023.11.0 or later. """ diff --git a/graphblas/core/automethods.py b/graphblas/core/automethods.py index 98dc61137..937e331fd 100644 --- a/graphblas/core/automethods.py +++ b/graphblas/core/automethods.py @@ -1,6 +1,6 @@ """Define functions to use as property methods on expressions. -These will automatically compute the value and avoid the need for `.new()`. +These will automatically compute the value and avoid the need for ``.new()``. To automatically create the functions, run: diff --git a/graphblas/core/mask.py b/graphblas/core/mask.py index 9ad209095..3bda2188a 100644 --- a/graphblas/core/mask.py +++ b/graphblas/core/mask.py @@ -35,7 +35,7 @@ def new(self, dtype=None, *, complement=False, mask=None, name=None, **opts): """Return a new object with True values determined by the mask(s). By default, the result is True wherever the mask(s) would have been applied, - and empty otherwise. If `complement` is True, then these are switched: + and empty otherwise. If ``complement`` is True, then these are switched: the result is empty where the mask(s) would have been applied, and True otherwise. In other words, these are equivalent if complement is False (and mask keyword is None): @@ -48,14 +48,14 @@ def new(self, dtype=None, *, complement=False, mask=None, name=None, **opts): >>> C(self) << expr >>> C(~result.S) << expr # equivalent when complement is True - This can also efficiently merge two masks by using the `mask=` argument. + This can also efficiently merge two masks by using the ``mask=`` argument. This is equivalent to the following (but uses more efficient recipes): >>> val = Matrix(...) >>> val(self) << True >>> val(mask, replace=True) << val - If `complement=` argument is True, then the *complement* will be returned. + If ``complement=`` argument is True, then the *complement* will be returned. This is equivalent to the following (but uses more efficient recipes): >>> val = Matrix(...) @@ -83,7 +83,7 @@ def new(self, dtype=None, *, complement=False, mask=None, name=None, **opts): def __and__(self, other, **opts): """Return the intersection of two masks as a new mask. - `new_mask = mask1 & mask2` is equivalent to the following: + ``new_mask = mask1 & mask2`` is equivalent to the following: >>> val = Matrix(bool, nrows, ncols) >>> val(mask1) << True @@ -109,7 +109,7 @@ def __and__(self, other, **opts): def __or__(self, other, **opts): """Return the union of two masks as a new mask. - `new_mask = mask1 | mask2` is equivalent to the following: + ``new_mask = mask1 | mask2`` is equivalent to the following: >>> val = Matrix(bool, nrows, ncols) >>> val(mask1) << True diff --git a/graphblas/core/matrix.py b/graphblas/core/matrix.py index 0183893fd..b74ca347a 100644 --- a/graphblas/core/matrix.py +++ b/graphblas/core/matrix.py @@ -355,7 +355,7 @@ def isclose(self, other, *, rel_tol=1e-7, abs_tol=0.0, check_dtype=False, **opts Returns ------- bool - Whether all values of the Matrix are close to the values in `other`. + Whether all values of the Matrix are close to the values in ``other``. """ other = self._expect_type( other, (Matrix, TransposedMatrix), within="isclose", argname="other" @@ -448,19 +448,19 @@ def to_values(self, dtype=None, *, rows=True, columns=True, values=True, sort=Tr corresponding to the COO format of the Matrix. .. deprecated:: 2022.11.0 - `Matrix.to_values` will be removed in a future release. - Use `Matrix.to_coo` instead. Will be removed in version 2023.9.0 or later + ``Matrix.to_values`` will be removed in a future release. + Use ``Matrix.to_coo`` instead. Will be removed in version 2023.9.0 or later Parameters ---------- dtype : Requested dtype for the output values array. rows : bool, default=True - Whether to return rows; will return `None` for rows if `False` + Whether to return rows; will return ``None`` for rows if ``False`` columns :bool, default=True - Whether to return columns; will return `None` for columns if `False` + Whether to return columns; will return ``None`` for columns if ``False`` values : bool, default=True - Whether to return values; will return `None` for values if `False` + Whether to return values; will return ``None`` for values if ``False`` sort : bool, default=True Whether to require sorted indices. If internally stored rowwise, the sorting will be first by rows, then by column. @@ -488,11 +488,11 @@ def to_coo(self, dtype=None, *, rows=True, columns=True, values=True, sort=True) dtype : Requested dtype for the output values array. rows : bool, default=True - Whether to return rows; will return `None` for rows if `False` + Whether to return rows; will return ``None`` for rows if ``False`` columns :bool, default=True - Whether to return columns; will return `None` for columns if `False` + Whether to return columns; will return ``None`` for columns if ``False`` values : bool, default=True - Whether to return values; will return `None` for values if `False` + Whether to return values; will return ``None`` for values if ``False`` sort : bool, default=True Whether to require sorted indices. If internally stored rowwise, the sorting will be first by rows, then by column. @@ -559,7 +559,7 @@ def to_edgelist(self, dtype=None, *, values=True, sort=True): dtype : Requested dtype for the output values array. values : bool, default=True - Whether to return values; will return `None` for values if `False` + Whether to return values; will return ``None`` for values if ``False`` sort : bool, default=True Whether to require sorted indices. If internally stored rowwise, the sorting will be first by rows, then by column. @@ -585,7 +585,7 @@ def build(self, rows, columns, values, *, dup_op=None, clear=False, nrows=None, The typical use case is to create a new Matrix and insert values at the same time using :meth:`from_coo`. - All the arguments are used identically in :meth:`from_coo`, except for `clear`, which + All the arguments are used identically in :meth:`from_coo`, except for ``clear``, which indicates whether to clear the Matrix prior to adding the new values. """ # TODO: accept `dtype` keyword to match the dtype of `values`? @@ -781,8 +781,8 @@ def from_values( """Create a new Matrix from row and column indices and values. .. deprecated:: 2022.11.0 - `Matrix.from_values` will be removed in a future release. - Use `Matrix.from_coo` instead. Will be removed in version 2023.9.0 or later + ``Matrix.from_values`` will be removed in a future release. + Use ``Matrix.from_coo`` instead. Will be removed in version 2023.9.0 or later Parameters ---------- @@ -1086,7 +1086,7 @@ def from_csr( Parameters ---------- indptr : list or np.ndarray - Pointers for each row into col_indices and values; `indptr.size == nrows + 1`. + Pointers for each row into col_indices and values; ``indptr.size == nrows + 1``. col_indices : list or np.ndarray Column indices. values : list or np.ndarray or scalar, default 1.0 @@ -1133,7 +1133,7 @@ def from_csc( Parameters ---------- indptr : list or np.ndarray - Pointers for each column into row_indices and values; `indptr.size == ncols + 1`. + Pointers for each column into row_indices and values; ``indptr.size == ncols + 1``. col_indices : list or np.ndarray Column indices. values : list or np.ndarray or scalar, default 1.0 diff --git a/graphblas/core/operator/base.py b/graphblas/core/operator/base.py index a40438f14..cddee6a33 100644 --- a/graphblas/core/operator/base.py +++ b/graphblas/core/operator/base.py @@ -398,7 +398,7 @@ def _find(cls, funcname): def _initialize(cls, include_in_ops=True): """ include_in_ops determines whether the operators are included in the - `gb.ops` namespace in addition to the defined module. + ``gb.ops`` namespace in addition to the defined module. """ if cls._initialized: # pragma: no cover (safety) return diff --git a/graphblas/core/recorder.py b/graphblas/core/recorder.py index 2268c31eb..ca776f697 100644 --- a/graphblas/core/recorder.py +++ b/graphblas/core/recorder.py @@ -34,7 +34,7 @@ def gbstr(arg): class Recorder: """Record GraphBLAS C calls. - The recorder can use `.start()` and `.stop()` to enable/disable recording, + The recorder can use ``.start()`` and ``.stop()`` to enable/disable recording, or it can be used as a context manager. For example, diff --git a/graphblas/core/scalar.py b/graphblas/core/scalar.py index a7a251a1d..b55d601af 100644 --- a/graphblas/core/scalar.py +++ b/graphblas/core/scalar.py @@ -1056,7 +1056,7 @@ def _as_scalar(scalar, dtype=None, *, is_cscalar): def _dict_to_record(np_type, d): - """Converts e.g. `{"x": 1, "y": 2.3}` to `(1, 2.3)`.""" + """Converts e.g. ``{"x": 1, "y": 2.3}`` to ``(1, 2.3)``.""" rv = [] for name, (dtype, _) in np_type.fields.items(): val = d[name] diff --git a/graphblas/core/ss/descriptor.py b/graphblas/core/ss/descriptor.py index dffc4dec1..2f7d11ffa 100644 --- a/graphblas/core/ss/descriptor.py +++ b/graphblas/core/ss/descriptor.py @@ -132,7 +132,7 @@ def get_descriptor(**opts): sort : bool, default False A hint for whether methods may return a "jumbled" matrix secure_import : bool, default False - Whether to trust the data for `import` and `pack` functions. + Whether to trust the data for ``import`` and ``pack`` functions. When True, checks are performed to ensure input data is valid. compression : str, {"none", "default", "lz4", "lz4hc", "zstd"} Whether and how to compress the data for serialization. diff --git a/graphblas/core/ss/matrix.py b/graphblas/core/ss/matrix.py index cac0296c7..64aa43a96 100644 --- a/graphblas/core/ss/matrix.py +++ b/graphblas/core/ss/matrix.py @@ -63,7 +63,7 @@ def head(matrix, n=10, dtype=None, *, sort=False): def _concat_mn(tiles, *, is_matrix=None): - """Argument checking for `Matrix.ss.concat` and returns number of tiles in each dimension.""" + """Argument checking for ``Matrix.ss.concat`` and returns number of tiles in each dimension.""" from ..matrix import Matrix, TransposedMatrix from ..vector import Vector @@ -261,8 +261,8 @@ def build_diag(self, vector, k=0, **opts): vector : Vector Create a diagonal from this Vector. k : int, default 0 - Diagonal in question. Use `k>0` for diagonals above the main diagonal, - and `k<0` for diagonals below the main diagonal. + Diagonal in question. Use ``k>0`` for diagonals above the main diagonal, + and ``k<0`` for diagonals below the main diagonal. See Also -------- @@ -282,12 +282,12 @@ def split(self, chunks, *, name=None, **opts): """ GxB_Matrix_split. - Split a Matrix into a 2D array of sub-matrices according to `chunks`. + Split a Matrix into a 2D array of sub-matrices according to ``chunks``. This performs the opposite operation as ``concat``. - `chunks` is short for "chunksizes" and indicates the chunk sizes for each dimension. - `chunks` may be a single integer, or a length 2 tuple or list. Example chunks: + ``chunks`` is short for "chunksizes" and indicates the chunk sizes for each dimension. + ``chunks`` may be a single integer, or a length 2 tuple or list. Example chunks: - ``chunks=10`` - Split each dimension into chunks of size 10 (the last chunk may be smaller). @@ -295,7 +295,7 @@ def split(self, chunks, *, name=None, **opts): - Split rows into chunks of size 10 and columns into chunks of size 20. - ``chunks=(None, [5, 10])`` - Don't split rows into chunks, and split columns into two chunks of size 5 and 10. - ` ``chunks=(10, [20, None])`` + - ``chunks=(10, [20, None])`` - Split columns into two chunks of size 20 and ``ncols - 20`` See Also @@ -366,9 +366,9 @@ def concat(self, tiles, **opts): Concatenate a 2D list of Matrix objects into the current Matrix. Any existing values in the current Matrix will be discarded. - To concatenate into a new Matrix, use `graphblas.ss.concat`. + To concatenate into a new Matrix, use ``graphblas.ss.concat``. - Vectors may be used as `Nx1` Matrix objects. + Vectors may be used as ``Nx1`` Matrix objects. This performs the opposite operation as ``split``. @@ -542,8 +542,8 @@ def export(self, format=None, *, sort=False, give_ownership=False, raw=False, ** Parameters ---------- format : str, optional - If `format` is not specified, this method exports in the currently stored format. - To control the export format, set `format` to one of: + If ``format`` is not specified, this method exports in the currently stored format. + To control the export format, set ``format`` to one of: - "csr" - "csc" - "hypercsr" @@ -578,7 +578,7 @@ def export(self, format=None, *, sort=False, give_ownership=False, raw=False, ** Returns ------- - dict; keys depend on `format` and `raw` arguments (see below). + dict; keys depend on ``format`` and ``raw`` arguments (see below). See Also -------- @@ -732,10 +732,10 @@ def unpack(self, format=None, *, sort=False, raw=False, **opts): """ GxB_Matrix_unpack_xxx. - `unpack` is like `export`, except that the Matrix remains valid but empty. - `pack_*` methods are the opposite of `unpack`. + ``unpack`` is like ``export``, except that the Matrix remains valid but empty. + ``pack_*`` methods are the opposite of ``unpack``. - See `Matrix.ss.export` documentation for more details. + See ``Matrix.ss.export`` documentation for more details. """ return self._export( format, sort=sort, raw=raw, give_ownership=True, method="unpack", opts=opts @@ -1193,7 +1193,7 @@ def import_csr( col_indices : array-like is_iso : bool, default False Is the Matrix iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. sorted_cols : bool, default False Indicate whether the values in "col_indices" are sorted. take_ownership : bool, default False @@ -1210,7 +1210,7 @@ def import_csr( read-only and will no longer own the data. dtype : dtype, optional dtype of the new Matrix. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "csr" or None. This is included to be compatible with the dict returned from exporting. @@ -1259,10 +1259,10 @@ def pack_csr( """ GxB_Matrix_pack_CSR. - `pack_csr` is like `import_csr` except it "packs" data into an + ``pack_csr`` is like ``import_csr`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack("csr")`` - See `Matrix.ss.import_csr` documentation for more details. + See ``Matrix.ss.import_csr`` documentation for more details. """ return self._import_csr( indptr=indptr, @@ -1383,7 +1383,7 @@ def import_csc( row_indices : array-like is_iso : bool, default False Is the Matrix iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. sorted_rows : bool, default False Indicate whether the values in "row_indices" are sorted. take_ownership : bool, default False @@ -1400,7 +1400,7 @@ def import_csc( read-only and will no longer own the data. dtype : dtype, optional dtype of the new Matrix. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "csc" or None. This is included to be compatible with the dict returned from exporting. @@ -1449,10 +1449,10 @@ def pack_csc( """ GxB_Matrix_pack_CSC. - `pack_csc` is like `import_csc` except it "packs" data into an + ``pack_csc`` is like ``import_csc`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack("csc")`` - See `Matrix.ss.import_csc` documentation for more details. + See ``Matrix.ss.import_csc`` documentation for more details. """ return self._import_csc( indptr=indptr, @@ -1579,7 +1579,7 @@ def import_hypercsr( If not specified, will be set to ``len(rows)``. is_iso : bool, default False Is the Matrix iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. sorted_cols : bool, default False Indicate whether the values in "col_indices" are sorted. take_ownership : bool, default False @@ -1596,7 +1596,7 @@ def import_hypercsr( read-only and will no longer own the data. dtype : dtype, optional dtype of the new Matrix. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "hypercsr" or None. This is included to be compatible with the dict returned from exporting. @@ -1649,10 +1649,10 @@ def pack_hypercsr( """ GxB_Matrix_pack_HyperCSR. - `pack_hypercsr` is like `import_hypercsr` except it "packs" data into an + ``pack_hypercsr`` is like ``import_hypercsr`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack("hypercsr")`` - See `Matrix.ss.import_hypercsr` documentation for more details. + See ``Matrix.ss.import_hypercsr`` documentation for more details. """ return self._import_hypercsr( rows=rows, @@ -1803,7 +1803,7 @@ def import_hypercsc( If not specified, will be set to ``len(cols)``. is_iso : bool, default False Is the Matrix iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. sorted_rows : bool, default False Indicate whether the values in "row_indices" are sorted. take_ownership : bool, default False @@ -1820,7 +1820,7 @@ def import_hypercsc( read-only and will no longer own the data. dtype : dtype, optional dtype of the new Matrix. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "hypercsc" or None. This is included to be compatible with the dict returned from exporting. @@ -1873,10 +1873,10 @@ def pack_hypercsc( """ GxB_Matrix_pack_HyperCSC. - `pack_hypercsc` is like `import_hypercsc` except it "packs" data into an + ``pack_hypercsc`` is like ``import_hypercsc`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack("hypercsc")`` - See `Matrix.ss.import_hypercsc` documentation for more details. + See ``Matrix.ss.import_hypercsc`` documentation for more details. """ return self._import_hypercsc( cols=cols, @@ -2028,7 +2028,7 @@ def import_bitmapr( If not provided, will be inferred from values or bitmap if either is 2d. is_iso : bool, default False Is the Matrix iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. take_ownership : bool, default False If True, perform a zero-copy data transfer from input numpy arrays to GraphBLAS if possible. To give ownership of the underlying @@ -2043,7 +2043,7 @@ def import_bitmapr( read-only and will no longer own the data. dtype : dtype, optional dtype of the new Matrix. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "bitmapr" or None. This is included to be compatible with the dict returned from exporting. @@ -2090,10 +2090,10 @@ def pack_bitmapr( """ GxB_Matrix_pack_BitmapR. - `pack_bitmapr` is like `import_bitmapr` except it "packs" data into an + ``pack_bitmapr`` is like ``import_bitmapr`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack("bitmapr")`` - See `Matrix.ss.import_bitmapr` documentation for more details. + See ``Matrix.ss.import_bitmapr`` documentation for more details. """ return self._import_bitmapr( bitmap=bitmap, @@ -2221,7 +2221,7 @@ def import_bitmapc( If not provided, will be inferred from values or bitmap if either is 2d. is_iso : bool, default False Is the Matrix iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. take_ownership : bool, default False If True, perform a zero-copy data transfer from input numpy arrays to GraphBLAS if possible. To give ownership of the underlying @@ -2236,7 +2236,7 @@ def import_bitmapc( read-only and will no longer own the data. dtype : dtype, optional dtype of the new Matrix. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "bitmapc" or None. This is included to be compatible with the dict returned from exporting. @@ -2283,10 +2283,10 @@ def pack_bitmapc( """ GxB_Matrix_pack_BitmapC. - `pack_bitmapc` is like `import_bitmapc` except it "packs" data into an + ``pack_bitmapc`` is like ``import_bitmapc`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack("bitmapc")`` - See `Matrix.ss.import_bitmapc` documentation for more details. + See ``Matrix.ss.import_bitmapc`` documentation for more details. """ return self._import_bitmapc( bitmap=bitmap, @@ -2407,7 +2407,7 @@ def import_fullr( If not provided, will be inferred from values if it is 2d. is_iso : bool, default False Is the Matrix iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. take_ownership : bool, default False If True, perform a zero-copy data transfer from input numpy arrays to GraphBLAS if possible. To give ownership of the underlying @@ -2422,7 +2422,7 @@ def import_fullr( read-only and will no longer own the data. dtype : dtype, optional dtype of the new Matrix. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "fullr" or None. This is included to be compatible with the dict returned from exporting. @@ -2465,10 +2465,10 @@ def pack_fullr( """ GxB_Matrix_pack_FullR. - `pack_fullr` is like `import_fullr` except it "packs" data into an + ``pack_fullr`` is like ``import_fullr`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack("fullr")`` - See `Matrix.ss.import_fullr` documentation for more details. + See ``Matrix.ss.import_fullr`` documentation for more details. """ return self._import_fullr( values=values, @@ -2566,7 +2566,7 @@ def import_fullc( If not provided, will be inferred from values if it is 2d. is_iso : bool, default False Is the Matrix iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. take_ownership : bool, default False If True, perform a zero-copy data transfer from input numpy arrays to GraphBLAS if possible. To give ownership of the underlying @@ -2581,7 +2581,7 @@ def import_fullc( read-only and will no longer own the data. dtype : dtype, optional dtype of the new Matrix. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "fullc" or None. This is included to be compatible with the dict returned from exporting. @@ -2624,10 +2624,10 @@ def pack_fullc( """ GxB_Matrix_pack_FullC. - `pack_fullc` is like `import_fullc` except it "packs" data into an + ``pack_fullc`` is like ``import_fullc`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack("fullc")`` - See `Matrix.ss.import_fullc` documentation for more details. + See ``Matrix.ss.import_fullc`` documentation for more details. """ return self._import_fullc( values=values, @@ -2727,7 +2727,7 @@ def import_coo( The number of columns for the Matrix. is_iso : bool, default False Is the Matrix iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. sorted_rows : bool, default False True if rows are sorted or when (cols, rows) are sorted lexicographically sorted_cols : bool, default False @@ -2736,7 +2736,7 @@ def import_coo( Ignored. Zero-copy is not possible for "coo" format. dtype : dtype, optional dtype of the new Matrix. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "coo" or None. This is included to be compatible with the dict returned from exporting. @@ -2787,10 +2787,10 @@ def pack_coo( """ GrB_Matrix_build_XXX and GxB_Matrix_build_Scalar. - `pack_coo` is like `import_coo` except it "packs" data into an + ``pack_coo`` is like ``import_coo`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack("coo")`` - See `Matrix.ss.import_coo` documentation for more details. + See ``Matrix.ss.import_coo`` documentation for more details. """ return self._import_coo( nrows=self._parent._nrows, @@ -2914,7 +2914,7 @@ def import_coor( The number of columns for the Matrix. is_iso : bool, default False Is the Matrix iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. sorted_cols : bool, default False True indicates indices are sorted by column, then row. take_ownership : bool, default False @@ -2932,7 +2932,7 @@ def import_coor( For "coor", ownership of "rows" will never change. dtype : dtype, optional dtype of the new Matrix. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "coor" or None. This is included to be compatible with the dict returned from exporting. @@ -2983,10 +2983,10 @@ def pack_coor( """ GxB_Matrix_pack_CSR. - `pack_coor` is like `import_coor` except it "packs" data into an + ``pack_coor`` is like ``import_coor`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack("coor")`` - See `Matrix.ss.import_coor` documentation for more details. + See ``Matrix.ss.import_coor`` documentation for more details. """ return self._import_coor( rows=rows, @@ -3083,7 +3083,7 @@ def import_cooc( The number of columns for the Matrix. is_iso : bool, default False Is the Matrix iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. sorted_rows : bool, default False True indicates indices are sorted by column, then row. take_ownership : bool, default False @@ -3101,7 +3101,7 @@ def import_cooc( For "cooc", ownership of "cols" will never change. dtype : dtype, optional dtype of the new Matrix. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "cooc" or None. This is included to be compatible with the dict returned from exporting. @@ -3152,10 +3152,10 @@ def pack_cooc( """ GxB_Matrix_pack_CSC. - `pack_cooc` is like `import_cooc` except it "packs" data into an + ``pack_cooc`` is like ``import_cooc`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack("cooc")`` - See `Matrix.ss.import_cooc` documentation for more details. + See ``Matrix.ss.import_cooc`` documentation for more details. """ return self._import_cooc( ncols=self._parent._ncols, @@ -3255,7 +3255,7 @@ def import_any( GxB_Matrix_import_xxx. Dispatch to appropriate import method inferred from inputs. - See the other import functions and `Matrix.ss.export`` for details. + See the other import functions and ``Matrix.ss.export`` for details. Returns ------- @@ -3352,10 +3352,10 @@ def pack_any( """ GxB_Matrix_pack_xxx. - `pack_any` is like `import_any` except it "packs" data into an + ``pack_any`` is like ``import_any`` except it "packs" data into an existing Matrix. This is the opposite of ``unpack()`` - See `Matrix.ss.import_any` documentation for more details. + See ``Matrix.ss.import_any`` documentation for more details. """ return self._import_any( values=values, @@ -3701,8 +3701,8 @@ def head(self, n=10, dtype=None, *, sort=False): def scan(self, op=monoid.plus, order="rowwise", *, name=None, **opts): """Perform a prefix scan across rows (default) or columns with the given monoid. - For example, use `monoid.plus` (the default) to perform a cumulative sum, - and `monoid.times` for cumulative product. Works with any monoid. + For example, use ``monoid.plus`` (the default) to perform a cumulative sum, + and ``monoid.times`` for cumulative product. Works with any monoid. Returns ------- @@ -3718,12 +3718,12 @@ def scan_columnwise(self, op=monoid.plus, *, name=None, **opts): """Perform a prefix scan across columns with the given monoid. .. deprecated:: 2022.11.1 - `Matrix.ss.scan_columnwise` will be removed in a future release. - Use `Matrix.ss.scan(order="columnwise")` instead. + ``Matrix.ss.scan_columnwise`` will be removed in a future release. + Use ``Matrix.ss.scan(order="columnwise")`` instead. Will be removed in version 2023.7.0 or later - For example, use `monoid.plus` (the default) to perform a cumulative sum, - and `monoid.times` for cumulative product. Works with any monoid. + For example, use ``monoid.plus`` (the default) to perform a cumulative sum, + and ``monoid.times`` for cumulative product. Works with any monoid. Returns ------- @@ -3741,12 +3741,12 @@ def scan_rowwise(self, op=monoid.plus, *, name=None, **opts): """Perform a prefix scan across rows with the given monoid. .. deprecated:: 2022.11.1 - `Matrix.ss.scan_rowwise` will be removed in a future release. - Use `Matrix.ss.scan` instead. + ``Matrix.ss.scan_rowwise`` will be removed in a future release. + Use ``Matrix.ss.scan`` instead. Will be removed in version 2023.7.0 or later - For example, use `monoid.plus` (the default) to perform a cumulative sum, - and `monoid.times` for cumulative product. Works with any monoid. + For example, use ``monoid.plus`` (the default) to perform a cumulative sum, + and ``monoid.times`` for cumulative product. Works with any monoid. Returns ------- @@ -3904,8 +3904,8 @@ def selectk_rowwise(self, how, k, *, name=None): # pragma: no cover (deprecated """Select (up to) k elements from each row. .. deprecated:: 2022.11.1 - `Matrix.ss.selectk_rowwise` will be removed in a future release. - Use `Matrix.ss.selectk` instead. + ``Matrix.ss.selectk_rowwise`` will be removed in a future release. + Use ``Matrix.ss.selectk`` instead. Will be removed in version 2023.7.0 or later Parameters @@ -3950,8 +3950,8 @@ def selectk_columnwise(self, how, k, *, name=None): # pragma: no cover (depreca """Select (up to) k elements from each column. .. deprecated:: 2022.11.1 - `Matrix.ss.selectk_columnwise` will be removed in a future release. - Use `Matrix.ss.selectk(order="columnwise")` instead. + ``Matrix.ss.selectk_columnwise`` will be removed in a future release. + Use ``Matrix.ss.selectk(order="columnwise")`` instead. Will be removed in version 2023.7.0 or later Parameters @@ -4216,23 +4216,23 @@ def sort(self, op=binary.lt, order="rowwise", *, values=True, permutation=True, """GxB_Matrix_sort to sort values along the rows (default) or columns of the Matrix. Sorting moves all the elements to the left (if rowwise) or top (if columnwise) just - like `compactify`. The returned matrices will be the same shape as the input Matrix. + like ``compactify``. The returned matrices will be the same shape as the input Matrix. Parameters ---------- op : :class:`~graphblas.core.operator.BinaryOp`, optional Binary operator with a bool return type used to sort the values. - For example, `binary.lt` (the default) sorts the smallest elements first. + For example, ``binary.lt`` (the default) sorts the smallest elements first. Ties are broken according to indices (smaller first). order : {"rowwise", "columnwise"}, optional Whether to sort rowwise or columnwise. Rowwise shifts all values to the left, and columnwise shifts all values to the top. The default is "rowwise". values : bool, default=True - Whether to return values; will return `None` for values if `False`. + Whether to return values; will return ``None`` for values if ``False``. permutation : bool, default=True Whether to compute the permutation Matrix that has the original column indices (if rowwise) or row indices (if columnwise) of the sorted values. - Will return None if `False`. + Will return None if ``False``. nthreads : int, optional The maximum number of threads to use for this operation. None, 0 or negative nthreads means to use the default number of threads. @@ -4301,7 +4301,7 @@ def serialize(self, compression="default", level=None, **opts): None, 0 or negative nthreads means to use the default number of threads. For best performance, this function returns a numpy array with uint8 dtype. - Use `Matrix.ss.deserialize(blob)` to create a Matrix from the result of serialization + Use ``Matrix.ss.deserialize(blob)`` to create a Matrix from the result of serialization This method is intended to support all serialization options from SuiteSparse:GraphBLAS. @@ -4327,7 +4327,7 @@ def deserialize(cls, data, dtype=None, *, name=None, **opts): """Deserialize a Matrix from bytes, buffer, or numpy array using GxB_Matrix_deserialize. The data should have been previously serialized with a compatible version of - SuiteSparse:GraphBLAS. For example, from the result of `data = matrix.ss.serialize()`. + SuiteSparse:GraphBLAS. For example, from the result of ``data = matrix.ss.serialize()``. Examples -------- diff --git a/graphblas/core/ss/vector.py b/graphblas/core/ss/vector.py index 2b1e8bf05..1babc556e 100644 --- a/graphblas/core/ss/vector.py +++ b/graphblas/core/ss/vector.py @@ -155,8 +155,8 @@ def build_diag(self, matrix, k=0, **opts): matrix : Matrix or TransposedMatrix Extract a diagonal from this matrix. k : int, default 0 - Diagonal in question. Use `k>0` for diagonals above the main diagonal, - and `k<0` for diagonals below the main diagonal. + Diagonal in question. Use ``k>0`` for diagonals above the main diagonal, + and ``k<0`` for diagonals below the main diagonal. See Also -------- @@ -185,12 +185,12 @@ def split(self, chunks, *, name=None, **opts): """ GxB_Matrix_split. - Split a Vector into a 1D array of sub-vectors according to `chunks`. + Split a Vector into a 1D array of sub-vectors according to ``chunks``. This performs the opposite operation as ``concat``. - `chunks` is short for "chunksizes" and indicates the chunk sizes. - `chunks` may be a single integer, or a tuple or list. Example chunks: + ``chunks`` is short for "chunksizes" and indicates the chunk sizes. + ``chunks`` may be a single integer, or a tuple or list. Example chunks: - ``chunks=10`` - Split vector into chunks of size 10 (the last chunk may be smaller). @@ -253,7 +253,7 @@ def concat(self, tiles, **opts): Concatenate a 1D list of Vector objects into the current Vector. Any existing values in the current Vector will be discarded. - To concatenate into a new Vector, use `graphblas.ss.concat`. + To concatenate into a new Vector, use ``graphblas.ss.concat``. This performs the opposite operation as ``split``. @@ -415,8 +415,8 @@ def export(self, format=None, *, sort=False, give_ownership=False, raw=False, ** Parameters ---------- format : str or None, default None - If `format` is not specified, this method exports in the currently stored format. - To control the export format, set `format` to one of: + If ``format`` is not specified, this method exports in the currently stored format. + To control the export format, set ``format`` to one of: - "sparse" - "bitmap" - "full" @@ -434,7 +434,7 @@ def export(self, format=None, *, sort=False, give_ownership=False, raw=False, ** Returns ------- - dict; keys depend on `format` and `raw` arguments (see below). + dict; keys depend on ``format`` and ``raw`` arguments (see below). See Also -------- @@ -442,7 +442,7 @@ def export(self, format=None, *, sort=False, give_ownership=False, raw=False, ** Vector.ss.import_any Return values - - Note: for `raw=True`, arrays may be larger than specified. + - Note: for ``raw=True``, arrays may be larger than specified. - "sparse" format - indices : ndarray(dtype=uint64, size=nvals) - values : ndarray(size=nvals) @@ -481,10 +481,10 @@ def unpack(self, format=None, *, sort=False, raw=False, **opts): """ GxB_Vector_unpack_xxx. - `unpack` is like `export`, except that the Vector remains valid but empty. - `pack_*` methods are the opposite of `unpack`. + ``unpack`` is like ``export``, except that the Vector remains valid but empty. + ``pack_*`` methods are the opposite of ``unpack``. - See `Vector.ss.export` documentation for more details. + See ``Vector.ss.export`` documentation for more details. """ return self._export( format=format, sort=sort, give_ownership=True, raw=raw, method="unpack", opts=opts @@ -658,7 +658,7 @@ def import_any( GxB_Vector_import_xxx. Dispatch to appropriate import method inferred from inputs. - See the other import functions and `Vector.ss.export`` for details. + See the other import functions and ``Vector.ss.export`` for details. Returns ------- @@ -724,10 +724,10 @@ def pack_any( """ GxB_Vector_pack_xxx. - `pack_any` is like `import_any` except it "packs" data into an + ``pack_any`` is like ``import_any`` except it "packs" data into an existing Vector. This is the opposite of ``unpack()`` - See `Vector.ss.import_any` documentation for more details. + See ``Vector.ss.import_any`` documentation for more details. """ return self._import_any( values=values, @@ -858,7 +858,7 @@ def import_sparse( If not specified, will be set to ``len(values)``. is_iso : bool, default False Is the Vector iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. sorted_index : bool, default False Indicate whether the values in "col_indices" are sorted. take_ownership : bool, default False @@ -875,7 +875,7 @@ def import_sparse( read-only and will no longer own the data. dtype : dtype, optional dtype of the new Vector. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "sparse" or None. This is included to be compatible with the dict returned from exporting. @@ -922,10 +922,10 @@ def pack_sparse( """ GxB_Vector_pack_CSC. - `pack_sparse` is like `import_sparse` except it "packs" data into an + ``pack_sparse`` is like ``import_sparse`` except it "packs" data into an existing Vector. This is the opposite of ``unpack("sparse")`` - See `Vector.ss.import_sparse` documentation for more details. + See ``Vector.ss.import_sparse`` documentation for more details. """ return self._import_sparse( indices=indices, @@ -1045,7 +1045,7 @@ def import_bitmap( If not specified, it will be set to the size of values. is_iso : bool, default False Is the Vector iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. take_ownership : bool, default False If True, perform a zero-copy data transfer from input numpy arrays to GraphBLAS if possible. To give ownership of the underlying @@ -1060,7 +1060,7 @@ def import_bitmap( read-only and will no longer own the data. dtype : dtype, optional dtype of the new Vector. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "bitmap" or None. This is included to be compatible with the dict returned from exporting. @@ -1105,10 +1105,10 @@ def pack_bitmap( """ GxB_Vector_pack_Bitmap. - `pack_bitmap` is like `import_bitmap` except it "packs" data into an + ``pack_bitmap`` is like ``import_bitmap`` except it "packs" data into an existing Vector. This is the opposite of ``unpack("bitmap")`` - See `Vector.ss.import_bitmap` documentation for more details. + See ``Vector.ss.import_bitmap`` documentation for more details. """ return self._import_bitmap( bitmap=bitmap, @@ -1226,7 +1226,7 @@ def import_full( If not specified, it will be set to the size of values. is_iso : bool, default False Is the Vector iso-valued (meaning all the same value)? - If true, then `values` should be a length 1 array. + If true, then ``values`` should be a length 1 array. take_ownership : bool, default False If True, perform a zero-copy data transfer from input numpy arrays to GraphBLAS if possible. To give ownership of the underlying @@ -1241,7 +1241,7 @@ def import_full( read-only and will no longer own the data. dtype : dtype, optional dtype of the new Vector. - If not specified, this will be inferred from `values`. + If not specified, this will be inferred from ``values``. format : str, optional Must be "full" or None. This is included to be compatible with the dict returned from exporting. @@ -1282,10 +1282,10 @@ def pack_full( """ GxB_Vector_pack_Full. - `pack_full` is like `import_full` except it "packs" data into an + ``pack_full`` is like ``import_full`` except it "packs" data into an existing Vector. This is the opposite of ``unpack("full")`` - See `Vector.ss.import_full` documentation for more details. + See ``Vector.ss.import_full`` documentation for more details. """ return self._import_full( values=values, @@ -1364,8 +1364,8 @@ def head(self, n=10, dtype=None, *, sort=False): def scan(self, op=monoid.plus, *, name=None, **opts): """Perform a prefix scan with the given monoid. - For example, use `monoid.plus` (the default) to perform a cumulative sum, - and `monoid.times` for cumulative product. Works with any monoid. + For example, use ``monoid.plus`` (the default) to perform a cumulative sum, + and ``monoid.times`` for cumulative product. Works with any monoid. Returns ------- @@ -1561,20 +1561,20 @@ def compactify(self, how="first", size=None, *, reverse=False, asindex=False, na def sort(self, op=binary.lt, *, values=True, permutation=True, **opts): """GxB_Vector_sort to sort values of the Vector. - Sorting moves all the elements to the left just like `compactify`. + Sorting moves all the elements to the left just like ``compactify``. The returned vectors will be the same size as the input Vector. Parameters ---------- op : :class:`~graphblas.core.operator.BinaryOp`, optional Binary operator with a bool return type used to sort the values. - For example, `binary.lt` (the default) sorts the smallest elements first. + For example, ``binary.lt`` (the default) sorts the smallest elements first. Ties are broken according to indices (smaller first). values : bool, default=True - Whether to return values; will return `None` for values if `False`. + Whether to return values; will return ``None`` for values if ``False``. permutation : bool, default=True Whether to compute the permutation Vector that has the original indices of the - sorted values. Will return None if `False`. + sorted values. Will return None if ``False``. nthreads : int, optional The maximum number of threads to use for this operation. None, 0 or negative nthreads means to use the default number of threads. @@ -1642,7 +1642,7 @@ def serialize(self, compression="default", level=None, **opts): None, 0 or negative nthreads means to use the default number of threads. For best performance, this function returns a numpy array with uint8 dtype. - Use `Vector.ss.deserialize(blob)` to create a Vector from the result of serialization· + Use ``Vector.ss.deserialize(blob)`` to create a Vector from the result of serialization· This method is intended to support all serialization options from SuiteSparse:GraphBLAS. @@ -1668,7 +1668,7 @@ def deserialize(cls, data, dtype=None, *, name=None, **opts): """Deserialize a Vector from bytes, buffer, or numpy array using GxB_Vector_deserialize. The data should have been previously serialized with a compatible version of - SuiteSparse:GraphBLAS. For example, from the result of `data = vector.ss.serialize()`. + SuiteSparse:GraphBLAS. For example, from the result of ``data = vector.ss.serialize()``. Examples -------- diff --git a/graphblas/core/utils.py b/graphblas/core/utils.py index 77c64a7ac..74e03f2f9 100644 --- a/graphblas/core/utils.py +++ b/graphblas/core/utils.py @@ -22,7 +22,7 @@ def libget(name): def wrapdoc(func_with_doc): - """Decorator to copy `__doc__` from a function onto the wrapped function.""" + """Decorator to copy ``__doc__`` from a function onto the wrapped function.""" def inner(func_wo_doc): func_wo_doc.__doc__ = func_with_doc.__doc__ @@ -159,7 +159,7 @@ def get_order(order): def normalize_chunks(chunks, shape): - """Normalize chunks argument for use by `Matrix.ss.split`. + """Normalize chunks argument for use by ``Matrix.ss.split``. Examples -------- @@ -249,17 +249,17 @@ def normalize_chunks(chunks, shape): def ensure_type(x, types): - """Try to ensure `x` is one of the given types, computing if necessary. + """Try to ensure ``x`` is one of the given types, computing if necessary. - `types` must be a type or a tuple of types as used in `isinstance`. + ``types`` must be a type or a tuple of types as used in ``isinstance``. - For example, if `types` is a Vector, then a Vector input will be returned, - and a `VectorExpression` input will be computed and returned as a Vector. + For example, if ``types`` is a Vector, then a Vector input will be returned, + and a ``VectorExpression`` input will be computed and returned as a Vector. TypeError will be raised if the input is not or can't be converted to types. - This function ignores `graphblas.config["autocompute"]`; it always computes - if the return type will match `types`. + This function ignores ``graphblas.config["autocompute"]``; it always computes + if the return type will match ``types``. """ if isinstance(x, types): return x @@ -358,6 +358,7 @@ def _autogenerate_code( specializer=None, begin="# Begin auto-generated code", end="# End auto-generated code", + callblack=True, ): """Super low-tech auto-code generation used by automethods.py and infixmethods.py.""" with filepath.open() as f: # pragma: no branch (flaky) @@ -384,7 +385,8 @@ def _autogenerate_code( f.write(new_text) import subprocess - try: - subprocess.check_call(["black", filepath]) - except FileNotFoundError: # pragma: no cover (safety) - pass # It's okay if `black` isn't installed; pre-commit hooks will do linting + if callblack: + try: + subprocess.check_call(["black", filepath]) + except FileNotFoundError: # pragma: no cover (safety) + pass # It's okay if `black` isn't installed; pre-commit hooks will do linting diff --git a/graphblas/core/vector.py b/graphblas/core/vector.py index 57851420d..d2ddee372 100644 --- a/graphblas/core/vector.py +++ b/graphblas/core/vector.py @@ -453,17 +453,17 @@ def to_values(self, dtype=None, *, indices=True, values=True, sort=True): """Extract the indices and values as a 2-tuple of numpy arrays. .. deprecated:: 2022.11.0 - `Vector.to_values` will be removed in a future release. - Use `Vector.to_coo` instead. Will be removed in version 2023.9.0 or later + ``Vector.to_values`` will be removed in a future release. + Use ``Vector.to_coo`` instead. Will be removed in version 2023.9.0 or later Parameters ---------- dtype : Requested dtype for the output values array. indices :bool, default=True - Whether to return indices; will return `None` for indices if `False` + Whether to return indices; will return ``None`` for indices if ``False`` values : bool, default=True - Whether to return values; will return `None` for values if `False` + Whether to return values; will return ``None`` for values if ``False`` sort : bool, default=True Whether to require sorted indices. @@ -487,9 +487,9 @@ def to_coo(self, dtype=None, *, indices=True, values=True, sort=True): dtype : Requested dtype for the output values array. indices :bool, default=True - Whether to return indices; will return `None` for indices if `False` + Whether to return indices; will return ``None`` for indices if ``False`` values : bool, default=True - Whether to return values; will return `None` for values if `False` + Whether to return values; will return ``None`` for values if ``False`` sort : bool, default=True Whether to require sorted indices. @@ -539,7 +539,7 @@ def build(self, indices, values, *, dup_op=None, clear=False, size=None): """Rarely used method to insert values into an existing Vector. The typical use case is to create a new Vector and insert values at the same time using :meth:`from_coo`. - All the arguments are used identically in :meth:`from_coo`, except for `clear`, which + All the arguments are used identically in :meth:`from_coo`, except for ``clear``, which indicates whether to clear the Vector prior to adding the new values. """ # TODO: accept `dtype` keyword to match the dtype of `values`? @@ -695,8 +695,8 @@ def from_values(cls, indices, values, dtype=None, *, size=None, dup_op=None, nam """Create a new Vector from indices and values. .. deprecated:: 2022.11.0 - `Vector.from_values` will be removed in a future release. - Use `Vector.from_coo` instead. Will be removed in version 2023.9.0 or later + ``Vector.from_values`` will be removed in a future release. + Use ``Vector.from_coo`` instead. Will be removed in version 2023.9.0 or later Parameters ---------- diff --git a/graphblas/io/_numpy.py b/graphblas/io/_numpy.py index 1c40e1633..954d28df7 100644 --- a/graphblas/io/_numpy.py +++ b/graphblas/io/_numpy.py @@ -11,14 +11,14 @@ def from_numpy(m): # pragma: no cover (deprecated) """Create a sparse Vector or Matrix from a dense numpy array. .. deprecated:: 2023.2.0 - `from_numpy` will be removed in a future release. - Use `Vector.from_dense` or `Matrix.from_dense` instead. + ``from_numpy`` will be removed in a future release. + Use ``Vector.from_dense`` or ``Matrix.from_dense`` instead. Will be removed in version 2023.10.0 or later A value of 0 is considered as "missing". - - m.ndim == 1 returns a `Vector` - - m.ndim == 2 returns a `Matrix` + - m.ndim == 1 returns a ``Vector`` + - m.ndim == 2 returns a ``Matrix`` - m.ndim > 2 raises an error dtype is inferred from m.dtype @@ -65,8 +65,8 @@ def to_numpy(m): # pragma: no cover (deprecated) """Create a dense numpy array from a sparse Vector or Matrix. .. deprecated:: 2023.2.0 - `to_numpy` will be removed in a future release. - Use `Vector.to_dense` or `Matrix.to_dense` instead. + ``to_numpy`` will be removed in a future release. + Use ``Vector.to_dense`` or ``Matrix.to_dense`` instead. Will be removed in version 2023.10.0 or later Missing values will become 0 in the output. diff --git a/graphblas/select/__init__.py b/graphblas/select/__init__.py index c7a1897f5..72aa8d226 100644 --- a/graphblas/select/__init__.py +++ b/graphblas/select/__init__.py @@ -57,9 +57,9 @@ def _resolve_expr(expr, callname, opname): def _match_expr(parent, expr): - """Match expressions to rewrite `A.select(A < 5)` into select expression. + """Match expressions to rewrite ``A.select(A < 5)`` into select expression. - The argument must match the parent, so this _won't_ be rewritten: `A.select(B < 5)` + The argument must match the parent, so this _won't_ be rewritten: ``A.select(B < 5)`` """ args = expr.args op = expr.op @@ -83,7 +83,7 @@ def value(expr): Example usage: >>> gb.select.value(A > 0) - The example will dispatch to `gb.select.valuegt(A, 0)` + The example will dispatch to ``gb.select.valuegt(A, 0)`` while being nicer to read. """ return _resolve_expr(expr, "value", "value") @@ -97,7 +97,7 @@ def row(expr): Example usage: >>> gb.select.row(A <= 5) - The example will dispatch to `gb.select.rowle(A, 5)` + The example will dispatch to ``gb.select.rowle(A, 5)`` while being potentially nicer to read. """ return _resolve_expr(expr, "row", "row") @@ -111,7 +111,7 @@ def column(expr): Example usage: >>> gb.select.column(A <= 5) - The example will dispatch to `gb.select.colle(A, 5)` + The example will dispatch to ``gb.select.colle(A, 5)`` while being potentially nicer to read. """ return _resolve_expr(expr, "column", "col") @@ -125,7 +125,7 @@ def index(expr): Example usage: >>> gb.select.index(v <= 5) - The example will dispatch to `gb.select.indexle(v, 5)` + The example will dispatch to ``gb.select.indexle(v, 5)`` while being potentially nicer to read. """ return _resolve_expr(expr, "index", "index") diff --git a/graphblas/ss/_core.py b/graphblas/ss/_core.py index 441458a42..ec5a89504 100644 --- a/graphblas/ss/_core.py +++ b/graphblas/ss/_core.py @@ -12,7 +12,7 @@ class _graphblas_ss: - """Used in `_expect_type`.""" + """Used in ``_expect_type``.""" _graphblas_ss.__name__ = "graphblas.ss" @@ -33,8 +33,8 @@ def diag(x, k=0, dtype=None, *, name=None, **opts): The Vector to assign to the diagonal, or the Matrix from which to extract the diagonal. k : int, default 0 - Diagonal in question. Use `k>0` for diagonals above the main diagonal, - and `k<0` for diagonals below the main diagonal. + Diagonal in question. Use ``k>0`` for diagonals above the main diagonal, + and ``k<0`` for diagonals below the main diagonal. See Also -------- @@ -71,9 +71,9 @@ def concat(tiles, dtype=None, *, name=None, **opts): Concatenate a 2D list of Matrix objects into a new Matrix, or a 1D list of Vector objects into a new Vector. To concatenate into existing objects, - use ``Matrix.ss.concat`` or `Vector.ss.concat`. + use ``Matrix.ss.concat`` or ``Vector.ss.concat``. - Vectors may be used as `Nx1` Matrix objects when creating a new Matrix. + Vectors may be used as ``Nx1`` Matrix objects when creating a new Matrix. This performs the opposite operation as ``split``. diff --git a/graphblas/tests/test_io.py b/graphblas/tests/test_io.py index 24df55e9d..df94c6469 100644 --- a/graphblas/tests/test_io.py +++ b/graphblas/tests/test_io.py @@ -167,7 +167,11 @@ def test_matrix_to_from_networkx(): def test_mmread_mmwrite(engine): if engine == "fmm" and fmm is None: # pragma: no cover (import) pytest.skip("needs fast_matrix_market") - from scipy.io.tests import test_mmio + try: + from scipy.io.tests import test_mmio + except ImportError: + # Test files are mysteriously missing from some conda-forge builds + pytest.skip("scipy.io.tests.test_mmio unavailable :(") p31 = 2**31 p63 = 2**63 diff --git a/graphblas/viz.py b/graphblas/viz.py index d8a96d343..fafeae5f0 100644 --- a/graphblas/viz.py +++ b/graphblas/viz.py @@ -67,7 +67,7 @@ def draw(m): # pragma: no cover def spy(M, *, centered=False, show=True, figure=None, axes=None, figsize=None, **kwargs): - """Plot the sparsity pattern of a Matrix using `matplotlib.spy`. + """Plot the sparsity pattern of a Matrix using ``matplotlib.spy``. See: - https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.spy.html @@ -106,8 +106,8 @@ def spy(M, *, centered=False, show=True, figure=None, axes=None, figsize=None, * def datashade(M, agg="count", *, width=None, height=None, opts_kwargs=None, **kwargs): """Interactive plot of the sparsity pattern of a Matrix using hvplot and datashader. - The `datashader` library rasterizes large data into a 2d grid of pixels. Each pixel - may contain multiple data points, which are combined by an aggregator (`agg="count"`). + The ``datashader`` library rasterizes large data into a 2d grid of pixels. Each pixel + may contain multiple data points, which are combined by an aggregator (``agg="count"``). Common aggregators are "count", "sum", "mean", "min", and "max". See full list here: - https://datashader.org/api.html#reductions diff --git a/scripts/check_versions.sh b/scripts/check_versions.sh index 3809eb805..dda7adbaa 100755 --- a/scripts/check_versions.sh +++ b/scripts/check_versions.sh @@ -7,11 +7,11 @@ conda search 'numpy[channel=conda-forge]>=1.24.3' conda search 'pandas[channel=conda-forge]>=2.0.1' conda search 'scipy[channel=conda-forge]>=1.10.1' conda search 'networkx[channel=conda-forge]>=3.1' -conda search 'awkward[channel=conda-forge]>=2.1.4' +conda search 'awkward[channel=conda-forge]>=2.2.0' conda search 'sparse[channel=conda-forge]>=0.14.0' conda search 'fast_matrix_market[channel=conda-forge]>=1.5.1' conda search 'numba[channel=conda-forge]>=0.56.4' conda search 'pyyaml[channel=conda-forge]>=6.0' -conda search 'flake8-bugbear[channel=conda-forge]>=23.3.23' +conda search 'flake8-bugbear[channel=conda-forge]>=23.5.9' conda search 'flake8-simplify[channel=conda-forge]>=0.20.0' # conda search 'python[channel=conda-forge]>=3.8 *pypy*'