Add static typing support

.github/stubtest-allowlist

@@ -0,0 +1,33 @@
+netCDF4.AccessModeOptions
+netCDF4.CompressionLevelOptions
+netCDF4.CompressionOptions
+netCDF4.DatatypeOptions
+netCDF4.DimensionsOptions
+netCDF4.DiskFormatOptions
+netCDF4.EndianOptions
+netCDF4.FormatOptions
+netCDF4.QuantizeOptions
+netCDF4.CalendarOptions
+netCDF4.ellipsis
+netCDF4.DateTimeArray
+netCDF4.FiltersDict
+netCDF4.SzipInfo
+netCDF4.BloscInfo
+netCDF4.BoolInt
+netCDF4.GetSetItemKey
+netCDF4.T_Datatype
+netCDF4.T_DatatypeNC
+netCDF4.Dataset.__dealloc
+netCDF4.Dimension.__reduce_cython__
+netCDF4.Dimension.__setstate_cython__
+netCDF4.Variable.auto_complex
+netCDF4._netCDF4.Dataset.__dealloc
+netCDF4._netCDF4.Dimension.__reduce_cython__
+netCDF4._netCDF4.Dimension.__setstate_cython__
+netCDF4._netCDF4.NC_DISKLESS
+netCDF4._netCDF4.NC_PERSIST
+netCDF4._netCDF4.Variable.auto_complex
+netCDF4._netCDF4.__reduce_cython__
+netCDF4._netCDF4.__setstate_cython__
+netCDF4._netCDF4.__test__
+netCDF4.utils.bytes

.github/workflows/build_master.yml

@@ -47,13 +47,14 @@ jobs:
     - name: Install python dependencies via pip
       run: |
         python -m pip install --upgrade pip
-        pip install numpy cython cftime pytest twine wheel check-manifest mpi4py
+        pip install numpy cython cftime pytest twine wheel check-manifest mpi4py mypy types-setuptools
 
     - name: Install netcdf4-python
       run: |
         export PATH=${NETCDF_DIR}/bin:${PATH} 
         export NETCDF_PLUGIN_DIR=${{ github.workspace }}/netcdf-c/plugins/plugindir
         python setup.py install
+
     - name: Test
       run: |
         export PATH=${NETCDF_DIR}/bin:${PATH} 
@@ -78,3 +79,9 @@ jobs:
         else
           echo "hdf5 compressed mpi test passed!"
         fi
+
+    - name: Stubtest
+      run: |
+        stubtest netCDF4 --allowlist .github/stubtest-allowlist --mypy-config-file=pyproject.toml
+        mypy test
+        mypy examples

.gitignore

@@ -2,8 +2,11 @@ build/
 *.pyc
 dist/
 *.egg-info/
-netCDF4/_netCDF4.c
-netCDF4/*.so
+__pycache__
+.mypy_cache
+src/netCDF4/*.c
+src/netCDF4/*.so
+src/netCDF4/*.pyd
 include/constants.pyx
 include/parallel_support_imports.pxi
 netcdftime/_netcdftime.c

Changelog

@@ -1,3 +1,7 @@
+ version 1.7.2 (tag v1.7.2rel)
+===============================
+ * add static type hints (PR #1302)
+
  version 1.7.1 (tag v1.7.1rel)
 ===============================
  * include nc_complex source code from v0.2.0 tag (instead of using submodule).

MANIFEST.in

@@ -15,6 +15,7 @@ include src/netCDF4/_netCDF4.pyx
 exclude src/netCDF4/_netCDF4.c
 include src/netCDF4/utils.py
 include src/netCDF4/plugins/empty.txt
+include src/netCDF4/py.typed
 include include/netCDF4.pxi
 include include/mpi-compat.h
 include include/membuf.pyx
@@ -23,6 +24,7 @@ include include/no_parallel_support_imports.pxi.in
 include include/parallel_support_imports.pxi.in
 include *.md
 include *.py
+include *.pyi
 include *.release
 include *.sh
 include LICENSE

docs/index.html

@@ -118,8 +118,8 @@ <h2 id="creatingopeningclosing-a-netcdf-file">Creating/Opening/Closing a netCDF
 If the file is open for write access (<code>mode='w', 'r+'</code> or <code>'a'</code>), you may
 write any type of data including new dimensions, groups, variables and
 attributes.
-netCDF files come in five flavors (<code>NETCDF3_CLASSIC,
-NETCDF3_64BIT_OFFSET, NETCDF3_64BIT_DATA, NETCDF4_CLASSIC&lt;code&gt;, and &lt;/code&gt;NETCDF4</code>).
+netCDF files come in five flavors (<code>NETCDF3_CLASSIC</code>,
+<code>NETCDF3_64BIT_OFFSET</code>, <code>NETCDF3_64BIT_DATA</code>, <code>NETCDF4_CLASSIC</code>, and <code>NETCDF4</code>).
 <code>NETCDF3_CLASSIC</code> was the original netcdf binary format, and was limited
 to file sizes less than 2 Gb. <code>NETCDF3_64BIT_OFFSET</code> was introduced
 in version 3.6.0 of the library, and extended the original binary format

examples/bench_compress.py

@@ -13,7 +13,7 @@
 ntrials = 10
 sys.stdout.write('reading and writing a %s by %s by %s by %s random array ..\n'%(n1dim,n2dim,n3dim,n4dim))
 sys.stdout.write('(average of %s trials)\n' % ntrials)
-array = netCDF4.utils._quantize(uniform(size=(n1dim,n2dim,n3dim,n4dim)),4)
+array = netCDF4.utils._quantize(uniform(size=(n1dim,n2dim,n3dim,n4dim)),4)  # type: ignore
 
 
 def write_netcdf(filename,zlib=False,shuffle=False,complevel=6):

examples/mpi_example.py

@@ -1,36 +1,50 @@
 # to run: mpirun -np 4 python mpi_example.py
 import sys
+from typing import Literal
 from mpi4py import MPI
 import numpy as np
 from netCDF4 import Dataset
+
+format: Literal[
+    'NETCDF4',
+    'NETCDF4_CLASSIC',
+    'NETCDF3_CLASSIC',
+    'NETCDF3_64BIT_OFFSET',
+    'NETCDF3_64BIT_DATA'
+]
 if len(sys.argv) == 2:
-	format = sys.argv[1]
+    format = sys.argv[1]  # type: ignore
 else:
 	format = 'NETCDF4_CLASSIC'
+
 rank = MPI.COMM_WORLD.rank  # The process ID (integer 0-3 for 4-process run)
 if rank == 0:
-	print('Creating file with format {}'.format(format))
+    print('Creating file with format {}'.format(format))
 nc = Dataset('parallel_test.nc', 'w', parallel=True, comm=MPI.COMM_WORLD,
-        info=MPI.Info(),format=format)
+    info=MPI.Info(), format=format)
 # below should work also - MPI_COMM_WORLD and MPI_INFO_NULL will be used.
 #nc = Dataset('parallel_test.nc', 'w', parallel=True)
 d = nc.createDimension('dim',4)
 v = nc.createVariable('var', np.int32, 'dim')
 v[rank] = rank
+
 # switch to collective mode, rewrite the data.
 v.set_collective(True)
 v[rank] = rank
 nc.close()
+
 # reopen the file read-only, check the data
 nc = Dataset('parallel_test.nc', parallel=True, comm=MPI.COMM_WORLD,
-        info=MPI.Info())
+    info=MPI.Info())
 assert rank==nc['var'][rank]
 nc.close()
+
 # reopen the file in append mode, modify the data on the last rank.
 nc = Dataset('parallel_test.nc', 'a',parallel=True, comm=MPI.COMM_WORLD,
-        info=MPI.Info())
+    info=MPI.Info())
 if rank == 3: v[rank] = 2*rank
 nc.close()
+
 # reopen the file read-only again, check the data.
 # leave out the comm and info kwargs to check that the defaults
 # (MPI_COMM_WORLD and MPI_INFO_NULL) work.

examples/test_stringarr.py

@@ -1,5 +1,6 @@
 from netCDF4 import Dataset, stringtochar, chartostring
 import random, numpy
+from typing import Final
 
 # test utilities for converting arrays of fixed-length strings
 # to arrays of characters (with an extra dimension), and vice-versa.
@@ -16,7 +17,7 @@
 
 
 FILE_NAME = 'tst_stringarr.nc'
-FILE_FORMAT = 'NETCDF4_CLASSIC'
+FILE_FORMAT: Final = 'NETCDF4_CLASSIC'
 chars = '1234567890aabcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
 
 nc = Dataset(FILE_NAME,'w',format=FILE_FORMAT)
@@ -26,7 +27,6 @@
 nc.createDimension('nchar',nchar)
 v = nc.createVariable('strings','S1',('n1','n2','nchar'))
 for nrec in range(nrecs):
-    data = []
     data = numpy.empty((n2,),'S'+repr(nchar))
     # fill data with random nchar character strings
     for n in range(n2):

examples/threaded_read.py

@@ -28,7 +28,7 @@
     nc.close()
 
 # Queue them up
-items = queue.Queue()
+items: queue.Queue = queue.Queue()
 for data,fname in zip(datal,fnames):
     items.put(fname)