python-graphblas 2023.3.0__py3-none-any.whl → 2023.7.0__py3-none-any.whl

graphblas/__init__.py

@@ -137,7 +137,21 @@ def _init(backend_arg, blocking, automatic=False):
 
     backend = backend_arg
     if backend in {"suitesparse", "suitesparse-vanilla"}:
-        from suitesparse_graphblas import ffi, initialize, is_initialized, lib
+        try:
+            from suitesparse_graphblas import ffi, initialize, is_initialized, lib
+        except ImportError:  # pragma: no cover (import)
+            raise ImportError(
+                f"suitesparse_graphblas is required for {backend!r} backend. "
+                "It may be installed with pip or conda:\n\n"
+                "    $ pip install suitesparse-graphblas\n"
+                "    $ conda install -c conda-forge python-suitesparse-graphblas\n\n"
+                "SuiteSparse:GraphBLAS is the primary C implementation and backend of "
+                "python-graphblas and is what we recommend to most users. If you are "
+                "installing python-graphblas with pip, we recommend installing with one "
+                "of the following to automatically include suitespare-graphblas:\n\n"
+                "    $ pip install python-graphblas[suitesparse]\n"
+                "    $ pip install python-graphblas[default]"
+            ) from None
 
         if is_initialized():
             mode = ffi.new("int32_t*")

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 @@ Custom recipes (specific to SuiteSparse:GraphBLAS):
     - 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))

graphblas/binary/__init__.py

@@ -1,5 +1,7 @@
 # All items are dynamically added by classes in operator.py
 # This module acts as a container of BinaryOp instances
+from ..core import _supports_udfs
+
 _delayed = {}
 _delayed_commutes_to = {
     "absfirst": "abssecond",
@@ -9,6 +11,15 @@ _delayed_commutes_to = {
     "rpow": "pow",
 }
 _deprecated = {}
+_udfs = {
+    "absfirst",
+    "abssecond",
+    "binom",
+    "floordiv",
+    "isclose",
+    "rfloordiv",
+    "rpow",
+}
 
 
 def __dir__():
@@ -50,6 +61,11 @@ def __getattr__(key):
         ss = import_module(".ss", __name__)
         globals()["ss"] = ss
         return ss
+    if not _supports_udfs and key in _udfs:
+        raise AttributeError(
+            f"module {__name__!r} unable to compile UDF for {key!r}; "
+            "install numba for UDF support"
+        )
     raise AttributeError(f"module {__name__!r} has no attribute {key!r}")
 
 

graphblas/binary/numpy.py

@@ -10,6 +10,7 @@ import numpy as _np
 from .. import _STANDARD_OPERATOR_NAMES
 from .. import binary as _binary
 from .. import config as _config
+from ..core import _supports_udfs
 
 _delayed = {}
 _binary_names = {
@@ -130,7 +131,13 @@ _commutes_to = {
 
 
 def __dir__():
-    return globals().keys() | _delayed.keys() | _binary_names
+    if not _supports_udfs and not _config["mapnumpy"]:
+        # float_power is special: it's constructed from builtin operators
+        return globals().keys() | {"float_power"}  # FLAKY COVERAGE
+    attrs = _delayed.keys() | _binary_names
+    if not _supports_udfs:
+        attrs &= _numpy_to_graphblas.keys()
+    return attrs | globals().keys()
 
 
 def __getattr__(name):
@@ -141,7 +148,7 @@ def __getattr__(name):
         return rv
     if name not in _binary_names:
         raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-    if _config.get("mapnumpy") and name in _numpy_to_graphblas:
+    if _config.get("mapnumpy") and name in _numpy_to_graphblas or name == "float_power":
         if name == "float_power":
             from ..core.operator import binary
             from ..dtypes import FP64
@@ -166,6 +173,11 @@ def __getattr__(name):
             globals()[name] = new_op
         else:
             globals()[name] = getattr(_binary, _numpy_to_graphblas[name])
+    elif not _supports_udfs:
+        raise AttributeError(
+            f"module {__name__!r} unable to compile UDF for {name!r}; "
+            "install numba for UDF support"
+        )
     else:
         numpy_func = getattr(_np, name)
 

graphblas/binary/ss.py

@@ -1,3 +1,6 @@
 from ..core import operator
+from ..core.ss.binary import register_new  # noqa: F401
+
+_delayed = {}
 
 del operator

graphblas/core/__init__.py

@@ -1,3 +1,12 @@
+try:
+    import numba
+except ImportError:
+    _has_numba = _supports_udfs = False
+else:
+    _has_numba = _supports_udfs = True
+    del numba
+
+
 def __getattr__(name):
     if name in {"ffi", "lib", "NULL"}:
         from .. import _autoinit

graphblas/core/agg.py

@@ -1,14 +1,14 @@
 """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.
 
 """
 import warnings
 
-from .operator.agg import *
+from .operator.agg import *  # pylint: disable=wildcard-import,unused-wildcard-import
 
 warnings.warn(
     "graphblas.core.agg namespace is deprecated; please use graphblas.core.operator.agg instead.",

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:
 

graphblas/core/base.py

@@ -348,7 +348,7 @@ class BaseType:
                         return
                     if opts:
                         # Ignore opts for now
-                        descriptor_lookup(**opts)
+                        desc = descriptor_lookup(**opts)
                     self.value = expr
                     return
 
@@ -371,7 +371,7 @@ class BaseType:
                 else:
                     if opts:
                         # Ignore opts for now
-                        descriptor_lookup(**opts)
+                        desc = descriptor_lookup(**opts)
                     self.value = expr
                     return
             else:
@@ -571,7 +571,7 @@ class BaseExpression:
         ):
             if opts:
                 # Ignore opts for now
-                descriptor_lookup(**opts)
+                desc = descriptor_lookup(**opts)  # noqa: F841 (keep desc in scope for context)
             if self._is_scalar and self._value._is_cscalar != is_cscalar:
                 return self._value.dup(is_cscalar=is_cscalar, name=name)
             rv = self._value

graphblas/core/descriptor.py

@@ -26,6 +26,7 @@ class Descriptor:
         self.mask_structure = mask_structure
         self.transpose_first = transpose_first
         self.transpose_second = transpose_second
+        self._context = None  # Used by SuiteSparse:GraphBLAS 8
 
     @property
     def _carg(self):

graphblas/{dtypes.py → core/dtypes.py}

@@ -1,17 +1,16 @@
-import warnings as _warnings
+import warnings
 
-import numba as _numba
-import numpy as _np
-from numpy import find_common_type as _find_common_type
-from numpy import promote_types as _promote_types
+import numpy as np
+from numpy import promote_types, result_type
 
-from . import backend
-from .core import NULL as _NULL
-from .core import ffi as _ffi
-from .core import lib as _lib
+from .. import backend, dtypes
+from ..core import NULL, _has_numba, ffi, lib
+
+if _has_numba:
+    import numba
 
 # Default assumption unless FC32/FC64 are found in lib
-_supports_complex = hasattr(_lib, "GrB_FC64") or hasattr(_lib, "GxB_FC64")
+_supports_complex = hasattr(lib, "GrB_FC64") or hasattr(lib, "GxB_FC64")
 
 
 class DataType:
@@ -23,7 +22,7 @@ class DataType:
         self.gb_name = gb_name
         self.c_type = c_type
         self.numba_type = numba_type
-        self.np_type = _np.dtype(np_type)
+        self.np_type = np.dtype(np_type) if np_type is not None else None
 
     def __repr__(self):
         return self.name
@@ -59,7 +58,7 @@ class DataType:
 
     @property
     def _is_anonymous(self):
-        return globals().get(self.name) is not self
+        return getattr(dtypes, self.name, None) is not self
 
     @property
     def _is_udt(self):
@@ -77,27 +76,29 @@ class DataType:
 def register_new(name, dtype):
     if not name.isidentifier():
         raise ValueError(f"`name` argument must be a valid Python identifier; got: {name!r}")
-    if name in _registry or name in globals():
+    if name in _registry or hasattr(dtypes, name):
         raise ValueError(f"{name!r} name for dtype is unavailable")
     rv = register_anonymous(dtype, name)
     _registry[name] = rv
-    globals()[name] = rv
+    setattr(dtypes, name, rv)
     return rv
 
 
 def register_anonymous(dtype, name=None):
     try:
-        dtype = _np.dtype(dtype)
+        dtype = np.dtype(dtype)
     except TypeError:
         if isinstance(dtype, dict):
             # Allow dtypes such as `{'x': int, 'y': float}` for convenience
-            dtype = _np.dtype([(key, lookup_dtype(val).np_type) for key, val in dtype.items()])
+            dtype = np.dtype(
+                [(key, lookup_dtype(val).np_type) for key, val in dtype.items()], align=True
+            )
         elif isinstance(dtype, str) and "[" in dtype and dtype.endswith("]"):
             # Allow dtypes such as `"INT64[3, 4]"` for convenience
             base_dtype, shape = dtype.split("[", 1)
             base_dtype = lookup_dtype(base_dtype)
-            shape = _np.lib.format.safe_eval(f"[{shape}")
-            dtype = _np.dtype((base_dtype.np_type, shape))
+            shape = np.lib.format.safe_eval(f"[{shape}")
+            dtype = np.dtype((base_dtype.np_type, shape))
         else:
             raise
     if dtype in _registry:
@@ -111,112 +112,194 @@ def register_anonymous(dtype, name=None):
     if dtype.hasobject:
         raise ValueError("dtype must not allow Python objects")
 
-    from .exceptions import check_status_carg
+    from ..exceptions import check_status_carg
 
-    gb_obj = _ffi.new("GrB_Type*")
+    gb_obj = ffi.new("GrB_Type*")
     if backend == "suitesparse":
         # We name this so that we can serialize and deserialize UDTs
         # We don't yet have C definitions
         np_repr = _dtype_to_string(dtype).encode()
-        if len(np_repr) > _lib.GxB_MAX_NAME_LEN:
+        if len(np_repr) > lib.GxB_MAX_NAME_LEN:
             msg = (
                 f"UDT repr is too large to serialize ({len(repr(dtype).encode())} > "
-                f"{_lib.GxB_MAX_NAME_LEN})."
+                f"{lib.GxB_MAX_NAME_LEN})."
             )
             if name is not None:
-                np_repr = name.encode()[: _lib.GxB_MAX_NAME_LEN]
+                np_repr = name.encode()[: lib.GxB_MAX_NAME_LEN]
             else:
-                np_repr = np_repr[: _lib.GxB_MAX_NAME_LEN]
-            _warnings.warn(
+                np_repr = np_repr[: lib.GxB_MAX_NAME_LEN]
+            warnings.warn(
                 f"{msg}.  It will use the following name, "
                 f"and the dtype may need to be specified when deserializing: {np_repr}",
                 stacklevel=2,
             )
-        status = _lib.GxB_Type_new(gb_obj, dtype.itemsize, np_repr, _NULL)
+        status = lib.GxB_Type_new(gb_obj, dtype.itemsize, np_repr, NULL)
     else:
-        status = _lib.GrB_Type_new(gb_obj, dtype.itemsize)
+        status = lib.GrB_Type_new(gb_obj, dtype.itemsize)
     check_status_carg(status, "Type", gb_obj[0])
 
     # For now, let's use "opaque" unsigned bytes for the c type.
     if name is None:
         name = _default_name(dtype)
-    numba_type = _numba.typeof(dtype).dtype
+    numba_type = numba.typeof(dtype).dtype if _has_numba else None
     rv = DataType(name, gb_obj, None, f"uint8_t[{dtype.itemsize}]", numba_type, dtype)
     _registry[gb_obj] = rv
     _registry[dtype] = rv
-    _registry[numba_type] = rv
-    _registry[numba_type.name] = rv
+    if _has_numba:
+        _registry[numba_type] = rv
+        _registry[numba_type.name] = rv
     return rv
 
 
-BOOL = DataType("BOOL", _lib.GrB_BOOL, "GrB_BOOL", "_Bool", _numba.types.bool_, _np.bool_)
-INT8 = DataType("INT8", _lib.GrB_INT8, "GrB_INT8", "int8_t", _numba.types.int8, _np.int8)
-UINT8 = DataType("UINT8", _lib.GrB_UINT8, "GrB_UINT8", "uint8_t", _numba.types.uint8, _np.uint8)
-INT16 = DataType("INT16", _lib.GrB_INT16, "GrB_INT16", "int16_t", _numba.types.int16, _np.int16)
+BOOL = DataType(
+    "BOOL",
+    lib.GrB_BOOL,
+    "GrB_BOOL",
+    "_Bool",
+    numba.types.bool_ if _has_numba else None,
+    np.bool_,
+)
+INT8 = DataType(
+    "INT8", lib.GrB_INT8, "GrB_INT8", "int8_t", numba.types.int8 if _has_numba else None, np.int8
+)
+UINT8 = DataType(
+    "UINT8",
+    lib.GrB_UINT8,
+    "GrB_UINT8",
+    "uint8_t",
+    numba.types.uint8 if _has_numba else None,
+    np.uint8,
+)
+INT16 = DataType(
+    "INT16",
+    lib.GrB_INT16,
+    "GrB_INT16",
+    "int16_t",
+    numba.types.int16 if _has_numba else None,
+    np.int16,
+)
 UINT16 = DataType(
-    "UINT16", _lib.GrB_UINT16, "GrB_UINT16", "uint16_t", _numba.types.uint16, _np.uint16
+    "UINT16",
+    lib.GrB_UINT16,
+    "GrB_UINT16",
+    "uint16_t",
+    numba.types.uint16 if _has_numba else None,
+    np.uint16,
+)
+INT32 = DataType(
+    "INT32",
+    lib.GrB_INT32,
+    "GrB_INT32",
+    "int32_t",
+    numba.types.int32 if _has_numba else None,
+    np.int32,
 )
-INT32 = DataType("INT32", _lib.GrB_INT32, "GrB_INT32", "int32_t", _numba.types.int32, _np.int32)
 UINT32 = DataType(
-    "UINT32", _lib.GrB_UINT32, "GrB_UINT32", "uint32_t", _numba.types.uint32, _np.uint32
+    "UINT32",
+    lib.GrB_UINT32,
+    "GrB_UINT32",
+    "uint32_t",
+    numba.types.uint32 if _has_numba else None,
+    np.uint32,
+)
+INT64 = DataType(
+    "INT64",
+    lib.GrB_INT64,
+    "GrB_INT64",
+    "int64_t",
+    numba.types.int64 if _has_numba else None,
+    np.int64,
 )
-INT64 = DataType("INT64", _lib.GrB_INT64, "GrB_INT64", "int64_t", _numba.types.int64, _np.int64)
 # _Index (like UINT64) is for internal use only and shouldn't be exposed to the user
 _INDEX = DataType(
-    "UINT64", _lib.GrB_UINT64, "GrB_Index", "GrB_Index", _numba.types.uint64, _np.uint64
+    "UINT64",
+    lib.GrB_UINT64,
+    "GrB_Index",
+    "GrB_Index",
+    numba.types.uint64 if _has_numba else None,
+    np.uint64,
 )
 UINT64 = DataType(
-    "UINT64", _lib.GrB_UINT64, "GrB_UINT64", "uint64_t", _numba.types.uint64, _np.uint64
+    "UINT64",
+    lib.GrB_UINT64,
+    "GrB_UINT64",
+    "uint64_t",
+    numba.types.uint64 if _has_numba else None,
+    np.uint64,
+)
+FP32 = DataType(
+    "FP32",
+    lib.GrB_FP32,
+    "GrB_FP32",
+    "float",
+    numba.types.float32 if _has_numba else None,
+    np.float32,
+)
+FP64 = DataType(
+    "FP64",
+    lib.GrB_FP64,
+    "GrB_FP64",
+    "double",
+    numba.types.float64 if _has_numba else None,
+    np.float64,
 )
-FP32 = DataType("FP32", _lib.GrB_FP32, "GrB_FP32", "float", _numba.types.float32, _np.float32)
-FP64 = DataType("FP64", _lib.GrB_FP64, "GrB_FP64", "double", _numba.types.float64, _np.float64)
 
-if _supports_complex and hasattr(_lib, "GxB_FC32"):
+if _supports_complex and hasattr(lib, "GxB_FC32"):
     FC32 = DataType(
-        "FC32", _lib.GxB_FC32, "GxB_FC32", "float _Complex", _numba.types.complex64, _np.complex64
+        "FC32",
+        lib.GxB_FC32,
+        "GxB_FC32",
+        "float _Complex",
+        numba.types.complex64 if _has_numba else None,
+        np.complex64,
     )
-if _supports_complex and hasattr(_lib, "GrB_FC32"):  # pragma: no cover (unused)
+if _supports_complex and hasattr(lib, "GrB_FC32"):  # pragma: no cover (unused)
     FC32 = DataType(
-        "FC32", _lib.GrB_FC32, "GrB_FC32", "float _Complex", _numba.types.complex64, _np.complex64
+        "FC32",
+        lib.GrB_FC32,
+        "GrB_FC32",
+        "float _Complex",
+        numba.types.complex64 if _has_numba else None,
+        np.complex64,
     )
-if _supports_complex and hasattr(_lib, "GxB_FC64"):
+if _supports_complex and hasattr(lib, "GxB_FC64"):
     FC64 = DataType(
         "FC64",
-        _lib.GxB_FC64,
+        lib.GxB_FC64,
         "GxB_FC64",
         "double _Complex",
-        _numba.types.complex128,
-        _np.complex128,
+        numba.types.complex128 if _has_numba else None,
+        np.complex128,
     )
-if _supports_complex and hasattr(_lib, "GrB_FC64"):  # pragma: no cover (unused)
+if _supports_complex and hasattr(lib, "GrB_FC64"):  # pragma: no cover (unused)
     FC64 = DataType(
         "FC64",
-        _lib.GrB_FC64,
+        lib.GrB_FC64,
         "GrB_FC64",
         "double _Complex",
-        _numba.types.complex128,
-        _np.complex128,
+        numba.types.complex128 if _has_numba else None,
+        np.complex128,
     )
 
 # Used for testing user-defined functions
 _sample_values = {
-    INT8: _np.int8(1),
-    UINT8: _np.uint8(1),
-    INT16: _np.int16(1),
-    UINT16: _np.uint16(1),
-    INT32: _np.int32(1),
-    UINT32: _np.uint32(1),
-    INT64: _np.int64(1),
-    UINT64: _np.uint64(1),
-    FP32: _np.float32(0.5),
-    FP64: _np.float64(0.5),
-    BOOL: _np.bool_(True),
+    INT8: np.int8(1),
+    UINT8: np.uint8(1),
+    INT16: np.int16(1),
+    UINT16: np.uint16(1),
+    INT32: np.int32(1),
+    UINT32: np.uint32(1),
+    INT64: np.int64(1),
+    UINT64: np.uint64(1),
+    FP32: np.float32(0.5),
+    FP64: np.float64(0.5),
+    BOOL: np.bool_(True),
 }
 if _supports_complex:
     _sample_values.update(
         {
-            FC32: _np.complex64(complex(0, 0.5)),
-            FC64: _np.complex128(complex(0, 0.5)),
+            FC32: np.complex64(complex(0, 0.5)),
+            FC64: np.complex128(complex(0, 0.5)),
         }
     )
 
@@ -246,8 +329,9 @@ for dtype in _dtypes_to_register:
     _registry[dtype.gb_name.lower()] = dtype
     _registry[dtype.c_type] = dtype
     _registry[dtype.c_type.upper()] = dtype
-    _registry[dtype.numba_type] = dtype
-    _registry[dtype.numba_type.name] = dtype
+    if _has_numba:
+        _registry[dtype.numba_type] = dtype
+        _registry[dtype.numba_type.name] = dtype
     val = _sample_values[dtype]
     _registry[val.dtype] = dtype
     _registry[val.dtype.name] = dtype
@@ -303,19 +387,11 @@ def unify(type1, type2, *, is_left_scalar=False, is_right_scalar=False):
     if type1 is type2:
         return type1
     if is_left_scalar:
-        scalar_types = [type1.np_type]
-        array_types = []
-    elif not is_right_scalar:
-        # Using `promote_types` is faster than `find_common_type`
-        return lookup_dtype(_promote_types(type1.np_type, type2.np_type))
-    else:
-        scalar_types = []
-        array_types = [type1.np_type]
-    if is_right_scalar:
-        scalar_types.append(type2.np_type)
-    else:
-        array_types.append(type2.np_type)
-    return lookup_dtype(_find_common_type(array_types, scalar_types))
+        if not is_right_scalar:
+            return lookup_dtype(result_type(np.array(0, type1.np_type), type2.np_type))
+    elif is_right_scalar:
+        return lookup_dtype(result_type(type1.np_type, np.array(0, type2.np_type)))
+    return lookup_dtype(promote_types(type1.np_type, type2.np_type))
 
 
 def _default_name(dtype):
@@ -345,7 +421,7 @@ def _dtype_to_string(dtype):
     >>> dtype == new_dtype
     True
     """
-    if isinstance(dtype, _np.dtype) and dtype not in _registry:
+    if isinstance(dtype, np.dtype) and dtype not in _registry:
         np_type = dtype
     else:
         dtype = lookup_dtype(dtype)
@@ -354,11 +430,11 @@ def _dtype_to_string(dtype):
         np_type = dtype.np_type
     s = str(np_type)
     try:
-        if _np.dtype(_np.lib.format.safe_eval(s)) == np_type:  # pragma: no branch (safety)
+        if np.dtype(np.lib.format.safe_eval(s)) == np_type:  # pragma: no branch (safety)
             return s
     except Exception:
         pass
-    if _np.dtype(np_type.str) != np_type:  # pragma: no cover (safety)
+    if np.dtype(np_type.str) != np_type:  # pragma: no cover (safety)
         raise ValueError(f"Unable to reliably convert dtype to string and back: {dtype}")
     return repr(np_type.str)
 
@@ -373,5 +449,5 @@ def _string_to_dtype(s):
         return lookup_dtype(s)
     except Exception:
         pass
-    np_type = _np.dtype(_np.lib.format.safe_eval(s))
+    np_type = np.dtype(np.lib.format.safe_eval(s))
     return lookup_dtype(np_type)

graphblas/core/expr.py

@@ -421,7 +421,7 @@ class Updater:
             # Fast path using assignElement
             if self.opts:
                 # Ignore opts for now
-                descriptor_lookup(**self.opts)
+                desc = descriptor_lookup(**self.opts)  # noqa: F841 (keep desc in scope for context)
             self.parent._assign_element(resolved_indexes, obj)
         else:
             mask = self.kwargs.get("mask")

graphblas/core/formatting.py

@@ -880,6 +880,7 @@ def format_index_expression_html(expr):
         computed = get_expr_result(expr, html=True)
         if "__EXPR__" in computed:
             return computed.replace("<tt>__EXPR__</tt>", topline)
+        # BRANCH NOT COVERED
 
     keys = []
     values = []

graphblas/core/mask.py

@@ -35,7 +35,7 @@ class Mask:
         """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 @@ class Mask:
         >>> 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 @@ class Mask:
     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 @@ class Mask:
     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