chore(types): Type hint Utils module (#1043)

* Add types to Generic sequence implementations

* Fix type hints for python 3.9 and add changelog entry

* Correct type hints

* Add typing to instances of Maps

* Use typehints on CachedMaps

* Tighten types

* Restore type var for rebasing

* Update and prevent problems

* Correct type hints

* Correct changelog version

Author: DiamondJoseph

CHANGELOG.md

@@ -3,6 +3,11 @@ Write the date in place of the "Unreleased" in the case a new version is release
 
 # Changelog
 
+## v0.1.0-b36 (Unreleased)
+
+### Changed
+
+- Typehint utils collection implementations
 
 ## v0.1.0-b35 (2025-08-20)
 
@@ -86,7 +91,6 @@ continuous deployment processes.
 - Typehinted database access methods
 - Explicit type conversion in SQL adapter when appending to an existing table.
 
-
 ## v0.1.0-b30 (2025-07-18)
 
 ### Changed

tiled/_tests/test_caches.py

@@ -8,7 +8,7 @@ def test_one_shot_cached_map():
 
     counter = 0
 
-    def f():
+    def f() -> int:
         nonlocal counter
         counter += 1
         return 5
@@ -36,7 +36,7 @@ def test_caching_map():
 
     counter = 0
 
-    def f():
+    def f() -> int:
         nonlocal counter
         counter += 1
         return 5

tiled/_tests/test_utils.py

@@ -172,10 +172,10 @@ def text(self, s):
 
 def test_oneshotcachedmap_repr_lazy_and_evaluated():
     # Value factories
-    def factory1():
+    def factory1() -> int:
         return 42
 
-    def factory2():
+    def factory2() -> str:
         return "foo"
 
     # All values are lazy initially
@@ -200,10 +200,10 @@ def factory2():
 
 def test_cachingmap_repr_lazy_and_evaluated():
     # Value factories
-    def factory1():
+    def factory1() -> int:
         return 123
 
-    def factory2():
+    def factory2() -> str:
         return "bar"
 
     mapping = {"x": factory1, "y": factory2}

tiled/catalog/adapter.py

@@ -109,7 +109,9 @@
     StructureFamily.table: PARQUET_MIMETYPE,
     StructureFamily.sparse: SPARSE_BLOCKS_PARQUET_MIMETYPE,
 }
-STORAGE_ADAPTERS_BY_MIMETYPE = OneShotCachedMap(
+
+# TODO: make type[Adapter] after #1047
+STORAGE_ADAPTERS_BY_MIMETYPE = OneShotCachedMap[str, type](
     {
         ZARR_MIMETYPE: lambda: importlib.import_module(
             "...adapters.zarr", __name__

tiled/client/base.py

@@ -2,6 +2,7 @@
 from copy import copy, deepcopy
 from dataclasses import asdict
 from pathlib import Path
+from typing import Dict, List, Union
 from urllib.parse import parse_qs, urlparse
 
 import json_merge_patch
@@ -17,6 +18,10 @@
 from .metadata_update import apply_update_patch
 from .utils import MSGPACK_MIME_TYPE, handle_error, retry_context
 
+# TODO: Duplicated from  tiled.type_aliases to prevent importing numpy
+# After #1407 replace AnyAdapter with the BaseClass and remove this redefinition
+JSON_ITEM = Union[str, int, float, bool, Dict[str, "JSON_ITEM"], List["JSON_ITEM"]]
+
 
 class MetadataRevisions:
     def __init__(self, context, link):
@@ -229,7 +234,7 @@ def item(self):
         return self._item
 
     @property
-    def metadata(self):
+    def metadata(self) -> DictView[str, JSON_ITEM]:
         "Metadata about this data source."
         # Ensure this is immutable (at the top level) to help the user avoid
         # getting the wrong impression that editing this would update anything
@@ -262,12 +267,12 @@ def metadata_copy(self):
         ]  # returning as list of mutable items
 
     @property
-    def specs(self):
+    def specs(self) -> ListView[Spec]:
         "List of specifications describing the structure of the metadata and/or data."
         return ListView([Spec(**spec) for spec in self._item["attributes"]["specs"]])
 
     @property
-    def access_blob(self):
+    def access_blob(self) -> DictView[str, JSON_ITEM]:
         "Authorization information about this node, in blob form"
         access_blob = self._item["attributes"]["access_blob"]
         if access_blob is None:

tiled/client/container.py

@@ -44,7 +44,7 @@ class Container(BaseClient, collections.abc.Mapping, IndexersMixin):
     STRUCTURE_CLIENTS_FROM_ENTRYPOINTS = None
 
     @classmethod
-    def _discover_entrypoints(cls, entrypoint_name):
+    def _discover_entrypoints(cls, entrypoint_name) -> OneShotCachedMap[str, Any]:
         return OneShotCachedMap(
             {
                 name: entrypoint.load

tiled/client/context.py

@@ -6,7 +6,7 @@
 import urllib.parse
 import warnings
 from pathlib import Path
-from typing import List
+from typing import List, Literal
 from urllib.parse import parse_qs, urlparse
 
 import httpx
@@ -473,7 +473,7 @@ def from_app(
         return context
 
     @property
-    def tokens(self):
+    def tokens(self) -> DictView[Literal["access_token", "refresh_token"], str]:
         "A view of the current access and refresh tokens."
         return DictView(self.http_client.auth.tokens)
 

tiled/media_type_registration.py

@@ -51,7 +51,7 @@ def __init__(self):
         for ext, media_type in self.DEFAULT_ALIASES.items():
             self.register_alias(ext, media_type)
 
-    def media_types(self, structure_family):
+    def media_types(self, structure_family) -> DictView[str, str]:
         """
         List the supported media types for a given structure family.
         """

tiled/mimetypes.py

@@ -12,7 +12,8 @@
 ZARR_MIMETYPE = "application/x-zarr"
 AWKWARD_BUFFERS_MIMETYPE = "application/x-awkward-buffers"
 TILED_SQL_TABLE_MIMETYPE = "application/x-tiled-sql-table"
-DEFAULT_ADAPTERS_BY_MIMETYPE = OneShotCachedMap(
+# TODO: make type[Adapter] after #1047
+DEFAULT_ADAPTERS_BY_MIMETYPE = OneShotCachedMap[str, type](
     {
         "image/tiff": lambda: importlib.import_module(
             "..adapters.tiff", __name__

tiled/query_registration.py

@@ -27,11 +27,11 @@ def __init__(self):
         self._query_type_to_name = {}
 
     @property
-    def name_to_query_type(self):
+    def name_to_query_type(self) -> DictView[Any, Any]:
         return DictView(self._name_to_query_type_type)
 
     @property
-    def query_type_to_name(self):
+    def query_type_to_name(self) -> DictView[Any, Any]:
         return DictView(self._query_type_to_name)
 
     def register(self, name=None, overwrite=False, must_revalidate=True):