From b80f8eb8e76f8a105d9b44bc3dff77ffd463e855 Mon Sep 17 00:00:00 2001
From: spider-hand <creative.spider.hand@gmail.com>
Date: Mon, 20 Oct 2025 22:33:59 +0900
Subject: [PATCH] refactor: type header (#597)

---
 python/pmtiles/pmtiles/tile.py   | 33 ++++++++++++++++++++++++++++++--
 python/pmtiles/test/test_tile.py |  8 +++++++-
 2 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/python/pmtiles/pmtiles/tile.py b/python/pmtiles/pmtiles/tile.py
index 6e0429f..66682c3 100644
--- a/python/pmtiles/pmtiles/tile.py
+++ b/python/pmtiles/pmtiles/tile.py
@@ -1,6 +1,7 @@
 import gzip
 import io
 from enum import Enum
+from typing import TypedDict
 
 
 class Entry:
@@ -186,7 +187,35 @@ class MagicNumberNotFound(Exception):
     pass
 
 
-def deserialize_header(buf):
+class HeaderDict(TypedDict):
+    version: int
+    root_offset: int
+    root_length: int
+    metadata_offset: int
+    metadata_length: int
+    leaf_directory_offset: int
+    leaf_directory_length: int
+    tile_data_offset: int
+    tile_data_length: int
+    addressed_tiles_count: int
+    tile_entries_count: int
+    tile_contents_count: int
+    clustered: bool
+    internal_compression: Compression
+    tile_compression: Compression
+    tile_type: TileType
+    min_zoom: int
+    max_zoom: int
+    min_lon_e7: int
+    min_lat_e7: int
+    max_lon_e7: int
+    max_lat_e7: int
+    center_zoom: int
+    center_lon_e7: int
+    center_lat_e7: int
+
+
+def deserialize_header(buf) -> HeaderDict:
     if buf[0:7].decode() != "PMTiles":
         raise MagicNumberNotFound()
 
@@ -228,7 +257,7 @@ def deserialize_header(buf):
     }
 
 
-def serialize_header(h):
+def serialize_header(h: HeaderDict):
     b_io = io.BytesIO()
 
     def write_uint64(i):
diff --git a/python/pmtiles/test/test_tile.py b/python/pmtiles/test/test_tile.py
index 25859e0..468a81e 100644
--- a/python/pmtiles/test/test_tile.py
+++ b/python/pmtiles/test/test_tile.py
@@ -1,7 +1,7 @@
 import unittest
 from pmtiles.tile import zxy_to_tileid, tileid_to_zxy, Entry
 from pmtiles.tile import read_varint, write_varint
-from pmtiles.tile import Entry, find_tile, Compression, TileType
+from pmtiles.tile import Entry, find_tile, Compression, TileType, HeaderDict
 from pmtiles.tile import serialize_directory, deserialize_directory
 from pmtiles.tile import serialize_header, deserialize_header, SpecVersionUnsupported, MagicNumberNotFound
 import io
@@ -194,3 +194,9 @@ class TestHeader(unittest.TestCase):
 
         with self.assertRaises(MagicNumberNotFound):
             result = deserialize_header(b'PM\x00\x02')
+
+    def test_type(self):
+        result = deserialize_header(b"PMTiles\x03" + b"\x00" * 120)
+        self.assertIsInstance(result, dict)
+        expected_keys = set(HeaderDict.__annotations__.keys())
+        self.assertTrue(expected_keys.issubset(result.keys()))