add dev dep group to pyproject.toml, expand idm example

Author: wpbonelli

docs/examples/input_data_model_example.py

@@ -1,10 +1,13 @@
 # # Input data model
 #
+# TODO: flesh this out, describe prospective plan for type hints,
+# determine whether we want to work directly with numpy or with
+# e.g. xarray, etc. This will probably evolve for a while as we
+# rework the prototype with c/attrs
+#
 # FloPy organizes input variables in components: simulations, models,
 # packages, and subpackages.
 #
-# The MODFLOW 6 data model is arranged in the following way:
-#
 # ```mermaid
 # classDiagram
 #     Simulation *-- "1+" Package
@@ -17,29 +20,61 @@
 #     Package *-- "1+" Variable
 # ```
 #
-# Components are generally mutable and variables can be manipulated at will.
+# Components are generally mutable: subcomponents can be added/removed and
+# variables can be manipulated.
 #
 # # Variable types
 #
-# Variables are generally scalars, arrays, or composite data types: list,
-# sum, union.
+# Variables are scalars, paths, arrays, or composite types: list, sum, union.
+#
+# MODFLOW 6 defines the following scalars types:
+#
+# - `keyword`
+# - `integer`
+# - `double precision`
+# - `string`
+#
+# And the following composites:
 #
-# The variable type structure can be summarized briefly as:
+# - `record`: product type
+# - `keystring`: union type
+# - `recarray`: list type
+#
+# Scalars may (and `recarray` must) have a `shape`. If a scalar has a `shape`,
+# its type becomes a homogeneous scalar array. A `recarray` may contain records
+# or unions of records as items.
+#
+# We map this typology roughly to the following in Python:
 
 # +
 from os import PathLike
 from typing import (
+    Any,
     Iterable,
     Tuple,
     Union,
 )
 
 from numpy.typing import ArrayLike
+from pandas import DataFrame
 
 Scalar = Union[bool, int, float, str]
 Path = PathLike
 Array = ArrayLike
 Record = Tuple[Union[Scalar, "Record"], ...]
-Table = Iterable["Record"]
-Variable = Union[Scalar, Array, Table, Record]
+Table = Union[Iterable[Record], DataFrame]
+List = Iterable[Any]
+Variable = Union[Scalar, Array, Record, Table, List]
 # -
+
+# Note that:
+#
+# - Keystrings are omitted above, since a keystring simply becomes a
+# `Union` of records or scalars.
+# - List input may be regular (items all have the same record type) or
+# irregular (items are unions of records).
+# - A table is a special case of list input; since it is regular it can
+# be represented as a dataframe.
+# - While MODFLOW 6 typically formulates file path inputs as records with
+# 3 fields (identifying keyword, `filein`/`fileout`, and filename), FloPy
+# simply accepts `PathLike`.

pyproject.toml

@@ -47,6 +47,7 @@ dependencies = [
 dynamic = ["version"]
 
 [project.optional-dependencies]
+dev = ["flopy4[lint,test,build]"]
 lint = [
     "ruff"
 ]