examples/deepzoom: add type hints

Signed-off-by: Benjamin Gilbert <[email protected]>

Author: bgilbert

.pre-commit-config.yaml

@@ -58,8 +58,8 @@ repos:
     hooks:
       - id: mypy
         name: Check Python types
-        additional_dependencies: [openslide-bin, pillow, types-setuptools]
-        exclude: "^(doc/.*|examples/deepzoom/.*)$"
+        additional_dependencies: [flask, openslide-bin, pillow, types-setuptools]
+        exclude: "^doc/.*$"
 
   - repo: https://github.com/rstcheck/rstcheck
     rev: v6.2.4

examples/deepzoom/deepzoom_multiserver.py

@@ -24,18 +24,24 @@
 from argparse import ArgumentParser
 import base64
 from collections import OrderedDict
+from collections.abc import Callable
 from io import BytesIO
 import os
 from threading import Lock
+from typing import TYPE_CHECKING, Any, Literal
 import zlib
 
-from PIL import ImageCms
-from flask import Flask, abort, make_response, render_template, url_for
+from PIL import Image, ImageCms
+from flask import Flask, Response, abort, make_response, render_template, url_for
+
+if TYPE_CHECKING:
+    # Python 3.10+
+    from typing import TypeAlias
 
 if os.name == 'nt':
     _dll_path = os.getenv('OPENSLIDE_PATH')
     if _dll_path is not None:
-        with os.add_dll_directory(_dll_path):
+        with os.add_dll_directory(_dll_path):  # type: ignore[attr-defined]
             import openslide
     else:
         import openslide
@@ -62,10 +68,36 @@
 )
 SRGB_PROFILE = ImageCms.getOpenProfile(BytesIO(SRGB_PROFILE_BYTES))
 
+if TYPE_CHECKING:
+    ColorMode: TypeAlias = Literal[
+        'default',
+        'absolute-colorimetric',
+        'perceptual',
+        'relative-colorimetric',
+        'saturation',
+        'embed',
+        'ignore',
+    ]
+    Transform: TypeAlias = Callable[[Image.Image], None]
+
+
+class DeepZoomMultiServer(Flask):
+    basedir: str
+    cache: _SlideCache
+
+
+class AnnotatedDeepZoomGenerator(DeepZoomGenerator):
+    filename: str
+    mpp: float
+    transform: Transform
+
 
-def create_app(config=None, config_file=None):
+def create_app(
+    config: dict[str, Any] | None = None,
+    config_file: str | None = None,
+) -> Flask:
     # Create and configure app
-    app = Flask(__name__)
+    app = DeepZoomMultiServer(__name__)
     app.config.from_mapping(
         SLIDE_DIR='.',
         SLIDE_CACHE_SIZE=10,
@@ -99,7 +131,7 @@ def create_app(config=None, config_file=None):
     )
 
     # Helper functions
-    def get_slide(path):
+    def get_slide(path: str) -> AnnotatedDeepZoomGenerator:
         path = os.path.abspath(os.path.join(app.basedir, path))
         if not path.startswith(app.basedir + os.path.sep):
             # Directory traversal
@@ -115,11 +147,11 @@ def get_slide(path):
 
     # Set up routes
     @app.route('/')
-    def index():
+    def index() -> str:
         return render_template('files.html', root_dir=_Directory(app.basedir))
 
     @app.route('/<path:path>')
-    def slide(path):
+    def slide(path: str) -> str:
         slide = get_slide(path)
         slide_url = url_for('dzi', path=path)
         return render_template(
@@ -130,15 +162,15 @@ def slide(path):
         )
 
     @app.route('/<path:path>.dzi')
-    def dzi(path):
+    def dzi(path: str) -> Response:
         slide = get_slide(path)
         format = app.config['DEEPZOOM_FORMAT']
         resp = make_response(slide.get_dzi(format))
         resp.mimetype = 'application/xml'
         return resp
 
     @app.route('/<path:path>_files/<int:level>/<int:col>_<int:row>.<format>')
-    def tile(path, level, col, row, format):
+    def tile(path: str, level: int, col: int, row: int, format: str) -> Response:
         slide = get_slide(path)
         format = format.lower()
         if format != 'jpeg' and format != 'png':
@@ -165,19 +197,27 @@ def tile(path, level, col, row, format):
 
 
 class _SlideCache:
-    def __init__(self, cache_size, tile_cache_mb, dz_opts, color_mode):
+    def __init__(
+        self,
+        cache_size: int,
+        tile_cache_mb: int,
+        dz_opts: dict[str, Any],
+        color_mode: ColorMode,
+    ):
         self.cache_size = cache_size
         self.dz_opts = dz_opts
         self.color_mode = color_mode
         self._lock = Lock()
-        self._cache = OrderedDict()
+        self._cache: OrderedDict[str, AnnotatedDeepZoomGenerator] = OrderedDict()
         # Share a single tile cache among all slide handles, if supported
         try:
-            self._tile_cache = OpenSlideCache(tile_cache_mb * 1024 * 1024)
+            self._tile_cache: OpenSlideCache | None = OpenSlideCache(
+                tile_cache_mb * 1024 * 1024
+            )
         except OpenSlideVersionError:
             self._tile_cache = None
 
-    def get(self, path):
+    def get(self, path: str) -> AnnotatedDeepZoomGenerator:
         with self._lock:
             if path in self._cache:
                 # Move to end of LRU
@@ -188,7 +228,7 @@ def get(self, path):
         osr = OpenSlide(path)
         if self._tile_cache is not None:
             osr.set_cache(self._tile_cache)
-        slide = DeepZoomGenerator(osr, **self.dz_opts)
+        slide = AnnotatedDeepZoomGenerator(osr, **self.dz_opts)
         try:
             mpp_x = osr.properties[openslide.PROPERTY_NAME_MPP_X]
             mpp_y = osr.properties[openslide.PROPERTY_NAME_MPP_Y]
@@ -204,7 +244,7 @@ def get(self, path):
                 self._cache[path] = slide
         return slide
 
-    def _get_transform(self, image):
+    def _get_transform(self, image: OpenSlide) -> Transform:
         if image.color_profile is None:
             return lambda img: None
         mode = self.color_mode
@@ -215,7 +255,7 @@ def _get_transform(self, image):
             # embed ICC profile in tiles
             return lambda img: None
         elif mode == 'default':
-            intent = ImageCms.getDefaultIntent(image.color_profile)
+            intent = ImageCms.Intent(ImageCms.getDefaultIntent(image.color_profile))
         elif mode == 'absolute-colorimetric':
             intent = ImageCms.Intent.ABSOLUTE_COLORIMETRIC
         elif mode == 'relative-colorimetric':
@@ -232,10 +272,10 @@ def _get_transform(self, image):
             'RGB',
             'RGB',
             intent,
-            0,
+            ImageCms.Flags(0),
         )
 
-        def xfrm(img):
+        def xfrm(img: Image.Image) -> None:
             ImageCms.applyTransform(img, transform, True)
             # Some browsers assume we intend the display's color space if we
             # don't embed the profile.  Pillow's serialization is larger, so
@@ -246,9 +286,9 @@ def xfrm(img):
 
 
 class _Directory:
-    def __init__(self, basedir, relpath=''):
+    def __init__(self, basedir: str, relpath: str = ''):
         self.name = os.path.basename(relpath)
-        self.children = []
+        self.children: list[_Directory | _SlideFile] = []
         for name in sorted(os.listdir(os.path.join(basedir, relpath))):
             cur_relpath = os.path.join(relpath, name)
             cur_path = os.path.join(basedir, cur_relpath)
@@ -261,7 +301,7 @@ def __init__(self, basedir, relpath=''):
 
 
 class _SlideFile:
-    def __init__(self, relpath):
+    def __init__(self, relpath: str):
         self.name = os.path.basename(relpath)
         self.url_path = relpath
 

examples/deepzoom/deepzoom_server.py

@@ -23,26 +23,32 @@
 
 from argparse import ArgumentParser
 import base64
+from collections.abc import Callable
 from io import BytesIO
 import os
 import re
+from typing import TYPE_CHECKING, Any, Literal, Mapping
 from unicodedata import normalize
 import zlib
 
-from PIL import ImageCms
-from flask import Flask, abort, make_response, render_template, url_for
+from PIL import Image, ImageCms
+from flask import Flask, Response, abort, make_response, render_template, url_for
+
+if TYPE_CHECKING:
+    # Python 3.10+
+    from typing import TypeAlias
 
 if os.name == 'nt':
     _dll_path = os.getenv('OPENSLIDE_PATH')
     if _dll_path is not None:
-        with os.add_dll_directory(_dll_path):
+        with os.add_dll_directory(_dll_path):  # type: ignore[attr-defined]
             import openslide
     else:
         import openslide
 else:
     import openslide
 
-from openslide import ImageSlide, open_slide
+from openslide import AbstractSlide, ImageSlide, open_slide
 from openslide.deepzoom import DeepZoomGenerator
 
 SLIDE_NAME = 'slide'
@@ -64,10 +70,33 @@
 )
 SRGB_PROFILE = ImageCms.getOpenProfile(BytesIO(SRGB_PROFILE_BYTES))
 
+if TYPE_CHECKING:
+    ColorMode: TypeAlias = Literal[
+        'default',
+        'absolute-colorimetric',
+        'perceptual',
+        'relative-colorimetric',
+        'saturation',
+        'embed',
+        'ignore',
+    ]
+    Transform: TypeAlias = Callable[[Image.Image], None]
+
+
+class DeepZoomServer(Flask):
+    slides: dict[str, DeepZoomGenerator]
+    transforms: dict[str, Transform]
+    slide_properties: Mapping[str, str]
+    associated_images: list[str]
+    slide_mpp: float
+
 
-def create_app(config=None, config_file=None):
+def create_app(
+    config: dict[str, Any] | None = None,
+    config_file: str | None = None,
+) -> Flask:
     # Create and configure app
-    app = Flask(__name__)
+    app = DeepZoomServer(__name__)
     app.config.from_mapping(
         DEEPZOOM_SLIDE=None,
         DEEPZOOM_FORMAT='jpeg',
@@ -117,7 +146,7 @@ def create_app(config=None, config_file=None):
 
     # Set up routes
     @app.route('/')
-    def index():
+    def index() -> str:
         slide_url = url_for('dzi', slug=SLIDE_NAME)
         associated_urls = {
             name: url_for('dzi', slug=slugify(name)) for name in app.associated_images
@@ -131,7 +160,7 @@ def index():
         )
 
     @app.route('/<slug>.dzi')
-    def dzi(slug):
+    def dzi(slug: str) -> Response:
         format = app.config['DEEPZOOM_FORMAT']
         try:
             resp = make_response(app.slides[slug].get_dzi(format))
@@ -142,7 +171,7 @@ def dzi(slug):
             abort(404)
 
     @app.route('/<slug>_files/<int:level>/<int:col>_<int:row>.<format>')
-    def tile(slug, level, col, row, format):
+    def tile(slug: str, level: int, col: int, row: int, format: str) -> Response:
         format = format.lower()
         if format != 'jpeg' and format != 'png':
             # Not supported by Deep Zoom
@@ -170,12 +199,12 @@ def tile(slug, level, col, row, format):
     return app
 
 
-def slugify(text):
+def slugify(text: str) -> str:
     text = normalize('NFKD', text.lower()).encode('ascii', 'ignore').decode()
     return re.sub('[^a-z0-9]+', '-', text)
 
 
-def get_transform(image, mode):
+def get_transform(image: AbstractSlide, mode: ColorMode) -> Transform:
     if image.color_profile is None:
         return lambda img: None
     if mode == 'ignore':
@@ -185,7 +214,7 @@ def get_transform(image, mode):
         # embed ICC profile in tiles
         return lambda img: None
     elif mode == 'default':
-        intent = ImageCms.getDefaultIntent(image.color_profile)
+        intent = ImageCms.Intent(ImageCms.getDefaultIntent(image.color_profile))
     elif mode == 'absolute-colorimetric':
         intent = ImageCms.Intent.ABSOLUTE_COLORIMETRIC
     elif mode == 'relative-colorimetric':
@@ -202,10 +231,10 @@ def get_transform(image, mode):
         'RGB',
         'RGB',
         intent,
-        0,
+        ImageCms.Flags(0),
     )
 
-    def xfrm(img):
+    def xfrm(img: Image.Image) -> None:
         ImageCms.applyTransform(img, transform, True)
         # Some browsers assume we intend the display's color space if we don't
         # embed the profile.  Pillow's serialization is larger, so use ours.