From ffcb9e1621579bbfbf56e5417cb7946b4d2fe9cd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edouard=20Choini=C3=A8re?=
 <27212526+echoix@users.noreply.github.com>
Date: Sun, 27 Oct 2024 09:56:30 -0400
Subject: [PATCH] temporal: Add precise typing overloads to dataset_factory
 (#4600)

* temporal: Add precise typing overloads to dataset_factory

This enables type checkers like mypy or Pyright to understand the returned class from the string passed as the type argument

* temporal: Add typing overloads to dataset_factory

* temporal: Add dataset_factory implementation with str type for type argument

* temporal: Remove dataset_factory overload that listed all literal types

* temporal: Update dataset_factory file header

* temporal: Add dataset_factory overload with str type for type argument

* temporal: Accept None for id argument in dataset_factory overload as used in existing calls
---
 python/grass/temporal/factory.py | 109 +++++++++++++++++++++++--------
 1 file changed, 80 insertions(+), 29 deletions(-)

diff --git a/python/grass/temporal/factory.py b/python/grass/temporal/factory.py
index ba7f5e7d4f0..f246700ef44 100644
--- a/python/grass/temporal/factory.py
+++ b/python/grass/temporal/factory.py
@@ -1,23 +1,18 @@
 """
 Object factory
 
-Usage:
-
-.. code-block:: python
-
-    import grass.temporal as tgis
-
-    tgis.register_maps_in_space_time_dataset(type, name, maps)
-
-
-(C) 2012-2013 by the GRASS Development Team
+(C) 2012-2024 by the GRASS Development Team
 This program is free software under the GNU General Public
 License (>=v2). Read the file COPYING that comes with GRASS
 for details.
 
-:authors: Soeren Gebbert
+:authors: Soeren Gebbert, Edouard Choinière
 """
 
+from __future__ import annotations
+
+from typing import Literal, overload
+
 from .core import get_tgis_message_interface
 from .space_time_datasets import (
     Raster3DDataset,
@@ -31,7 +26,65 @@
 ###############################################################################
 
 
-def dataset_factory(type, id):
+@overload
+def dataset_factory(type: Literal["strds"], id: str) -> SpaceTimeRasterDataset:
+    pass
+
+
+@overload
+def dataset_factory(type: Literal["str3ds"], id: str) -> SpaceTimeRaster3DDataset:
+    pass
+
+
+@overload
+def dataset_factory(type: Literal["stvds"], id: str) -> SpaceTimeVectorDataset:
+    pass
+
+
+@overload
+def dataset_factory(type: Literal["rast", "raster"], id: str) -> RasterDataset:
+    pass
+
+
+@overload
+def dataset_factory(
+    type: Literal["raster_3d", "rast3d", "raster3d"],
+    id: str,
+) -> Raster3DDataset:
+    pass
+
+
+@overload
+def dataset_factory(type: Literal["vect", "vector"], id: str) -> VectorDataset:
+    pass
+
+
+@overload
+def dataset_factory(
+    type: str, id: str
+) -> (
+    SpaceTimeRasterDataset
+    | SpaceTimeRaster3DDataset
+    | SpaceTimeVectorDataset
+    | RasterDataset
+    | Raster3DDataset
+    | VectorDataset
+    | None
+):
+    pass
+
+
+def dataset_factory(
+    type: str, id: str | None
+) -> (
+    SpaceTimeRasterDataset
+    | SpaceTimeRaster3DDataset
+    | SpaceTimeVectorDataset
+    | RasterDataset
+    | Raster3DDataset
+    | VectorDataset
+    | None
+):
     """A factory functions to create space time or map datasets
 
     :param type: the dataset type: rast or raster; rast3d, raster3d or raster_3d;
@@ -39,20 +92,18 @@ def dataset_factory(type, id):
     :param id: The id of the dataset ("name@mapset")
     """
     if type == "strds":
-        sp = SpaceTimeRasterDataset(id)
-    elif type == "str3ds":
-        sp = SpaceTimeRaster3DDataset(id)
-    elif type == "stvds":
-        sp = SpaceTimeVectorDataset(id)
-    elif type in {"rast", "raster"}:
-        sp = RasterDataset(id)
-    elif type in {"raster_3d", "rast3d", "raster3d"}:
-        sp = Raster3DDataset(id)
-    elif type in {"vect", "vector"}:
-        sp = VectorDataset(id)
-    else:
-        msgr = get_tgis_message_interface()
-        msgr.error(_("Unknown dataset type: %s") % type)
-        return None
-
-    return sp
+        return SpaceTimeRasterDataset(id)
+    if type == "str3ds":
+        return SpaceTimeRaster3DDataset(id)
+    if type == "stvds":
+        return SpaceTimeVectorDataset(id)
+    if type in {"rast", "raster"}:
+        return RasterDataset(id)
+    if type in {"raster_3d", "rast3d", "raster3d"}:
+        return Raster3DDataset(id)
+    if type in {"vect", "vector"}:
+        return VectorDataset(id)
+
+    msgr = get_tgis_message_interface()
+    msgr.error(_("Unknown dataset type: %s") % type)
+    return None