Typecheck some API interfaces (#593)

Co-authored-by: Jessica Scheick <jbscheick@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Jessica Scheick <JessicaS11@users.noreply.github.com>

.github/workflows/typecheck.yml

@@ -0,0 +1,29 @@
+name: Typecheck
+
+on:
+ pull_request:
+ push:
+ branches:
+ - main
+ - development
+
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.10"
+
+ - name: Install package and test dependencies
+ run: |
+ python -m pip install .[complete]
+ python -m pip install -r requirements-dev.txt
+
+ - uses: jakebailey/pyright-action@v2

doc/source/conf.py

@@ -32,13 +32,17 @@
 # ones.
 extensions = [
  "sphinx.ext.autodoc",
+ # IMPORTANT: napoleon must be loaded before sphinx_autodoc_typehints
+ # https://github.com/tox-dev/sphinx-autodoc-typehints/issues/15
+ "sphinx.ext.napoleon",
+ "sphinx_autodoc_typehints",
  "sphinx.ext.autosectionlabel",
  "numpydoc",
  # "sphinx.ext.autosummary",
  "myst_nb",
  "contributors", # custom extension, from pandas
  "sphinxcontrib.bibtex",
- "sphinx_panels",
+ "sphinx_design",
  # "sphinx.ext.imgconverter", # this extension should help the latex svg warning, but results in an error instead
 ]
 myst_enable_extensions = [
@@ -79,6 +83,31 @@
 nb_execution_mode = "off"
 suppress_warnings = ["myst.header"] # suppress non-consecutive header warning
 
+
+# -- Options for Napoleon docstring parsing ----------------------------------
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+
+
+# -- Options for autodoc -----------------------------------------------------
+
+# Show the typehints in the description of each object instead of the signature.
+autodoc_typehints = "description"
+
+
+# -- Options for autodoc typehints--------------------------------------------
+
+# Replace Union annotations with union operator "|"
+always_use_bars_union = True
+# always_document_param_types = True
+
+# Show the default value for a parameter after its type
+typehints_defaults = "comma"
+typehints_use_return = True
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages. See the documentation for

doc/source/index.rst

@@ -31,86 +31,109 @@ ICESat-2 datasets to enable scientific discovery.
 To further enhance data discovery, we have developed the QUEST module to facilitate querying of ICESat-2 data and complimentary Argo oceanographic data, with additional dataset support expected in the future.
 
 
-.. panels::
- :card: + intro-card text-center
- :column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2
- :img-top-cls: pl-2 pr-2 pt-2 pb-2
+.. grid:: 1 2 2 3
+ :gutter: 3
+ :class-container: sd-text-center
 
- ---
- :img-top: https://cdn-icons-png.flaticon.com/128/2498/2498074.png
+ .. grid-item-card::
+ :img-top: https://cdn-icons-png.flaticon.com/128/2498/2498074.png
+ :class-img-top: sd-p-2
+ :class-card: sd-shadow-md
 
- **Getting Started**
- ^^^^^^^^^^^^^^^^^^^
+  **Getting Started**
+  ^^^^^^^^^^^^^^^^^^^
 
- New to ICESat-2 or icepyx?
- Learn how to install icepyx and use it to jumpstart your project today.
- Check out our gallery of examples, too!
+  New to ICESat-2 or icepyx?
+  Learn how to install icepyx and use it to jumpstart your project today.
+  Check out our gallery of examples, too!
 
- .. link-button:: install_ref
- :type: ref
- :text: Installation Instructions
- :classes: stretched-link btn-outline-primary btn-block
+ .. button-ref:: install_ref
+ :ref-type: ref
+ :color: primary
+ :outline:
+ :expand:
 
- ---
- :img-top: https://cdn-icons-png.flaticon.com/128/3730/3730041.png
+ Installation Instructions
 
- **User Guide**
- ^^^^^^^^^^^^^^
+ .. grid-item-card::
+ :img-top: https://cdn-icons-png.flaticon.com/128/3730/3730041.png
+ :class-img-top: sd-p-2
+ :class-card: sd-shadow-md
 
- The user guide provides in-depth information on the tools and functionality
- available for obtaining and interacting with ICESat-2 data products.
+  **User Guide**
+  ^^^^^^^^^^^^^^
 
- .. link-button:: api_doc_ref
- :type: ref
- :text: Software Docs
- :classes: stretched-link btn-outline-primary btn-block
+ The user guide provides in-depth information on the tools and functionality
+ available for obtaining and interacting with ICESat-2 data products.
 
- ---
- :img-top: https://cdn-icons-png.flaticon.com/512/4230/4230997.png
+ .. button-ref:: api_doc_ref
+ :ref-type: ref
+ :color: primary
+ :outline:
+ :expand:
 
- **Development Guide**
- ^^^^^^^^^^^^^^^^^^^^^
+ Software Docs
 
- Have an idea or an ancillary dataset to contribute to icepyx? Go here for information on best practices
- for developing and contributing to icepyx.
+ .. grid-item-card::
+ :img-top: https://cdn-icons-png.flaticon.com/512/4230/4230997.png
+ :class-img-top: sd-p-2
+ :class-card: sd-shadow-md
 
- .. link-button:: dev_guide_label
- :type: ref
- :text: Development Guide
- :classes: stretched-link btn-outline-primary btn-block
+ **Development Guide**
+ ^^^^^^^^^^^^^^^^^^^^^
 
- ---
- :img-top: https://cdn-icons-png.flaticon.com/128/1283/1283342.png
+  Have an idea or an ancillary dataset to contribute to icepyx? Go here for information on best practices
+  for developing and contributing to icepyx.
 
- **Get in Touch**
- ^^^^^^^^^^^^^^^^
+ .. button-ref:: dev_guide_label
+ :ref-type: ref
+ :color: primary
+ :outline:
+ :expand:
 
- icepyx is more than just software!
- We're a community of data producers, managers, and users
- who collaborate openly and share code and skills
- for every step along the entire data pipeline. Find resources for
- your questions here!
+ Development Guide
 
- .. link-button:: contact_ref_label
- :type: ref
- :text: Get Involved!
- :classes: stretched-link btn-outline-primary btn-block
+ .. grid-item-card::
+ :img-top: https://cdn-icons-png.flaticon.com/128/1283/1283342.png
+ :class-img-top: sd-p-2
+ :class-card: sd-shadow-md
 
- ---
- :img-top: https://icesat-2.gsfc.nasa.gov/sites/default/files/MissionLogo_0.png
- :img-top-cls: pl-2 pr-2 pt-4 pb-4
+ **Get in Touch**
+ ^^^^^^^^^^^^^^^^
 
- **ICESat-2 Resources**
- ^^^^^^^^^^^^^^^^^^^^^^
+ icepyx is more than just software!
+ We're a community of data producers, managers, and users
+ who collaborate openly and share code and skills
+ for every step along the entire data pipeline. Find resources for
+ your questions here!
 
- Curious about other tools for working with ICESat-2 data?
- Want to share your resource?
- Check out the amazing work already in progress!
+ .. button-ref:: contact_ref_label
+ :ref-type: ref
+ :color: primary
+ :outline:
+ :expand:
 
- .. link-button:: resource_ref_label
- :type: ref
- :text: ICESat-2 Resource Guide
- :classes: stretched-link btn-outline-primary btn-block
+ Get Involved!
+
+ .. grid-item-card::
+ :img-top: https://icesat-2.gsfc.nasa.gov/sites/default/files/MissionLogo_0.png
+ :class-img-top: sd-p-2
+ :class-card: sd-shadow-md
+
+ **ICESat-2 Resources**
+ ^^^^^^^^^^^^^^^^^^^^^^
+
+ Curious about other tools for working with ICESat-2 data?
+ Want to share your resource?
+ Check out the amazing work already in progress!
+
+ .. button-ref:: resource_ref_label
+ :ref-type: ref
+ :color: primary
+ :outline:
+ :expand:
+
+ ICESat-2 Resource Guide
 
 
 .. toctree::

doc/source/user_guide/documentation/icepyx.rst

@@ -19,3 +19,4 @@ Diagrams are updated automatically after a pull request (PR) is approved and bef
  read
  variables
  components
+ types

doc/source/user_guide/documentation/types.rst

@@ -0,0 +1,11 @@
+Types
+=====
+
+.. automodule:: icepyx.core.types
+ :members:
+ :undoc-members:
+ :exclude-members: CMRParamsBase,CMRParamsWithBbox,CMRParamsWithPolygon
+
+.. COMMENT. `exclude-members` specified above is required because those models
+ contain symbols ('[', ']') in some keys, which sphinx doesn't like.
+ See: https://github.com/sphinx-doc/sphinx/issues/11039

icepyx/core/APIformatting.py

@@ -1,6 +1,13 @@
-# Generate and format information for submitting to API (CMR and NSIDC)
+"""Generate and format information for submitting to API (CMR and NSIDC)."""
 
 import datetime as dt
+from typing import Any, Generic, Literal, TypeVar, Union, overload
+
+from icepyx.core.types import (
+ CMRParams,
+ EGIParamsSubset,
+ EGIRequiredParams,
+)
 
 # ----------------------------------------------------------------------
 # parameter-specific formatting for display
@@ -183,12 +190,56 @@ def to_string(params):
  return "&".join(param_list)
 
 
+ParameterType = Literal["CMR", "required", "subset"]
+# DevGoal: When Python 3.12 is minimum supported version, migrate to PEP695 style
+T = TypeVar("T", bound=ParameterType)
+
+
+class _FmtedKeysDescriptor:
+ """Enable the Parameters class' fmted_keys property to be typechecked correctly.
+
+ See: https://github.com/microsoft/pyright/issues/3071#issuecomment-1043978070
+ """
+
+ @overload
+ def __get__(
+ self,
+ instance: 'Parameters[Literal["CMR"]]',
+ owner: Any,
+ ) -> CMRParams: ...
+
+ @overload
+ def __get__(
+ self,
+ instance: 'Parameters[Literal["required"]]',
+ owner: Any,
+ ) -> EGIRequiredParams: ...
+
+ @overload
+ def __get__(
+ self,
+ instance: 'Parameters[Literal["subset"]]',
+ owner: Any,
+ ) -> EGIParamsSubset: ...
+
+ def __get__(
+ self,
+ instance: "Parameters",
+ owner: Any,
+ ) -> Union[CMRParams, EGIRequiredParams, EGIParamsSubset]:
+ """
+ Returns the dictionary of formatted keys associated with the
+ parameter object.
+ """
+ return instance._fmted_keys
+
+
 # ----------------------------------------------------------------------
 # DevNote: Currently, this class is not tested!!
 # DevGoal: this could be expanded, similar to the variables class, to provide users with valid options if need be
 # DevGoal: currently this does not do much by way of checking/formatting of other subsetting options (reprojection or formats)
 # it would be great to incorporate that so that people can't just feed any keywords in...
-class Parameters:
+class Parameters(Generic[T]):
  """
  Build and update the parameter lists needed to submit a data order
 
@@ -206,7 +257,14 @@ class Parameters:
  on the type of query. Must be one of ['search','download']
  """
 
- def __init__(self, partype, values=None, reqtype=None):
+ fmted_keys = _FmtedKeysDescriptor()
+
+ def __init__(
+ self,
+ partype: T,
+ values=None,
+ reqtype=None,
+ ):
  assert partype in [
  "CMR",
  "required",
@@ -242,15 +300,7 @@ def poss_keys(self):
 
  # return self._wanted
 
- @property
- def fmted_keys(self):
- """
- Returns the dictionary of formatted keys associated with the
- parameter object.
- """
- return self._fmted_keys
-
- def _get_possible_keys(self):
+ def _get_possible_keys(self) -> dict[str, list[str]]:
  """
  Use the parameter type to get a list of possible parameter keys.
  """
@@ -347,7 +397,7 @@ def check_values(self):
  else:
  return False
 
- def build_params(self, **kwargs):
+ def build_params(self, **kwargs) -> None:
  """
  Build the parameter dictionary of formatted key:value pairs for submission to NSIDC
  in the data request.
@@ -443,3 +493,8 @@ def build_params(self, **kwargs):
  k = "Boundingshape"
 
  self._fmted_keys.update({k: kwargs["spatial_extent"]})
+
+
+CMRParameters = Parameters[Literal["CMR"]]
+RequiredParameters = Parameters[Literal["required"]]
+SubsetParameters = Parameters[Literal["subset"]]