I there a better Python documentation? More structured?

Question

I guess this question has already been asked but I didn't find it.

I have worked in the past with Java and PHP and I believe their documentation structure for the language is better. At least their API.

If you look at Java's API, it's awesome. Very well structured and predictable. It also allows you to find new stuff you didn't know existed. I'm taking about this https://docs.oracle.com/javase/7/docs/api/ .

PHP isn't as well structured but it works great alto. I'm talking about this: https://www.php.net/manual/en/ .

Now, if you see Python's equivalent (at least what I've found https://docs.python.org/3/index.html ) it feels like a very long tutorial. From my point of view, searching for stuff is difficult and the there isn't a truly hierarchical organization. When you're reading about functions there's also a lot of text describing stuff when I'm really looking for a summary. Take for instance https://docs.python.org/3/library/string.html , see the part about "Format String Syntax", that feels it should go somewhere else exclusively dedicated to that topic.

So my question is: Is there somewhere where the Python API is structured in a smiliar fashion to what's done in JAVA?

Answer 1

Python has a near-equivalent of Javadoc in the standard library, called pydoc.

You can start it as a web server using the command

$ python -m pydoc -b

(Or -p 80 if the random port is giving you trouble, then go to http://localhost)

This should open a web browser that will let you explore the standard library, as well as any other packages you happen to have installed.

---

Note that you can also get all this information from Python's interactive shell/REPL using the help() utility.

>>> help()

let's say you wanted to find functions to do stuff on strings, as an example let's say strip(). How would you find this function using either method?

$ python -m pydoc str

or

>>> help(str)

Will show help for the str type, including all of its methods.

If you didn't know a string was of type str, you can make one and ask it for its type:

>>> type("foo")
<class 'str'>
>>> help(type("foo"))

To see a more compact directory of an object's attributes, you can use

>>> dir(str)
['__add__', '__class__', '__contains__', '__delattr__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getnewargs__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__iter__', '__le__', '__len__', '__lt__', '__mod__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__rmod__', '__rmul__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'capitalize', 'casefold', 'center', 'count', 'encode', 'endswith', 'expandtabs', 'find', 'format', 'format_map', 'index', 'isalnum', 'isalpha', 'isascii', 'isdecimal', 'isdigit', 'isidentifier', 'islower', 'isnumeric', 'isprintable', 'isspace', 'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip', 'maketrans', 'partition', 'replace', 'rfind', 'rindex', 'rjust', 'rpartition', 'rsplit', 'rstrip', 'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']

But since you already know the name is strip(), you can just ask for help on that object.

>>> help(str.strip)

This will display the method signature and docstring, if any.

Using Pydoc's web server, you click the builtins link in the "Built-in Modules" on the starting page and click the str link to see the exact same information, since help() is also served by pydoc.

There's also a "Search" and a "Get" bar. Entering str.strip in the "Get" bar will take you right to it, just like using help(str.strip).

This is great info. Thanks. Is there somewhere where this is posted online? So you don't have to start a server locally?

Not that I know of. And there doesn't seem to be much point given https://docs.python.org . The advantage of the local server is that it documents exactly what's installed on your system, based on the interpreter you launch it with, even if you have more than one Python version installed (or are using virtualenvs with different packages installed). Even the standard library can vary based on OS or distribution and (when compiled from source) the available C libraries when it was compiled.

Answer 2

Not sure if it's exactly what you want, but within the python REPL environment you can use help, to get something more to the point:

If you enter in the specific method name you can get a little more information i.e. help(str.format):