From 80bcb4f062d996ed56fc395f8bdb7758008aee40 Mon Sep 17 00:00:00 2001
From: Eliot Robson <eliot.robson24@gmail.com>
Date: Fri, 24 Jan 2025 22:09:30 -0600
Subject: [PATCH] Add some more type hints

---
 pooch/core.py  | 41 +++++++++++++++++++++--------------------
 pooch/utils.py | 10 +++++++++-
 2 files changed, 30 insertions(+), 21 deletions(-)

diff --git a/pooch/core.py b/pooch/core.py
index 3629c3be..3141f80f 100644
--- a/pooch/core.py
+++ b/pooch/core.py
@@ -26,10 +26,11 @@
     temporary_file,
     os_cache,
     unique_file_name,
+    FilePath,
+    FilePathInput,
 )
 from .downloaders import DOIDownloader, choose_downloader, doi_to_repository
 
-FilePath = Union[str, os.PathLike]
 Actions = Literal["download", "fetch", "update"]
 
 
@@ -49,18 +50,18 @@ def __call__(  # noqa: E704
     ) -> Any: ...
 
 
-Processor = Callable[[str, Actions, "Pooch"], Any]
+Processor = Callable[[str, Actions, Optional["Pooch"]], Any]
 
 
 def retrieve(
-    url,
-    known_hash,
-    fname=None,
-    path=None,
-    processor=None,
-    downloader=None,
-    progressbar=False,
-):
+    url: str,
+    known_hash: Optional[str] = None,
+    fname: Optional[str] = None,
+    path: Optional[FilePath] = None,
+    processor: Optional[Processor] = None,
+    downloader: Optional[Downloader] = None,
+    progressbar: bool = False,
+) -> str:
     """
     Download and cache a single file locally.
 
@@ -278,15 +279,15 @@ def retrieve(
 
 
 def create(
-    path,
-    base_url,
-    version=None,
-    version_dev="master",
-    env=None,
-    registry=None,
-    urls=None,
-    retry_if_failed=0,
-    allow_updates=True,
+    path: FilePathInput,
+    base_url: str,
+    version: Optional[str] = None,
+    version_dev: str = "master",
+    env: Optional[str] = None,
+    registry: Optional[dict] = None,
+    urls: Optional[dict] = None,
+    retry_if_failed: int = 0,
+    allow_updates: Union[bool, str] = True,
 ):
     """
     Create a :class:`~pooch.Pooch` with sensible defaults to fetch data files.
@@ -503,7 +504,7 @@ class Pooch:
 
     def __init__(
         self,
-        path: str,
+        path: FilePath,
         base_url: str,
         registry: Optional[dict[str, str]] = None,
         urls: Optional[dict[str, str]] = None,
diff --git a/pooch/utils.py b/pooch/utils.py
index fb88dab7..70bbb2d5 100644
--- a/pooch/utils.py
+++ b/pooch/utils.py
@@ -7,6 +7,7 @@
 """
 Misc utilities
 """
+
 import logging
 import os
 import tempfile
@@ -198,7 +199,14 @@ def parse_url(url):
     return {"protocol": protocol, "netloc": netloc, "path": path}
 
 
-def cache_location(path, env=None, version=None):
+from typing import Optional, Union
+
+FilePath = Union[str, os.PathLike]
+FilePathInput = Union[FilePath, list[FilePath], tuple[FilePath]]
+
+def cache_location(
+    path: FilePathInput, env: Optional[str] = None, version: Optional[str] = None
+) -> Path:
     """
     Location of the cache given a base path and optional configuration.