[python] Clean-up docstrings in python-spec (#275)

* Fix docstrings to match arg order of method signatures

* Fixes docstring formatting to match Google style

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jp-dark

python-spec/src/somacore/base.py

@@ -35,7 +35,10 @@ def open(
             context: The Context value to use when opening the object.
             platform_config: Platform configuration options specific to
                 this open operation.
-        Returns: The SOMA object, opened for reading.
+
+        Returns:
+            The SOMA object, opened for reading.
+
         Lifecycle: maturing
         """
         ...
@@ -50,6 +53,7 @@ def exists(cls, uri: str, *, context: Any | None = None) -> bool:
         Returns:
             True if the object exists and is of the correct type.
             False if the object does not exist, or is of a different type.
+
         Lifecycle: maturing
         """
         ...

python-spec/src/somacore/collection.py

@@ -58,8 +58,10 @@ def create(
 
         Args:
             uri: The URI where the collection will be created.
+
         Returns:
             The newly created collection, opened for writing.
+
         Lifecycle: maturing
         """
         ...
@@ -99,6 +101,7 @@ def add_new_collection(
         platform_config: options.PlatformConfig | None = None,
     ) -> "BaseCollection":
         """Creates a new sub-collection of this collection.
+
         To add an existing collection as a sub-element of this collection,
         use :meth:`set` or indexed access (``coll[name] = value``) instead.
 
@@ -140,7 +143,6 @@ def add_new_collection(
             kind: The type of child that should be added.
             uri: If provided, overrides the default URI that would be used
                 to create this object. This may be absolute or relative.
-                If not provided,
             platform_config: Platform-specific configuration options used
                 when creating the child.
 
@@ -247,7 +249,8 @@ def set(self, key: str, value: _Elem, *, use_relative_uri: bool | None = None) -
                 is not possible at all, the collection should raise an error.
                 If ``False``, will always use an absolute URI.
 
-        Returns: ``self``, to enable method chaining.
+        Returns:
+            ``self``, to enable method chaining.
 
         Lifecycle: maturing
         """

python-spec/src/somacore/coordinates.py

@@ -26,7 +26,7 @@ def unit(self) -> str | None:
 class CoordinateSpace(Protocol):
     """A coordinate space for spatial data.
 
-    Args:
+    Attributes:
         axes: The axes of the coordinate system in order.
 
     Lifecycle: experimental
@@ -58,7 +58,7 @@ def axis_names(self) -> tuple[str, ...]:
 class CoordinateTransform(Protocol):
     """A coordinate transformation from one coordinate space to another.
 
-    Args:
+    Attributes:
         input_axes: The names of the axes for the input coordinate space.
         output_axes: The names of the axes for the output coordinate space.
 

python-spec/src/somacore/data.py

@@ -53,26 +53,22 @@ def create(
 
         Args:
             uri: The URI where the dataframe will be created.
-
             schema: Arrow schema defining the per-column schema. This schema
                 must define all columns, including columns to be named as index
                 columns.  If the schema includes types unsupported by the SOMA
                 implementation, an error will be raised.
-
+            domain: A sequence of tuples specifying the domain of each index
+                column. Each tuple must be a pair consisting of the minimum
+                and maximum values storable in the index column. This sequence
+                must have the same length as ``index_column_names``. Use
+                ``None`` for string index columns when the implementation does
+                not support string domains.
             index_column_names: A list of column names to use as user-defined
                 index columns (e.g., ``['cell_type', 'tissue_type']``).
                 All named columns must exist in the schema, and at least one
                 index column name is required.
-
-            domain:
-                A sequence of tuples specifying the domain of each index
-                column. Each tuple must be a pair consisting of the minimum
-                and maximum values storable in the index column. This sequence
-                must have the same length as ``index_column_names``. Use ``None`` for string
-                index columns when the implementation does not support string domains.
             platform_config: platform-specific configuration; keys are SOMA
                 implementation names.
-
             context: Other implementation-specific configuration.
 
         Returns:
@@ -110,10 +106,10 @@ def read(
                 The default of ``None`` represents no filter. Value filter
                 syntax is implementation-defined; see the documentation
                 for the particular SOMA implementation for details.
+
         Returns:
             A :class:`ReadIter` of :class:`pa.Table`s.
 
-
         **Indexing:**
 
         Indexing is performed on a per-column basis for each indexed column.
@@ -203,7 +199,8 @@ def write(
                 the index columns. The schema for the values must match
                 the schema for the ``DataFrame``.
 
-        Returns: ``self``, to enable method chaining.
+        Returns:
+            ``self``, to enable method chaining.
 
         Lifecycle: maturing
         """
@@ -231,7 +228,8 @@ def index_column_names(self) -> tuple[str, ...]:
     def domain(self) -> tuple[tuple[Any, Any], ...]:
         """The allowable range of values in each index column.
 
-        Returns: a tuple of minimum and maximum values, inclusive,
+        Returns:
+            A tuple of minimum and maximum values, inclusive,
             storable on each index column of the dataframe.
 
         Lifecycle: maturing
@@ -266,7 +264,8 @@ def create(
                 All lengths must be in the positive int64 range. The shape can
                 be increased after creation using :meth:`resize`.
 
-        Returns: The newly created array, opened for writing.
+        Returns:
+            The newly created array, opened for writing.
 
         Lifecycle: maturing
         """
@@ -308,8 +307,7 @@ def schema(self) -> pa.Schema:
 
 @runtime_checkable
 class DenseNDArray(NDArray, Protocol):
-    """
-    An N-dimensional array stored densely.
+    """An N-dimensional array stored densely.
 
     Lifecycle: maturing
     """
@@ -340,7 +338,8 @@ def read(
             platform_config: platform-specific configuration; keys are SOMA
                 implementation names.
 
-        Returns: The data over the requested range as a tensor.
+        Returns:
+            The data over the requested range as a tensor.
 
         **Indexing:**
 
@@ -386,7 +385,10 @@ def write(
                 See :meth:`read` for details about indexing.
             values: The values to be written to the subarray.  Must have
                 the same shape as ``coords``, and matching type to the array.
-        Returns: ``self``, to enable method chaining.
+
+        Returns:
+            ``self``, to enable method chaining.
+
         Lifecycle: maturing
         """
         ...
@@ -420,15 +422,16 @@ def read(
             coords: A per-dimension sequence of coordinates defining
                 the range to be read.
             batch_size: The size of batches that should be returned from a read.
-            See :class:`options.BatchSize` for details.
+                See :class:`options.BatchSize` for details.
             partitions: Specifies that this is part of a partitioned read,
                 and which partition to include, if present.
             result_order: the order to return results, specified as a
                 :class:`~options.ResultOrder` or its string value.
             platform_config: platform-specific configuration; keys are SOMA
                 implementation names.
 
-        Returns: The data that was requested in a :class:`SparseRead`,
+        Returns:
+            The data that was requested in a :class:`SparseRead`,
             allowing access in any supported format.
 
         **Indexing:**
@@ -483,7 +486,8 @@ def write(
             platform_config: platform-specific configuration; keys are SOMA
                 implementation names.
 
-        Returns: ``self``, to enable method chaining.
+        Returns:
+            ``self``, to enable method chaining.
 
         Lifecycle: maturing
         """

python-spec/src/somacore/query/query.py

@@ -29,8 +29,7 @@
 
 
 class AxisColumnNames(TypedDict, total=False):
-    """
-    Specifies column names for experiment axis query read operations.
+    """Specifies column names for experiment axis query read operations.
 
     Lifecycle: maturing
     """
@@ -170,12 +169,14 @@ def varp(self, layer: str) -> SparseRead:
 
     def obsm(self, layer: str) -> SparseRead:
         """Returns an ``obsm`` layer as a sparse read.
+
         Lifecycle: maturing
         """
         ...
 
     def varm(self, layer: str) -> SparseRead:
         """Returns a ``varm`` layer as a sparse read.
+
         Lifecycle: maturing
         """
         ...
@@ -208,25 +209,19 @@ def to_anndata(
         varp_layers: Sequence[str] = (),
         drop_levels: bool = False,
     ) -> AnnData:
-        """
-        Executes the query and return result as an ``AnnData`` in-memory object.
+        """Executes the query and return result as an ``AnnData`` in-memory object.
 
         Args:
             X_name: The X layer to read and return in the ``X`` slot.
             column_names: The columns in the ``var`` and ``obs`` dataframes
                 to read.
             X_layers: Additional X layers to read and return
                 in the ``layers`` slot.
-            obsm_layers:
-                Additional obsm layers to read and return in the obsm slot.
-            obsp_layers:
-                Additional obsp layers to read and return in the obsp slot.
-            varm_layers:
-                Additional varm layers to read and return in the varm slot.
-            varp_layers:
-                Additional varp layers to read and return in the varp slot.
-            drop_levels:
-                Indicate whether unused categories on axis frames should be
+            obsm_layers: Additional obsm layers to read and return in the obsm slot.
+            obsp_layers: Additional obsp layers to read and return in the obsp slot.
+            varm_layers: Additional varm layers to read and return in the varm slot.
+            varp_layers: Additional varp layers to read and return in the varp slot.
+            drop_levels: Indicate whether unused categories on axis frames should be
                 dropped. By default, False, the categories which are present
                 in the SOMA Experiment and not present in the query output
                 are not dropped.
@@ -257,8 +252,7 @@ def __exit__(self, *_: Any) -> None: ...
 
 @runtime_checkable
 class AxisIndexer(Protocol):
-    """
-    Given a query, provides index-building services for obs/var axis.
+    """Given a query, provides index-building services for obs/var axis.
 
     Lifecycle: maturing
     """

python-spec/src/somacore/scene.py

@@ -128,9 +128,9 @@ def add_new_geometry_dataframe(
             subcollection: The name, or sequence of names, of the subcollection the
                 dataframe is stored in.
             transform: The coordinate transformation from the scene to the dataframe.
-            uri: If provided, overrides the default URI what would be used to create
-                this object. This may be aboslution or relative.
-            kwargs: Additional keyword arugments as specified in
+            uri: If provided, overrides the default URI that would be used to create
+                this object. This may be absolute or relative.
+            kwargs: Additional keyword arguments as specified in
                 :meth:`spatial.GeometryDataFrame.create`.
 
         Returns:
@@ -159,9 +159,9 @@ def add_new_multiscale_image(
             subcollection: The name, or sequence of names, of the subcollection the
                 dataframe is stored in.
             transform: The coordinate transformation from the scene to the dataframe.
-            uri: If provided, overrides the default URI what would be used to create
-                this object. This may be aboslution or relative.
-            kwargs: Additional keyword arugments as specified in
+            uri: If provided, overrides the default URI that would be used to create
+                this object. This may be absolute or relative.
+            kwargs: Additional keyword arguments as specified in
                 :meth:`spatial.MultiscaleImage.create`.
 
         Returns:
@@ -192,17 +192,16 @@ def add_new_point_cloud_dataframe(
                 'transcripts', subcollection=['var', 'RNA'], **kwargs
             )
 
-
         See :meth:`add_new_collection` for details about child URIs.
 
         Args:
             key: The name of the point cloud dataframe.
             subcollection: The name, or sequence of names, of the subcollection the
                 dataframe is stored in.
             transform: The coordinate transformation from the scene to the dataframe.
-            uri: If provided, overrides the default URI what would be used to create
-                this object. This may be aboslution or relative.
-            kwargs: Additional keyword arugments as specified in
+            uri: If provided, overrides the default URI that would be used to create
+                this object. This may be absolute or relative.
+            kwargs: Additional keyword arguments as specified in
                 :meth:`spatial.PointCloudDataFrame.create`.
 
         Returns:
@@ -234,9 +233,9 @@ def set_transform_to_geometry_dataframe(
 
         Args:
             key: The name of the geometry dataframe.
-            transform: The coordinate transformation from the scene to the dataframe.
             subcollection: The name, or sequence of names, of the subcollection the
                 dataframe is stored in. Defaults to ``'obsl'``.
+            transform: The coordinate transformation from the scene to the dataframe.
             coordinate_space: Optional coordinate space for the dataframe. This will
                 replace the existing coordinate space of the dataframe.