5

I'd like to add some meta information to my Python modules' docstrings, such as author, email, version. Is there a canonical way to do that? I searched quite a while, but couldn't find anything with definite authority, here or on the web.

PEP 426 -- Metadata for Python Software Packages 2.0 talks about it some. And it looks like __author__, __version__ and some others are recognized by pydoc (V2.7). Also, there is epydoc and sphinx-doc.

Is there a standard way to include such information in the docstring? Or as global variables? If so, is there a list of accepted keywords / variable names?

Example:

#########
# Parts
# <description>
#
"""Helper module for selling car parts on the web.
   Author: Sue Baru
   EMail: sb@carparts.com
   Version: 1.0
"""

Update

This is not really an answer, but I ended up using the __author__ 'keyword' and nothing else. Versioning is accomplished by being checked into a git repo.

Stefan Ludwig
  • 333
  • 2
  • 8
  • For love of god, don't use global variables :). – Bhavish Agarwal May 01 '13 at 12:19
  • 1
    @BhavishAgarwal -- things like `__version__` are used by *LOTS* of packages. It's not the best, but I don't think there's anything much better. It's even mentioned in [PEP3001](http://www.python.org/dev/peps/pep-3001/#unification-of-module-metadata). Ultimately, when it comes to docstrings though, I'm not aware of the various tools following a specific convention. – mgilson May 01 '13 at 12:21
  • @mgilson, for the lack of standard and assuming that this is for internal usage, why not store this info as json string? – Bhavish Agarwal May 01 '13 at 12:23
  • @BhavishAgarwal, agreed. That's why I said I wanted to store this information in the docstring. That way, you also see with help(). – Stefan Ludwig May 01 '13 at 12:26
  • @mgilson, I saw the PEP3001 as well, but figured, since it was from 2006, there might be something more relevant... Thanks for the quick replies! – Stefan Ludwig May 01 '13 at 12:28
  • @StefanLudwig -- There are function annotations in python3 which are useful for annotating functions, but that's a bit of a different niche I'm afraid. – mgilson May 01 '13 at 12:39
  • @BhavishAgarwal: one thing is a global constant, another is is a global variable; just because global variables are bad (because they change and thus have the ability to cause unexpected side effects) doesn't mean global constants are bad. In fact, almost all constants in source code are global in the first place. – Erik Kaplun Sep 01 '13 at 13:01
  • @StefanLudwig: just one thought though: if you're using `__author__` in the source code, what if a snippet of code has 2 authors? or 3? Why not just rely on `git blame` to dynamically get the author(s) for any given range of lines? – Erik Kaplun Sep 01 '13 at 13:03
  • @ErikAllik: Thanks, I didn't remember `git blame`, I always use `git log`, sometimes in combination with `grep` to get that sort of information. However, we need a way for "regular" users to tell who to contact, if they run into trouble. Not everyone is or wants to be a git. ;-) – Stefan Ludwig Sep 01 '13 at 17:26
  • Then these regular users will get out of date or partial information. :) – Erik Kaplun Sep 01 '13 at 22:36

1 Answers1

0

Sphinx does it this way (using reST):

"""A pypi demonstration vehicle.

.. moduleauthor:: Andrew Carter <andrew@invalid.com>

"""

See Documenting Your Project Using Sphinx and this cheatsheet for more.

jhermann
  • 2,071
  • 13
  • 17