__author__

[David Keeney]

I see this set (or similar) of variables in various modules I read.
They are found near the top of each module file, outside of any class
or function definitions.

"
__author__ = "Software Authors Name"
__copyright__ = "Copyright (C) 2004 Author Name"
__license__ = "Public Domain"
__version__ = "1.0"
"

What is the function of this set of variables? I assume there are
software products that use these, (Python itself, perhaps), that
expect to find certain variables explained.

What are the expected variables, other than the ones listed above, and
what software would I expect to use them?

David

[Peter L Hansen]

Re: __author__

David Keeney wrote:[color=blue]
> I see this set (or similar) of variables in various modules I read.
> They are found near the top of each module file, outside of any class
> or function definitions.
>
> "
> __author__ = "Software Authors Name"
> __copyright__ = "Copyright (C) 2004 Author Name"
> __license__ = "Public Domain"
> __version__ = "1.0"
> "
>
> What is the function of this set of variables? I assume there are
> software products that use these, (Python itself, perhaps), that
> expect to find certain variables explained.
>
> What are the expected variables, other than the ones listed above, and
> what software would I expect to use them?[/color]

IME, other than __version__, none of these are *widely* used,
nor are they necessary.

In any case, they are all just conventions, and there are NO
"expected variables" along the lines of what you're thinking,
and while there is probably some software that uses some
particular set of them, looking for such a thing just so
that you can throw a bunch of things like that at the top
of your modules, where they will never actually be used
(except for __version__), is a waste of time, IMHO.

*If* you want to write them that way, then use them in, say,
an About Dialog or when a "-h" option is specified, then go
ahead. I personally use things like APP_AUTHOR and APP_COPYRIGHT
rather than the double-underscore convention, which in my
view makes them look like they are somehow "special" to
Python, causing just the sort of confusion that you have
faced here. :-(

-Peter

[Jeffrey Froman]

Re: __author__

Peter L Hansen wrote:

<snip>[color=blue]
> they will never actually be used
> (except for __version__)[/color]
<snip>

So what uses __version__ ?

Thanks,
Jeffrey

[Anna Martelli Ravenscroft]

Re: __author__

David Keeney wrote:[color=blue]
> I see this set (or similar) of variables in various modules I read.
> They are found near the top of each module file, outside of any class
> or function definitions.
>
> "
> __author__ = "Software Authors Name"
> __copyright__ = "Copyright (C) 2004 Author Name"
> __license__ = "Public Domain"
> __version__ = "1.0"
> "
>
> What is the function of this set of variables? I assume there are
> software products that use these, (Python itself, perhaps), that
> expect to find certain variables explained.
>
> What are the expected variables, other than the ones listed above, and
> what software would I expect to use them?
>
> David[/color]


You may be seeing those in modules that were packaged up with distutils.
The setup.py expects certain metadata about the distribution,in cluding
those you've listed above. A list of the expected values is available on
page 562 of _Python in a Nutshell_, or in _Distributing Python Modules_
section 3, accessible at thttp://docs.python.org/dist/dist.html

HTH,
Anna

[Peter L Hansen]

Re: __author__

Anna Martelli Ravenscroft wrote:[color=blue]
> You may be seeing those in modules that were packaged up with distutils.
> The setup.py expects certain metadata about the distribution,in cluding
> those you've listed above. A list of the expected values is available on
> page 562 of _Python in a Nutshell_, or in _Distributing Python Modules_
> section 3, accessible at thttp://docs.python.org/dist/dist.html[/color]

Anna, I'd like a clarification please. Are you suggesting that
those variables as written *with underscores* are what distutils
expects to see, or merely that the names of those variables
is similar to those required by distutils? I don't see any
mention of __whatever__ on the page you cite above.

-Peter

[Anna Martelli Ravenscroft]

Re: __author__

Peter L Hansen wrote:[color=blue]
> Anna Martelli Ravenscroft wrote:
>[color=green]
>> You may be seeing those in modules that were packaged up with
>> distutils. The setup.py expects certain metadata about the
>> distribution,in cluding those you've listed above. A list of the
>> expected values is available on page 562 of _Python in a Nutshell_, or
>> in _Distributing Python Modules_ section 3, accessible at
>> thttp://docs.python.org/dist/dist.html[/color]
>
>
> Anna, I'd like a clarification please. Are you suggesting that
> those variables as written *with underscores* are what distutils
> expects to see, or merely that the names of those variables
> is similar to those required by distutils? I don't see any
> mention of __whatever__ on the page you cite above.[/color]

Yep - you're right.
__whatever__ isn't there. Copyright isn't on that page either (as Alex
helpfully pointed out to me after I posted this). (Good thing I said
"may". That's what I get for posting while fighting a cold...)

I hope that someone like someone whose modules use __something__ can
explain for both of us...

Anna

[Peter L Hansen]

Re: __author__

Jeffrey Froman wrote:[color=blue]
> Peter L Hansen wrote:[color=green]
>>they will never actually be used (except for __version__)[/color]
>
> So what uses __version__ ?[/color]

Very many third party packages I have installed. It's
not that it is *consumed* by anything, but that it seems to
be a very widely used convention.

A quick scan shows it is present in:

- Twisted
- SOAPpy
- wxPython
- ReportLab
- libxml2
- fpconst
- metakit
- mx stuff
- matplotlib
- docutils
- Numeric
- OpenGL
- PIL
- pysco
- pyPgSQL
- py2exe

-Peter

[Michael Hoffman]

Re: __author__

Peter L Hansen wrote:
[color=blue][color=green]
>> So what uses __version__ ?[/color]
>
> Very many third party packages I have installed. It's
> not that it is *consumed* by anything, but that it seems to
> be a very widely used convention.[/color]

Probably because Guido suggests it in the Python Style Guide, PEP 8:

http://www.python.org/peps/pep-0008.html

--
Michael Hoffman

[Mike C. Fletcher]

Re: __author__

Peter L Hansen wrote:
[color=blue]
> Jeffrey Froman wrote:
>[color=green]
>> Peter L Hansen wrote:
>>[color=darkred]
>>> they will never actually be used (except for __version__)[/color]
>>
>>
>> So what uses __version__ ?[/color]
>
>
> Very many third party packages I have installed. It's
> not that it is *consumed* by anything, but that it seems to
> be a very widely used convention.
>
> A quick scan shows it is present in:[/color]

....
[color=blue]
> - Numeric
> - OpenGL[/color]

And the plan is that newer versions of PyOpenGL are going to be using
Numeric's __version__ to decide what stub-dlls to load (or at least, to
complain if the version doesn't match what PyOpenGL was compiled
against). Generally speaking, the purpose of the meta-data is to have a
run-time queryable mechanism to determine information about the
package. Author isn't likely to be that interesting at run-time (save
for very specialised email-a-bug-report type stuff), but version allows
you to imply capabilities for the package.

Oh, IIRC, pydoc treats those __names__ as special and creates a separate
section for them (then they are duplicated in the "data" section IIRC).

Have fun,
Mike

_______________ _______________ _______________ ___
Mike C. Fletcher
Designer, VR Plumber, Coder

http://www.vrplumber.com

http://blog.vrplumber.com

[Peter L Hansen]

Re: __author__

Michael Hoffman wrote:[color=blue]
> Peter L Hansen wrote:[/color]
[re __version__][color=blue][color=green]
>> Very many third party packages I have installed. It's
>> not that it is *consumed* by anything, but that it seems to
>> be a very widely used convention.[/color]
>
> Probably because Guido suggests it in the Python Style Guide, PEP 8:
>
> http://www.python.org/peps/pep-0008.html[/color]

Checking that page.... it appears the suggestion was more specific
than that:

"""If you have to have RCS or CVS crud in your source file, do it as
follows.

__version__ = "$Revision: 1.25 $"
# $Source: /cvsroot/python/python/nondist/peps/pep-0008.txt,v $
"""

Perhaps those who have used it for a more typical version number,
ala __version__ = '1.2.34', have expanded the usage beyond what
Guido recommended.

I suspect a majority of modules actually use VERSION in preference
to __version__, maybe because many authors didn't interpret the
PEP8 comment as widely as some did.

(I've tended to use VERSION, I believe, but I'm moving towards
using a build.xml file containing a variety of meta-information
for the entire package, rather than an embedded constant.)

-Peter

[Mike C. Fletcher]

Re: __author__

Peter L Hansen wrote:
....
[color=blue]
> I suspect a majority of modules actually use VERSION in preference
> to __version__, maybe because many authors didn't interpret the
> PEP8 comment as widely as some did.[/color]

I'd actually be suspicious of that suspicion, I can't recall every
seeing VERSION used, while __version__ is something I've seen time and
time again. Those times I've wanted to check an installed package's
version I've always used

import package
package.__versi on__

in the interpreter. Never even occurred to me to use VERSION (and it's
never shown up in a dir() of a package when I've wanted to do this (that
I can recall)).
[color=blue]
> (I've tended to use VERSION, I believe, but I'm moving towards
> using a build.xml file containing a variety of meta-information
> for the entire package, rather than an embedded constant.)[/color]

Ah yes, much easier to work with ;) :

import package
if [int(i) for i in package.__versi on__.split('.')[:2]] > [2,3]:
blah()

versus:

import package
tag = findVersionTag( parseXMLFile(fi ndXMLFile( package )))
if (findMajorVersi on(tag),findMin orVersion(tag)) > (2,3):
blah()

Just teasing, you know I believe that XML is the solution to all
problems in the universe which can't be addressed *directly* with Java
;) . As long as you're exposing APIs that mean client libraries never
have to do the actual finding and parsing of the XML file, having your
"get version" API integrated into your package-management code can be
very useful for keeping them in sync.

Still, __version__ is a pretty simple API...

Smile!
Mike

_______________ _______________ _______________ ___
Mike C. Fletcher
Designer, VR Plumber, Coder

http://www.vrplumber.com

http://blog.vrplumber.com

[Peter L Hansen]

Re: __author__

Mike C. Fletcher wrote:[color=blue]
> Peter L Hansen wrote:[color=green]
>> (I've tended to use VERSION, I believe, but I'm moving towards
>> using a build.xml file containing a variety of meta-information
>> for the entire package, rather than an embedded constant.)[/color]
>
> Ah yes, much easier to work with ;) :
>
> import package
> if [int(i) for i in package.__versi on__.split('.')[:2]] > [2,3]:
> blah()
>
> versus:
>
> import package
> tag = findVersionTag( parseXMLFile(fi ndXMLFile( package )))
> if (findMajorVersi on(tag),findMin orVersion(tag)) > (2,3):
> blah()
>
> Just teasing, you know I believe that XML is the solution to all
> problems in the universe which can't be addressed *directly* with Java
> ;) . As long as you're exposing APIs that mean client libraries never
> have to do the actual finding and parsing of the XML file, having your
> "get version" API integrated into your package-management code can be
> very useful for keeping them in sync.
>
> Still, __version__ is a pretty simple API...[/color]

Actually, the XML is invisible to anything outside the application,
while simplifying a variety of things relating to the rest of my
infrastructure, including automatic documentation generation,
testing framework, packaging, and revision control.

At the top of the app/package, I have a "from buildutils import build"
call, and then I can do "build.version" , or "build.exename" , or
whatever... if I care to support folks like you who might want to
do "xxx.__version_ _" I guess I should do a "__version_ _ = build.version"
at the top of the module... hadn't thought of that.

Basically, the stuff is read at run-time, so _you_ wouldn't
be able to tell the difference, but I have the information
maintained externally instead of being coupled to the Python
code and inaccessible to, say, InnoSetup or py2exe or my own
utilities which might not or have the means to import the
module.

And as you surmised, this is largely about keeping things in
sync and avoiding duplication. In the most recent thing that
uses this, I need pieces of the build.xml content in all the
places mentioned above, meaning I've finally achieved my goal
of removing about five different instances of duplication and
my release process can be completely automated, provided I've
remembered to update the version number at all...

-Peter

[Thorsten Kampe]

Re: __author__

* Anna Martelli Ravenscroft (2004-10-01 18:58 +0200)[color=blue]
> Peter L Hansen wrote:[color=green]
>> Anna Martelli Ravenscroft wrote:[/color]
> Yep - you're right.
> __whatever__ isn't there. Copyright isn't on that page either (as Alex
> helpfully pointed out to me after I posted this). (Good thing I said
> "may". That's what I get for posting while fighting a cold...)
>
> I hope that someone like someone whose modules use __something__ can
> explain for both of us...[/color]

The standard help(module) uses at least __author__, __version__ and
__date__ to display these values separately at the bottom of the help
page so they don't get lost unnoticed in the 'data' section.

Thorsten