This is a test version of Biostars. For the public version, visit https://www.biostars.org.
Proper Way To Reading Python Documentation?

The problem with being biologists is that when we beginners start using a programming language we often learn it the wrong way. I started scripting a few months ago and I realise that the only reason things work is because I take a sledgehammer approach - trial and error 20 times until somehow the logic of some bit of example code finally gets through!

Any pro's have some advice on teaching us how to learn on our own? The python documentation is obviously fantastic, but its so full of jargon! some of it is general computer jargon and other bits are pythonic.

Either way I spend most of my time figuring out what the help file for a function even means, let alone understanding how to use it!

Example? here's a chunk from the help(sys.stdin).

How do I even begin to google any of what that means? whats with all the underscores?

Any good jargon buster sites? Or a tutorial just for the documentation?

 __init__(...)
 |      x.__init__(...) initializes x; see help(type(x)) for signature
 |   |  __iter__(...)
 |      x.__iter__() <==> iter(x)
 |  
 |  __repr__(...)
 |      x.__repr__() <==> repr(x)
 |  
 |  __setattr__(...)
 |      x.__setattr__('name', value) <==> x.name = value
 |  
 |  close(...)
 |      close() -> None or (perhaps) an integer.  Close the file.
 |
python biopython

Programming and documentation questions are not bioinformatics. However you have an accepted answer and some good information. Question closed!

They are if you would like to hear the perspective of biologists, not computer scientists. Closing it was not necessary, proved by the fact that there were 82 views in one day.

"Programming and documentation questions are not bioinformatics." Like discussion of sentence structure and language have no place in creative writing? I think programming and documentation questions ARE a part of bioinformatics for anyone who applies those things to biological questions - which is...all of us. What is the point of a discussion board that doesn't allow discussion?

3 answers

Start here.

I think that ignoring double underscore methods as a beginner is a mistake unless you intend to remain a beginner. These allow you to do interesting things with objects. You can get this behavior:

a = Interval(30, 40)
b = Interval(35, 50)

a
Interval(30, 40)

a == b
False
a in b
True

a[0], a[1]
(30, 40)

a < b
False
a < Interval(100, 200)
True

a("some", "args")
('called with ', ('some', 'args'))

len(a)
10

by defining the special methods in this class:

class Interval(object):
    __slots__ = ('start', 'end')

    def __init__(self, start, end):
        self.start = start
        self.end   = end

    def __lt__(self, other): # a completely leftOf b ?
        return self.end < other.start

    def __eq__(self, other):
        return self.start == other.start and self.end == other.end

    def __getitem__(self, i): # a[0], a[1]
        if not 0 <= I <= 1: raise IndexError
        if I == 0: return self.start
        if I == 1: return self.end

    def __repr__(self): # representation of the object:
        return "Interval(%i, %i)" % (self.start, self.end)

    def __str__(self): # string of the object:
        return "%i\t%i" % (self.start, self.end)

    def __call__(self, *args): # a(*args)
        return "called with ", args

    def __len__(self): # len(a)
        return self.end - self.start

    def __add__(self, other):
        return Interval(min(self.start, other.start), max(self.end, other.end))

    def __contains__(self, other): # a in b
        return other.start < self.end and other.end >= self.start

import doctest
doctest.testmod()
`

You can ignore all the methods starting and ending with two underscores (e.g.: __init__, __iter__, __setattr__, ..), at least as long as you are a beginner.

So, when you see something like what you posted:

 |      x.__init__(...) initializes x; see help(type(x)) for signature
 |   |  __iter__(...)
 |      x.__iter__() <==> iter(x)
 |  
 |  __repr__(...)
 |      x.__repr__() <==> repr(x)
 |  
 |  __setattr__(...)
 |      x.__setattr__('name', value) <==> x.name = value
 |  
 |  close(...)
 |      close() -> None or (perhaps) an integer.  Close the file.

You can see it as it were:

 |  close(...)
 |      close() -> None or (perhaps) an integer.  Close the file.

They represent methods used internally, that are not meant to be used directly. For example, __repr__ is used to define how an object is printed to screen when you do it with "print". The rest of the documentation should be easy to read. The first line of the documentation tell you the name of the function, its parameters, and its output. If any parameter is between brackets, it means that it is an optional argument:

help(function)

function(...)
    function(arguments of the function, [optional arguments]) -> output
`

For example:

help(sum)

sum(...)
    sum(sequence[, start]) -> value

    Returns the sum of a sequence of numbers (NOT strings) plus the value
    of parameter 'start' (which defaults to 0).  When the sequence is
    empty, returns start.

From a biologist turned Python programmer, I rarely use the help function, unless there's no internet connection. I usually refer to the online documentation which is much more explicit and "friendly" in my opinion.

Otherwise, there are also the doc strings that you can print to get a general message on what the class/function does. And last resort, good old opening the source code and reading a bit, this more in case of libraries and modules that you install a posteriori.

Regarding the underscores, check here, you will also see them in some variables in some modules. It usually means it's a method you don't want to call directly (usually).

You can always start with the tutorials from python.org to get used to the jargon. Also, most of it you will learn by experience.

Log in to answer this question.