Add public docstring to Bio.Seq #1251

Gasta88 · 2017-05-22T11:33:34Z

As mentioned in issue #1203 I've added public docstring to Bio.Seq module.

codecov · 2017-05-22T11:53:20Z

Codecov Report

Merging #1251 into master will decrease coverage by <.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master    #1251      +/-   ##
==========================================
- Coverage   79.59%   79.58%   -0.01%     
==========================================
  Files         323      323              
  Lines       51701    51701              
==========================================
- Hits        41149    41147       -2     
- Misses      10552    10554       +2

Impacted Files	Coverage Δ
Bio/Seq.py	`98.35% <100%> (ø)`	⬆️
Bio/NeuralNetwork/Gene/Schema.py	`71.07% <0%> (-0.83%)`	⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 06e15e6...672897c. Read the comment docs.

peterjc · 2017-05-22T11:58:22Z

Bio/Seq.py

@@ -62,7 +63,7 @@ def _maketrans(complement_mapping):


 class Seq(object):
-    """A read-only sequence object (essentially a string with an alphabet).
+    """Create a read-only sequence object (essentially a string with an alphabet).


The __init__ could be said to create the object, but that does not make sense for the class docstring. You could just remove the A and use Read-only sequence object (essentially a string with an alphabet).

peterjc · 2017-05-22T11:59:17Z

Bio/Seq.py

@@ -198,12 +199,12 @@ def __eq__(self, other):
        return str(self) == str(other)

    def __ne__(self, other):
-        """Not equal, see __eq__ documentation."""
+        """Compare sequences with a not-equal operand, see __eq__ documentation."""


Is this really clearer (likewise for the other special methods)?

How about """Implement the XYZ operand.""" without any reference to __eq__?

That seems like an improvement.

peterjc · 2017-05-22T12:00:01Z

Bio/Seq.py

@@ -513,7 +514,7 @@ def rfind(self, sub, start=0, end=sys.maxsize):
        return str(self).rfind(sub_str, start, end)

    def startswith(self, prefix, start=0, end=sys.maxsize):
-        """Does the Seq start with the given prefix?  Returns True/False.
+        """Reurn True if the Seq starts with the given prefix, False otherwise.


Typo (Return)

peterjc · 2017-05-22T12:00:17Z

Bio/Seq.py

@@ -544,7 +545,7 @@ def startswith(self, prefix, start=0, end=sys.maxsize):
            return str(self).startswith(prefix_str, start, end)

    def endswith(self, suffix, start=0, end=sys.maxsize):
-        """Does the Seq end with the given suffix?  Returns True/False.
+        """Return True if the Seq end with the given suffix, False otherwise.


end --> ends

peterjc · 2017-05-22T12:01:12Z

Bio/Seq.py

@@ -1139,7 +1140,7 @@ def ungap(self, gap=None):


 class UnknownSeq(Seq):
-    """A read-only sequence object of known length but unknown contents.
+    """Create a read-only sequence object of known length but unknown contents.


See comment for the Seq class docstring, Create ... is not quite right here.

peterjc · 2017-05-22T12:01:43Z

Bio/Seq.py

@@ -1391,7 +1394,7 @@ def complement(self):
        return self

    def reverse_complement(self):
-        """The reverse complement of an unknown nucleotide equals itself.
+        """Return the reverse complement of an unknown nucleotide equals itself.


The new version does not make sense to me.

The function itself does not make sense.

How about Return the reverse complement of an unknown nucleotide,which equals itself.?

If you think the function does not make sense, then clearly the current docstring is not clear enough. How about:

def reverse_complement(self): """Return the reverse complement of an unknown sequence. The reverse complement of an unknown nucleotide equals itself: >>> from Bio.Seq import UnknownSeq >>> from Bio.Alphabet import generic_dna >>> example = UnknownSeq(6, generic_dna) >>> print(example) NNNNNN >>> print(example.reverse_complement()) NNNNNN """

Much better, thanks.

peterjc · 2017-05-22T12:02:11Z

Bio/Seq.py

@@ -1556,7 +1559,7 @@ def ungap(self, gap=None):


 class MutableSeq(object):
-    """An editable sequence object (with an alphabet).
+    """Create an editable sequence object (with an alphabet).


Again, Create ... is not appropriate.

peterjc · 2017-05-22T12:03:06Z

Bio/Seq.py

@@ -1986,7 +2001,7 @@ def transcribe(dna):


 def back_transcribe(rna):
-    """Back-transcribes an RNA sequence into DNA.
+    """Return the RNA back-transcribed sequence into DNA.


How about Return the RNA sequence back-transcribed into DNA.

peterjc · 2017-05-22T12:04:23Z

Bio/Seq.py

@@ -2009,7 +2024,7 @@ def back_transcribe(rna):

 def _translate_str(sequence, table, stop_symbol="*", to_stop=False,
                   cds=False, pos_stop="X", gap=None):
-    """Helper function to translate a nucleotide string (PRIVATE).
+    """Translate a nucleotide to string (PRIVATE).


"a nucleotide" implies a single base letter.

How about Translate nucleotide string into a protein string (PRIVATE).

Gasta88 · 2017-05-22T20:02:30Z

File edited.

peterjc · 2017-05-22T20:48:02Z

Bio/Seq.py


-        >>> my_nuc = UnknownSeq(10)
-        >>> my_nuc


Is there a tab here? The display on GitHub looks different for some reason...

Well, if it was a tab it is being removed in this change so never mind.

Squashed commit of biopython#1251. Cross reference biopython#1203.

Add public docstring to Bio.Seq

49ef501

peterjc requested changes May 22, 2017

View reviewed changes

Update Seq.py

672897c

peterjc reviewed May 22, 2017

View reviewed changes

peterjc merged commit 9129c0f into biopython:master May 22, 2017

peterjc pushed a commit to peterjc/biopython that referenced this pull request May 23, 2017

Add and update public docstrings in Bio.Seq

3cf875b

Squashed commit of biopython#1251. Cross reference biopython#1203.

MarkusPiotrowski pushed a commit to MarkusPiotrowski/biopython that referenced this pull request Oct 31, 2017

Add and update public docstrings in Bio.Seq

30afbac

Squashed commit of biopython#1251. Cross reference biopython#1203.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add public docstring to Bio.Seq #1251

Add public docstring to Bio.Seq #1251

Gasta88 commented May 22, 2017

codecov bot commented May 22, 2017 •

edited

Loading

peterjc May 22, 2017

peterjc May 22, 2017

Gasta88 May 22, 2017

peterjc May 22, 2017

peterjc May 22, 2017

peterjc May 22, 2017

peterjc May 22, 2017

peterjc May 22, 2017

Gasta88 May 22, 2017

peterjc May 22, 2017

Gasta88 May 22, 2017

peterjc May 22, 2017

peterjc May 22, 2017

peterjc May 22, 2017

Gasta88 commented May 22, 2017

peterjc May 22, 2017

peterjc May 22, 2017

Add public docstring to Bio.Seq #1251

Add public docstring to Bio.Seq #1251

Conversation

Gasta88 commented May 22, 2017

codecov bot commented May 22, 2017 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Gasta88 commented May 22, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented May 22, 2017 •

edited

Loading