Docs: Add description of olefile to "External Libraries"

[F30]

olefile became an optional dependency in commit 9175706, but it hasn't been mentioned in the library list so far.

[nulano]

I'm not sure this is the right place to mention this library. olefile is a Python library, not a native library, so it probably shouldn't be under the "Building from source" heading.

I am surprised it is not mentioned in docs/handbook/image-file-formats.rst for the two file types it is used for, MIC and FPX.
Edit: I see now @radarhere has created #7503 to add it there.

[radarhere]

I've created PR #7509 as an alternative to this, mentioning olefile under 'Basic Installation' instead.

[F30]

I'm not sure this is the right place to mention this library. olefile is a Python library, not a native library, so it probably shouldn't be under the "Building from source" heading.

I agree that this is a bit convoluted. While the general headline is "Building From Source", the specific section just lists external libraries and does not distinguish between build and runtime dependencies.

An even more complex situation occurs for tcl/tk: Even though listed here and in the package lists below, Tcl and Tk headers are actually not required to build Pillow. (I tried that on Debian and Alpine.) What is required at runtime are that tkinter Python bindings, which are part of the Python standard library, but packaged separately by most distributions.

I have added another commit (8a87d37) to mention tkinter and move non-library dependencies to the bottom of the list (not that there was consistent ordering in the first place). This is still not ideal and somewhat inconsistent with the package lists below, but better than the status quo.

I've created PR #7509 as an alternative to this, mentioning olefile under 'Basic Installation' instead.

I also like that PR, but I think the information should be available in both places.

[hugovk]

#7509 has been merged. Please could you update this PR from main so we can see them both combined?

Further discussion has occurred

[radarhere]

the specific section just lists external libraries and does not distinguish between build and runtime dependencies.

libraqm does provide some information on this front.

I've created #7562 to update the description of tcl/tk, explaining that it was once a build dependency, but no longer.

[radarhere]

Please could you update this PR from main so we can see them both combined?

Here's a link to that version of the docs if it is helpful - https://pillow-radarhere.readthedocs.io/en/olefile-docs/installation.html

I don't have permissions to merge main into this.

[hugovk]

@aclark4life Please could you enable this setting at https://github.com/python-pillow/Pillow/settings so we can update PRs from main?

[radarhere]

What is required at runtime are that tkinter Python bindings, which are part of the Python standard library, but packaged separately by most distributions.

I have added another commit (8a87d37) to mention tkinter

I don't think Pillow requires tkinter, it just interfaces with it. If you don't have tkinter installed, you are not missing out on any Pillow functionality. For a similar example, Pillow doesn't require NumPy - unless you're trying to pass data between Pillow and NumPy. I don't think these are things that users need to concern themselves with if their goal is just to install Pillow.

As for olefile, my vote is also that between mentioning it in the 'Basic Installation' and 'Image file formats'. it is sufficiently documented. If you discover after installation that you want to install it, then that is fairly trivial to do.

[F30]

I don't think Pillow requires tkinter, it just interfaces with it. If you don't have tkinter installed, you are not missing out on any Pillow functionality.

Are you sure about that?

https://pillow.readthedocs.io/en/stable/reference/ImageTk.html says "The ImageTk module contains support to create and modify Tkinter BitmapImage and PhotoImage objects". To me, this sounds like some image formats from the Tk world. But I'm not very familiar with that, so it may also be possible that BitmapImage and PhotoImage are not full-blown image formats, but just useful for building UIs.

[radarhere]

"Tkinter BitmapImage and PhotoImage objects" aren't images that exist on disk, they're Python objects.

[radarhere]

#7563 has also been merged, documenting the use of olefile further in a way, by adding it as an optional dependency to pyproject.toml.