Add type hinting (fixes DEV-127)

.github/workflows/run-tests.yml

@@ -45,15 +45,16 @@ jobs:
         # numpy<2 is needed for gdal to contain support for gdal array
         pip install 'numpy<2'
         CPLUS_INCLUDE_PATH=/usr/include/gdal C_INCLUDE_PATH=/usr/include/gdal pip install --no-build-isolation 'gdal==3.8.4'
-        pip install coverage isort flake8 'black<25' twine setuptools build
+        pip install coverage isort flake8 'black<25' twine setuptools build pyright setuptools_scm cython
         pip install -e .
 
     - name: Run Tests
       run: |
         source ~/.venv/bin/activate
         black --check .
-        flake8 --max-line-length=88 .
+        flake8 --extend-ignore=E501 .
         isort --check-only --diff --profile=black *.py .
+        pyright .
         python -m build
         twine check dist/*
         coverage run --include="./*" --omit="docs/","*/tests/*","_version.py","*.pyx" -m unittest -v

CHANGELOG.rst

@@ -2,6 +2,12 @@
 Changelog
 =========
 
+DEV
+===
+
+* Added textbisect module.
+* Added type hints.
+
 2.6.0 (2025-10-01)
 ==================
 

MANIFEST.in

@@ -5,5 +5,7 @@ include README.rst
 recursive-include tests *
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]
+recursive-include src *.pyi
+recursive-include src py.typed
 
 recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif

docs/enhydris_cache/api.rst

@@ -12,9 +12,10 @@ enhydris-cache API
    is downloaded from Enhydris using the Enhydris web service API.
    *timeseries_groups* is a list; each item is a dictionary
    representing an Enhydris time series; its keys are *base_url*,
-   *auth_token*, *id*, and *file*; the latter is the filename of
-   the file to which the time series will be cached (absolute or
-   relative to the current working directory).
+   *auth_token*, *station_id*, *timeseries_group_id*, *timeseries_id*,
+   and *file*; the latter is the filename of the file to which the
+   time series will be cached (absolute or relative to the current
+   working directory).
 
    .. method:: update()
 

docs/index.rst

@@ -12,9 +12,10 @@ pthelma - Utilities for hydrological and meteorological time series processing
 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    htimeseries
+   textbisect
 
 
 .. toctree::

docs/textbisect.rst

@@ -0,0 +1,37 @@
+=========================================
+textbisect - Binary search in a text file
+=========================================
+
+This module provides functionality to search inside sorted text
+files.  The lines of the files need not be all of the same length. The
+module contains the following functions:
+
+.. function:: text_bisect_left(a, x, lo=0, hi=None, key=lambda x: x)
+
+   Locates the insertion point for line ``x`` in seekable filelike
+   object ``a`` consisting of a number of lines; ``x`` must be specified
+   without a trailing newline. ``a`` must use ``\n`` as the newline
+   character and must not perform any line endings translation (use
+   ``open(..., newline='\n')``).  The parameters ``lo`` and ``hi``, if
+   specified, must be absolute positions within object ``a``, and
+   specify which part of ``a`` to search; the default is to search the
+   entire ``a``. The character pointed to by ``hi`` (or the last
+   character of the object, if ``hi`` is unspecified) must be a newline.
+   ``key`` is a function that is used to compare each line of ``a`` with
+   ``x``; line endings are removed from the lines of ``a`` before
+   comparison. ``a`` must be sorted or the result will be undefined. If
+   ``x`` compares equal to a line in ``a``, the returned insertion point
+   is the beginning of that line. The initial position of ``a`` is
+   discarded. The function returns the insertion point, which is an
+   integer between ``lo`` and ``hi+1``, pointing to the beginning of a
+   line; when it exits, ``a`` is positioned there.
+
+.. function:: text_bisect_right(a, x, lo=0, hi=None, key=lambda x: x)
+
+   The same as :func:`text_bisect_left`, except that if ``x`` compares
+   equal to a line in ``a``, the returned insertion point is the
+   beginning of the next line.
+
+.. function:: text_bisect(a, x, lo=0, hi=None, key=lambda x: x)
+
+   Same as :func:`text_bisect_right`.

pyproject.toml

@@ -15,7 +15,6 @@ dependencies = [
     # that it be <2.
     "numpy<2",
     "iso8601>=2.1,<3",
-    "textbisect>=0.1,<1",
     "tzdata",
     "Click>=7.0,<8.2",
     "simpletail>=1,<2",
@@ -61,6 +60,9 @@ max-line-length = 88
 [tool.setuptools]
 package-dir = {"" = "src"}
 
+[tool.setuptools.package-data]
+"*" = ["*.pyi", "py.typed"]
+
 [tool.setuptools_scm]
 write_to = "src/pthelma/_version.py"
 
@@ -75,3 +77,6 @@ skip = "pp* cp313-*"
 [tool.isort]
 skip = ["_version.py"]
 extra_standard_library = ["cpython", "libc"]
+
+[tool.pyright]
+ignore = ["osgeo.*", "django.contrib.gis.*"]