Repository: python-pillow/Pillow

Issue:
Confusion getting PIL / Pillow version string
I was trying to figure out which version of pillow (PIL) is installed, and stumbled on this:

```cmd
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


Discussion:
@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…

Resolving patch:
diff --git a/src/PIL/__init__.py b/src/PIL/__init__.py
--- a/src/PIL/__init__.py
+++ b/src/PIL/__init__.py
@@ -1,15 +1,18 @@
-#
-# The Python Imaging Library.
-# $Id$
-#
-# package placeholder
-#
-# Copyright (c) 1999 by Secret Labs AB.
-#
-# See the README file for information on usage and redistribution.
-#
+"""Pillow {} (Fork of the Python Imaging Library)
 
-# ;-)
+Pillow is the friendly PIL fork by Alex Clark and Contributors.
+    https://github.com/python-pillow/Pillow/
+
+Pillow is forked from PIL 1.1.7.
+
+PIL is the Python Imaging Library by Fredrik Lundh and Contributors.
+Copyright (c) 1999 by Secret Labs AB.
+
+Use PIL.__version__ for this Pillow version.
+PIL.VERSION is the old PIL version and will be removed in the future.
+
+;-)
+"""
 
 from . import _version
 
@@ -21,6 +24,9 @@
 
 del _version
 
+__doc__ = __doc__.format(__version__)  # include version in docstring
+
+
 _plugins = ['BlpImagePlugin',
             'BmpImagePlugin',
             'BufrStubImagePlugin',


Test patch: