Add FastxRecord to the docs

doc/api.rst

@@ -259,6 +259,9 @@ FASTQ files
 .. autoclass:: pysam.FastxFile
    :members:
 
+.. autoclass:: pysam.FastxRecord
+   :members:
+
 .. autoclass:: pysam.FastqProxy
    :members:
 

pysam/libcfaidx.pxd

@@ -42,7 +42,16 @@ cdef class FastxRecord:
     """
     Python container for pysam.libcfaidx.FastqProxy with persistence.
     """
-    cdef public str comment, quality, sequence, name
+    cdef public str comment
+    """str or None : An optional comment or description following the name."""
+    cdef public str quality
+    """str or None : Quality scores as an ASCII-encoded string (for FASTQ records).
+    None for FASTA records.
+    """
+    cdef public str sequence
+    """str : The nucleotide or amino acid sequence."""
+    cdef public str name
+    """str : The name (identifier) of the record."""
     cdef cython.str to_string(self)
     cdef cython.str tostring(self)
     cpdef array.array get_quality_array(self, int offset=*)

pysam/libcfaidx.pyx

@@ -1,5 +1,4 @@
 # cython: language_level=3
-# cython: embedsignature=True
 ###############################################################################
 ###############################################################################
 # Cython wrapper for SAM/BAM/CRAM files based on htslib
@@ -420,6 +419,35 @@ cdef class FastxRecord:
     A record must contain a name and a sequence. If either of them are
     None, a ValueError is raised on writing.
 
+    Parameters
+    ----------
+    name : str, optional
+        The name of the record.
+
+    comment : str, optional
+        An optional comment for the record.
+
+    sequence : str, optional
+        The sequence of the record.
+
+    quality : str, optional
+        Quality scores as an ASCII-encoded string.
+
+    proxy : FastqProxy, optional
+        If provided, initialize from an existing FastqProxy object.
+
+    Examples
+    --------
+    >>> record = pysam.FastxRecord(name="read1", sequence="ACGT")
+    >>> print(record)
+    >read1
+    ACGT
+    >>> record = pysam.FastxRecord(name="read1", sequence="ACGT", quality="IIII")
+    >>> print(record)
+    @read1
+    ACGT
+    +
+    IIII
     """
     def __init__(self,
                  name=None,
@@ -467,16 +495,18 @@ cdef class FastxRecord:
         return self.to_string()
 
     def set_name(self, name):
+        """Set the record's name, which must not be None."""
         if name is None:
             raise ValueError("FastxRecord must have a name and not None")
         self.name = name
 
     def set_comment(self, comment):
+        """Set the record's optional comment."""
         self.comment = comment
 
     def set_sequence(self, sequence, quality=None):
-        """set sequence of this record.
-
+        """Set the sequence and optionally the quality scores of this record.
+        If `quality` is specified, it must be the same length as `sequence`.
         """
         self.sequence = sequence
         if quality is not None:
@@ -491,6 +521,9 @@ cdef class FastxRecord:
     def __str__(self):
         return self.to_string()
 
+    def __repr__(self):
+        return f"<{type(self).__name__}(name={self.name!r}, comment={self.comment!r}, sequence={self.sequence!r}, quality={self.quality!r})>"
+
     cpdef array.array get_quality_array(self, int offset=33):
         '''return quality values as array after subtracting offset.'''
         if self.quality is None:
@@ -509,12 +542,12 @@ cdef class FastxFile:
 
     This file object permits iterating over all entries in the
     file. Random access is not implemented. The iteration returns
-    objects of type :class:`FastqProxy`
+    objects of type :class:`FastxRecord` or :class:`FastqProxy`
+    as determined by `persist`.
 
     Parameters
     ----------
-
-    filename : string
+    filename : str
         Filename of fasta/fastq file to be opened.
 
     persist : bool
@@ -530,7 +563,6 @@ cdef class FastxFile:
 
     Raises
     ------
-
     IOError
         if file could not be opened