6

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?

cyborg
  • 9,989
  • 4
  • 38
  • 56

2 Answers2

3

I've never seen any real convention for this, but I personally put it in a main sentinel within __init__.py so that it can be invoked via python -m somepackage.

Ignacio Vazquez-Abrams
  • 776,304
  • 153
  • 1,341
  • 1,358
  • +1: I'd probably execute it only if a certain switch is present, such as `python -m somemodule --demo`. This would be consistent when adding other execution-modes, like running all tests. – Björn Pollex Oct 06 '11 at 07:39
3

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.

S.Lott
  • 384,516
  • 81
  • 508
  • 779