Fix numpydoc lints

pyproject.toml

@@ -103,6 +103,10 @@ checks = [
 ]
 exclude = [
   '\._[_a-z0-9]+$',  # Do not validate private or special methods
+  # Dataclasses: Numpydoc complains about additional constructor parameters,
+  # but the constructor is absent
+  'sdf.Metadata\.Key',
+  'header.Header',
 ]
 
 [tool.pytest.ini_options]

src/biotite/structure/io/general.py

@@ -34,7 +34,7 @@ def load_structure(file_path, template=None, **kwargs):
         The path to structure file.
     template : AtomArray or AtomArrayStack or file-like object or str, optional
         Only required when reading a trajectory file.
-    kwargs
+    **kwargs
         Additional parameters will be passed to either the
         :func:`get_structure()` or :func:`read()` method of the file
         object.
@@ -146,7 +146,7 @@ def save_structure(file_path, array, **kwargs):
         The path to structure file.
     array : AtomArray or AtomArrayStack
         The structure to be saved.
-    kwargs
+    **kwargs
         Additional parameters will be passed to the respective `set_structure`
         method.
 

src/biotite/structure/io/gro/file.py

@@ -48,7 +48,6 @@ class GROFile(TextFile):
     >>> file = GROFile()
     >>> file.set_structure(array_stack_mod)
     >>> file.write(os.path.join(path_to_directory, "1l2y_mod.gro"))
-
     """
 
     def get_model_count(self):
@@ -89,13 +88,13 @@ def get_structure(self, model=None):
             The return type depends on the `model` parameter.
         """
 
-        def get_atom_line_i(model_start_i, model_atom_counts):
+        def _get_atom_line_i(model_start_i, model_atom_counts):
             """
             Helper function to get the indices of all atoms for a model
             """
             return np.arange(model_start_i + 1, model_start_i + 1 + model_atom_counts)
 
-        def set_box_dimen(box_param):
+        def _set_box_dimen(box_param):
             """
             Helper function to create the box vectors from the values
             in the GRO file
@@ -145,7 +144,7 @@ def set_box_dimen(box_param):
 
             # Line indices for annotation determination is determined
             # from model 1
-            annot_i = get_atom_line_i(model_start_i[0], length)
+            annot_i = _get_atom_line_i(model_start_i[0], length)
         else:
             if model == 0:
                 raise ValueError("The model index must not be 0")
@@ -160,7 +159,7 @@ def set_box_dimen(box_param):
             length = model_atom_counts[model - 1]
             array = AtomArray(length)
 
-            annot_i = get_atom_line_i(model_start_i[model - 1], length)
+            annot_i = _get_atom_line_i(model_start_i[model - 1], length)
 
         # Replace empty strings for elements with guessed types
         # i is index in array, line_i is line index
@@ -183,11 +182,11 @@ def set_box_dimen(box_param):
             # Box is stored in last line (after coordinates)
             box_i = atom_i[-1] + 1
             box_param = [float(e) * 10 for e in self.lines[box_i].split()]
-            array.box = set_box_dimen(box_param)
+            array.box = _set_box_dimen(box_param)
 
         elif isinstance(array, AtomArrayStack):
             for m in range(len(model_start_i)):
-                atom_i = get_atom_line_i(model_start_i[m], model_atom_counts[m])
+                atom_i = _get_atom_line_i(model_start_i[m], model_atom_counts[m])
                 for i, line_i in enumerate(atom_i):
                     line = self.lines[line_i]
                     array.coord[m, i, 0] = float(line[20:28]) * 10
@@ -196,7 +195,7 @@ def set_box_dimen(box_param):
                 # Box is stored in last line (after coordinates)
                 box_i = atom_i[-1] + 1
                 box_param = [float(e) * 10 for e in self.lines[box_i].split()]
-                box = set_box_dimen(box_param)
+                box = _set_box_dimen(box_param)
                 # Create a box in the stack if not already existing
                 # and the box is not a dummy
                 if box is not None:

src/biotite/structure/io/mol/convert.py

@@ -52,7 +52,7 @@ def set_structure(
     ----------
     mol_file : MOLFile
         The MOL file.
-    array : AtomArray
+    atoms : AtomArray
         The array to be saved into this file.
         Must have an associated :class:`BondList`.
         Bond type fallback for the *Bond block*, if a

src/biotite/structure/io/mol/ctab.py

@@ -50,7 +50,7 @@ def read_structure_from_ctab(ctab_lines):
     ----------
     ctab_lines : lines of str
         The lines containing the *ctab*.
-        Must begin with the *counts* line and end with the `M END` line
+        Must begin with the *counts* line and end with the `M END` line.
 
     Returns
     -------
@@ -65,7 +65,6 @@ def read_structure_from_ctab(ctab_lines):
     `<https://discover.3ds.com/sites/default/files/2020-08/biovia_ctfileformats_2020.pdf>`_.
 
     .. footbibliography::
-
     """
     match _get_version(ctab_lines[0]):
         case "V2000":
@@ -113,7 +112,6 @@ def write_structure_to_ctab(atoms, default_bond_type=BondType.ANY, version=None)
     `<https://discover.3ds.com/sites/default/files/2020-08/biovia_ctfileformats_2020.pdf>`_.
 
     .. footbibliography::
-
     """
     if isinstance(atoms, AtomArrayStack):
         raise TypeError(

src/biotite/structure/io/mol/mol.py

@@ -122,7 +122,7 @@ def set_structure(self, atoms, default_bond_type=BondType.ANY, version=None):
 
         Parameters
         ----------
-        array : AtomArray
+        atoms : AtomArray
             The array to be saved into this file.
             Must have an associated :class:`BondList`.
         default_bond_type : BondType, optional

src/biotite/structure/io/mol/sdf.py

@@ -78,7 +78,6 @@ class Metadata(MutableMapping):
     >>> print(metadata[Metadata.Key(number=42, name="bar")])
     dolor sit amet,
     consectetur
-
     """
 
     @dataclass(frozen=True, kw_only=True)
@@ -144,12 +143,18 @@ def __post_init__(self):
         @staticmethod
         def deserialize(text):
             """
-            Create an object by deserializing the given text content.
+            Create a :class:`Metadata.Key` object by deserializing the given text
+            content.
 
             Parameters
             ----------
-            content : str
+            text : str
                 The content to be deserialized.
+
+            Returns
+            -------
+            key : Metadata.Key
+                The parsed key.
             """
             # Omit the leading '>'
             key_components = text[1:].split()
@@ -207,12 +212,17 @@ def __init__(self, metadata=None):
     @staticmethod
     def deserialize(text):
         """
-        Create an object by deserializing the given text content.
+        Create a :class:`Metadata` objtect by deserializing the given text content.
 
         Parameters
         ----------
-        content : str
+        text : str
             The content to be deserialized.
+
+        Returns
+        -------
+        metadata : Metadata
+            The parsed metadata.
         """
         metadata = {}
         current_key = None
@@ -430,12 +440,17 @@ def metadata(self, metadata):
     @staticmethod
     def deserialize(text):
         """
-        Create an object by deserializing the given text content.
+        Create an :class:`SDRecord` by deserializing the given text content.
 
         Parameters
         ----------
-        content : str
+        text : str
             The content to be deserialized.
+
+        Returns
+        -------
+        record : SDRecord
+            The parsed record.
         """
         lines = text.splitlines()
         ctab_end = _get_ctab_stop(lines)
@@ -494,7 +509,7 @@ def set_structure(self, atoms, default_bond_type=BondType.ANY, version=None):
 
         Parameters
         ----------
-        array : AtomArray
+        atoms : AtomArray
             The array to be saved into this file.
             Must have an associated :class:`BondList`.
         default_bond_type : BondType, optional
@@ -539,6 +554,13 @@ class SDFile(File, MutableMapping):
     :class:`SDRecord` object via :func:`get_structure()` or
     :func:`set_structure()`, respectively.
 
+    Parameters
+    ----------
+    records : dict (str -> SDRecord), optional
+        The initial records of the file.
+        Maps the record names to the corresponding :class:`SDRecord` objects.
+        By default no initial records are added.
+
     Attributes
     ----------
     record : CIFBlock
@@ -732,12 +754,17 @@ def record(self):
     @staticmethod
     def deserialize(text):
         """
-        Create an object by deserializing the given text content.
+        Create an :class:`SDFile` by deserializing the given text content.
 
         Parameters
         ----------
-        content : str
+        text : str
             The content to be deserialized.
+
+        Returns
+        -------
+        file_object : SDFile
+            The parsed file.
         """
         lines = text.splitlines()
         record_ends = np.array(

src/biotite/structure/io/pdb/convert.py

@@ -89,14 +89,13 @@ def get_structure(
     -------
     array : AtomArray or AtomArrayStack
         The return type depends on the `model` parameter.
-
     """
     return pdb_file.get_structure(model, altloc, extra_fields, include_bonds)
 
 
 def set_structure(pdb_file, array, hybrid36=False):
     """
-    write an :class:`AtomArray` or :class:`AtomArrayStack` into a
+    Write an :class:`AtomArray` or :class:`AtomArrayStack` into a
     :class:`PDBFile`.
 
     This function is a thin wrapper around the :class:`PDBFile` method
@@ -114,7 +113,7 @@ def set_structure(pdb_file, array, hybrid36=False):
     array : AtomArray or AtomArrayStack
         The structure to be written. If a stack is given, each array in
         the stack will be in a separate model.
-    hybrid36: boolean, optional
+    hybrid36 : boolean, optional
         Defines wether the file should be written in hybrid-36 format.
 
     Notes

src/biotite/structure/io/pdb/file.py

@@ -72,8 +72,8 @@ class PDBFile(TextFile):
 
     See Also
     --------
-    CIFFile
-    BinaryCIFFile
+    CIFFile : Interface to CIF files, a modern replacement for PDB files.
+    BinaryCIFFile : Interface to BinaryCIF files, a binary variant of CIF files.
 
     Examples
     --------
@@ -597,7 +597,7 @@ def set_structure(self, array, hybrid36=False):
             The array or stack to be saved into this file. If a stack
             is given, each array in the stack is saved as separate
             model.
-        hybrid36: bool, optional
+        hybrid36 : bool, optional
             Defines wether the file should be written in hybrid-36
             format.
 

src/biotite/structure/io/pdbx/bcif.py

@@ -256,6 +256,11 @@ def as_array(self, dtype=None, masked_value=None):
             ``MaskValue.INAPPLICABLE`` or ``MaskValue.MISSING``.
             By default, masked elements are converted to ``'.'`` or
             ``'?'`` depending on the :class:`MaskValue`.
+
+        Returns
+        -------
+        array : ndarray
+            The column data as array.
         """
         if dtype is None:
             dtype = self._data.array.dtype
@@ -341,12 +346,15 @@ class BinaryCIFCategory(_HierarchicalContainer):
         into a :class:`BinaryCIFColumn`).
         By default, an empty category is created.
         Each column must have the same length.
+    row_count : int, optional
+        The number of rows in the category.
 
     Attributes
     ----------
     row_count : int
         The number of rows in the category, i.e. the length of each
         column.
+        By default, the row count is determined when the first column is added.
 
     Examples
     --------
@@ -526,6 +534,19 @@ class BinaryCIFFile(File, _HierarchicalContainer):
     object, use the high-level :func:`get_structure()` or
     :func:`set_structure()` function respectively.
 
+    Parameters
+    ----------
+    blocks : dict (str -> BinaryCIFBlock), optional
+        The initial blocks of the file.
+        Maps the block names to the corresponding :class:`BinaryCIFBlock` objects.
+        By default no initial blocks are added.
+
+    Attributes
+    ----------
+    block : BinaryCIFBlock
+        The sole block of the file.
+        If the file contains multiple blocks, an exception is raised.
+
     Notes
     -----
     The content of *BinaryCIF* files are lazily deserialized:
@@ -534,12 +555,6 @@ class BinaryCIFFile(File, _HierarchicalContainer):
     The decoded :class:`BinaryCIFBlock`/:class:`BinaryCIFCategory`
     objects are cached for subsequent accesses.
 
-    Attributes
-    ----------
-    block : BinaryCIFBlock
-        The sole block of the file.
-        If the file contains multiple blocks, an exception is raised.
-
     Examples
     --------
     Read a *BinaryCIF* file and access its content:

src/biotite/structure/io/pdbx/cif.py

@@ -215,6 +215,11 @@ def as_array(self, dtype=str, masked_value=None):
             ``MaskValue.INAPPLICABLE`` or ``MaskValue.MISSING``.
             By default, masked elements are converted to ``'.'`` or
             ``'?'`` depending on the :class:`MaskValue`.
+
+        Returns
+        -------
+        array : ndarray
+            The column data as array.
         """
         if self._mask is None:
             return self._data.array.astype(dtype, copy=False)
@@ -721,6 +726,19 @@ class CIFFile(_Component, File, MutableMapping):
     use the high-level :func:`get_structure()` or
     :func:`set_structure()` function respectively.
 
+    Parameters
+    ----------
+    blocks : dict (str -> CIFBlock), optional
+        The initial blocks of the file.
+        Maps the block names to the corresponding :class:`CIFBlock` objects.
+        By default no initial blocks are added.
+
+    Attributes
+    ----------
+    block : CIFBlock
+        The sole block of the file.
+        If the file contains multiple blocks, an exception is raised.
+
     Notes
     -----
     The content of CIF files are lazily deserialized:
@@ -731,12 +749,6 @@ class CIFFile(_Component, File, MutableMapping):
     The deserialized :class:`CIFBlock`/:class:`CIFCategory` objects
     are cached for subsequent accesses.
 
-    Attributes
-    ----------
-    block : CIFBlock
-        The sole block of the file.
-        If the file contains multiple blocks, an exception is raised.
-
     Examples
     --------
     Read a CIF file and access its content: