From 0165f110c016c0b50ba79142d33374bad3cf4e9c Mon Sep 17 00:00:00 2001 From: Nils Homer Date: Sat, 25 Nov 2023 11:58:23 -0700 Subject: [PATCH 1/2] Add FastxRecord to the docs Add FastxRecord to API documentation and improve its docstring with proper Sphinx-style documentation including attributes, parameters, and usage examples. --- doc/api.rst | 3 +++ pysam/libcfaidx.pyx | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+) diff --git a/doc/api.rst b/doc/api.rst index 4a27a768..95bce82a 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -259,6 +259,9 @@ FASTQ files .. autoclass:: pysam.FastxFile :members: +.. autoclass:: pysam.FastxRecord + :members: + .. autoclass:: pysam.FastqProxy :members: diff --git a/pysam/libcfaidx.pyx b/pysam/libcfaidx.pyx index 48445d11..16f4d0c0 100644 --- a/pysam/libcfaidx.pyx +++ b/pysam/libcfaidx.pyx @@ -420,6 +420,44 @@ cdef class FastxRecord: A record must contain a name and a sequence. If either of them are None, a ValueError is raised on writing. + Attributes + ---------- + name : str + The name (identifier) of the record. + sequence : str + The nucleotide or amino acid sequence. + comment : str or None + An optional comment or description following the name. + quality : str or None + Quality scores as an ASCII-encoded string (for FASTQ records). + None for FASTA records. + + 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, From b825d46ef64d52fcbb613bd0b299cb2395cb8c94 Mon Sep 17 00:00:00 2001 From: John Marshall Date: Tue, 14 Jul 2026 23:04:10 +1200 Subject: [PATCH 2/2] Move the attribute documentation to `cdef public ...` in the .pxd file, where Cython will use it to populate these attributes' docstrings. Remove embedsignature=True as it caused these to get bad type information. This unembedding removes the `self` parameter from the documentation of seven existing methods in libcfaidx.pyx, but this arguably improves them. Add/improve the documentation of the other Python-visible FastxRecord methods. Add a __repr__() method for ease of observation. --- pysam/libcfaidx.pxd | 11 ++++++++++- pysam/libcfaidx.pyx | 34 ++++++++++++++-------------------- 2 files changed, 24 insertions(+), 21 deletions(-) diff --git a/pysam/libcfaidx.pxd b/pysam/libcfaidx.pxd index 8380e90e..1ce555db 100644 --- a/pysam/libcfaidx.pxd +++ b/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=*) diff --git a/pysam/libcfaidx.pyx b/pysam/libcfaidx.pyx index 16f4d0c0..6b00002b 100644 --- a/pysam/libcfaidx.pyx +++ b/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,28 +419,20 @@ cdef class FastxRecord: A record must contain a name and a sequence. If either of them are None, a ValueError is raised on writing. - Attributes - ---------- - name : str - The name (identifier) of the record. - sequence : str - The nucleotide or amino acid sequence. - comment : str or None - An optional comment or description following the name. - quality : str or None - Quality scores as an ASCII-encoded string (for FASTQ records). - None for FASTA records. - 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. @@ -457,7 +448,6 @@ cdef class FastxRecord: ACGT + IIII - """ def __init__(self, name=None, @@ -505,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: @@ -529,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: @@ -547,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 @@ -568,7 +563,6 @@ cdef class FastxFile: Raises ------ - IOError if file could not be opened