I originally proposed this under the Demo and Tools cleanup issue [1]. The idea was to create a new package "demo" in the standard library which will host selected demo programs or modules that currently reside in the Demo/ directory of the source distribution. There are several advantages to this approach: 1. Discoverability. Currently, various distributions place demo scripts in different places or not include them at all. There is no easy way for an end user to discover them. With a demo package, there will be a natural place in the python manual to document demo scripts and users will be able to run them using -m option. IDEs will be able to present demo source code and documentation consistently. 2. Test coverage. One of the points raised in [1] was that Demo scripts are not routinely tested. While it is not strictly necessary to move them under Lib to enable testing, doing so will put these scripts on the same footing as the rest of the standard library modules eliminating an unnecessary barrier to writing tests. 3. Quality/relevance. Many scripts in Demo are very old and do not reflect modern best practices. By picking and choosing what goes to Lib/demo, we can improve the demo collection without removing older scripts that some may find useful. One objection raised to this idea was that Demo scripts do not have the same stability of the API and backward compatibility requirements as the rest of the standard library. I don't think this is a serious issue. As long as we don't start importing demo modules from other stdlib modules, there is no impact on the stdlib itself from changing demo APIs. Users may be warned that their production programs should not depend on the demo modules. I think the word "demo" itself suggests that. What do you think? [1] http://bugs.python.org/issue7962#msg111677
Alexander Belopolsky wrote:
Calling a stdlib package "demo" or "example" is not a good idea, since those are rather common package names in existing applications. I also don't really see the point in moving *scripts* to the stdlib. The lib modules are usually not executable or meant for execution and you'd normally expect scripts to be under .../bin rather than .../lib. Why don't you turn the ones you find useful into PyPI packages to install separately ?
-- Marc-Andre Lemburg eGenix.com Professional Python Services directly from the Source (#1, Oct 26 2010)
::: Try our new mxODBC.Connect Python Database Interface for free ! :::: eGenix.com Software, Skills and Services GmbH Pastor-Loeh-Str.48 D-40764 Langenfeld, Germany. CEO Dipl.-Math. Marc-Andre Lemburg Registered at Amtsgericht Duesseldorf: HRB 46611 http://www.egenix.com/company/contact/
On Tue, Oct 26, 2010 at 10:15 AM, M.-A. Lemburg <mal@egenix.com> wrote: ..
Since proposed "demo" package is not intended to be imported by applications, there is not a problem if they are shadowed by application modules. There are plenty of common names in the stdlib. I don't remember this cited as a problem in the past. For example, recently added collections and subprocess modules were likely to conflict with names used by applications. The "test" package has been installed with stdlib for ages and it often conflicts with user test packages. I believe applications commonly using a "demo" or "example" package is an argument for rather than against my idea. (What's good for users is probably good for stdlib.) Finally, if the name conflict is indeed an issue, it is not hard to come up with a less common name: "pydemo", "python_examples", etc.
I also don't really see the point in moving *scripts* to the stdlib.
I gave three reasons in my first post. The first is specifically for *scripts*: to be able to run them using python -m without having to know an obscure path or polluting system path.
Most of stdlib modules are in fact executable with python -m. Just grep for 'if __name__ == "__main__":' line. While most demo scripts are self-contained programs, many are examples on how to write modules or classes. See for example Demo/classes. Furthermore, while users can run demos, presumably the main purpose of demos is to present the source code in them. I believe it is more natural too look for python source code along PYTHONPATH than along PATH. I don't think any demo scripts are suitable to be installed under .../bin. In fact, Red Hat distribution installs them under /usr/lib/pythonX.Y/Demo.
Why don't you turn the ones you find useful into PyPI packages to install separately ?
That's a good way to make them *less* discoverable than they currently are and make even fewer distributions include them by default. BTW, what is the purpose of the "Demo" directory to begin with? I would naively assume that it is the place where new users would look to get the idea of what they can do with python. If this is the case, it completely misses the target because new users are unlikely to have a source distribution or look under /usr/lib/pythonX.Y/Demo or other system specific place.
On Tue, Oct 26, 2010 at 16:00, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote:
What do you think?
After browsing through the Demo dir a bit, I came away thinking most of these should just be removed from the repository. I think there's enough demo material out there on the internet (for example in the cookbook), a lot of it of higher quality than what we have in the Demo dir right now. Maybe it makes sense to have a basic tkinter app to get you started. And some of the smaller functions or classes could possibly be used in the documentation. But as it is, it seems silly to waste developer time on stuff that few people look at or make use of (I'm assuming this from the fact that they have previously been neglected). Back to the original question: I don't think moving the Demo stuff to the Lib dir is a good idea, simply because the Lib dir should contain libraries, not applications or scripts. Writing a section for the documentation seems a better way to solve the discoverability problem, testing could be done even in the Demo dir (with more structure if need be), and quality control could just as well be exercised in the current location. Cheers, Dirkjan
On Tue, Oct 26, 2010 at 7:33 AM, Dirkjan Ochtman <dirkjan@ochtman.nl> wrote:
+1. Most of them are either quick hacks I once wrote and didn't know where to put (dutree.py, repeat.py come to mind) or in some cases contributed 3rd party code that was looking for a home. I think that all of these ought to live somewhere else and I have no problem with tossing out the entire Demo and Tools directories -- anything that's not needed as part of the build should go. (Though a few things might indeed be moved into the stdlib if they are useful enough.)
None of that belongs in the core distro any more.
If there are demos that are useful for testing, move them into Lib/test/. -- --Guido van Rossum (python.org/~guido)
On Tue, Oct 26, 2010 at 07:56, Guido van Rossum <guido@python.org> wrote:
Just to toss in my +1, I have suggested doing this before and received push-back in the form of "it isn't hurting anyone". But considering how often the idea of trying to fix the directory comes up and never occurs, it is obviously wasting people's time keeping the directories around. So I say move the stuff needed as part fo the build or dev process (e.g., patchcheck is in the Tools directory) and then drop the directory. We can give a deadline of some release like Python 3.2b1 or b2 to move scripts people care about, and then simply do a mass deletion just before cutting a release. -Brett
Am 26.10.2010 20:01, schrieb Brett Cannon:
I've started a list of Demos and Tools here: https://spreadsheets.google.com/ccc?key=0AherhJVUN_I2dFNQdjNPMFdnOHVpdERSdWxqaXBkWWc&hl=en&authkey=CMWEn84C Please, feel free to complete and argue about fates. I'd like the corresponding actions taken by 3.2b1. (One note about the fate "showcase": it might be nice to keep a minimal set of demos from various topics as a kind of showcase what you can do with a few lines of Python.) Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out.
On Tue, Oct 26, 2010 at 10:33 AM, Dirkjan Ochtman <dirkjan@ochtman.nl> wrote:
The one demo that I want to find a better place for is Demo/turtle. For a novice-oriented framework that turtle is, it is really a shame to require $ cd <whatever>/Demo/turtle $ python turtleDemo.py to run the demo. I would much rather use $ python demo.turtle or $ python turtle.demo (the later would require converting turtle.py into a package)
And some of the smaller functions or classes could possibly be used in the documentation.
And most likely not be automatically tested contributing to users' confusion: "I copied it from the documentation and it does not work!" See http://bugs.python.org/issue10029 .
It is debatable what is the cause and what is the effect here.
Introduction of -m option has changed that IMO. For example, when I work with recent versions of python, I always run pydoc as python -m pydoc because pydoc script on the path amy not correspond to the same version of python that I use. The trace, timeit, dis and probably many other useful modules don't even have a corresponding script in the standard distribution.
Writing a section for the documentation seems a better way to solve the discoverability problem,
What exactly such a section should say? "In order to find demo scripts, pleas unpack the source distribution and look under the Demo directory"?
This is a valid option and if running Demo tests is added to make test target, it has a fighting chance to work. However, if Demo test are organized differently from stdlib module tests, maintaining them will be more difficult than it needs to be.
On Tue, Oct 26, 2010 at 8:13 AM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote:
The one demo that I want to find a better place for is Demo/turtle.
Sure, go for it. It is a special case because the turtle module is also in the stdlib and these are intended for a particular novice audience. Anything we can do to make things easier for those people to get start with is probably worth it. Ideally they could just double click some file and the demo would fire up, with a command-line alternative (for the geeks among them) e.g. "python -m turtledemo" . -- --Guido van Rossum (python.org/~guido)
On Tue, Oct 26, 2010 at 11:18 AM, Guido van Rossum <guido@python.org> wrote:
Please see http://bugs.python.org/issue10199 for further discussion.
I would like to report a conclusion reached on the tracker to a wider audience before committing the changes. The new home for Demo/turtle is Lib/turtledemo. (Lib/turtle/demo alternative received no support and Lib/demo/turtle was not even in the running.) If anyone is interested in reviewing the patch, please see http://bugs.python.org/issue10199. Note that I tried to limit changes to what was necessary for running the demo script as python -m demoturtle. Running the scripts as unit tests and from python prompt will be subject of a separate issue. On Tue, Oct 26, 2010 at 11:49 AM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote:
Alexander Belopolsky wrote:
Calling a stdlib package "demo" or "example" is not a good idea, since those are rather common package names in existing applications. I also don't really see the point in moving *scripts* to the stdlib. The lib modules are usually not executable or meant for execution and you'd normally expect scripts to be under .../bin rather than .../lib. Why don't you turn the ones you find useful into PyPI packages to install separately ?
-- Marc-Andre Lemburg eGenix.com Professional Python Services directly from the Source (#1, Oct 26 2010)
::: Try our new mxODBC.Connect Python Database Interface for free ! :::: eGenix.com Software, Skills and Services GmbH Pastor-Loeh-Str.48 D-40764 Langenfeld, Germany. CEO Dipl.-Math. Marc-Andre Lemburg Registered at Amtsgericht Duesseldorf: HRB 46611 http://www.egenix.com/company/contact/
On Tue, Oct 26, 2010 at 10:15 AM, M.-A. Lemburg <mal@egenix.com> wrote: ..
Since proposed "demo" package is not intended to be imported by applications, there is not a problem if they are shadowed by application modules. There are plenty of common names in the stdlib. I don't remember this cited as a problem in the past. For example, recently added collections and subprocess modules were likely to conflict with names used by applications. The "test" package has been installed with stdlib for ages and it often conflicts with user test packages. I believe applications commonly using a "demo" or "example" package is an argument for rather than against my idea. (What's good for users is probably good for stdlib.) Finally, if the name conflict is indeed an issue, it is not hard to come up with a less common name: "pydemo", "python_examples", etc.
I also don't really see the point in moving *scripts* to the stdlib.
I gave three reasons in my first post. The first is specifically for *scripts*: to be able to run them using python -m without having to know an obscure path or polluting system path.
Most of stdlib modules are in fact executable with python -m. Just grep for 'if __name__ == "__main__":' line. While most demo scripts are self-contained programs, many are examples on how to write modules or classes. See for example Demo/classes. Furthermore, while users can run demos, presumably the main purpose of demos is to present the source code in them. I believe it is more natural too look for python source code along PYTHONPATH than along PATH. I don't think any demo scripts are suitable to be installed under .../bin. In fact, Red Hat distribution installs them under /usr/lib/pythonX.Y/Demo.
Why don't you turn the ones you find useful into PyPI packages to install separately ?
That's a good way to make them *less* discoverable than they currently are and make even fewer distributions include them by default. BTW, what is the purpose of the "Demo" directory to begin with? I would naively assume that it is the place where new users would look to get the idea of what they can do with python. If this is the case, it completely misses the target because new users are unlikely to have a source distribution or look under /usr/lib/pythonX.Y/Demo or other system specific place.
On Tue, Oct 26, 2010 at 16:00, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote:
What do you think?
After browsing through the Demo dir a bit, I came away thinking most of these should just be removed from the repository. I think there's enough demo material out there on the internet (for example in the cookbook), a lot of it of higher quality than what we have in the Demo dir right now. Maybe it makes sense to have a basic tkinter app to get you started. And some of the smaller functions or classes could possibly be used in the documentation. But as it is, it seems silly to waste developer time on stuff that few people look at or make use of (I'm assuming this from the fact that they have previously been neglected). Back to the original question: I don't think moving the Demo stuff to the Lib dir is a good idea, simply because the Lib dir should contain libraries, not applications or scripts. Writing a section for the documentation seems a better way to solve the discoverability problem, testing could be done even in the Demo dir (with more structure if need be), and quality control could just as well be exercised in the current location. Cheers, Dirkjan
On Tue, Oct 26, 2010 at 7:33 AM, Dirkjan Ochtman <dirkjan@ochtman.nl> wrote:
+1. Most of them are either quick hacks I once wrote and didn't know where to put (dutree.py, repeat.py come to mind) or in some cases contributed 3rd party code that was looking for a home. I think that all of these ought to live somewhere else and I have no problem with tossing out the entire Demo and Tools directories -- anything that's not needed as part of the build should go. (Though a few things might indeed be moved into the stdlib if they are useful enough.)
None of that belongs in the core distro any more.
If there are demos that are useful for testing, move them into Lib/test/. -- --Guido van Rossum (python.org/~guido)
On Tue, Oct 26, 2010 at 07:56, Guido van Rossum <guido@python.org> wrote:
Just to toss in my +1, I have suggested doing this before and received push-back in the form of "it isn't hurting anyone". But considering how often the idea of trying to fix the directory comes up and never occurs, it is obviously wasting people's time keeping the directories around. So I say move the stuff needed as part fo the build or dev process (e.g., patchcheck is in the Tools directory) and then drop the directory. We can give a deadline of some release like Python 3.2b1 or b2 to move scripts people care about, and then simply do a mass deletion just before cutting a release. -Brett
Am 26.10.2010 20:01, schrieb Brett Cannon:
I've started a list of Demos and Tools here: https://spreadsheets.google.com/ccc?key=0AherhJVUN_I2dFNQdjNPMFdnOHVpdERSdWxqaXBkWWc&hl=en&authkey=CMWEn84C Please, feel free to complete and argue about fates. I'd like the corresponding actions taken by 3.2b1. (One note about the fate "showcase": it might be nice to keep a minimal set of demos from various topics as a kind of showcase what you can do with a few lines of Python.) Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out.
On Tue, Oct 26, 2010 at 10:33 AM, Dirkjan Ochtman <dirkjan@ochtman.nl> wrote:
The one demo that I want to find a better place for is Demo/turtle. For a novice-oriented framework that turtle is, it is really a shame to require $ cd <whatever>/Demo/turtle $ python turtleDemo.py to run the demo. I would much rather use $ python demo.turtle or $ python turtle.demo (the later would require converting turtle.py into a package)
And some of the smaller functions or classes could possibly be used in the documentation.
And most likely not be automatically tested contributing to users' confusion: "I copied it from the documentation and it does not work!" See http://bugs.python.org/issue10029 .
It is debatable what is the cause and what is the effect here.
Introduction of -m option has changed that IMO. For example, when I work with recent versions of python, I always run pydoc as python -m pydoc because pydoc script on the path amy not correspond to the same version of python that I use. The trace, timeit, dis and probably many other useful modules don't even have a corresponding script in the standard distribution.
Writing a section for the documentation seems a better way to solve the discoverability problem,
What exactly such a section should say? "In order to find demo scripts, pleas unpack the source distribution and look under the Demo directory"?
This is a valid option and if running Demo tests is added to make test target, it has a fighting chance to work. However, if Demo test are organized differently from stdlib module tests, maintaining them will be more difficult than it needs to be.
On Tue, Oct 26, 2010 at 8:13 AM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote:
The one demo that I want to find a better place for is Demo/turtle.
Sure, go for it. It is a special case because the turtle module is also in the stdlib and these are intended for a particular novice audience. Anything we can do to make things easier for those people to get start with is probably worth it. Ideally they could just double click some file and the demo would fire up, with a command-line alternative (for the geeks among them) e.g. "python -m turtledemo" . -- --Guido van Rossum (python.org/~guido)
On Tue, Oct 26, 2010 at 11:18 AM, Guido van Rossum <guido@python.org> wrote:
Please see http://bugs.python.org/issue10199 for further discussion.
I would like to report a conclusion reached on the tracker to a wider audience before committing the changes. The new home for Demo/turtle is Lib/turtledemo. (Lib/turtle/demo alternative received no support and Lib/demo/turtle was not even in the running.) If anyone is interested in reviewing the patch, please see http://bugs.python.org/issue10199. Note that I tried to limit changes to what was necessary for running the demo script as python -m demoturtle. Running the scripts as unit tests and from python prompt will be subject of a separate issue. On Tue, Oct 26, 2010 at 11:49 AM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote:
participants (8)
-
Alexander Belopolsky -
Brett Cannon -
Dirkjan Ochtman -
Georg Brandl -
Guido van Rossum -
Lie Ryan -
M.-A. Lemburg -
Raymond Hettinger