Python "header" files

Discussion in 'Python' started by beliavsky@aol.com, Jun 8, 2004.

  1. Guest

    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.
    , Jun 8, 2004
    #1
    1. Advertising

  2. wrote:
    > 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

    --
    Timo "WT" Virkkala

    "In the battle between you and the world, bet on the world."
    Timo Virkkala, Jun 8, 2004
    #2
    1. Advertising

  3. 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?


    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
    Nicolas Fleury, Jun 8, 2004
    #3
  4. Miki Tebeka Guest

    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.
    --
    -------------------------------------------------------------------------
    Miki Tebeka <>
    The only difference between children and adults is the price of the toys.
    Miki Tebeka, Jun 8, 2004
    #4
  5. 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.
    Donald 'Paddy' McCarthy, Jun 9, 2004
    #5
  6. Peter Hansen Guest

    wrote:
    > 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
    Peter Hansen, Jun 9, 2004
    #6
  7. Guest

    Timo Virkkala <> wrote in message news:<9rqxc.493$>...

    > 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.
    , Jun 9, 2004
    #7
  8. David Bolen Guest

    writes:

    > 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
    David Bolen, Jun 9, 2004
    #8
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Newsgroup - Ann
    Replies:
    4
    Views:
    701
    lilburne
    Nov 2, 2003
  2. John Smith

    Header files included in header files

    John Smith, Jul 21, 2004, in forum: C Programming
    Replies:
    18
    Views:
    603
    Jack Klein
    Jul 24, 2004
  3. Replies:
    3
    Views:
    1,296
    Walter Roberson
    May 1, 2006
  4. Bit byte
    Replies:
    1
    Views:
    651
    benben
    Apr 19, 2006
  5. mlt
    Replies:
    2
    Views:
    831
    Jean-Marc Bourguet
    Jan 31, 2009
Loading...

Share This Page