Herbie v2 API (Major refactor/rewrite)

.github/workflows/tests-conda.yml

@@ -5,6 +5,7 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+    types: [opened, synchronize, reopened, ready_for_review]
   workflow_dispatch:
 
 # Cancel in-progress jobs when pushing to the same branch.

.github/workflows/tests-python.yml

@@ -5,6 +5,7 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+    types: [opened, synchronize, reopened, ready_for_review]
   workflow_dispatch:
 
 # Cancel in-progress jobs when pushing to the same branch.

.python-version

@@ -0,0 +1 @@
+3.13

docs/api_reference/index.rst

@@ -6,6 +6,7 @@ Docstring reference for the ``herbie`` module
 
 .. toctree::
    :maxdepth: 2
+   :caption: Herbie - Legacy API
 
    core
    accessors
@@ -14,3 +15,9 @@ Docstring reference for the ``herbie`` module
    paint
    wgrib2
    misc
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Herbie - v2 API
+
+   v2

docs/api_reference/v2.rst

@@ -0,0 +1,38 @@
+=========
+herbie.v2
+=========
+
+
+I recommend importing the Herbie Namespace or a specific model directly
+
+
+.. code-block:: python
+
+   from herbie.v2 import Herbie
+
+   H = Herbie.HRRR('2025-01-01')
+
+.. code-block:: python
+
+   from herbie.v2 import HRRR
+
+   H = HRRR('2025-01-01')
+
+
+.. toctree::
+    :maxdepth: 2
+
+.. currentmodule:: herbie.v2
+
+.. autosummary::
+   :toctree: _autosummary
+
+   Herbie
+   _base
+   _config
+   _download
+   _inventory
+   _search_help
+   _sources
+   _xarray
+   fast

docs/conf.py

@@ -138,6 +138,11 @@
     "navbar_center": ["navbar-nav"],
     "footer_start": ["copyright"],
     "footer_center": ["sphinx-version"],
+    "announcement": (
+        "🚧 <b>Herbie v2</b> is in active development — a redesigned API with "
+        "Polars, Rich, and a cleaner model interface. "
+        "<a href='/en/stable/v2/index.html'>See the v2 preview docs →</a>"
+    ),
 }
 
 html_sidebars = {}

docs/index.rst

@@ -16,6 +16,9 @@ Herbie: Download Weather Forecast Model Data in Python
 
 **Access HRRR, GFS, RAP, GEFS, ECMWF and 15+ Weather Models**
 
+.. note::
+   A redesigned **Herbie v2** API is in active development.
+   See :doc:`/v2/index` for a preview.
 
 **Herbie** is a Python package that makes downloading and working with numerical weather prediction (NWP) model data simple and fast. Whether you're a researcher, meteorologist, data scientist, or weather enthusiast, Herbie provides easy access to forecast data from NOAA, ECMWF, and other sources.
 
@@ -34,8 +37,9 @@ Herbie: Download Weather Forecast Model Data in Python
 
    /user_guide/index
    /gallery/index
-   /grib_reference/index
    /api_reference/index
+   /v2/index
+   /grib_reference/index
 
 .. grid:: 2
     :gutter: 3
@@ -46,6 +50,11 @@ Herbie: Download Weather Forecast Model Data in Python
 
         Learn how to use Herbie with tutorials and examples
 
+    .. grid-item-card:: 🧪 Herbie v2 Preview
+        :link: v2/index
+        :link-type: doc
+        New API with Polars, Rich, and cleaner model templates
+
     .. grid-item-card:: 🖼️ Model Gallery
         :link: gallery/index
         :link-type: doc

docs/v2/CHANGELOG.md

@@ -0,0 +1,112 @@
+# New Herbie
+
+New Dependencies
+
+- Polars: I much prefer using this DataFrame library over Pandas.
+- Rich: For printing information for the user in a fancy way.
+
+The default save directory is now `~/herbie-data/`
+
+```python
+from herbie.v2 import Herbie
+```
+
+Herbie is now a namespace, with many model HerbieModel classes for different models.
+
+```python
+H = Herbie.HRRR('2025-01-01')
+```
+
+you may also just import the model you want to use instead
+
+```python
+from herbie.v2 import HRRR
+H = HRRR('2025-01-01')
+```
+
+## Herbie config file
+
+There is a new config file that can be used
+
+...
+
+## Default download directory structure
+
+Herbie by default downloads ata to `~/herbie-data`, and the file structure matches the directory structure of the original model source.
+
+## `fxx` is now `step`
+
+The forecast lead time is now controlled with the step parameter, and may be a timedelta object (which is converted to integer hours). The following are equivalent:
+
+```python
+from herbie.v2 import Herbie
+from datetime import datetime, timedelta
+
+H = Herbie.HRRR('2025-01-01', step=12)
+
+H = Herbie.HRRR(datetime(2025,1,1), step=timedelta(hours=12))
+```
+
+## Notebook HTML Representor
+
+For convenient user exploration, when displaying a Herbie object in a Jupyter Notebook, there is a new HTML display showing the parameters selected and sources.
+
+## Model Templates
+
+Big change to the model templates. These are subclassed from the base class HerbieModel.
+
+## Inventory
+
+Use Polars as the DataFrame. I'm a big Polars fan, and find it much easier to read and write than Pandas.
+
+Since I'm using Polars for the DataFrame, users can filter the inventory with expressions for each column rather than just the "search_this" column.
+
+The data and index source are now included in the inventory dataframe. This will enable downloading fields from multiple files and "build your own GRIB files."
+
+## Download
+
+Download for subsets are now done with multiple threads, one thread for each subset group.
+
+Use rich progress bars for downloads.
+
+Remote file paths are preserved rather than specifying a custom data path. I wanted to make it possible to use rclone to quickly pre-fill your `herbie-data/` directory, then use Herbie to access those files locally.
+
+## xarray
+
+Multiple hypercubes are returned as a DataTree.
+
+## status
+
+Display the sources and which sources have been checked and if the files exist.
+
+## resolve
+
+Manually check if files exist
+
+```python
+# Find first available file
+H.resolve()
+
+# Check specific source
+H.resolve('google')
+
+# Check all
+H.resolve('all')
+```
+
+## FastHerbie
+
+This behaves _very_ different. Inventory DataFrames are concatted together for many files, then parallel downloads happen and join the fields into a new, custom grib file. It's a "build your own GRIB" feature.
+
+Examples:
+
+- Get all 6-hr `TMP:2 m` forecasts for the day in one file.
+- Get all `GRD:10 m` forecasts initialized at a single time.
+
+## Zarr Support
+
+Built infrastructure to support access to Zarr model sources
+
+```python
+Herbie.HRRR.from_zarr('dynamical', 'analysis')
+```