OpenSlide Python 1.4.1 released

Sat Nov 2 03:03:01 EDT 2024

OpenSlide Python [1] is a Python 3.8+ package providing an interface
to OpenSlide [2], a simple way to read whole-slide images (also known
as virtual slides).  OpenSlide Python 1.4.1 is a significant new
release that adds Linux and macOS wheels, supports OpenSlide installed
from PyPI, adds type hints, and fixes bugs.

OpenSlide Python is released under the terms of the GNU Lesser General
Public License, version 2.1 [3].

[1]: https://pypi.org/project/openslide-python/
[2]: https://openslide.org/
[3]: https://openslide.org/license/

# Major changes

## Expanded set of binary wheels

OpenSlide Python now provides pre-compiled wheels for Linux aarch64
and x86_64, macOS arm64 and x86_64, and Windows x64.  On these
platforms, `pip install openslide-python` installs OpenSlide Python
without requiring a C compiler or Python development headers on your
system.  On all other platforms, `pip install openslide-python` must
still compile C source code.

The 32-bit Windows wheel is no longer provided.  The OpenSlide project
has stopped providing 32-bit OpenSlide binaries for Windows, so a
32-bit Windows wheel would not be useful.

OpenSlide Python now uses Python's Limited API [4] on Python 3.11+.
As a result, new Python releases will immediately work with existing
OpenSlide Python wheels, without waiting for the OpenSlide project to
provide binaries for the new release.

[4]: https://docs.python.org/3/c-api/stable.html#limited-c-api

## Support for OpenSlide installed from PyPI

OpenSlide Python requires a functioning copy of OpenSlide.  Starting
with this release, OpenSlide can be installed from PyPI with `pip
install openslide-bin`.  This provides a convenient way to obtain
OpenSlide without using Conda, a Linux package manager, Homebrew or
MacPorts on macOS, or manually downloading binaries on Windows.  The
copy of OpenSlide installed by pip is self-contained and will not
conflict with other libraries in your Python installation.

openslide-bin [5] supports the following platforms:

* Linux aarch64 and x86_64 with glibc 2.28+ (Debian, Fedora, RHEL 8+,
  Ubuntu, many others)
* macOS 11+ (arm64 and x86_64)
* Windows 10+ and Windows Server 2016+ (x64)

On RHEL 8 and Ubuntu 20.04, you must first upgrade pip with `pip
install --upgrade pip` before installing openslide-bin.  On RHEL 8,
you must also ensure you are using Python 3.8+, not the default
installation of Python 3.6.

[5]: https://pypi.org/project/openslide-bin/

## Type hints

OpenSlide Python now provides Python type hints.  These allow you to
statically check your program's interactions with the OpenSlide Python
API using a type checker such as Mypy [6].  OpenSlide Python's type
hints require at least Python 3.10.

[6]: https://mypy-lang.org/

## Other improvements

OpenSlide Python now reports the error from a failed attempt to load
OpenSlide 4.x, even if OpenSlide 3.x also fails to load.

There have been several fixes to filename handling.  Filenames are now
encoded using the Python filesystem encoding [7] (usually UTF-8) on
non-Windows systems, rather than always encoding to UTF-8.  `bytes`
filename arguments are supported again, and arbitrary filename
arguments (for example, of type `int`) are now properly rejected.

The AbstractSlide base class now requires implementation of all its
abstract methods, provides a default set_cache() implementation, and
is now (lightly) documented.  This class is useful for connecting a
custom image loader to DeepZoomGenerator.

The deepzoom_tile.py example program now uses all available CPUs by
default if the number of CPUs is known.

[7]: https://docs.python.org/3/glossary.html#term-filesystem-encoding-and-error-handler

# Installing OpenSlide Python

`pip install openslide-python openslide-bin` is the fastest way to get
OpenSlide Python running on your system.  OpenSlide and OpenSlide
Python are also available from a variety of package managers [8].

[8]: https://openslide.org/download/#distribution-packages

# How to help

If you have a slide scanner that can produce files we don't have [9],
or ones OpenSlide can't read, please consider contributing a sample
[10].  If you grant us permission to redistribute your sample under
the Creative Commons Zero [11] license, we can use it in automated
tests and share it with other developers working on open source WSI
support!

[9]: https://github.com/openslide/openslide/wiki/DesiredTestData
[10]: https://openslide.org/submit/
[11]: https://creativecommons.org/public-domain/cc0/

# Full changelog

## Version 1.4.1, 2024-10-30

### Bug fixes

* Fix `setup.py install` with old setuptools (1.4.0 regression)
* examples: Fix `deepzoom_tile.py -r` with Jinja < 2.11.0 (1.4.0 regression)

## Version 1.4.0, 2024-10-29

### New features

* Support OpenSlide installed from PyPI [5] with `pip install openslide-bin`
* Add type hints for Python ≥ 3.10
* Add wheels for Linux aarch64, Linux x86_64, and macOS arm64 + x86_64
* Build version-independent wheels on Python ≥ 3.11
* examples: Default deepzoom_tile.py job count to available CPUs when known

### Changes

* Drop wheel for 32-bit Windows
* Rename source distribution to `openslide_python` per PEP 625 [12]
* Require AbstractSlide subclasses to implement all abstract methods
* Provide default AbstractSlide.set_cache() implementation
* Switch to PEP 621 [13] project metadata
* docs: Document existence of AbstractSlide
* examples: Update OpenSeadragon to 5.0.0

### Bug fixes

* If OpenSlide cannot be loaded, report errors from all attempts
* Fix `OpenSlide` support for `bytes` filename arguments (1.2.0 regression)
* Disallow arbitrary types as `OpenSlide` filename arguments (1.2.0 regression)
* Encode `OpenSlide` filename arguments using Python filesystem encoding [7]
* Add error check to OpenSlide.set_cache()
* docs: Fix types of properties that return tuples of items

[12]: https://peps.python.org/pep-0625/
[13]: https://peps.python.org/pep-0621/