Helper function to read __version__

Maintaining a consistent version number across different parts of a package is a burden for authors. It may be needed in different places such as the package/module itself, setup.py or a sphinx conf.py.

The packaging guide describes a total of 7 different approaches.

I propose to support at least a few of them with a new get_version() function in setuptools.

def get_version(filename, rel_to_filname=None, method='regexp'):
    """
    Read the content of the variable __version__ from a file.
    
    Arguments:
        filename: 
            The file containing __version__
        rel_to_filename:
            If given, filname will be interpreted to be relative to
            the directory of this file. Otherwise, it will be relative
            to the working directory.
            In most cases, you will want to pass __file__.
        method:
            If 'regexp', the value of __version__ will be read determined
            via a regular expression. This requires, that it's a string.
            If 'exec', the file will be executed and the local variable
            __version__ will be read out. This if __version__ is defined
            in a more complex way. However, the disadvatage is that the
            file will be executed, including possible side-effects. 
    
    Returns:
        The __version__ value or None, if it could not be determined.

The basic implementation should support methods 1 (parse the file for a regexp) and 3 (execute the file in a separate context). IMO, these are the best approaches unless you have or need further functionality like extra tools (2) or VCS support (7).

The idea is to have __version__ set in your source code and fetch that value in helper scripts like setup.py or conf.py with a single line of code.

Example uses:

• get_version('mypackage.__init__.py', __file__)
• get_version('../mypackage._version.py, __file__, method='exec')

I figure this is a reasonable functionality to provide for setuptools. If there is interest, I can provide a PR.

[timhoffm]

I accept you point of view but don’t share it. To me, it’s actually little effort for a good payoff.

When trying to find out how to do this correctly, I found a lot of users with the same question and a number of different answers (let alone the 7 in the guide). Apparently, this is something many people stumble over.

setuptools could really help package maintainers here by providing a simple standard solution.

I would be willing to provide a PR and I don’t think it’s much of a burden to maintain. Essentially I don’t see why the function should need any future changes. It’s really simple and self-contained.

Of course, the decision is up to you.

[timhoffm]

Motivation

Maybe it’s helpful to state my motivation in a bit more detail.

I want to:

• Define the version only in one place
• Distribute it to __version__, setup.py and sphinx conf.py
• Don’t require to import the module in setup.py and sphinx conf.py.

To me defining the version in the source code (1, 3) seem to be the best solution for this unless you need/want extra tools (2, 7). 4 and 5 don’t have an advantage compared to 1, 3 but the added difficulty that I have to somehow set __version__ in the source code. 6 does not qualify because of the import.

The proposed function helps to make the value of __version__ available in other scripts like setup.py and conf.py without the need to write extra boilerplate code.