Merge for v8.3.3

raphaelquast · web-flow · commit 63c5a3d74646 · 2025-06-03T21:24:47.000+02:00
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -12,3 +12,9 @@ repos:
     rev: 22.3.0
     hooks:
     -   id: black
+-   repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+    -   id: codespell
+        additional_dependencies:
+        -   tomli  # TODO only required for python < 3.11
diff --git a/README.md b/README.md
@@ -88,7 +88,7 @@ conda install -c conda-forge eomaps
 
 
 > Advanced users can also use `pip` to install **EOmaps** (and selectively install optional dependency groups)
-> ```pyhton
+> ```python
 > pip install eomaps       # install only minimal required dependencies
 > pip install eomaps[all]  # install all optional dependencies
 > ...
diff --git a/docs/source/FAQ.rst b/docs/source/FAQ.rst
@@ -216,7 +216,7 @@ Most notably (start of 2024), the **required dependency** `cartopy <https://gith
 
 .. tip::
 
-    If you want to get a quick overview of the licenses of an existing pyhton environment, I recommend having a look at the `pip-licenses <https://github.com/raimon49/pip-licenses>`_ package!
+    If you want to get a quick overview of the licenses of an existing python environment, I recommend having a look at the `pip-licenses <https://github.com/raimon49/pip-licenses>`_ package!
 
 
 Important changes between major versions
diff --git a/docs/source/_static/version_switcher.json b/docs/source/_static/version_switcher.json
@@ -9,8 +9,8 @@
     "url": "https://eomaps.readthedocs.io/en/dev/"
   },
   {
-    "version": "v8.3.2",
-    "url": "https://eomaps.readthedocs.io/en/v8.3.2/"
+    "version": "v8.3.3",
+    "url": "https://eomaps.readthedocs.io/en/v8.3.3/"
   },
   {
     "version": "v8.2.1",
diff --git a/docs/source/contribute/contribute.rst b/docs/source/contribute/contribute.rst
@@ -153,6 +153,7 @@ To ensure uniform code style, EOmaps uses `pre-commit hooks <https://pre-commit.
 - Removal of trailing whitespaces in `.py` files
 - Making sure that files end with a newline
 - Compliance to the used `black <https://github.com/psf/black>`_ code formatting standards
+- Making sure files don't contain common typos as detected by the `codespell <https://github.com/codespell-project/codespell>`_ spell checker
 
 
 To initialize pre-commit hooks in your current environment, first install `pre-commit hooks <https://pre-commit.com/>`_ with
@@ -183,6 +184,7 @@ This will install the required pre-commit hooks in your current environment so t
     trim trailing whitespace.................................................Passed
     mixed line ending........................................................Passed
     black....................................................................Passed
+    codespell................................................................Passed
 
 
 .. note::
@@ -204,6 +206,9 @@ This will install the required pre-commit hooks in your current environment so t
   `pre-commit Issue #2178 comment <https://github.com/pre-commit/pre-commit/issues/2178#issuecomment-1002163763>`_
   for a potential resolution.
 
+.. tip::
+
+    - When using the `codespell` spell checker, false positives are possible. You should add these to the `[tool.codespell.ignore-words-list]` list in the `pyproject.toml` file.
 
 
 
diff --git a/docs/source/user_guide/how_to_use/api_basics.rst b/docs/source/user_guide/how_to_use/api_basics.rst
@@ -759,7 +759,7 @@ of the following structure:
 .. code-block:: python
 
     dict(
-        name1 = N  # position the axis at the Nth grid cell (counting firs)
+        name1 = N  # position the axis at the Nth grid cell (counting first)
         name2 = (row, col), # position the axis at the (row, col) grid-cell
         name3 = (row, slice(col_start, col_end)) # span the axis over multiple columns
         name4 = (slice(row_start, row_end), col) # span the axis over multiple rows
diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst
@@ -5,7 +5,7 @@ User guide
 ==========
 
 
-The following chapters provide detailed informatio on how to use EOmaps
+The following chapters provide detailed information on how to use EOmaps
 with a lot of code-examples!
 
 
diff --git a/docs/source/user_guide/miscellaneous/api_read_data.rst b/docs/source/user_guide/miscellaneous/api_read_data.rst
@@ -64,7 +64,7 @@ Create a new Map from a file
 
     m = Maps.from_file.GeoTIFF(
         "the filepath",
-        classify_specs=dict(Maps.CLASSFIERS.Quantiles, k=10),
+        classify_specs=dict(Maps.CLASSIFIERS.Quantiles, k=10),
         cmap="RdBu"
         )
     m.add_colorbar()
@@ -95,7 +95,7 @@ Similar to :py:class:`Maps.from_file` , a new layer based on a file can be added
         coords=("longitude", "latitude"),
         data_crs=4326,
         isel=dict(time=123),
-        classify_specs=dict(Maps.CLASSFIERS.Quantiles, k=10),
+        classify_specs=dict(Maps.CLASSIFIERS.Quantiles, k=10),
         cmap="RdBu"
         )
 
diff --git a/environment.yml b/environment.yml
@@ -3,7 +3,7 @@ channels:
   - conda-forge
 
 dependencies:
-  - python >= 3.8
+  - python >= 3.8, <3.13
   - numpy
   - scipy
   - matplotlib >=3.4
diff --git a/eomaps/_blit_manager.py b/eomaps/_blit_manager.py
@@ -6,15 +6,15 @@
 """The BlitManager used to handle drawing and caching of backgrounds."""
 
 import logging
+from contextlib import ExitStack, contextmanager
+from functools import lru_cache
 from itertools import chain
-from contextlib import contextmanager, ExitStack
 from weakref import WeakSet
-from functools import lru_cache
 
-import numpy as np
 import matplotlib.pyplot as plt
-from matplotlib.transforms import Bbox
+import numpy as np
 from matplotlib.spines import Spine
+from matplotlib.transforms import Bbox
 
 _log = logging.getLogger(__name__)
 
@@ -840,7 +840,6 @@ def _on_draw_cb(self, event):
         loglevel = _log.getEffectiveLevel()
 
         if hasattr(cv, "get_renderer") and not cv.is_saving():
-
             renderer = cv.get_renderer()
             if renderer is None:
                 # don't run if no renderer is available
@@ -886,7 +885,7 @@ def _on_draw_cb(self, event):
 
             # workaround for nbagg backend to avoid glitches
             # it's slow but at least it works...
-            # check progress of the following issuse
+            # check progress of the following issues
             # https://github.com/matplotlib/matplotlib/issues/19116
             if self._mpl_backend_blit_fix:
                 self.update()
@@ -1368,7 +1367,7 @@ def update(
         if blit:
             # workaround for nbagg backend to avoid glitches
             # it's slow but at least it works...
-            # check progress of the following issuse
+            # check progress of the following issues
             # https://github.com/matplotlib/matplotlib/issues/19116
             if self._mpl_backend_force_full:
                 cv._force_full = True
@@ -1549,7 +1548,6 @@ def _cleanup_bg_layers(self, layer):
             )
 
     def _cleanup_on_layer_activation(self, layer):
-
         try:
             # remove not yet executed lazy-activation methods
             # (e.g. not yet fetched WMS services)
diff --git a/eomaps/_maps_base.py b/eomaps/_maps_base.py
@@ -151,7 +151,7 @@ def apply_webagg_fix(cls):
         (e.g. when using `matplotlib.use("webagg")`)
 
         - Events that occur while draws are pending are dropped and only the
-          last event of each type that occured during the wait is finally executed.
+          last event of each type that occurred during the wait is finally executed.
 
         Note
         ----
@@ -216,7 +216,7 @@ def handle_event(self, event):
                 # cache the latest event of each type so we can process it once we are ready
                 self._event_cache[event["type"]] = event
 
-                # a final savety precaution in case send count is lower than ack count
+                # a final safety precaution in case send count is lower than ack count
                 # (e.g. we wait for an image but there was no image sent)
                 if self.manager._send_cnt < self._ack_cnt:
                     # reset counts... they seem to be incorrect
@@ -1298,7 +1298,7 @@ def set_extent(self, extents, crs=None):
 
         Parameters
         ----------
-        extent : array-like
+        extents : array-like
             The extent in the given crs (x0, x1, y0, y1).
         crs : a crs identifier, optional
             The coordinate-system in which the extent is evaluated.
diff --git a/eomaps/_webmap.py b/eomaps/_webmap.py
@@ -1333,7 +1333,7 @@ class SlippyImageArtistNew(AxesImage):
     """
     A subclass of :class:`~matplotlib.image.AxesImage` which provides an
     interface for getting a raster from the given object with interactive
-    slippy map type functionality.
+    slippery map type functionality.
 
     Kwargs are passed to the AxesImage constructor.
 
diff --git a/eomaps/annotation_editor.py b/eomaps/annotation_editor.py
@@ -604,7 +604,7 @@ def print_code(
             The default is "all".
         sanitize_coordinates : bool, optional
             If Tue, annotation coordinates where the crs has not been specified
-            explicitly are reprojected to epsg=4326 to avoid amiguities (e.g. if the
+            explicitly are reprojected to epsg=4326 to avoid ambiguities (e.g. if the
             plot-crs changes etc.)
 
             If False, coordinates will be returned as-is (which might lead to incorrect
diff --git a/eomaps/eomaps.py b/eomaps/eomaps.py
@@ -15,6 +15,7 @@
 from pathlib import Path
 from types import SimpleNamespace
 from textwrap import fill
+from difflib import get_close_matches
 
 import copy
 import importlib.metadata
@@ -1309,12 +1310,50 @@ def _set_gdf_path_boundary(self, gdf, set_extent=True):
 
             self.set_extent([x0, x1, y0, y1], gdf.crs)
 
-    def set_frame(self, rounded=0, gdf=None, set_extent=True, **kwargs):
+    def _set_country_frame(self, countries, scale=50):
+        """
+        Set the map-frame to one (or more) country boarders defined by
+        the NaturalEarth admin_0_countries dataset.
+
+        For more details, see:
+
+            https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-0-countries/
+
+        Parameters
+        ----------
+        countries : str or list of str
+            The countries who should be included in the map-frame.
+        scale : int, optional
+            The scale factor of the used NaturalEarth dataset.
+            One of 10, 50, 110.
+            The default is 50.
+
+        """
+        countries = [i.lower() for i in np.atleast_1d(countries)]
+        gdf = self.add_feature.cultural.admin_0_countries.get_gdf(scale=scale)
+        names = gdf.NAME.str.lower().values
+
+        q = np.isin(names, countries)
+
+        if np.count_nonzero(q) == len(countries):
+            self.set_frame(gdf=gdf[q])
+        else:
+            for c in countries:
+                if c not in names:
+                    print(
+                        f"Unable to identify the country '{c}'. "
+                        f"Fid you mean {get_close_matches(c, gdf.NAME)}"
+                    )
+
+    def set_frame(self, rounded=0, gdf=None, countries=None, **kwargs):
         """
         Set the properties of the map boundary and the background patch.
 
-        You can either use a rectangle with rounded corners or arbitrary geometries
-        provided as a geopandas.GeoDataFrame.
+        - use `rounded` kwarg to get a rectangle border with rounded corners
+        - use `gdf` kwarg to use `geopandas.GeoDataFrame` geometries as map-border
+        - use `countries` kwarg to set the map-border to one (or more) countries.
+
+        All additional kwargs are used to style the border-line.
 
         Parameters
         ----------
@@ -1346,6 +1385,17 @@ def set_frame(self, rounded=0, gdf=None, set_extent=True, **kwargs):
 
             - "facecolor" or "fc": The color of the background patch
 
+        Other Parameters
+        ----------------
+        set_extent : bool, optional
+            Only relevant if `gdf` is used.
+            If True, the map-extent is set to the extent of the provided geometry.
+            The default is True.
+        scale : int, optional
+            Only relevant if `countries` is used.
+            The scale factor of the used NaturalEarth dataset.
+            Must be one of [10, 50, 110]. The default is 50.
+
         Examples
         --------
 
@@ -1372,6 +1422,11 @@ def set_frame(self, rounded=0, gdf=None, set_extent=True, **kwargs):
         >>> # set the map-boundary to the Austrian country-boarder
         >>> m.set_frame(gdf = gdf[gdf.NAME=="Austria"])
 
+        Set the map-boundary to the country-border of Austria and Italy
+
+        >>> m = Maps(facecolor="0.4")
+        >>> m.set_frame(countries=["Austria", "Italy"], ec="r", lw=2, fc="k")
+
         """
 
         for key in ("fc", "facecolor"):
@@ -1384,8 +1439,18 @@ def set_frame(self, rounded=0, gdf=None, set_extent=True, **kwargs):
             assert (
                 rounded == 0
             ), "EOmaps: using rounded > 0 is not supported for gdf frames!"
+            assert countries is None, "You cannot specify both 'gdf' and 'countries'"
+
+            self._set_gdf_path_boundary(
+                self._handle_gdf(gdf), set_extent=kwargs.pop("set_extent", True)
+            )
+        elif countries is not None:
+            assert (
+                rounded == 0
+            ), "EOmaps: using rounded > 0 is not supported for country-border frames!"
+            assert gdf is None, "You cannot specify both 'gdf' and 'countries'"
 
-            self._set_gdf_path_boundary(self._handle_gdf(gdf), set_extent=set_extent)
+            self._set_country_frame(countries, scale=kwargs.pop("scale", 50))
 
         elif rounded:
             assert (
@@ -3389,7 +3454,7 @@ def snapshot(self, *args, **kwargs):
     @wraps(MapsBase.savefig)
     def savefig(self, *args, refetch_wms=False, rasterize_data=True, **kwargs):
         with ExitStack() as stack:
-            # re-fetch webmap servies if required
+            # re-fetch webmap services if required
             if refetch_wms is False:
                 if _cx_refetch_wms_on_size_change is not None:
                     stack.enter_context(_cx_refetch_wms_on_size_change(refetch_wms))
@@ -3800,7 +3865,6 @@ def _open_companion_widget(self, xy=None):
             else:
                 clicked_map._companion_widget.show()
                 clicked_map._indicate_companion_map(True)
-
                 # execute all actions that should trigger before opening the widget
                 # (e.g. update tabs to show visible layers etc.)
                 for f in clicked_map._on_show_companion_widget:
@@ -3838,7 +3902,7 @@ def _init_companion_widget(self, show_hide_key="w"):
                     " Maps-object!"
                 )
                 return
-            if plt.get_backend() in ["QtAgg", "Qt5Agg"]:
+            if plt.get_backend().lower() in ["qtagg", "qt5agg"]:
                 # only pass parent if Qt is used as a backend for matplotlib!
                 self._companion_widget = MenuWindow(m=self, parent=self.f.canvas)
             else:
diff --git a/eomaps/grid.py b/eomaps/grid.py
@@ -1018,6 +1018,15 @@ def add_grid(
 
             The default is: (ec="0.2", lw=0.5, zorder=100)
 
+        Other Parameters
+        ----------------
+        clip_on: bool, optional
+            If True, clip the gridlines at the map-boundary.
+            If False, clip the gridliens at the figure-boundary.
+            This is useful if you want gridlines to extend beyond custom map-boundaries
+            set with :py:meth:`Maps.set_frame`.
+            Note: This has to be set for the grid-labels as well!
+
         Returns
         -------
         g : GridLines
diff --git a/eomaps/layout_editor.py b/eomaps/layout_editor.py
diff --git a/eomaps/webmap_containers.py b/eomaps/webmap_containers.py
diff --git a/eomaps/widgets.py b/eomaps/widgets.py
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/tests/test_basic_functions.py b/tests/test_basic_functions.py

Original file line number	Diff line number	Diff line change
`@@ -9,8 +9,8 @@`
`9`	`9`	`"url": "https://eomaps.readthedocs.io/en/dev/"`
`10`	`10`	`},`
`11`	`11`	`{`
`12`		`- "version": "v8.3.2",`
`13`		`- "url": "https://eomaps.readthedocs.io/en/v8.3.2/"`
	`12`	`+ "version": "v8.3.3",`
	`13`	`+ "url": "https://eomaps.readthedocs.io/en/v8.3.3/"`
`14`	`14`	`},`
`15`	`15`	`{`
`16`	`16`	`"version": "v8.2.1",`