Python "header" files

[Donald 'Paddy' McCarthy]

beliavsky at aol.com wrote:
> Ideally, one can use someone's C++ code by just looking at the header
> files
> (which should contain comments describing the functions in addition to
> function definitions), without access to the full source code. Can
> analogs of C++ header files be created for Python code?
> 
> Python "header" files could list only the 'def' statements and
> docstrings of Python functions and classes, but that does not tell you
> what the functions return. One could list the return statements as
> well, but there can be several of them in a function, and they often
> show HOW something is calculated, which is "too much information" for
> a header file.
> 
> I wonder how Python projects with multiple programmers can be
> coordinated without giving all programmers access to all of the source
> code. I am currently working on one-man projects, but I am still
> interested in ways of separating interface from implementation.

You could use doctest: 
http://www.python.org/doc/current/lib/module-doctest.html
- together with meaningful docstring comments and pydoc:
http://www.python.org/doc/current/lib/module-pydoc

You might try help() in the interpreter on a few functions or modules 
for inspiration.

Cheers, Pad.