chore: add types to most of the uproot.source module (#996)

* typing

* annotations

* annotations on chunk

* annotations on cursor

* add annotations to sources

* Apply suggestions from code review

Co-authored-by: Jim Pivarski <[email protected]>

* style: pre-commit fixes

* type file paths as str

* use | instead of "or" for typing annotations

---------

Co-authored-by: Jim Pivarski <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

src/uproot/source/chunk.py

@@ -31,7 +31,7 @@ class Resource:
     """
 
     @property
-    def file_path(self):
+    def file_path(self) -> str:
         """
         A path to the file (or URL).
         """
@@ -49,7 +49,7 @@ class Source:
     the file.
     """
 
-    def chunk(self, start, stop) -> Chunk:
+    def chunk(self, start: int, stop: int) -> Chunk:
         """
         Args:
             start (int): Seek position of the first byte to include.
@@ -60,7 +60,9 @@ def chunk(self, start, stop) -> Chunk:
         :doc:`uproot.source.chunk.Chunk`.
         """
 
-    def chunks(self, ranges, notifications: queue.Queue) -> list[Chunk]:
+    def chunks(
+        self, ranges: list[(int, int)], notifications: queue.Queue
+    ) -> list[Chunk]:
         """
         Args:
             ranges (list of (int, int) 2-tuples): Intervals to fetch
@@ -90,7 +92,7 @@ def chunks(self, ranges, notifications: queue.Queue) -> list[Chunk]:
         """
 
     @property
-    def file_path(self):
+    def file_path(self) -> str:
         """
         A path to the file (or URL).
         """
@@ -154,7 +156,7 @@ def __repr__(self):
             type(self).__name__, path, self.num_workers, id(self)
         )
 
-    def chunk(self, start, stop) -> Chunk:
+    def chunk(self, start: int, stop: int) -> Chunk:
         self._num_requests += 1
         self._num_requested_chunks += 1
         self._num_requested_bytes += stop - start
@@ -164,7 +166,9 @@ def chunk(self, start, stop) -> Chunk:
         self._executor.submit(future)
         return chunk
 
-    def chunks(self, ranges, notifications: queue.Queue) -> list[Chunk]:
+    def chunks(
+        self, ranges: list[(int, int)], notifications: queue.Queue
+    ) -> list[Chunk]:
         self._num_requests += 1
         self._num_requested_chunks += len(ranges)
         self._num_requested_bytes += sum(stop - start for start, stop in ranges)
@@ -186,7 +190,7 @@ def executor(self):
         return self._executor
 
     @property
-    def num_workers(self):
+    def num_workers(self) -> int:
         """
         The number of :doc:`uproot.source.futures.ResourceWorker` threads in
         the :doc:`uproot.source.futures.ResourceThreadPoolExecutor`.
@@ -240,7 +244,7 @@ class Chunk:
     _dtype = numpy.dtype(numpy.uint8)
 
     @classmethod
-    def wrap(cls, source, data, start=0):
+    def wrap(cls, source: Source, data: numpy.ndarray | bytes, start: int = 0):
         """
         Args:
             source (:doc:`uproot.source.chunk.Source`): Source to attach to
@@ -255,7 +259,9 @@ def wrap(cls, source, data, start=0):
         future = uproot.source.futures.TrivialFuture(data)
         return Chunk(source, start, start + len(data), future)
 
-    def __init__(self, source, start, stop, future, is_memmap=False):
+    def __init__(
+        self, source: Source, start: int, stop: int, future, is_memmap: bool = False
+    ):
         self._source = source
         self._start = start
         self._stop = stop
@@ -267,21 +273,21 @@ def __repr__(self):
         return f"<Chunk {self._start}-{self._stop}>"
 
     @property
-    def source(self):
+    def source(self) -> Source:
         """
         Source from which this Chunk is derived.
         """
         return self._source
 
     @property
-    def start(self):
+    def start(self) -> int:
         """
         Seek position of the first byte to include.
         """
         return self._start
 
     @property
-    def stop(self):
+    def stop(self) -> int:
         """
         Seek position of the first byte to exclude (one greater than the last
         byte to include).
@@ -297,7 +303,7 @@ def future(self):
         return self._future
 
     @property
-    def is_memmap(self):
+    def is_memmap(self) -> bool:
         """
         If True, the `raw_data` is or will be a view into a memmap file, which
         must be handled carefully. Accessing that data after the file is closed
@@ -326,15 +332,15 @@ def detach_memmap(self):
         else:
             return self
 
-    def __contains__(self, range):
+    def __contains__(self, range: tuple[int, int]):
         start, stop = range
         if isinstance(start, uproot.source.cursor.Cursor):
             start = start.index
         if isinstance(stop, uproot.source.cursor.Cursor):
             stop = stop.index
         return self._start <= start and stop <= self._stop
 
-    def wait(self, insist=True):
+    def wait(self, insist: bool = True):
         """
         Args:
             insist (bool or int): If True, raise an OSError if ``raw_data`` does
@@ -368,7 +374,7 @@ def wait(self, insist=True):
             self._future = None
 
     @property
-    def raw_data(self):
+    def raw_data(self) -> numpy.ndarray | bytes:
         """
         Data from the Source as a ``numpy.ndarray`` of ``numpy.uint8``.
 
@@ -379,7 +385,9 @@ def raw_data(self):
         self.wait()
         return self._raw_data
 
-    def get(self, start, stop, cursor, context):
+    def get(
+        self, start: int, stop: int, cursor: uproot.source.cursor.Cursor, context: dict
+    ) -> numpy.ndarray:
         """
         Args:
             start (int): Seek position of the first byte to include.
@@ -417,7 +425,9 @@ def get(self, start, stop, cursor, context):
                 self._source.file_path,
             )
 
-    def remainder(self, start, cursor, context):
+    def remainder(
+        self, start: int, cursor: uproot.source.cursor.Cursor, context: dict
+    ) -> numpy.ndarray:
         """
         Args:
             start (int): Seek position of the first byte to include.