Where should I place a Python package's demo script?

Question

I am coding a new python package to be used by others. To demonstrate how it should be used, I am writing a demo script that executes the main parts of the new package.

What is the convention for doing this, so that other will find the script easily? Should it be a separate module (by what name)? Should it be located in the package's root directory? Out of the package? In __init__.py?

Answer 1

Should it be a separate module (by what name)?

demo/some_useful_name.py

A demo directory contains demo scripts. Similarly, a test directory contains all your unit tests.

Should it be located in the package's root directory?

No. It's not part of the package. It's a demo.

Out of the package?

Yes.

In init.py?

Never.

---

A package has two lives. (1) as uninstalled source, (2) in the lib/site-packages as installed code.

The "source" should include README, setup.py, demo directory, test directory, and the package itself.

The top-level "source" setup.py should install just the package. The demo and test don't get installed. They get left behind as part of the download.