Python 3: list.append() in documentation

Question

Could you suggest me where in the documentation can I find anything about 'append' method applied to lists.

I mean

L = [1, 2, 3]

L.append(3)         # The method modifies the list itself and L = L.append(4) is a             mistake.

I can find that about arrays, but for unknown reasons I failed to find that about lists.

In my textbook I can read that 'append' modifies the list itself without returning a value. So, I just wanted to find this very information in documentation and - secondly - learn how to smoke the manual.

Thank you in advance.

Solution

All functions in Python return value. It is None for the list.append method (to stress that it modifies its argument (self) inplace).

All list methods are enumerated in the tutorial. There is no more complete reference as far as I can see.

The docstring for list.append() specifies that it returns None. Run help(list.append) in a Python shell.

Comments

[Kifsif]

Well, that's exactly what I read in my textbook. But where is it in the documentation? I was shown the tutorial. But the tutorial is a tutorial, it's not what I'm looking for.

[Kifsif]

So, how can I use the documentation then? Shall I always consult a tutorial. I'm a newbie, and I'm a bit astonished. How can I see that the method returns None? How can I see that the method exists at all. Of course, it was mentioned somewhere in examples for sequences. But not more as far as I can see.

[Frédéric Hamidi]

@Kifsif, sequences are discussed in the library reference there, but list's methods are not enumerated there, possibly because the tutorial already covers them.

[Kifsif]

It's a pretty ugly practice, isn't it?

[jfs]

@Kifsif: It is surprising for me as well. help(list.append) shows that it returns None. The tutorial is a part of official Python documentation. Yes, I'd recommend to read it to all Python developers. Lists are ubiquitous in Python. It might explain why they are covered in the tutorial

[Kifsif]

Well, my python shows this: append(...) L.append(object) -- append object to end. So, nothing about it returning None. I use Python 3.2.2. And how can I see any help from my IDE. I had to launch Python in a separate window, then print the command. And just to see this very short sentence.

[jfs]

@Kifsif: It might hard be for an IDE to figure out what type of object you are using due to the dynamic nature of Python without executing the code, consider: def f(L): L.append(1) it works for anything that has .append() method. But if IDE knows that the object is a list then it is trivial to show the docstring (it is available as __doc__ attribute on list.append object). btw, an interactive shell is a useful tool (configure your IDE to have an easy access to it). It seems None is documented only recently

[Kifsif]

Thank you. Well, I can see 'doc' when I type dir(list.append). But then my skills give up. How can I extract more from this 'doc'?

[Kifsif]

Hm. I typed (print(list.append.__doc__) and got the same: L.append(object) -- append object to end. So, nothing more useful.

[jfs]

@Kifsif: it is just a string. There is nothing more to it. You are not expected to access it manually. pydoc, help() use it internally. bpython, ipython (with ?) show it automatically. If you think that the docs are not enough then you could file a bug bugs.python.org (It is easy to make your documentation patch accepted in my experience).