Confusion getting PIL / Pillow version string

[gnbl]

I was trying to figure out which version of pillow (PIL) is installed, and stumbled on this:

Python 3.6.5 (v3.6.5:f59c0932b4, Mar 28 2018, 17:00:18) [MSC v.1900 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import PIL
>>> PIL.version
<module 'PIL.version' from 'C:\\Users\\me\\AppData\\Local\\Programs\\Python\\Python36\\lib\\site-packages\\PIL\\version.py'>
>>> help(PIL.version)
Help on module PIL.version in PIL:

NAME
    PIL.version - # Master version for Pillow

VERSION
    5.1.0

FILE
    c:\users\me\appdata\local\programs\python\python36\lib\site-packages\pil\version.py


>>> help(PIL)
Help on package PIL:

NAME
    PIL

DESCRIPTION
    # The Python Imaging Library.
    # $Id$
    #
    # package placeholder
    #
    # Copyright (c) 1999 by Secret Labs AB.
    #
    # See the README file for information on usage and redistribution.
    #

PACKAGE CONTENTS
    BdfFontFile
    BlpImagePlugin
    ...

>>> PIL.VERSION
'1.1.7'
>>> PIL.version.__version__
'5.1.0'
>>> PIL.PILLOW_VERSION
'5.1.0'
>>> PIL.__version__
'5.1.0'
>>>

• it's confusing that PIL.VERSION returns the version string of the former PIL instead of Pillow's
• there does not seem to be documentation on this version number (why this, will it ever change, ..) e.g. at https://pillow.readthedocs.io/en/5.1.x/about.html#why-a-fork
• it's confusing that PIL.version is a module and does not return the version information directly or hints on how to get it
• the package information header is essentially useless (placeholder, does not even mention Pillow, nor the version)
• PIL.version module documentation comment could explain how to access the version information

Others also have trouble finding it: https://stackoverflow.com/questions/44739775/how-to-get-python-pil-version

Source files:

• https://github.com/python-pillow/Pillow/blob/master/src/PIL/version.py
• https://github.com/python-pillow/Pillow/blob/master/src/PIL/__init__.py#L2

[aclark4life]

@gnbl A fork, by definition, is confusing. We're open to considering any specific changes you suggest to make Pillow versioning less confusing (preferably in the form of a pull request!) As far as I know, it's possible we could drop the 1.1.7 at some point. At least, I can't think of any specific reason why we couldn't do that…

[gnbl]

@aclark4life And there I thought you would be happy if someone took the time to point out an issue (admittedly less pressing) in your project ("All contributions are welcome."). I also thought I was quite specific and that potential minimum required changes to dust off the docstrings were obvious. :-)
But, I also understand that you life would be easier if the solution was provided directly.
Let's meet halfway:

I've messed with your code a little, but that is on Python 3.6.5 (v3.6.5:f59c0932b4, Mar 28 2018, 17:00:18) [MSC v.1900 64 bit (AMD64)] on win32 so it might break for earlier versions, and it's also probably not pythonic, and I don't know how to run the build tests, so no pull-request yet, but have a look for yourself: master...gnbl:gnbl_version_doc

Changes:

• actual """docstrings""" instead of line-comments. Using __doc__.format() to include version string!
• move version string definition to __init__.py from version.py
• hint at last PIL release version in about.rst

Let me know if this would work for you and I'll be glad to create a pull-request.
Cheers!

---

The changes would then produce:

Python 3.6.5 (v3.6.5:f59c0932b4, Mar 28 2018, 17:00:18) [MSC v.1900 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import PIL
>>> help(PIL)
Help on package PIL:

NAME
    PIL - Pillow 5.1.0 (Fork of the Python Imaging Library)

DESCRIPTION
    Pillow is the friendly PIL fork by Alex Clark and Contributors.
        https://github.com/python-pillow/Pillow/

    It's forked from PIL 1.1.7, released in 2009

    Access the version strings, use:
        PIL.PILLOW_VERSION (for this Pillow version)
        PIL.VERSION        (for the old PIL version)

    PIL is the Python Imaging Library by Fredrik Lundh and Contributors.
    Copyright (c) 1999 by Secret Labs AB.

    See the README file for more information.

PACKAGE CONTENTS
    BdfFontFile
    ...

>>> help(PIL.version)
Help on module PIL.version in PIL:

NAME
    PIL.version - Pillow version (access as PIL.PILLOW_VERSION)

VERSION
    5.1.0

FILE
    c:\users\gnbl\appdata\local\programs\python\python36\lib\site-packages\pil\version.py


>>> PIL.VERSION
'1.1.7'
>>> PIL.PILLOW_VERSION
'5.1.0'
>>> ^Z

For some reason the help system does not produce a VERSION from __version__ for the package, like it does for a module.
Edit: Never mind, it does actually, after listing the PACKAGE CONTENTS, e.g.

    ...
    features
    version

DATA
    PILLOW_VERSION = '5.1.0'
    VERSION = '1.1.7'

VERSION
    5.1.0

FILE
    c:\users\gnbl\appdata\local\programs\python\python36\lib\site-packages\pil\__init__.py

(docmodule() does it: https://github.com/python/cpython/blob/3.6/Lib/pydoc.py#L1098)

[homm]

The right place is PIL.PILLOW_VERSION.

it's confusing that PIL.version returns the version string of the former PIL instead of Pillow's

PIL.VERSION (not PIL.version) was there before forking, so we should pretend to be compliant.

there does not seem to be documentation on this version number

You are right, PIL.PILLOW_VERSION isn't mentioned in the docs, this should be fixed.

it's confusing that PIL.version is a module and does not return the version information directly or hints on how to get it

I believe it should be renamed to _version.

[gnbl]

@homm Fixed my typo in the OP. Was not sure where this would fit into the docs, so I did not proceed. The version module does not seem to be documented at all.

If the __doc__.format() is acceptable, one could also include the actual location of the readme, in addition to "See the README file for more information.".

[hugovk]

We're happy for both issues and pull requests! PRs are good to get the conversation going and also you don't need to worry about testing locally as the CIs will do it for us. :)

---

In general, master...gnbl:gnbl_version_doc looks like a step in the right direction to clarify the confusion.

The reason for version.py is to have a single source of truth for the Pillow version, so we don't need to update both setup.py and Image.py when making a release (https://packaging.python.org/guides/single-sourcing-package-version/). PILLOW_VERSION used to be in Image.py, but was moved so it can be imported by Image.py and also read by setup.py.

So I'd keep PILLOW_VERSION in version.py. If we want them both together, I'd also put the PIL version in version.py and have Image.py import it.

---

As more time passes since the last PIL release (1.1.7 in 2009), the likelihood of a new PIL release decreases. However, we've yet to hear an official "PIL is dead" announcement. So if you still want to support PIL, please report issues here first, then open corresponding Pillow tickets here.

Let's revisit this. Is there any point people reporting things back upstream to https://bitbucket.org/effbot/pil-2009-raclette/issues?

---

Also, do we still need to report 1.1.7 as the PIL version? I don't think we really care about it at this point and can't think of a great reason to keep it as 1.1.7. It's extremely unlikely at this point there'll be a 1.1.8, and there's been many here changes in the past 10 years.

Should we put the current Pillow version in PIL.VERSION as well?

We could even clean up and have a single version variable (eg. ditch PILLOW_VERSION) but this would be a breaking change as there may be some user code out there checking it. Perhaps that could wait until the next major release. Thoughts?

[homm]

My suggestion (without documentation): #3083

[aclark4life]

@gnbl Definitely happy to have this issue addressed! Thanks all

[hugovk]

And #3085 is another suggestion that can be used as well as or instead of #3083.

[wiredfool]

IIRC, there were tests for some package out there that was relying on the PIL 1.1.7 version. Removing/changing that at this point should be considered a major change.

The version submodule is an implementation detail, it exists solely to provide a side-effect free simple import of the version number at build time so that we can have the one source of truth for the python and c code.

[homm]

@gnbl Do you think this fix is enough?

[gnbl]

@homm Thanks for the quick work on this! It's never enough ;-)
It looks like the suggestions regarding the docstrings (master...gnbl:gnbl_version_doc) have not yet found their way into 096a81b in some form. Maybe, "while you're at it", you could update these to eliminate the package placeholder etc. as well?

[aclark4life]

@gnbl @homm @hugovk I can't tell if we are done or if there's more to do?

[hugovk]

There's been several things done, here's a final PR to close this that updates some docs: #3218.