distinguish bmipy package and bmi specification versions

Author: mcflugen

CHANGES.md

@@ -5,6 +5,8 @@
 
 ### Added
 
+* Add `bmipy.bmi2_0` with `Bmi` and `BMI_VERSION` for explicit BMI 2.0 imports,
+  while preserving existing package-level and `bmipy.bmi` imports.
 * Add a changelog ([#72](https://github.com/csdms/bmipy/pull/72))
 * Add `--docstring` / `--no-docstring` CLI options ([#45](https://github.com/csdms/bmipy/pull/45))
 * Add `width` option for generated code formatting ([#46](https://github.com/csdms/bmipy/pull/46))

README.md

@@ -5,19 +5,33 @@ Python bindings for the CSDMS [Basic Model Interface](https://bmi.readthedocs.io
 ![[Python][pypi-link]][python-badge]
 ![[DOI][doi-link]][doi-badge]
 ![[Build Status][build-link]][build-badge]
-![[PyPI][pypi-link]][pypi-badge]
-![[Build Status][anaconda-link]][anaconda-badge]
+[![bmipy package version][pypi-badge]][pypi-link]
+[![BMI specification version][bmi-badge]][bmi-link]
 
-[anaconda-badge]: https://anaconda.org/conda-forge/bmipy/badges/version.svg
-[anaconda-link]: https://anaconda.org/conda-forge/bmipy
 [build-badge]: https://github.com/csdms/bmi-python/actions/workflows/test.yml/badge.svg
 [build-link]: https://github.com/csdms/bmi-python/actions/workflows/test.yml
 [doi-badge]: https://zenodo.org/badge/179283861.svg
 [doi-link]: https://zenodo.org/badge/latestdoi/179283861
-[pypi-badge]: https://badge.fury.io/py/bmipy.svg
+[bmi-badge]: https://img.shields.io/badge/BMI_specification-2.0-blue
+[bmi-link]: https://github.com/csdms/bmi/releases/tag/v2.0
+[pypi-badge]: https://img.shields.io/pypi/v/bmipy?label=bmipy
 [pypi-link]: https://pypi.org/project/bmipy/
 [python-badge]: https://img.shields.io/pypi/pyversions/bmipy.svg
 
+## Package and specification versions
+
+Note that a new *bmipy* release does not necessarily change the supported BMI
+specification. You can check the package version independently of the interface
+specification version:
+
+```python
+from bmipy import __version__
+from bmipy.bmi2_0 import BMI_VERSION
+
+print(__version__)  # bmipy package version
+print(BMI_VERSION)  # Supported BMI specification
+```
+
 ## Install
 
 Install *bmipy* with *pip*,
@@ -42,7 +56,7 @@ pip install git+https://github.com/csdms/bmi-python.git
 ## Usage
 
 ```python
-from bmipy import Bmi
+from bmipy.bmi2_0 import Bmi
 
 
 class MyBmi(Bmi):
@@ -51,6 +65,10 @@ class MyBmi(Bmi):
         # Your implementation goes here
 ```
 
+The `bmipy.bmi2_0` module explicitly selects the BMI 2.0 specification.
+The existing `from bmipy import Bmi` and `from bmipy.bmi import Bmi` imports
+remain available for compatibility.
+
 A complete sample implementation is given in the
 <https://github.com/csdms/bmi-example-python>
 repository.

src/bmipy/__init__.py

@@ -4,6 +4,7 @@
 
 from bmipy._stub import BmiStub
 from bmipy._version import __version__
-from bmipy.bmi import Bmi
+from bmipy.bmi2_0 import BMI_VERSION
+from bmipy.bmi2_0 import Bmi
 
-__all__ = ["__version__", "Bmi", "BmiStub"]
+__all__ = ["__version__", "BMI_VERSION", "Bmi", "BmiStub"]

src/bmipy/_stub.py

@@ -3,7 +3,7 @@
 from typing import TYPE_CHECKING
 from typing import Any
 
-from bmipy.bmi import Bmi
+from bmipy.bmi2_0 import Bmi
 
 if TYPE_CHECKING:
     import numpy as np

src/bmipy/_template.py

@@ -7,7 +7,7 @@
 from collections import OrderedDict
 from collections import defaultdict
 
-from bmipy.bmi import Bmi
+from bmipy.bmi2_0 import Bmi
 
 GROUPS = (
     ("initialize", "initialize"),
@@ -47,7 +47,7 @@ def render(self, with_docstring: bool = True) -> str:
     import numpy as np
     from numpy.typing import NDArray
 
-from bmipy.bmi import Bmi
+from bmipy.bmi2_0 import Bmi
 
 
 class {self._name}(Bmi):