[python] Misc. formatting fix-ups (#3287)

apis/python/src/tiledbsoma/__init__.py

@@ -83,7 +83,6 @@
 - :class:`NotImplementedError` will be raised when the requested function or method
   is unsupported.
 - :class:`SOMAError` is a base class for all SOMA-specific errors.
-- ``TileDBError`` will be raised for many TileDB-specific errors.
 
 Most errors will raise an appropriate Python error, e.g., ::class:`TypeError` or
 :class:`ValueError`.

apis/python/src/tiledbsoma/_common_nd_array.py

@@ -88,7 +88,7 @@ def create(
     def shape(self) -> Tuple[int, ...]:
         """Returns capacity of each dimension, always a list of length ``ndim``.
         This will not necessarily match the bounds of occupied cells within the array.
-        Rather, it is the bounds outside of which no data may be written.
+        Rather, it is the bounds outside of which no data may be read or written.
 
         Lifecycle:
             Maturing.

apis/python/src/tiledbsoma/_dataframe.py

@@ -428,7 +428,7 @@ def _maybe_soma_joinid_maxshape(self) -> Optional[int]:
     def tiledbsoma_has_upgraded_domain(self) -> bool:
         """Returns true if the array has the upgraded resizeable domain feature
         from TileDB-SOMA 1.15: the array was created with this support, or it has
-        had ``.tiledbsoma_upgrade_domain`` applied to it.
+        had ``tiledbsoma_upgrade_domain`` applied to it.
 
         Lifecycle:
             Maturing.

apis/python/src/tiledbsoma/_indexer.py

@@ -29,15 +29,15 @@
 def tiledbsoma_build_index(
     data: IndexerDataType, *, context: Optional["SOMATileDBContext"] = None
 ) -> IndexLike:
-    """Initialize re-indexer for provided indices.
+    """Initialize re-indexer for provided indices (deprecated).
 
-    Deprecated. Provides the same functionality as the``IntIndexer`` class.
+    Provides the same functionality as the``IntIndexer`` class.
 
     Args:
        data:
            Integer keys used to build the index (hash) table.
        context:
-           ``SOMATileDBContext`` object containing concurrecy level.
+           ``SOMATileDBContext`` object containing concurrency level.
 
     Lifecycle:
         Deprecated.
@@ -62,7 +62,7 @@ def __init__(
            data:
                Integer keys used to build the index (hash) table.
            context:
-               ``SOMATileDBContext`` object containing concurrecy level.
+               ``SOMATileDBContext`` object containing concurrency level.
 
         Lifecycle:
             Maturing.

apis/python/src/tiledbsoma/_sparse_nd_array.py

@@ -528,7 +528,7 @@ def _dim_capacity_and_extent(
 
     def used_shape(self) -> Tuple[Tuple[int, int], ...]:
         """
-        Retrieve the range of indexes for a dimension that were explicitly written.
+        Retrieve the range of indexes for a dimension that were explicitly written (deprecated).
         Compare this to ``shape`` which returns the available/writable capacity.
 
         This method is deprecated as of TileDB-SOMA 1.13, and will be removed in TileDB-SOMA 1.15.

apis/python/src/tiledbsoma/io/ingest.py

@@ -279,7 +279,7 @@ def from_h5ad(
           ``obs`` / ``var``.
 
           NOTE: it is not necessary for this column to be the index-column
-          name in the input AnnData objects ``obs``/``var``.
+          name in the input AnnData object's ``obs``/``var``.
 
         X_layer_name: SOMA array name for the AnnData's ``X`` matrix.
 
@@ -759,7 +759,7 @@ def append_obs(
     Writes new rows to an existing ``obs`` dataframe. (This is distinct from ``update_obs``
     which mutates the entirety of the ``obs`` dataframe, e.g. to add/remove columns.)
 
-    Example:
+    Example::
 
         rd = tiledbsoma.io.register_anndatas(
             exp_uri,
@@ -817,7 +817,7 @@ def append_var(
     Writes new rows to an existing ``var`` dataframe. (This is distinct from ``update_var``
     which mutates the entirety of the ``var`` dataframe, e.g. to add/remove columns.)
 
-    Example:
+    Example::
 
         rd = tiledbsoma.io.register_anndatas(
             exp_uri,
@@ -886,7 +886,7 @@ def append_X(
     with ``update_obs`` and ``update_var``, as an itemized alternative to doing
     ``from_anndata`` with a registration mapping supplied.
 
-    Example:
+    Example::
 
         rd = tiledbsoma.io.register_anndatas(
             exp_uri,
@@ -1413,18 +1413,17 @@ def update_obs(
     type for the column, the entire update will raise a ``ValueError`` exception.
 
     Args:
-        exp: The :class:`SOMAExperiment` whose ``obs`` is to be updated. Must
-        be opened for write.
+        exp: The :class:`SOMAExperiment` whose ``obs`` is to be updated. Must be opened for write.
 
         new_data: a Pandas dataframe with the desired contents.
 
         context: Optional :class:`SOMATileDBContext` containing storage parameters, etc.
 
-        platform_config: Platform-specific options used to update this array, provided
-        in the form ``{"tiledb": {"create": {"dataframe_dim_zstd_level": 7}}}``
+        platform_config: Platform-specific options used to update this array, provided in the form
+            ``{"tiledb": {"create": {"dataframe_dim_zstd_level": 7}}}``
 
-        default_index_name: What to call the ``new_data`` index column if it is
-        nameless in Pandas, or has name ``"index"``.
+        default_index_name: What to call the ``new_data`` index column if it is nameless in Pandas,
+            or has name ``"index"``.
 
     Returns:
         None
@@ -1473,11 +1472,11 @@ def update_var(
 
         context: Optional :class:`SOMATileDBContext` containing storage parameters, etc.
 
-        platform_config: Platform-specific options used to update this array, provided
-        in the form ``{"tiledb": {"create": {"dataframe_dim_zstd_level": 7}}}``
+        platform_config: Platform-specific options used to update this array, provided in the form
+            ``{"tiledb": {"create": {"dataframe_dim_zstd_level": 7}}}``
 
-        default_index_name: What to call the ``new_data`` index column if it is
-        nameless in Pandas, or has name ``"index"``.
+        default_index_name: What to call the ``new_data`` index column if it is nameless in Pandas,
+            or has name ``"index"``.
 
     Returns:
         None
@@ -1615,7 +1614,7 @@ def update_matrix(
     intended shape of written contents of the array match those of the existing
     data. The intended use-case is to replace updated numerical values.
 
-    Example:
+    Example::
 
         with tiledbsoma.Experiment.open(uri, "w") as exp:
             tiledbsoma.io.update_matrix(
@@ -1633,7 +1632,7 @@ def update_matrix(
         context: Optional :class:`SOMATileDBContext` containing storage parameters, etc.
 
         platform_config: Platform-specific options used to update this array, provided
-        in the form ``{"tiledb": {"create": {"dataframe_dim_zstd_level": 7}}}``
+            in the form ``{"tiledb": {"create": {"dataframe_dim_zstd_level": 7}}}``
 
     Returns:
         None
@@ -1740,8 +1739,7 @@ def add_matrix_to_collection(
     context: Optional[SOMATileDBContext] = None,
 ) -> None:
     """This is useful for adding X/obsp/varm/etc data, for example from
-    `Scanpy <https://scanpy.readthedocs.io/>`_'s ``scanpy.pp.normalize_total``,
-    ``scanpy.pp.log1p``, etc.
+    Scanpy's ``scanpy.pp.normalize_total``, ``scanpy.pp.log1p``, etc.
 
     Use ``ingest_mode="resume"`` to not error out if the schema already exists.
 

apis/python/src/tiledbsoma/io/outgest.py

@@ -69,8 +69,7 @@ def to_h5ad(
     obsm_varm_width_hints: Optional[Dict[str, Dict[str, int]]] = None,
     uns_keys: Optional[Sequence[str]] = None,
 ) -> None:
-    """Converts the experiment group to `AnnData <https://anndata.readthedocs.io/>`_
-    format and writes it to the specified ``.h5ad`` file.
+    """Converts the experiment group to AnnData format and writes it to the specified ``.h5ad`` file.
 
     Arguments are as in ``to_anndata``.
 
@@ -203,14 +202,14 @@ def to_anndata(
     obsm_varm_width_hints: Optional[Dict[str, Dict[str, int]]] = None,
     uns_keys: Optional[Sequence[str]] = None,
 ) -> ad.AnnData:
-    """Converts the experiment group to `AnnData <https://anndata.readthedocs.io/>`_
-    format. Choice of matrix formats is following what we often see in input
-    ``.h5ad`` files:
+    """Converts the experiment group to AnnData format.
+
+    The choice of matrix formats is following what we often see in input ``.h5ad`` files:
 
     * ``X`` as ``scipy.sparse.csr_matrix``
-    * ``obs``,``var`` as ``pandas.dataframe``
-    * ``obsm``,``varm`` arrays as ``numpy.ndarray``
-    * ``obsp``,``varp`` arrays as ``scipy.sparse.csr_matrix``
+    * ``obs``, ``var`` as ``pandas.dataframe``
+    * ``obsm``, ``varm`` arrays as ``numpy.ndarray``
+    * ``obsp``, ``varp`` arrays as ``scipy.sparse.csr_matrix``
 
     The ``X_layer_name`` is the name of the TileDB-SOMA measurement's ``X``
     collection which will be outgested to the resulting AnnData object's

apis/python/src/tiledbsoma/io/shaping.py

@@ -118,7 +118,7 @@ def resize_experiment(
     output_handle: Printable = cast(Printable, sys.stdout),
 ) -> bool:
     """For each dataframe contained within the SOMA ``Experiment`` pointed to by
-    the given URI, resizes the ``domain`` for the ``soma_joinid index column
+    the given URI, resizes the ``domain`` for the ``soma_joinid`` index column
     (if it is an indexed column) to match the desired new value.
 
     The desired new value may be the same size as at present, or bigger, but not
@@ -137,10 +137,10 @@ def resize_experiment(
     given dimension, or bigger, but not exceeding ``maxshape`` for the given
     dimension.
 
-    If any array has not been upgraded, then its resize will fail.
+    If any array has not been upgraded, then the experiment's ``resize`` will fail.
 
     Args:
-        uri: The URI of a SOMA :class:`Experiment``.
+        uri: The URI of a SOMA :class:`Experiment`.
         nobs: The desired new shape of the experiment's ``obs`` dataframe.
         nvars: The desired new shapes of the experiment's ``var`` dataframes.
             This should be a dict from measurement name to shape, e.g.

apis/python/src/tiledbsoma/stats.py

@@ -11,12 +11,12 @@
 
 
 def tiledbsoma_stats_json() -> str:
-    """Returns tiledbsoma stats as a JSON string"""
+    """Returns tiledbsoma stats as a JSON string."""
     # cast is needed for pybind11 things
     return cast(str, tiledbsoma_stats_string())
 
 
 def tiledbsoma_stats_as_py() -> ParsedStats:
-    """Returns tiledbsoma stats as a Python dict"""
+    """Returns tiledbsoma stats as a Python dict."""
     # cast is needed for pybind11 things
     return cast(ParsedStats, json.loads(tiledbsoma_stats_string()))