The Python documentation should borrow the idea from the PHP.net

[nedbat (Ned Batchelder)]

@elis.byberi

As I mentioned in my previous post, shutil.copyfileobj lack an example in its module documentation. Why? Because it’s not possible to demonstrate it, you need two open two files and practice it by yourself.

This seems to me to be a reason why an example would be useful: a code example is a great way to demonstrate that the function doesn’t take file names it takes file objects, and how you could create the needed file objects. We might disagree whether the function needs an example, but I can’t understand “it’s not possible to demonstrate it.” Of course it can be demonstrated. I think an example would be useful.

Examples don’t prevent people from practicing code themselves. Some here have said that users have to practice using the functions themselves. Of course. Then they seem to argue that means we don’t need examples. Examples are a good on-ramp to practicing by yourself.

@elis.byberi

Simple Boolean Functions (etc)

You name this as something that doesn’t need an example. I don’t understand. Can you give an example of what you consider simple boolean functions? (See what I did there…?) Is any a simple boolean function? I think it could use examples.

@elis.byberi

If you find a one-liner example, its purpose is to demonstrate a concept not related to the language itself. For example, fmean([3.5, 4.0, 5.25]) . However, it is not going to help if you lack the necessary background in statistics. That is more related to the mathematical style of teaching, rather than the documentation format.

I don’t understand if you are saying fmean should have examples, or should not? It looks like a useful example to me.

[yt87 (George Trojan)]

Disclaimer: I have not read all posts on this thread.

My 2 cents:
Take, as an example, pathlib — Object-oriented filesystem paths — Python 3.12.3 documentation. There are examples, what I miss on that page is:

1. No index of methods/properties. Usually I scroll to the bottom to see the os equivalency table. I would prefer an xarray style: API reference
2. Consider the documentation of PurePath.match(*pattern*, ***, *case_sensitive=None* ). I have to scroll to the bottom to see the options for case_sensitive: None for platform defaults, True or False. My preference would be numpy style (not necessarily one page per function), like here: numpy.reshape — NumPy v1.26 Manual

I am fully aware those are my personal preferences.

[elis.byberi]

@nedbat

Of course it can be demonstrated. I think an example would be useful.

I don’t think it will be useful if you haven’t read in the shutil module documentation: For operations on individual files, see also the os module. In other words, if you (as a user) cannot distinguish between a file name and a file object, an example won’t help.

@nedbat

Is any a simple boolean function? I think it could use examples.

Currently, any only provides an equivalent code:

def any(iterable):
    for element in iterable:
        if element:
            return True
    return False

…which, in my opinion, is much more helpful than an example:

>>> any(True, False)
True

@nedbat

fmean should have examples

Yes, as I have seen in mathematical literature, simple examples are given to demonstrate concepts. But as you delve into more advanced concepts, you often encounter only “why?”

---

What you (@bauca) are looking for, I believe, is more of a guided book. This brings us back to Python tutorials. In my opinion, linking function (and others) documentation to their respective usage in Python tutorials would be the solution for the problem being discussed in this thread.

[nedbat (Ned Batchelder)]

@elis.byberi

I don’t think it will be useful if you haven’t read in the shutil module documentation: For operations on individual files, see also the os module. In other words, if you (as a user) cannot distinguish between a file name and a file object, an example won’t help.

No one has said they haven’t read the shutil docs. No one has said they can’t distinguish between names and file objects. The point is that an example can be a concise demonstration of the concepts in a very practical way. What is wrong with providing this example?:

    with open("source.dat", "rb") as src_file:
        with open("destination.dat", "wb") as dest_file:
            shutil.copyfileobj(src_file, dest_file)

It quickly shows using the with statement, includes the “rb” mode that will be important, has variable names that help indicate what is happening, and is complete. It only takes three lines. What is your objection to including it?

@elis.byberi

…which, in my opinion, is much more helpful than an example:

>>> any(True, False)
True

I’m not sure what to make of the incorrect usage here. Would seeing this example have helped you?

>>> any([True, False])
True

[elis.byberi]

@nedbat

>>> any([True, False])

Yes, I missed that. I started with a tuple a = (True, False) and ended with a REPL example.

Providing repetitive examples would create never-ending documentation. That’s why I suggest creating useful tutorials and linking to them from the documentation.

[bauca (Bruno Assis)]

Thanks for your valuable input, I would also be fine with a link to a useful tutorial on how to use the function, we all just need to create an agreement on where to put it and how.

[nedbat (Ned Batchelder)]

I don’t think there is a good reason to omit examples. We can choose them judiciously so that they are not repetitive, and they will not create “never-ending documentation.” Examples are a good way to get people started playing with code themselves. If we are afraid pages will get too long, we are already discussing how to split up long pages into shorter more searchable pages.

[erlendaasland (Erlend E. Aasland)]

@yt87

My preference would be numpy style (not necessarily one page per function), like here: numpy.reshape — NumPy v1.26 Manual

See the previous discussion:

Explicit parameter list in function documentation

I prefer the parameters of a function (with their documentation) to be listed explicitly in the function’s documentation. This is in contrast with man-style, which describes the positionals in prose. Compare open (what I call man-style) with numpy.linalg.norm (what I say employs an explicit list). I think it’s more than a preference however: I think the available parameters are easier to identify, and typing is obvious. It also reduces the mixing of parameters with side-effects and further fun…

Since that discussion, many functions and methods with lots of arguments have been converted to use this “param list” style^{[1][2][3][4][5][6][7][8]}, and more will probably follow.

If you spot a good candidate for the param list markup, feel free to submit a PR

---

1. sqlite3.connect() ↩︎

2. dbm.open() ↩︎

3. eval() ↩︎

4. ftplib.FTP() ↩︎

5. logging.Formatter() ↩︎

6. multiprocessing.shared_memory.SharedMemory() ↩︎

7. turtle.write() ↩︎

8. typing.dataclass_transform() ↩︎

[ncoghlan (Alyssa Coghlan)]

@tjreedy

I believe someone once started a website to document functions by use examples

You’re likely remembering Python Module of the Week: Python 3 Module of the Week — PyMOTW 3

Doug eventually collated and published those as a book: The Python 3 Standard Library by Example · Doug Hellmann

(There was discussion years ago about linking to PyMotW from the relevant stdlib pages, but the related questions of editorial control when the stdlib gets updated weren’t easy to resolve, so the idea lapsed into history)