From 442e7a4805a71d6a9bd735095e5a6e2db254beb1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edouard=20Choini=C3=A8re?=
 <27212526+echoix@users.noreply.github.com>
Date: Sat, 26 Oct 2024 23:23:46 +0000
Subject: [PATCH 1/7] 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
---
 python/grass/temporal/factory.py | 46 +++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 18 deletions(-)

diff --git a/python/grass/temporal/factory.py b/python/grass/temporal/factory.py
index ba7f5e7d4f0..578c2d74a9c 100644
--- a/python/grass/temporal/factory.py
+++ b/python/grass/temporal/factory.py
@@ -18,6 +18,8 @@
 :authors: Soeren Gebbert
 """
 
+from __future__ import annotations
+
 from .core import get_tgis_message_interface
 from .space_time_datasets import (
     Raster3DDataset,
@@ -31,7 +33,17 @@
 ###############################################################################
 
 
-def dataset_factory(type, id):
+def dataset_factory(
+    type: str, id: str
+) -> (
+    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 +51,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

From 238f4180a9a031fb17b17ed2092f89fbc9211c67 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 00:33:03 +0000
Subject: [PATCH 2/7] temporal: Add typing overloads to dataset_factory

---
 python/grass/temporal/factory.py | 49 +++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/python/grass/temporal/factory.py b/python/grass/temporal/factory.py
index 578c2d74a9c..5408e091fa6 100644
--- a/python/grass/temporal/factory.py
+++ b/python/grass/temporal/factory.py
@@ -20,6 +20,8 @@
 
 from __future__ import annotations
 
+from typing import Literal, overload
+
 from .core import get_tgis_message_interface
 from .space_time_datasets import (
     Raster3DDataset,
@@ -33,8 +35,53 @@
 ###############################################################################
 
 
+@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
+
+
 def dataset_factory(
-    type: str, id: str
+    type: Literal[
+        "strds",
+        "str3ds",
+        "stvds",
+        "rast",
+        "raster",
+        "raster_3d",
+        "rast3d",
+        "raster3d",
+        "vect",
+        "vector",
+    ],
+    id: str,
 ) -> (
     SpaceTimeRasterDataset
     | SpaceTimeRaster3DDataset

From 51528601b55bf00e6b72d29c681734baea2efd3f 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 00:55:14 +0000
Subject: [PATCH 3/7] temporal: Add dataset_factory implementation with str
 type for type argument

---
 python/grass/temporal/factory.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/python/grass/temporal/factory.py b/python/grass/temporal/factory.py
index 5408e091fa6..559b219ed33 100644
--- a/python/grass/temporal/factory.py
+++ b/python/grass/temporal/factory.py
@@ -68,6 +68,7 @@ def dataset_factory(type: Literal["vect", "vector"], id: str) -> VectorDataset:
     pass
 
 
+@overload
 def dataset_factory(
     type: Literal[
         "strds",
@@ -82,6 +83,19 @@ def dataset_factory(
         "vector",
     ],
     id: str,
+) -> (
+    SpaceTimeRasterDataset
+    | SpaceTimeRaster3DDataset
+    | SpaceTimeVectorDataset
+    | RasterDataset
+    | Raster3DDataset
+    | VectorDataset
+):
+    pass
+
+
+def dataset_factory(
+    type: str, id: str
 ) -> (
     SpaceTimeRasterDataset
     | SpaceTimeRaster3DDataset

From e52e568c4c2dcad37fd5dc52fac6e701a768d66d 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 01:16:28 +0000
Subject: [PATCH 4/7] temporal: Remove dataset_factory overload that listed all
 literal types

---
 python/grass/temporal/factory.py | 26 --------------------------
 1 file changed, 26 deletions(-)

diff --git a/python/grass/temporal/factory.py b/python/grass/temporal/factory.py
index 559b219ed33..b336a300764 100644
--- a/python/grass/temporal/factory.py
+++ b/python/grass/temporal/factory.py
@@ -68,32 +68,6 @@ def dataset_factory(type: Literal["vect", "vector"], id: str) -> VectorDataset:
     pass
 
 
-@overload
-def dataset_factory(
-    type: Literal[
-        "strds",
-        "str3ds",
-        "stvds",
-        "rast",
-        "raster",
-        "raster_3d",
-        "rast3d",
-        "raster3d",
-        "vect",
-        "vector",
-    ],
-    id: str,
-) -> (
-    SpaceTimeRasterDataset
-    | SpaceTimeRaster3DDataset
-    | SpaceTimeVectorDataset
-    | RasterDataset
-    | Raster3DDataset
-    | VectorDataset
-):
-    pass
-
-
 def dataset_factory(
     type: str, id: str
 ) -> (

From eb1a7883946ef3da37e5ddea1e20729243464d0b 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 01:52:25 +0000
Subject: [PATCH 5/7] temporal: Update dataset_factory file header

---
 python/grass/temporal/factory.py | 13 ++-----------
 1 file changed, 2 insertions(+), 11 deletions(-)

diff --git a/python/grass/temporal/factory.py b/python/grass/temporal/factory.py
index b336a300764..ea23ba76ade 100644
--- a/python/grass/temporal/factory.py
+++ b/python/grass/temporal/factory.py
@@ -1,21 +1,12 @@
 """
 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 fb023d0eb1766687e449945c84a9e0915cf2f45f 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 01:53:58 +0000
Subject: [PATCH 6/7] temporal: Add dataset_factory overload with str type for
 type argument

---
 python/grass/temporal/factory.py | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/python/grass/temporal/factory.py b/python/grass/temporal/factory.py
index ea23ba76ade..4c9792d20a4 100644
--- a/python/grass/temporal/factory.py
+++ b/python/grass/temporal/factory.py
@@ -59,6 +59,21 @@ 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
 ) -> (

From a7d4b29d9a4862818df8feb4da19cfa6fc2b8e65 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 11:47:12 +0000
Subject: [PATCH 7/7] temporal: Accept None for id argument in dataset_factory
 overload as used in existing calls

---
 python/grass/temporal/factory.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/python/grass/temporal/factory.py b/python/grass/temporal/factory.py
index 4c9792d20a4..f246700ef44 100644
--- a/python/grass/temporal/factory.py
+++ b/python/grass/temporal/factory.py
@@ -75,7 +75,7 @@ def dataset_factory(
 
 
 def dataset_factory(
-    type: str, id: str
+    type: str, id: str | None
 ) -> (
     SpaceTimeRasterDataset
     | SpaceTimeRaster3DDataset