...

[Christopher Blunck]

...

...

Question #2: How about examples(function) that displays multiple examples of how to use the function provided? Similar to above, there are times when I look at the API and even if the parameters to the function are fully explained, it would help to have an example (case in point is os.path.walk - docs are great, but an example of how to make use of the third parameter (the arg you pass) would really clarify why 'the powers that be' chose to implement this capability.

...

If you look in the source distribution for Python there is a directory called Demos/ that has just examples of how to use things. Stuff like what you are suggesting can go there.

[Chad Netzer]

Perhaps an importable "examples" module, which could have, well, examples of things. It could and would be a separately maintained module, but would probably be useful to me and others it it just had examples of all the standard library functions (contributed to on a volunteer basis). hmmmmm...

I'm not sure what you would want to do after importing the examples module; it's not easy to look at the source of an imported module, and that's (presumably) what you want to do with an examples module. IMO examples belong in the documentation. The problem with the Demo directory is that few people have bothered to contribute or even weed out obsolete code, and so the collection there is quite stale. I would welcome contributions of any kind, but especially useful would be a somewhat separate project with the explicit goal of providing working examples of all the important parts of Python. Watch out for focusing too much on all the standard library functions; much of Python's power is in things that aren't functions (e.g. syntactic constructs, or methods, or classes, or modules). --Guido van Rossum (home page: http://www.python.org/~guido/)

[Jack Jansen]

I agree that it doesn't belong in the language itself, but what would be nice is if the help module could point you to examples. A first stab at this could be to use a well-defined naming scheme for the examples (so that examples for the "os" module would be in "Demos/os", and examples of os.walk() would be in, say, Demos/os/walk.py or walk_1.py and walk_2.py). And this could be extended with having index files in the Demos tree which would map Python names to example files. For example, if there was a demo Demos/os/renamefilesintreetouppercase.py then and index file in Demos/os could tell the help module that this is a useful file to examine if you're interested in os.walk or os.path.

This is more reasonable, but I still have reservations over having this kind of thing in the core. It isn't over whether it is useful or not, but whether people who do the bulk of CVS checkins want to be bothered with reading a possible deluge of example Python code on top of their usual Python work. Isn't the Cookbook supposed to cover stuff like this? And it was suggested to have a separate ``examples`` package, but that might be a barrier of entry for newbies (albeit a low barrier). -Brett

[Christopher Blunck]

On Sat, Jan 04, 2003 at 02:44:19PM -0800, Brett Cannon wrote:

...

And it was suggested to have a separate ``examples`` package, but that might be a barrier of entry for newbies (albeit a low barrier).

There seems to be diverging opinions in this thread, which I think is good.

Stick around; divergence happens all the time here at python-dev. =)

While I recognize (I have also personally used them) the existence of the "Demos" section in CVS, chances are strong that newbies do not.

Especially since it is not included in the Windows distro.

If somebody is bright enough to pull the python cvs module, build it, and use it then they probably are bright enough to discover the Demos. But the bright ones are not the folks I'm thinking about right now - I'm thinking of the common case user who gets a Linux distro with python installed out-of-the-box.

I wouldn't worry about people like that either. I think the question here is how do most people learn about Python. For instance, how do people even learn about the ``help()`` function? If they get it from the docs, we can point them to whatever to learn about examples. If they learn from a friend, then they probably would (and should) tell them where to get examples. And if they learn about it from launching the interpreter and typing ``help``, well that can have an added line mentioning where to go to get examples.

They may be totally new to programming and have never even heard of CVS before (and thus wouldn't have the Demos available to them). Maybe I'm not familiar with very many py installations for platforms other than my own, so feel free to correct me if the Demos *do* come pre-installed on many different environments. :)

It is not installed. You get it only with the source code.

I also recognize that this is ?feature? is not a core language functionality. But due to its special nature (I put this into the same area as help) I think that it does warrant thought about if it deserves to be included as a core feature *simply because* it might really help newbies out.

I still think putting it in the documentation is the better solution. ``help()`` should really be used as a quick reference. If that quick reference is not enough you should read the documentation which can have examples to help clarify usage.

A web page full of examples would be great, but again - would Joe New User know about the web page if they didn't even know about the lang (because it came pre-installed)? I don't know...

See above. -Brett