Python "header" files

[beliavsky]

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.

 

[Timo Virkkala]

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.

Probably the most convenient way is to write good docstrings which document
the return values as well, and then generate static documentation from them
with pydoc.

http://www.python.org/doc/current/lib/module-pydoc.html

 

[Nicolas Fleury]

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?

You don't want to do that. Use pydoc utilities instead. If you use
Windows with ActivePython, look at <PythonDir>\Tools\scripts\pydocgui.pyw.

Headers in C++ are there by obligation, not by choice. Expect that to
disappear the day modules are introduced in C++ (still dreaming).

Regards,
Nicolas

 

[Miki Tebeka]

Hello,

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.

Why. The header files are source to a lot of mistakes:
1. Using wrong header files
2. Reading header file twice
3. ...
All of it stems from the fact that there are *two* places where you
define the code.
I agree that you should document the code well. If you like something
like header files use pydoc (or teud or whatever) to generate the
documentation from the code.

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.

This is another subject. There are several ways to create interfaces in
Python (search the cookbook). The most trivial one is to create a base
class the raises NotImplementedError in each of its functions.

HTH.

Bye.

 

[Donald 'Paddy' McCarthy]

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.

 

[Peter Hansen]

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.

We had over a dozen Python programmers working on the same
project and didn't find it particularly a problem that the
full source code was available to them. In fact, given that
it was an XP environment (Extreme Programming, that is, though
it was also a partly WinXP environment) it was a huge
advantage over situations where only sketchy and inaccurate
documentation was available.

In the past, any time I've been limited to header files and
the docs I've encountered serious troubles. The header
files are often a mess, because of the inherent duplication,
inline code makes them even less readable, and the
documentation is _never_ maintained properly.

-Peter

 

[beliavsky]

Probably the most convenient way is to write good docstrings which document
the return values as well, and then generate static documentation from them
with pydoc.

http://www.python.org/doc/current/lib/module-pydoc.html

Thanks to you and others for suggesting pydoc. It easily generates
nice HTML. I like the results for my modules that just define
functions and classes.

For the main programs it actually runs the Python code and does
calculations before producing HTML. (Pychecker seems to work the same
way). The "DATA" section contains not only the parameters I set but
the computed results, which can change every time the program is run,
especially for simulations. PyDoc does not seem too helpful to me for
documenting the main program.

I think the HTML documentation for a main program should have (in
addition to the docstrings) the list of modules imported with links to
specific functions and variables imported.

 

[David Bolen]

For the main programs it actually runs the Python code and does
calculations before producing HTML. (Pychecker seems to work the same
way). The "DATA" section contains not only the parameters I set but
the computed results, which can change every time the program is run,
especially for simulations. PyDoc does not seem too helpful to me for
documenting the main program.

It sounds like you haven't protected your main script against being
imported as a module. It's not so much that pydoc/Pychecker are
"running" your Python code, but that they are importing the modules to
get at the information. While it's possible to write such a tool that
would instead compile the module and then analyse the resultant
compiled form, it's much easier to just introspect the normal Python
objects as a result of an import, so you'll find that most
introspection tools use the import-and-process approach. It does have
the side-effect of performing the import (so if modules do
calculations or operations when imported, that get's triggered).

If you haven't already, protect any top-level code in your main
modules inside an:

if __name__ == "__main__":

block, and you won't find your code running when the module is
processed by tools such as these.

-- David