matplotlib-map-utils 4.1.0__tar.gz → 4.1.1__tar.gz

{matplotlib_map_utils-4.1.0/matplotlib_map_utils.egg-info → matplotlib_map_utils-4.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matplotlib-map-utils
-Version: 4.1.0
+Version: 4.1.1
 Summary: A suite of tools for creating maps in matplotlib
 Author-email: David Moss <davidmoss1221@gmail.com>
 Project-URL: Homepage, https://github.com/moss-xyz/matplotlib-map-utils/
@@ -28,7 +28,7 @@ Dynamic: license-file
 
 **Feedback:** I welcome any and all feedback! See the *Development Notes* below for more details.
 
-**Current Version:** `v4.1.0`, featuring a brand-new documentation site and improved type validation! This DID introduce some breaking changes, see the documentation site for details!
+**Current Version:** `v4.1.1`, which fixed a a few bugs (see [here](https://moss-xyz.github.io/matplotlib-map-utils/package/#release-notes) for details!)
 
 ---
 

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1}/README.md

@@ -8,7 +8,7 @@
 
 **Feedback:** I welcome any and all feedback! See the *Development Notes* below for more details.
 
-**Current Version:** `v4.1.0`, featuring a brand-new documentation site and improved type validation! This DID introduce some breaking changes, see the documentation site for details!
+**Current Version:** `v4.1.1`, which fixed a a few bugs (see [here](https://moss-xyz.github.io/matplotlib-map-utils/package/#release-notes) for details!)
 
 ---
 

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1}/matplotlib_map_utils/__init__.py

@@ -4,11 +4,25 @@ from .core.scale_bar import ScaleBar, scale_bar, dual_bars
 from .core.inset_map import InsetMap, inset_map, ExtentIndicator, indicate_extent, DetailIndicator, indicate_detail, inset_usa
 from typing import Literal
 
+# TypedDicts describing the config dictionaries accepted by the objects/functions above.
+# These power editor intellisense (key + value autocomplete) and can be used by callers
+# to annotate their own config variables; runtime validation is still handled by pydantic.
+from .validation.scale_bar import (ScaleBarBarDict, ScaleBarLabelsDict, ScaleBarUnitsDict,
+                                    ScaleBarTextDict, ScaleBarAobDict)
+from .validation.north_arrow import (NorthArrowBaseDict, NorthArrowFancyDict, NorthArrowLabelDict,
+                                      NorthArrowShadowDict, NorthArrowPackDict, NorthArrowAobDict,
+                                      NorthArrowRotationDict)
+from .validation.inset_map import InsetMapPlotDict
+
 # This defines what wildcard imports should import
-__all__ = ["NorthArrow", "north_arrow", 
+__all__ = ["NorthArrow", "north_arrow",
            "ScaleBar", "scale_bar", "dual_bars",
            "InsetMap","inset_map", "ExtentIndicator","indicate_extent", "DetailIndicator","indicate_detail", "inset_usa",
-           "set_size"]
+           "set_size",
+           "ScaleBarBarDict", "ScaleBarLabelsDict", "ScaleBarUnitsDict", "ScaleBarTextDict", "ScaleBarAobDict",
+           "NorthArrowBaseDict", "NorthArrowFancyDict", "NorthArrowLabelDict", "NorthArrowShadowDict",
+           "NorthArrowPackDict", "NorthArrowAobDict", "NorthArrowRotationDict",
+           "InsetMapPlotDict"]
 
 from . import config
 

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1}/matplotlib_map_utils/core/inset_map.py

@@ -35,12 +35,12 @@ class InsetMap(matplotlib.artist.Artist):
     ## INITIALIZATION ##
     def __init__(self,
                  size: str=None,
-                 location: Literal["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]="lower left", 
+                 location: imt.Location="lower left",
                  imsize: Any=None,
                  pad: Any=None,
                  coords: Any=None,
                  transform=None,
-                 to_plot=None,
+                 to_plot: None | list[imt.InsetMapPlotDict]=None,
                  zorder: int=99,
                  **kwargs):
         # Starting up the object with the base properties of a matplotlib Artist
@@ -199,7 +199,7 @@ class ExtentIndicator(matplotlib.artist.Artist):
     
     ## INITIALIZATION ##
     def __init__(self,
-                 to_return: Any=None,
+                 to_return: None | imt.ExtentReturn=None,
                  straighten: bool=True,
                  pad: Any=0.05,
                  plot: bool=True,
@@ -358,7 +358,7 @@ class DetailIndicator(matplotlib.artist.Artist):
     
     ## INITIALIZATION ##
     def __init__(self,
-                 to_return: Any=None,
+                 to_return: None | imt.DetailReturn=None,
                  straighten: bool=True,
                  pad: Any=0.05,
                  plot: bool=True,
@@ -544,9 +544,9 @@ class DetailIndicator(matplotlib.artist.Artist):
 
 # Function for creating an inset map, independent of the InsetMap object model
 # It is intended to be an easier-to-use API than the default inset_axes
-def inset_map(ax, 
+def inset_map(ax,
               size: str=None,
-              location: Literal["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]="upper right", 
+              location: imt.Location="upper right",
               imsize: Any=None,
               pad: Any=None,
               coords: Any=None,
@@ -670,7 +670,7 @@ def indicate_extent(pax: matplotlib.axes.Axes,
                     bax: matplotlib.axes.Axes,
                     pcrs: Any,
                     bcrs: Any,
-                    to_return: Any=None,
+                    to_return: None | imt.ExtentReturn=None,
                     straighten: bool=True,
                     pad: Any=0.05,
                     plot: bool=True,
@@ -755,11 +755,11 @@ def indicate_extent(pax: matplotlib.axes.Axes,
 # This will also, call extent_indicator too, as the two are linked
 # here, PAX means "parent axis" (where the indicator is plotted) 
 # and IAX means "inset axis" (which contains the detail/zoomed-in section)
-def indicate_detail(pax: matplotlib.axes.Axes, 
-                    iax: matplotlib.axes.Axes, 
-                    pcrs: Any, 
+def indicate_detail(pax: matplotlib.axes.Axes,
+                    iax: matplotlib.axes.Axes,
+                    pcrs: Any,
                     icrs: Any,
-                    to_return: Any=None,
+                    to_return: None | imt.DetailReturn=None,
                     straighten: bool=True,
                     pad: Any=0.05,
                     plot: bool=True,

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1}/matplotlib_map_utils/core/north_arrow.py

@@ -34,11 +34,11 @@ from ..validation.shared import _del_keys
 class NorthArrow(matplotlib.artist.Artist):
     
     ## INITIALIZATION ##
-    def __init__(self, size: str=None, location: Literal["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]="upper right",
+    def __init__(self, size: str=None, location: nat.Location="upper right",
                        scale: None | float | int=None,
-                       base: None | bool | dict = None, fancy: None | bool | dict = None, 
-                       label: None | bool | dict = None, shadow: None | bool | dict = None, 
-                       pack: None | dict = None, aob: None | dict = None, rotation: None | dict = None,
+                       base: None | bool | nat.NorthArrowBaseDict = None, fancy: None | bool | nat.NorthArrowFancyDict = None,
+                       label: None | bool | nat.NorthArrowLabelDict = None, shadow: None | bool | nat.NorthArrowShadowDict = None,
+                       pack: None | nat.NorthArrowPackDict = None, aob: None | nat.NorthArrowAobDict = None, rotation: None | nat.NorthArrowRotationDict = None,
                        zorder: int=99,):
         # Starting up the object with the base properties of a matplotlib Artist
         matplotlib.artist.Artist.__init__(self)
@@ -231,15 +231,15 @@ class NorthArrow(matplotlib.artist.Artist):
 
 # This function presents a way to draw the north arrow independent of the NorthArrow object model
 # and is actually used by the object model when draw() is called anyways
-def north_arrow(ax, draw=True, size: str=None, location: Literal["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]="upper right",
+def north_arrow(ax, draw=True, size: str=None, location: nat.Location="upper right",
                 scale: None | float | int=None,
-                base: None | bool | dict=None, 
-                fancy: None | bool | dict=None,
-                label: None | bool | dict=None, 
-                shadow: None | bool | dict=None,
-                pack: None | dict=None, 
-                aob: None | dict=None, 
-                rotation: None | dict=None,
+                base: None | bool | nat.NorthArrowBaseDict=None,
+                fancy: None | bool | nat.NorthArrowFancyDict=None,
+                label: None | bool | nat.NorthArrowLabelDict=None,
+                shadow: None | bool | nat.NorthArrowShadowDict=None,
+                pack: None | nat.NorthArrowPackDict=None,
+                aob: None | nat.NorthArrowAobDict=None,
+                rotation: None | nat.NorthArrowRotationDict=None,
                 zorder: int=99,):
     
     if draw==True:

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1}/matplotlib_map_utils/core/scale_bar.py

@@ -35,13 +35,13 @@ from ..validation.shared import _del_keys
 class ScaleBar(matplotlib.artist.Artist):
     
     ## INITIALIZATION ##
-    def __init__(self, size: str=None, style: Literal["ticks","boxes"]="boxes",
-                       location: Literal["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]="upper right",
-                       bar: None | bool | dict=None,
-                       units: None | bool | dict=None,
-                       labels: None | bool | dict=None,
-                       text: None | bool | dict=None,
-                       aob: None | bool | dict=None,
+    def __init__(self, size: str=None, style: sbt.ScaleBarStyle="boxes",
+                       location: sbt.Location="upper right",
+                       bar: None | bool | sbt.ScaleBarBarDict=None,
+                       units: None | bool | sbt.ScaleBarUnitsDict=None,
+                       labels: None | bool | sbt.ScaleBarLabelsDict=None,
+                       text: None | bool | sbt.ScaleBarTextDict=None,
+                       aob: None | bool | sbt.ScaleBarAobDict=None,
                        zorder: int=99,
                        ):
         # Starting up the object with the base properties of a matplotlib Artist
@@ -220,13 +220,13 @@ class ScaleBar(matplotlib.artist.Artist):
 
 ### DRAWING FUNCTIONS ###
 
-def scale_bar(ax, draw=True, size: str=None, style: Literal["ticks","boxes"]="boxes",
-                  location: Literal["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]="upper right",
-                  bar: None | bool | dict=None,
-                  units: None | bool | dict=None,
-                  labels: None | bool | dict=None,
-                  text: None | bool | dict=None,
-                  aob: None | bool | dict=None,
+def scale_bar(ax, draw=True, size: str=None, style: sbt.ScaleBarStyle="boxes",
+                  location: sbt.Location="upper right",
+                  bar: None | bool | sbt.ScaleBarBarDict=None,
+                  units: None | bool | sbt.ScaleBarUnitsDict=None,
+                  labels: None | bool | sbt.ScaleBarLabelsDict=None,
+                  text: None | bool | sbt.ScaleBarTextDict=None,
+                  aob: None | bool | sbt.ScaleBarAobDict=None,
                   zorder: int=99,
                   return_aob: bool=True,):
     # For the default function mode, dispatch to the Artist class so final
@@ -301,7 +301,7 @@ def scale_bar(ax, draw=True, size: str=None, style: Literal["ticks","boxes"]="bo
     segments = _config_seg(bar_max, bar_length/major_div, major_div, minor_div, 
                            _bar["minor_type"], _labels["style"],
                            _labels["labels"], _labels["format"], _labels["format_int"])
-
+    
     # Also setting the segment gap to be either the edgewidth or the tickwidth
     gap_width = _bar.get("edgewidth", _bar.get("edgewidth", 0))
 
@@ -320,7 +320,7 @@ def scale_bar(ax, draw=True, size: str=None, style: Literal["ticks","boxes"]="bo
     major_height = _bar["height"]*72
 
     # Initializing the bar with an invisible spacer, to align it with the text later
-    # if all of these conditions are met, we do not need a spcer
+    # if all of these conditions are met, we do not need a spacer
     if _labels["style"] == "last_only" and major_div==1 and (minor_div==1 or minor_div==0):
         bar_artists = []
     # If we have minor divs, it will be equal to half the minor width
@@ -516,14 +516,14 @@ def scale_bar(ax, draw=True, size: str=None, style: Literal["ticks","boxes"]="bo
 # This is a convenience function for creating two scale bars, with different units, aligned with each other
 # The bars should be identical except for the units and the divisions
 # NOTE: still under development, will tidy up if there is usage of it
-def dual_bars(ax, draw=True, size: str=None, style: Literal["ticks","boxes"]="boxes",
-                  location: Literal["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]="upper right",
+def dual_bars(ax, draw=True, size: str=None, style: sbt.ScaleBarStyle="boxes",
+                  location: sbt.Location="upper right",
                   units_dual=["mi","km"], bar_maxes=[None,None], bar_lengths=[None,None], major_divs=[None, None], minor_divs=[None, None],
-                  bar: None | bool | dict=None,
-                  units: None | bool | dict=None,
-                  labels: None | bool | dict=None,
-                  text: None | bool | dict=None,
-                  aob: None | bool | dict=None,
+                  bar: None | bool | sbt.ScaleBarBarDict=None,
+                  units: None | bool | sbt.ScaleBarUnitsDict=None,
+                  labels: None | bool | sbt.ScaleBarLabelsDict=None,
+                  text: None | bool | sbt.ScaleBarTextDict=None,
+                  aob: None | bool | sbt.ScaleBarAobDict=None,
                   zorder: int=99,
                   pad=0, sep=0,
                   return_aob: bool=True
@@ -643,7 +643,13 @@ def _config_bar(ax, bar):
     # We've done most of the work here - just need to see if we want a minor div or not
     # If one is provided, override what we calculated above
     if bar["minor_div"] is not None:
-        bar_minor_div = bar["minor_div"] 
+        if bar["minor_div"] <= 1:
+          bar_minor_div = 1
+        else: 
+          bar_minor_div = bar["minor_div"] 
+    # Alternatively, if minor_type is "none", then we need to set to 1
+    if bar["minor_type"] == "none":
+        bar_minor_div = 1
     
     # Returning everything
     return bar_max, bar_length, units_label, bar_major_div, bar_minor_div

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1}/matplotlib_map_utils/validation/inset_map.py

@@ -8,17 +8,18 @@
 # Geo packages
 import matplotlib.axes
 # Pydantic type validation
-from typing import Annotated, Union, Tuple, List, Optional, Literal, Any, Dict
+from typing import Annotated, Union, Tuple, List, Optional, Literal, Any, Dict, TypedDict
 from pydantic import ConfigDict, BaseModel, Field, model_validator
-from .shared import MatplotlibColor, CRSInput, _get_size_key
+from .shared import MatplotlibColor, CRSInput, _get_size_key, Location, ExtentReturn, DetailReturn
 from .. import config
 from ..defaults import inset_map as imd
 
 ### ALL ###
 # This code tells other packages what to import if not explicitly stated
 __all__ = [
-    "InsetMapPlotModel", "InsetMapInsetModel", 
+    "InsetMapPlotModel", "InsetMapInsetModel",
     "InsetMapExtentModel", "InsetMapDetailModel",
+    "InsetMapPlotDict",
 ]
 
 ### COMPONENT MODELS ###
@@ -30,7 +31,7 @@ class InsetMapPlotModel(BaseModel):
 
 class InsetMapInsetModel(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
-    location: Literal["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]
+    location: Location
     imsize: Optional[Union[Annotated[Union[float, int], Field(ge=0)], Tuple[Annotated[Union[float, int], Field(ge=0)], Annotated[Union[float, int], Field(ge=0)]]]] = None
     pad: Optional[Union[Annotated[Union[float, int], Field(ge=0)], Tuple[Annotated[Union[float, int], Field(ge=0)], Annotated[Union[float, int], Field(ge=0)]]]] = None
     coords: Optional[Tuple[Union[float, int], Union[float, int]]] = None
@@ -64,11 +65,24 @@ class InsetMapExtentModel(BaseModel):
     alpha: Annotated[Union[float, int], Field(ge=0)]
     linewidth: Annotated[Union[float, int], Field(ge=0)]
     zorder: int
-    to_return: Optional[Literal["shape", "patch", "fig", "ax"]] = None
+    to_return: Optional[ExtentReturn] = None
 
 class InsetMapDetailModel(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
-    to_return: Optional[Literal["connectors", "lines"]] = None
+    to_return: Optional[DetailReturn] = None
     connector_color: MatplotlibColor
     connector_width: Annotated[Union[float, int], Field(ge=0)]
-    zorder: int
+    zorder: int
+
+### TYPED DICTS ###
+# Inset-map objects take their settings as individual keyword arguments rather
+# than nested config dicts, so (unlike ScaleBar/NorthArrow) there is no dict
+# literal to complete - the enumerated kwargs are typed with the shared Literal
+# aliases directly in core/inset_map.py. The one place a dict literal IS passed
+# is each element of `to_plot`, so we expose a TypedDict for that shape. It is
+# never validated at runtime (InsetMapPlotModel does that); it exists only so
+# `to_plot=[{"data": ..., "kwargs": ...}]` autocompletes its keys.
+
+class InsetMapPlotDict(TypedDict, total=False):
+    data: Any
+    kwargs: dict

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1}/matplotlib_map_utils/validation/north_arrow.py

@@ -8,24 +8,28 @@
 # Default packages
 import warnings
 # The types we use in this script
-from typing import Annotated, Union, Tuple, Optional, Literal, Any
+from typing import Annotated, Union, Tuple, Optional, Literal, Any, TypedDict
 # Pydantic type validation
 from pydantic import ConfigDict, BaseModel, Field, BeforeValidator, model_validator
-from .shared import MatplotlibColor, Numpy2DArray, MatplotlibFontsize, CRSInput, _get_size_key
+from .shared import (MatplotlibColor, Numpy2DArray, MatplotlibFontsize, CRSInput, _get_size_key,
+                     Location, LabelPosition, HAlign, VAlign, FontFamily, FontStyle, FontWeight,
+                     PackAlign, PackMode, RotationReference)
 from .. import config
 from ..defaults import north_arrow as nad
 
 ### ALL ###
 # This code tells other packages what to import if not explicitly stated
 __all__ = [
-    "NorthArrowPrimaryModel", "NorthArrowBaseModel", "NorthArrowFancyModel", 
-    "NorthArrowLabelModel", "NorthArrowShadowModel", "NorthArrowPackModel", 
-    "NorthArrowAobModel", "NorthArrowRotationModel"
+    "NorthArrowPrimaryModel", "NorthArrowBaseModel", "NorthArrowFancyModel",
+    "NorthArrowLabelModel", "NorthArrowShadowModel", "NorthArrowPackModel",
+    "NorthArrowAobModel", "NorthArrowRotationModel",
+    "NorthArrowBaseDict", "NorthArrowFancyDict", "NorthArrowLabelDict", "NorthArrowShadowDict",
+    "NorthArrowPackDict", "NorthArrowAobDict", "NorthArrowRotationDict"
 ]
 
 ### COMPONENT MODELS ###
 class NorthArrowPrimaryModel(BaseModel):
-    location: Literal["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]
+    location: Location
     scale: Annotated[Optional[Union[float, int]], Field(ge=0)] = None
     zorder: int
 
@@ -74,14 +78,14 @@ class NorthArrowFancyModel(BaseModel):
 class NorthArrowLabelModel(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
     text: str
-    position: Literal["top", "bottom", "left", "right"]
-    ha: Literal["left", "center", "right"]
-    va: Literal["baseline", "bottom", "center", "center_baseline", "top"]
+    position: LabelPosition
+    ha: HAlign
+    va: VAlign
     fontsize: MatplotlibFontsize
-    fontfamily: Literal["serif", "sans-serif", "cursive", "fantasy", "monospace"]
-    fontstyle: Literal["normal", "italic", "oblique"]
+    fontfamily: FontFamily
+    fontstyle: FontStyle
     color: MatplotlibColor
-    fontweight: Literal["normal", "bold", "heavy", "light", "ultrabold", "ultralight"]
+    fontweight: FontWeight
     stroke_width: Annotated[Union[float, int], Field(ge=0)]
     stroke_color: MatplotlibColor
     rotation: Annotated[Union[float, int], Field(ge=-360, le=360)]
@@ -112,11 +116,11 @@ class NorthArrowShadowModel(BaseModel):
 
 class NorthArrowPackModel(BaseModel):
     sep: Annotated[Union[float, int], Field(ge=0)]
-    align: Literal["top", "bottom", "left", "right", "center", "baseline"]
+    align: PackAlign
     pad: Annotated[Union[float, int], Field(ge=0)]
     width: Annotated[Optional[Union[float, int]], Field(ge=0)] = None
     height: Annotated[Optional[Union[float, int]], Field(ge=0)] = None
-    mode: Literal["fixed", "expand", "equal"]
+    mode: PackMode
 
     @model_validator(mode='before')
     @classmethod
@@ -151,7 +155,7 @@ class NorthArrowRotationModel(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
     degrees: Annotated[Optional[Union[float, int]], Field(ge=-360, le=360)] = None
     crs: Optional[CRSInput] = None
-    reference: Optional[Literal["axis", "data", "center"]] = None
+    reference: Optional[RotationReference] = None
     coords: Optional[Tuple[Union[float, int], Union[float, int]]] = None
 
     @model_validator(mode='before')
@@ -174,4 +178,69 @@ class NorthArrowRotationModel(BaseModel):
                     raise ValueError("If degrees is None, crs, reference, and coords cannot be None: please provide a valid input for each of these variables instead")
         elif isinstance(self.degrees, (int, float)) and (self.crs is not None or self.reference is not None or self.coords is not None):
             warnings.warn("A value for degrees was supplied; values for crs, reference, and coords will be ignored")
-        return self
+        return self
+
+### TYPED DICTS ###
+# These mirror the user-facing fields of the models above, purely for editor
+# intellisense (key + value autocomplete inside dict literals). They are never
+# instantiated or validated at runtime - the plain dicts users pass still flow
+# through the pydantic models above. total=False marks every key optional, since
+# users supply partial configs. Literal-typed fields reuse the shared aliases so
+# their allowed values stay in lockstep with the models.
+
+class NorthArrowBaseDict(TypedDict, total=False):
+    coords: Any
+    facecolor: Any
+    edgecolor: Any
+    linewidth: float | int
+    zorder: int
+
+class NorthArrowFancyDict(TypedDict, total=False):
+    coords: Any
+    facecolor: Any
+    zorder: int
+
+class NorthArrowLabelDict(TypedDict, total=False):
+    text: str
+    position: LabelPosition
+    ha: HAlign
+    va: VAlign
+    fontsize: float | int | str
+    fontfamily: FontFamily
+    fontstyle: FontStyle
+    color: Any
+    fontweight: FontWeight
+    stroke_width: float | int
+    stroke_color: Any
+    rotation: float | int
+    zorder: int
+
+class NorthArrowShadowDict(TypedDict, total=False):
+    offset: tuple
+    alpha: float | int
+    shadow_rgbFace: Any
+
+class NorthArrowPackDict(TypedDict, total=False):
+    sep: float | int
+    align: PackAlign
+    pad: float | int
+    width: float | int
+    height: float | int
+    mode: PackMode
+
+class NorthArrowAobDict(TypedDict, total=False):
+    facecolor: Any
+    edgecolor: Any
+    alpha: float | int
+    pad: float | int
+    borderpad: float | int
+    prop: float | int | str
+    frameon: bool
+    bbox_to_anchor: Any
+    bbox_transform: Any
+
+class NorthArrowRotationDict(TypedDict, total=False):
+    degrees: float | int
+    crs: Any
+    reference: RotationReference
+    coords: Any

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1}/matplotlib_map_utils/validation/scale_bar.py

@@ -6,9 +6,11 @@
 ### IMPORTING PACKAGES ###
 
 # Pydantic type validation
-from typing import Annotated, Union, Tuple, List, Optional, Literal, Any
+from typing import Annotated, Union, Tuple, List, Optional, Literal, Any, TypedDict
 from pydantic import ConfigDict, BaseModel, Field, BeforeValidator, model_validator
-from .shared import MatplotlibColor, MatplotlibFontsize, CRSInput, _validate_crs_input, _get_size_key
+from .shared import (MatplotlibColor, MatplotlibFontsize, CRSInput, _validate_crs_input, _get_size_key,
+                     ScaleBarStyle, Location, BarUnit, MinorType, TickLoc, LabelStyle, LabelsLoc, UnitsLoc,
+                     FontFamily, FontStyle, FontWeight, RotationMode)
 from .. import config
 from ..defaults import scale_bar as sbd
 
@@ -16,7 +18,8 @@ from ..defaults import scale_bar as sbd
 # This code tells other packages what to import if not explicitly stated
 __all__ = [
     "preferred_divs", "convert_dict", "units_standard",
-    "ScaleBarPrimaryModel", "ScaleBarBarModel", "ScaleBarLabelsModel", "ScaleBarUnitsModel", "ScaleBarTextModel", "ScaleBarAobModel"
+    "ScaleBarPrimaryModel", "ScaleBarBarModel", "ScaleBarLabelsModel", "ScaleBarUnitsModel", "ScaleBarTextModel", "ScaleBarAobModel",
+    "ScaleBarBarDict", "ScaleBarLabelsDict", "ScaleBarUnitsDict", "ScaleBarTextDict", "ScaleBarAobDict"
 ]
 
 ### CONSTANTS ###
@@ -73,8 +76,8 @@ units_standard = {
 ### COMPONENT MODELS ###
 
 class ScaleBarPrimaryModel(BaseModel):
-    style: Literal["ticks","boxes"]
-    location: Literal["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]
+    style: ScaleBarStyle
+    location: Location
     zorder: int
 
 def _validate_scalebar_projection(v):
@@ -87,7 +90,7 @@ ScaleBarProjection = Annotated[Any, BeforeValidator(_validate_scalebar_projectio
 class ScaleBarBarModel(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
     projection: ScaleBarProjection
-    unit: Optional[Literal["m","km","ft","yd","mi","nmi"]] = None
+    unit: Optional[BarUnit] = None
     rotation: Annotated[Optional[Union[float, int]], Field(ge=-360, le=360)] = None
     max: Annotated[Optional[Union[float, int]], Field(ge=0)] = None
     length: Annotated[Optional[Union[float, int]], Field(ge=0)] = None
@@ -96,12 +99,12 @@ class ScaleBarBarModel(BaseModel):
     major_div: Annotated[Optional[int], Field(ge=1)] = None
     minor_div: Annotated[Optional[int], Field(ge=0)] = None
     minor_frac: Annotated[Optional[Union[float, int]], Field(ge=0, le=1)] = None
-    minor_type: Optional[Literal["all","first","none"]] = None
+    minor_type: Optional[MinorType] = None
     major_mult: Annotated[Optional[Union[float, int]], Field(ge=0)] = None
     facecolors: Optional[Union[MatplotlibColor, List[MatplotlibColor], Tuple[MatplotlibColor, ...]]] = None
     edgecolors: Optional[Union[MatplotlibColor, List[MatplotlibColor], Tuple[MatplotlibColor, ...]]] = None
     edgewidth: Annotated[Optional[Union[float, int]], Field(ge=0)] = None
-    tick_loc: Optional[Literal["above","below","middle"]] = None
+    tick_loc: Optional[TickLoc] = None
     basecolors: Optional[Union[MatplotlibColor, List[MatplotlibColor], Tuple[MatplotlibColor, ...]]] = None
     tickcolors: Optional[Union[MatplotlibColor, List[MatplotlibColor], Tuple[MatplotlibColor, ...]]] = None
     tickwidth: Annotated[Optional[Union[float, int]], Field(ge=0)] = None
@@ -125,17 +128,17 @@ class ScaleBarLabelsModel(BaseModel):
     labels: Optional[Union[List[Any], Tuple[Any, ...]]] = None
     format: str
     format_int: bool
-    style: Literal["major","first_last","last_only","minor_all","minor_first"]
-    loc: Optional[Literal["above","below"]] = None
+    style: LabelStyle
+    loc: Optional[LabelsLoc] = None
     fontsize: Optional[MatplotlibFontsize] = None
     textcolors: Optional[Union[MatplotlibColor, List[MatplotlibColor], Tuple[MatplotlibColor, ...]]] = None
-    fontfamily: Optional[Literal["serif", "sans-serif", "cursive", "fantasy", "monospace"]] = None
-    fontstyle: Optional[Literal["normal", "italic", "oblique"]] = None
-    fontweight: Optional[Literal["normal", "bold", "heavy", "light", "ultrabold", "ultralight"]] = None
+    fontfamily: Optional[FontFamily] = None
+    fontstyle: Optional[FontStyle] = None
+    fontweight: Optional[FontWeight] = None
     stroke_width: Annotated[Optional[Union[float, int]], Field(ge=0)] = None
     stroke_color: Optional[MatplotlibColor] = None
     rotation: Annotated[Optional[Union[float, int]], Field(ge=-360, le=360)] = None
-    rotation_mode: Optional[Literal["anchor","default"]] = None
+    rotation_mode: Optional[RotationMode] = None
     sep: Annotated[Union[float, int], Field(ge=0)]
     pad: Annotated[Union[float, int], Field(ge=0)]
 
@@ -163,16 +166,16 @@ class ScaleBarLabelsModel(BaseModel):
 class ScaleBarUnitsModel(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
     label: Optional[str] = None
-    loc: Optional[Literal["bar","text","opposite"]] = None
+    loc: Optional[UnitsLoc] = None
     fontsize: Optional[MatplotlibFontsize] = None
     textcolor: Optional[MatplotlibColor] = None
-    fontfamily: Optional[Literal["serif", "sans-serif", "cursive", "fantasy", "monospace"]] = None
-    fontstyle: Optional[Literal["normal", "italic", "oblique"]] = None
-    fontweight: Optional[Literal["normal", "bold", "heavy", "light", "ultrabold", "ultralight"]] = None
+    fontfamily: Optional[FontFamily] = None
+    fontstyle: Optional[FontStyle] = None
+    fontweight: Optional[FontWeight] = None
     stroke_width: Annotated[Optional[Union[float, int]], Field(ge=0)] = None
     stroke_color: Optional[MatplotlibColor] = None
     rotation: Annotated[Optional[Union[float, int]], Field(ge=-360, le=360)] = None
-    rotation_mode: Optional[Literal["anchor","default"]] = None
+    rotation_mode: Optional[RotationMode] = None
     sep: Annotated[Union[float, int], Field(ge=0)]
     pad: Annotated[Union[float, int], Field(ge=0)]
 
@@ -198,13 +201,13 @@ class ScaleBarTextModel(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
     fontsize: MatplotlibFontsize
     textcolor: Union[MatplotlibColor, List[MatplotlibColor], Tuple[MatplotlibColor, ...]]
-    fontfamily: Literal["serif", "sans-serif", "cursive", "fantasy", "monospace"]
-    fontstyle: Literal["normal", "italic", "oblique"]
-    fontweight: Literal["normal", "bold", "heavy", "light", "ultrabold", "ultralight"]
+    fontfamily: FontFamily
+    fontstyle: FontStyle
+    fontweight: FontWeight
     stroke_width: Annotated[Union[float, int], Field(ge=0)]
     stroke_color: MatplotlibColor
     rotation: Annotated[Optional[Union[float, int]], Field(ge=-360, le=360)] = None
-    rotation_mode: Optional[Literal["anchor","default"]] = None
+    rotation_mode: Optional[RotationMode] = None
 
     @model_validator(mode='before')
     @classmethod
@@ -235,3 +238,92 @@ class ScaleBarAobModel(BaseModel):
         size = data.pop('size', config.DEFAULT_SIZE)
         defaults = sbd._DEFAULTS_SB[_get_size_key(size)][4]
         return defaults | data
+
+### TYPED DICTS ###
+# These mirror the user-facing fields of the models above, purely for editor
+# intellisense (key + value autocomplete inside dict literals). They are never
+# instantiated or validated at runtime - the plain dicts users pass still flow
+# through the pydantic models above. total=False marks every key optional, since
+# users supply partial configs. Literal-typed fields reuse the shared aliases so
+# their allowed values stay in lockstep with the models.
+
+class ScaleBarBarDict(TypedDict, total=False):
+    projection: Any
+    unit: BarUnit
+    rotation: float | int
+    max: float | int
+    length: float | int
+    height: float | int
+    reverse: bool
+    major_div: int
+    minor_div: int
+    minor_frac: float | int
+    minor_type: MinorType
+    major_mult: float | int
+    facecolors: Any
+    edgecolors: Any
+    edgewidth: float | int
+    tick_loc: TickLoc
+    basecolors: Any
+    tickcolors: Any
+    tickwidth: float | int
+    interpolation: str
+    dpi_cor: bool
+    resample: bool
+    raster_dpi: float | int
+    raster_dpi_scale: float | int
+
+class ScaleBarLabelsDict(TypedDict, total=False):
+    labels: list | tuple
+    format: str
+    format_int: bool
+    style: LabelStyle
+    loc: LabelsLoc
+    fontsize: float | int | str
+    textcolors: Any
+    fontfamily: FontFamily
+    fontstyle: FontStyle
+    fontweight: FontWeight
+    stroke_width: float | int
+    stroke_color: Any
+    rotation: float | int
+    rotation_mode: RotationMode
+    sep: float | int
+    pad: float | int
+
+class ScaleBarUnitsDict(TypedDict, total=False):
+    label: str
+    loc: UnitsLoc
+    fontsize: float | int | str
+    textcolor: Any
+    fontfamily: FontFamily
+    fontstyle: FontStyle
+    fontweight: FontWeight
+    stroke_width: float | int
+    stroke_color: Any
+    rotation: float | int
+    rotation_mode: RotationMode
+    sep: float | int
+    pad: float | int
+
+class ScaleBarTextDict(TypedDict, total=False):
+    fontsize: float | int | str
+    textcolor: Any
+    fontfamily: FontFamily
+    fontstyle: FontStyle
+    fontweight: FontWeight
+    stroke_width: float | int
+    stroke_color: Any
+    rotation: float | int
+    rotation_mode: RotationMode
+
+class ScaleBarAobDict(TypedDict, total=False):
+    facecolor: Any
+    edgecolor: Any
+    alpha: float | int
+    pad: float | int
+    borderpad: float | int
+    prop: float | int | str
+    frameon: bool
+    bbox_to_anchor: Any
+    bbox_transform: Any

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1}/matplotlib_map_utils/validation/shared.py

@@ -6,9 +6,44 @@
 import numpy
 import pyproj
 import matplotlib.rcsetup
-from typing import Annotated, Any
+from typing import Annotated, Any, Literal
 from pydantic import BeforeValidator
 
+### SHARED LITERAL ALIASES ###
+# These name the enumerated value-sets used across the validation models.
+# They are referenced by BOTH the pydantic models (for runtime validation) and
+# the TypedDicts (for editor intellisense), so the allowed values can never drift
+# between the two representations.
+
+# Shared across components
+Location = Literal["upper right", "upper left", "lower left", "lower right",
+                   "center left", "center right", "lower center", "upper center", "center"]
+FontFamily = Literal["serif", "sans-serif", "cursive", "fantasy", "monospace"]
+FontStyle = Literal["normal", "italic", "oblique"]
+FontWeight = Literal["normal", "bold", "heavy", "light", "ultrabold", "ultralight"]
+RotationMode = Literal["anchor", "default"]
+
+# scale_bar-specific
+ScaleBarStyle = Literal["ticks", "boxes"]
+BarUnit = Literal["m", "km", "ft", "yd", "mi", "nmi"]
+MinorType = Literal["all", "first", "none"]
+TickLoc = Literal["above", "below", "middle"]
+LabelStyle = Literal["major", "first_last", "last_only", "minor_all", "minor_first"]
+LabelsLoc = Literal["above", "below"]
+UnitsLoc = Literal["bar", "text", "opposite"]
+
+# north_arrow-specific
+LabelPosition = Literal["top", "bottom", "left", "right"]
+HAlign = Literal["left", "center", "right"]
+VAlign = Literal["baseline", "bottom", "center", "center_baseline", "top"]
+PackAlign = Literal["top", "bottom", "left", "right", "center", "baseline"]
+PackMode = Literal["fixed", "expand", "equal"]
+RotationReference = Literal["axis", "data", "center"]
+
+# inset_map-specific
+ExtentReturn = Literal["shape", "patch", "fig", "ax"]
+DetailReturn = Literal["connectors", "lines"]
+
 def _validate_color(v):
     if v is None:
         return v

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1/matplotlib_map_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matplotlib-map-utils
-Version: 4.1.0
+Version: 4.1.1
 Summary: A suite of tools for creating maps in matplotlib
 Author-email: David Moss <davidmoss1221@gmail.com>
 Project-URL: Homepage, https://github.com/moss-xyz/matplotlib-map-utils/
@@ -28,7 +28,7 @@ Dynamic: license-file
 
 **Feedback:** I welcome any and all feedback! See the *Development Notes* below for more details.
 
-**Current Version:** `v4.1.0`, featuring a brand-new documentation site and improved type validation! This DID introduce some breaking changes, see the documentation site for details!
+**Current Version:** `v4.1.1`, which fixed a a few bugs (see [here](https://moss-xyz.github.io/matplotlib-map-utils/package/#release-notes) for details!)
 
 ---
 

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1}/matplotlib_map_utils.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ docs/assets/quick/generator.py
 docs/assets/scale_bars/generator.py
 matplotlib_map_utils/__init__.py
 matplotlib_map_utils/config.py
+matplotlib_map_utils/py.typed
 matplotlib_map_utils.egg-info/PKG-INFO
 matplotlib_map_utils.egg-info/SOURCES.txt
 matplotlib_map_utils.egg-info/dependency_links.txt

{matplotlib_map_utils-4.1.0 → matplotlib_map_utils-4.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "matplotlib-map-utils"
-version = "4.1.0"
+version = "4.1.1"
 authors = [
   { name="David Moss", email="davidmoss1221@gmail.com" },
 ]
@@ -29,6 +29,7 @@ exclude = ["matplotlib_map_utils.scratch*", "site*", "docs*"]
 
 [tool.setuptools.package-data]
 "matplotlib_map_utils.utils" = ["*.json"]
+"matplotlib_map_utils" = ["py.typed"]
 
 [dependency-groups]
 dev = [
@@ -37,6 +38,7 @@ dev = [
     "ipykernel>=6.30.1",
     "jupyter>=1.1.1",
     "mapclassify>=2.8.1",
+    "marimo>=0.23.10",
     "matplotlib>=3.10.7",
     "notebook>=7.4.7",
     "pip>=25.2",