matplotlib-map-utils 2.0.2__py3-none-any.whl → 3.0.0__py3-none-any.whl

matplotlib_map_utils/utils/usa.py

@@ -0,0 +1,336 @@
+import re
+import json
+import warnings
+from importlib import resources
+from typing import List, Literal, Union
+
+# Literal lists, for intellisense
+regions = Literal["Midwest", "Northeast", "South", "West", 
+                  "Inhabited Territory", "Uninhabited Territory", "Sovereign State"]
+
+divisions = Literal["East North Central", "East South Central", "Mid-Atlantic", "Mountain", 
+                    "New England", "Pacific", "South Atlantic", "West North Central", "West South Central",
+                    "Commonwealth", "Compact of Free Association", "Incorporated and Unorganized", 
+                    "Unincorporated and Unorganized", "Unincorporated and Organized"] 
+
+ombs = Literal["Region I", "Region II", "Region III", "Region IV", "Region IX", "Region V", 
+               "Region VI", "Region VII", "Region VIII", "Region X",
+               "Inhabited Territory", "Uninhabited Territory", "Sovereign State"]
+
+beas = Literal["Far West", "Great Lakes", "Mideast", "New England", "Plains", 
+               "Rocky Mountain", "Southeast", "Southwest",
+               "Inhabited Territory", "Uninhabited Territory", "Sovereign State"]
+
+returns = Literal["fips","name","abbr","object","dict"]
+
+class USA:
+    # No arguments need to pass on initialization really
+    def __init__(self):
+        self._jurisdictions = self._load_json()
+
+    # This is just for loading the JSON
+    def _load_json(self):
+        with resources.files("matplotlib_map_utils.utils").joinpath("usa.json").open("r") as f:
+            usa_json = json.load(f)
+        return usa_json
+    
+    # Getter for all jurisdictions, VALID OR NOT
+    @property 
+    def _all(self):
+        return self._jurisdictions
+
+    # Getter for all valid jurisdictions
+    @property
+    def jurisdictions(self):
+        return self.filter_valid(True, self._all, "object")
+    
+    # Getter for all valid states
+    @property
+    def states(self):
+        return self.filter_state(True, self.jurisdictions, "object")
+    
+    # Getter for all valid territories
+    @property
+    def territories(self):
+        return self.filter_territory(True, self.jurisdictions, "object")
+    
+    # Getters to generate distinct values for Region, Division, OMB, and BEA
+    # which are useful if you can't recall which options are valid
+    # First, the function that will get the distinct values
+    def _distinct_options(self, key):
+        # First getting all the available options from the list
+        options = [j[key] for j in self.jurisdictions if j[key] is not None]
+        # Creating the distinct set
+        options_set = set(options)
+        # Returning the set (but as a list)
+        # this will also be alphabetically sorted
+        options = list(options_set)
+        options.sort()
+        return options
+    
+    # The getters are now just calls to the properties
+    @property 
+    def regions(self):
+        return self._distinct_options("region")
+    
+    @property 
+    def divisions(self):
+        return self._distinct_options("division")
+    
+    @property 
+    def omb(self):
+        return self._distinct_options("omb")
+    
+    @property 
+    def bea(self):
+        return self._distinct_options("bea")
+    
+    # Main filter function
+    # Each filter step will follow the same process
+    ## Check that there is a non-None filter
+    ## Normalize the input to be in a list (if not already)
+    ## Perform the filter step
+    # Each step is also available as its own independent function, as needed
+    def filter(self, valid: bool | None=True, 
+               fips: str | int | None=None, 
+               name: str | None=None, 
+               abbr: str | None=None, 
+               state: bool | None=None, 
+               contiguous: bool | None=None, 
+               territory: bool | None=None, 
+               region: Union[regions, List[regions]]=None, 
+               division: Union[divisions, List[divisions]]=None, 
+               omb: Union[ombs, List[ombs]]=None,
+               bea: Union[beas, List[beas]]=None,
+               to_return: Union[returns, List[returns]]="fips"):
+        
+        # Getting a copy of our jurisdictions, which will be filtered each time
+        filter_juris = self.jurisdictions.copy()
+
+        # Starting with an initial valid filtering
+        # Which will drop invalid FIPS codes 03, 07, 14, 43, and 52
+        if (valid is not None) and (len(filter_juris) > 0):
+            filter_juris = self.filter_valid(valid, filter_juris, to_return="_ignore")
+
+        # Going through each step
+        if (fips is not None) and (len(filter_juris) > 0):
+            filter_juris = self.filter_fips(fips, filter_juris, to_return="_ignore")
+        
+        if (name is not None) and (len(filter_juris) > 0):
+            filter_juris = self.filter_name(name, filter_juris, to_return="_ignore")
+        
+        if (abbr is not None) and (len(filter_juris) > 0):
+            filter_juris = self.filter_abbr(abbr, filter_juris, to_return="_ignore")
+        
+        if (state is not None) and (len(filter_juris) > 0):
+            filter_juris = self.filter_state(state, filter_juris, to_return="_ignore")
+        
+        if (contiguous is not None) and (len(filter_juris) > 0):
+            filter_juris = self.filter_contiguous(contiguous, filter_juris, to_return="_ignore")
+        
+        if (territory is not None) and (len(filter_juris) > 0):
+            filter_juris = self.filter_territory(territory, filter_juris, to_return="_ignore")
+        
+        if (region is not None) and (len(filter_juris) > 0):
+            filter_juris = self.filter_region(region, filter_juris, to_return="_ignore")
+        
+        if (division is not None) and (len(filter_juris) > 0):
+            filter_juris = self.filter_division(division, filter_juris, to_return="_ignore")
+        
+        if (omb is not None) and (len(filter_juris) > 0):
+            filter_juris = self.filter_omb(omb, filter_juris, to_return="_ignore")
+        
+        if (bea is not None) and (len(filter_juris) > 0):
+            filter_juris = self.filter_bea(bea, filter_juris, to_return="_ignore")
+        
+        # Final step is to process the input based on to_return
+        # and then return it!
+        return self._process_return(filter_juris, to_return)
+    
+    # Filtering bool values (valid, state, contiguous, territory)
+    # Will accept either true or false
+    def _filter_bool(self, value, key, to_filter=None, to_return="_ignore"):
+        # If nothing is passed to to_filter, getting the jurisdictions list
+        to_filter = self.jurisdictions.copy() if to_filter is None else to_filter
+        if not isinstance(value, bool):
+            warnings.warn(f"Invalid {key} filter: {value}. Only boolean values (True/False) are considered valid, see documentation for details.")
+        else:    
+            # Performing the filter
+            filtered = [j for j in to_filter if j[key] == value]
+            # And returning the values
+            return self._process_return(filtered, to_return)
+
+    # Shortcuts for filtering based on valid, state, contiguous, and territory
+    def filter_valid(self, valid: bool, to_filter=None, to_return="fips"):
+        return self._filter_bool(valid, "valid", to_filter, to_return)
+    
+    def filter_state(self, state: bool, to_filter=None, to_return="fips"):
+        return self._filter_bool(state, "state", to_filter, to_return)
+    
+    def filter_contiguous(self, contiguous: bool, to_filter=None, to_return="fips"):
+        return self._filter_bool(contiguous, "contiguous", to_filter, to_return)
+    
+    def filter_territory(self, territory: bool, to_filter=None, to_return="fips"):
+        return self._filter_bool(territory, "territory", to_filter, to_return)
+
+    # Filtering FIPS
+    # Will accept an integer or a two-digit string as an input
+    # If a longer string is inserted, will truncate to only the first two characters
+    def filter_fips(self, fips: str | List[str], to_filter=None, to_return="abbr"):
+        # If nothing is passed to to_filter, getting the jurisdictions list
+        to_filter = self.jurisdictions.copy() if to_filter is None else to_filter
+        # Normalizing the fips value being passed
+        fips = self._normalize_input(fips)
+        # This will store the cleaned-up fips codes
+        fips_clean = []
+        for f in fips:
+            # If the input is an integer, convert it to a two-digit string
+            if isinstance(f, int):
+                fips_clean.append(str(f).zfill(2)[:2])
+            # If the input is already a string, get the first two characters
+            elif isinstance(f, str):
+                fips_clean.append(f.zfill(2)[:2])
+            # Otherwise, throw a *warning*
+            else:
+                warnings.warn(f"Invalid FIPS filter: {f}. Only integers and strings are considered valid, see documentation for details.")
+        # Now can use the clean fips to actually filter
+        filtered = [j for j in to_filter if j["fips"] in fips_clean]
+        # And returning the values
+        return self._process_return(filtered, to_return)
+    
+    # Filtering name
+    # Will accept strings
+    # Will normalize the string first (trim, case, special characters), before checking
+    # Some states also have an alias available for checking against (Washington, D.C. and District of Columbia are equivalent)
+    def filter_name(self, name: str | List[str], to_filter=None, to_return="fips"):
+        # If nothing is passed to to_filter, getting the jurisdictions list
+        to_filter = self.jurisdictions.copy() if to_filter is None else to_filter
+        # Normalizing the name input being passed
+        name = self._normalize_input(name)
+        # This will store the cleaned-up name input
+        name_clean = []
+        for n in name:
+            # If the input is a string, clean it
+            if isinstance(n, str):
+                name_clean.append(self._normalize_string(n, case="lower"))
+            else:
+                warnings.warn(f"Invalid name filter: {n}. Only strings are considered valid, see documentation for details.")
+        # Now we can use the clean name to filter
+        # Note that we also normalize the names and aliases in our to_filter list!
+        filtered = [j for j in to_filter if ((self._normalize_string(j["name"], case="lower") in name_clean) or 
+                                             (j["alias"] is not None and self._normalize_string(j["alias"], case="lower") in name_clean))]
+        # And returning the values
+        return self._process_return(filtered, to_return)
+
+    # Filtering abbr
+    # Will accept strings
+    # Will normalize the string first (trim, case, special characters), before checking
+    # If a string longer than two characters is passed, will only look at the first two characters!
+    def filter_abbr(self, abbr: str | List[str], to_filter=None, to_return="fips"):
+        # If nothing is passed to to_filter, getting the jurisdictions list
+        to_filter = self.jurisdictions.copy() if to_filter is None else to_filter
+        # Normalizing the input being passed
+        abbr = self._normalize_input(abbr)
+        # This will store the cleaned-up input
+        abbr_clean = []
+        for a in abbr:
+            # If the input is a string, clean it
+            if isinstance(a, str):
+                abbr_clean.append(self._normalize_string(a, case="lower"))
+            else:
+                warnings.warn(f"Invalid abbr filter: {a}. Only strings are considered valid, see documentation for details.")
+        # Now we can use the clean input to filter
+        filtered = [j for j in to_filter if (j["abbr"] is not None and self._normalize_string(j["abbr"], case="lower")[:2] in abbr_clean)]
+        # And returning the values
+        return self._process_return(filtered, to_return)
+
+    # Filtering for categorical values (region/division/omb/bea)
+    # Will get the list of acceptable values and compare inputs to it
+    # while also warning if an invalid filter is requested
+    def _filter_categorical(self, input, key, to_filter=None, to_return="_ignore"):
+        # If nothing is passed to to_filter, getting the jurisdictions list
+        to_filter = self.jurisdictions.copy() if to_filter is None else to_filter
+        # Normalizing the input being passed
+        input = self._normalize_input(input)
+        # This has the acceptable inputs we want to compare against
+        accepted_inputs = self._distinct_options(key)
+        # This will store the cleaned-up input
+        input_clean = []
+        for i in input:
+            # If the input is not a string, warn
+            if not isinstance(i, str):
+                warnings.warn(f"Invalid {key} filter: {i}. Only strings are considered valid, see documentation for details.")
+            # If the input is not in our list, warn the user
+            elif i not in accepted_inputs:
+                warnings.warn(f"Invalid {key} filter: {i}. Only the following inputs are considered valid: {accepted_inputs}.")
+            # Otherwise, add it to our list
+            else:
+                input_clean.append(i)
+        # Now we can use the clean input to filter
+        filtered = [j for j in to_filter if j[key] in input_clean]
+        # And returning the values
+        return self._process_return(filtered, to_return)
+    
+    # Iterations for each categorical filter based on their respective inputs
+    def filter_region(self, region: Union[regions, List[regions]], to_filter=None, to_return="fips"):
+        return self._filter_categorical(region, "region", to_filter, to_return)
+    
+    def filter_division(self, division: Union[divisions, List[divisions]], to_filter=None, to_return="fips"):
+        return self._filter_categorical(division, "division", to_filter, to_return)
+    
+    def filter_omb(self, omb: Union[ombs, List[ombs]], to_filter=None, to_return="fips"):
+        return self._filter_categorical(omb, "omb", to_filter, to_return)
+    
+    def filter_bea(self, bea: Union[beas, List[beas]], to_filter=None, to_return="fips"):
+        return self._filter_categorical(bea, "bea", to_filter, to_return)
+
+    # Function that processes the returning of a filtered jurisdiction
+    def _process_return(self, filter_juris, to_return):
+        # If the length is zero, warn!
+        if filter_juris is None or len(filter_juris) == 0:
+            warnings.warn(f"No matching entities found. Please refer to the documentation and double-check your filters.")
+            return None
+        if to_return is None:
+            to_return == "_ignore"
+        # Available options for to_return include fips, name, and abbr
+        elif to_return.lower() == "fips":
+            juris_return = [j["fips"] for j in filter_juris]
+        elif to_return.lower() == "name":
+            juris_return = [j["name"] for j in filter_juris]
+        elif to_return.lower() == "abbr":
+            juris_return = [j["abbr"] for j in filter_juris]
+        # Can also request that the entire object be returned, in which case nothing is done
+        # This will also happen if an invalid return object is passed
+        elif to_return.lower() not in ["object","dict","_ignore"]:
+            warnings.warn(f"Invalid to_return request: {to_return}. The entire object will be returned.")
+            juris_return = filter_juris.copy()
+        else:
+            juris_return = filter_juris.copy()
+        
+        # Now, also processing the return request based on the length of the returned list
+        # If the length is zero, warn!
+        if len(juris_return) == 0:
+            warnings.warn(f"No matching entities found. Please refer to the documentation and double-check your filters.")
+            return None
+        # If only one element is returned, return the element itself, not a list
+        elif len(juris_return) == 1 and to_return != "_ignore":
+            return juris_return[0]
+        # Otherwise return the whole thing
+        else:
+            return juris_return
+
+    # Utility function to normalize a string that is passed to it
+    def _normalize_string(self, string, case="keep", nan="", spaces="_"):
+        string = string.strip()
+        if case == "lower":
+            string = string.lower()
+        string = re.sub(r"\W\S",nan,string)
+        string = re.sub(r"\s",spaces,string)
+        return string
+    
+    # Utility function to convert a relevant non-list input to a list
+    def _normalize_input(self, input):
+        if not isinstance(input, (list, tuple)):
+            return [input]
+        else:
+            return input

matplotlib_map_utils/validation/functions.py

@@ -20,7 +20,7 @@ def _validate_list(prop, val, list, none_ok=False):
         raise ValueError(f"'{val}' is not a valid value for {prop}, please provide a value in this list: {list}")
     return val
 
-def _validate_range(prop, val, min, max, none_ok=False):
+def _validate_range(prop, val, min, max=None, none_ok=False):
     if none_ok==False and val is None:
         raise ValueError(f"None is not a valid value for {prop}, please provide a value between {min} and {max}")
     elif none_ok==True and val is None:
@@ -69,7 +69,7 @@ def _validate_tuple(prop, val, length, types, none_ok=False):
         raise ValueError(f"None is not a valid value for {prop}, please provide a tuple of length {length} instead")
     elif none_ok==True and val is None:
         return val
-    elif type(val)!=tuple:
+    elif not isinstance(val, (tuple, list)):
         raise ValueError(f"{val} is not a valid value for {prop}, please provide a tuple of length {length} instead")
     elif len(val)!=length:
         raise ValueError(f"{val} is not a valid value for {prop}, please provide a tuple of length {length} instead")
@@ -117,7 +117,7 @@ def _validate_crs(prop, val, rotation_dict, none_ok=False):
         try:
             val = pyproj.CRS.from_user_input(val)
         except:
-            raise Exception(f"Invalid CRS supplied ({val}), please provide a valid CRS input for PyProj instead")
+            raise Exception(f"Invalid CRS supplied ({val}), please provide a valid CRS input that PyProj can use instead")
     return val
 
 # A simpler validation function for CRSs
@@ -128,14 +128,14 @@ def _validate_projection(prop, val, none_ok=False):
         try:
             val = pyproj.CRS.from_user_input(val)
         except:
-            raise Exception(f"Invalid CRS supplied ({val}), please provide a valid CRS input for PyProj instead")
+            raise Exception(f"Invalid CRS supplied ({val}) for {prop}, please provide a valid CRS input that PyProj can use instead")
     return val    
 
-# It is specifically to apply another validation function to the items in a list 
+# This is specifically to apply another validation function to the items in a list 
 # Ex. if we want to validate a LIST of colors instead of a single color
 def _validate_iterable(prop, val, func, kwargs=None):
     # Making sure we wrap everything in a list
-    if type(val) not in [tuple, list]:
+    if not isinstance(val, (tuple, list)):
         val = [val]
     # Then, we apply our validation func with optional kwargs to each item in said list, relying on it to return an error value
     if kwargs is not None:
@@ -148,21 +148,57 @@ def _validate_iterable(prop, val, func, kwargs=None):
             v = func(v)
         return val
     
-# This is specifically to apply multiple validation functions to a value, if needed
+# This is to check for the structure of a dictionary-like object 
+def _validate_keys(prop, val, keys, none_ok=False):
+    if none_ok==False and val is None:
+        raise ValueError(f"None is not a valid value for {prop}, please provide a dictionary with keys {keys} instead")
+    elif none_ok==True and val is None:
+        return val
+    elif not isinstance(val, (dict)):
+        raise ValueError(f"{val} is not a valid value for {prop}, please provide a dictionary with keys {keys} instead")
+    else:
+        for k in val.keys():
+            if k not in keys:
+                raise ValueError(f"{k} is not a valid key for the items in {prop}, please provide a dictionary with keys {keys} instead")
+    return val
+
+# This is to apply multiple validation functions to a value, if needed - only one needs to pass
 # Ex. If an item can be a string OR a list of strings, we can use this to validate it
-# "labels":{"func":_validate_multiple, "kwargs":{"funcs":[_validate_type, _validate_list], "kwargs":[{"match":str, "none_ok":True}, {"list":["major","first_last","minor_all","minor_first"], "none_ok":True}]}}, # any string or any item in the list
-def _validate_multiple(prop, val, funcs, kwargs):
+def _validate_or(prop, val, funcs, kwargs):
+    success = False
     # Simply iterate through each func and kwarg
     for f,k in zip(funcs,kwargs):
         # We wrap the attempts in a try block to suppress the errors
         try:
-            v = f(prop=prop, val=v, **k)
+            val = f(prop=prop, val=val, **k)
              # If we pass, we can stop here and return the value
-            return val
+            success = True 
+            break
         except:
-            continue
-    # If we didn't return a value and exit the loop yet, then the passed value is incorrect, as we raise an error
-    raise ValueError(f"{val} is not a valid value for {prop}, please provide check the documentation")
+            pass
+    if success == False:
+        # If we didn't return a value and exit the loop yet, then the passed value is incorrect, as we raise an error
+        raise ValueError(f"{val} is not a valid value for {prop}, please check the documentation")
+    else:
+        return val
+
+# This is the same, but ALL need to pass
+def _validate_and(prop, val, funcs, kwargs):
+    success = True
+    # Simply iterate through each func and kwarg
+    for f,k in zip(funcs,kwargs):
+        # We wrap the attempts in a try block to suppress the errors
+        try:
+            val = f(prop=prop, val=val, **k)
+        except:
+             # If we fail, we can stop here and return the value
+            success = False
+            break
+    if success == False:
+        # If we didn't return a value and exit the loop yet, then the passed value is incorrect, as we raise an error
+        raise ValueError(f"{val} is not a valid value for {prop}, please check the documentation")
+    else:
+        return val
 
 # This final one is used for keys that are not validated
 def _skip_validation(val, none_ok=False):
@@ -221,7 +257,7 @@ def _validate_dict(input_dict, default_dict, functions, to_validate=None, return
 def _validate(validate_dict, prop, val, return_val=True, kwargs={}):
     fd = validate_dict[prop]
     func = fd["func"]
-    # Our custom functions always have this dictionary key in them, so we know what form they take
+    # Most of our custom functions always have this dictionary key in them, so we know what form they take
     if "kwargs" in fd:
         val = func(prop=prop, val=val, **(fd["kwargs"] | kwargs))
     # The matplotlib built-in functions DON'T have that, and only ever take the one value

matplotlib_map_utils/validation/inset_map.py

@@ -0,0 +1,88 @@
+############################################################
+# validation/inset_map.py contains all the main objects
+# for checking inputs passed to class definitions
+############################################################
+
+### IMPORTING PACKAGES ###
+
+# Geo packages
+import matplotlib.axes
+import pyproj
+# Graphical packages
+import matplotlib
+# matplotlib's useful validation functions
+import matplotlib.rcsetup
+# The types we use in this script
+from typing import TypedDict, Literal
+# Finally, the validation functions
+from . import functions as vf
+
+### ALL ###
+# This code tells other packages what to import if not explicitly stated
+__all__ = [
+    "_TYPE_INSET", "_VALIDATE_INSET",
+    "_TYPE_EXTENT", "_VALIDATE_EXTENT",
+    "_TYPE_DETAIL", "_VALIDATE_DETAIL",
+]
+
+### TYPE HINTS ###
+# This section of the code is for defining structured dictionaries and lists
+# for the inputs necessary for object creation we've created (such as the style dictionaries)
+# so that intellisense can help with autocompletion
+
+class _TYPE_INSET(TypedDict, total=False):
+    size: int | float | tuple[int | float, int | float] | list[int | float, int | float] # each int or float should be between 0 and inf
+    pad: int | float | tuple[int | float, int | float] | list[int | float, int | float] # each int or float should be between 0 and inf
+    coords: tuple[int | float, int | float] | list[int | float, int | float] # each int or float should be between -inf and inf
+
+class _TYPE_EXTENT(TypedDict, total=False):
+    pax: matplotlib.axes.Axes # any Matplotlib Axes
+    bax: matplotlib.axes.Axes # any Matplotlib Axes
+    pcrs: str | int | pyproj.CRS # should be a valid cartopy or pyproj crs, or a string or int that can be converted to that
+    bcrs: str | int | pyproj.CRS # should be a valid cartopy or pyproj crs, or a string or int that can be converted to that
+    straighten: bool # either true or false
+    pad: float | int # any positive float or integer
+    plot: bool # either true or false
+    to_return: Literal["shape","patch","fig","ax"] | None # any item in the list, or None if nothing should be returned
+    facecolor: str # a color to use for the face of the box
+    linecolor: str # a color to use for the edge of the box
+    alpha: float | int # any positive float or integer
+    linewidth: float | int # any positive float or integer
+
+class _TYPE_DETAIL(TypedDict, total=False):
+    to_return: Literal["connectors", "lines"] | None # any item in the list, or None if nothing should be returned
+    connector_color: str # a color to use for the face of the box
+    connector_width: float | int # any positive float or integer
+
+### VALIDITY DICTS ###
+# These compile the functions in validation/functions, as well as matplotlib's built-in validity functions
+# into dictionaries that can be used to validate all the inputs to a dictionary at once
+
+_VALIDATE_INSET = {
+    "location":{"func":vf._validate_list, "kwargs":{"list":["upper right", "upper left", "lower left", "lower right", "center left", "center right", "lower center", "upper center", "center"]}},
+    "size":{"func":vf._validate_or, "kwargs":{"funcs":[vf._validate_range, vf._validate_and], "kwargs":[{"min":0, "none_ok":True}, {"funcs":[vf._validate_tuple, vf._validate_iterable], "kwargs":[{"length":2, "types":[float, int]}, {"func":vf._validate_range, "kwargs":{"min":0}}]}]}}, # between 0 and inf, or a two-tuple of (x,y) size, each between 0 and inf
+    "pad":{"func":vf._validate_or, "kwargs":{"funcs":[vf._validate_range, vf._validate_and], "kwargs":[{"min":0, "none_ok":True}, {"funcs":[vf._validate_tuple, vf._validate_iterable], "kwargs":[{"length":2, "types":[float, int]}, {"func":vf._validate_range, "kwargs":{"min":0}}]}]}}, # between 0 and inf, or a two-tuple of (x,y) size, each between 0 and inf
+    "coords":{"func":vf._validate_tuple, "kwargs":{"length":2, "types":[float, int], "none_ok":True}}, # a two-tuple of coordinates where you want to place the inset map
+    "to_plot":{"func":vf._validate_iterable, "kwargs":{"func":vf._validate_keys, "kwargs":{"keys":["data","kwargs"], "none_ok":True}}}, # a list of dictionaries, where each contains "data" and "kwargs" keys
+}
+
+_VALIDATE_EXTENT = {
+    "pax":{"func":vf._validate_type, "kwargs":{"match":matplotlib.axes.Axes}}, # any Matplotlib Axes
+    "bax":{"func":vf._validate_type, "kwargs":{"match":matplotlib.axes.Axes}}, # any Matplotlib Axes
+    "pcrs":{"func":vf._validate_projection, "kwargs":{"none_ok":False}}, # any valid projection input for PyProj
+    "bcrs":{"func":vf._validate_projection, "kwargs":{"none_ok":False}}, # any valid projection input for PyProj
+    "straighten":{"func":vf._validate_type, "kwargs":{"match":bool}}, # true or false
+    "pad":{"func":vf._validate_range, "kwargs":{"min":0}}, # any positive number
+    "plot":{"func":vf._validate_type, "kwargs":{"match":bool}}, # true or false
+    "facecolor":{"func":matplotlib.rcsetup.validate_color}, # any color value for matplotlib
+    "linecolor":{"func":matplotlib.rcsetup.validate_color}, # any color value for matplotlib
+    "alpha":{"func":vf._validate_range, "kwargs":{"min":0}}, # any positive number
+    "linewidth":{"func":vf._validate_range, "kwargs":{"min":0}}, # any positive number
+    "to_return":{"func":vf._validate_list, "kwargs":{"list":["shape", "patch", "fig", "ax"], "none_ok":True}}, # any value in this list
+}
+
+_VALIDATE_DETAIL = {
+    "to_return":{"func":vf._validate_list, "kwargs":{"list":["connectors", "lines"], "none_ok":True}}, # any value in this list
+    "connector_color":{"func":matplotlib.rcsetup.validate_color}, # any color value for matplotlib
+    "connector_width":{"func":vf._validate_range, "kwargs":{"min":0}}, # any positive number
+}

matplotlib_map_utils/validation/north_arrow.py

@@ -90,7 +90,7 @@ class _TYPE_ROTATION(TypedDict, total=False):
     coords: Tuple[float | int, float | int] # only required if degrees is None: should be a tuple of coordinates in the relevant reference window
 
 ### VALIDITY DICTS ###
-# These compile the functions above^, as well as matplotlib's built-in validity functions
+# These compile the functions in validation/functions, as well as matplotlib's built-in validity functions
 # into dictionaries that can be used to validate all the inputs to a dictionary at once
 
 _VALIDATE_PRIMARY = {

matplotlib_map_utils/validation/scale_bar.py

@@ -7,12 +7,10 @@
 
 # Geo packages
 import pyproj
-# Graphical packages
-import matplotlib
 # matplotlib's useful validation functions
 import matplotlib.rcsetup
 # The types we use in this script
-from typing import Tuple, TypedDict, Literal, get_args
+from typing import TypedDict, Literal, get_args
 # Finally, the validation functions
 from . import functions as vf
 
@@ -161,7 +159,7 @@ class _TYPE_AOB(TypedDict, total=False):
     # bbox_transform: None # NOTE: currently unvalidated, use at your own risk!
 
 ### VALIDITY DICTS ###
-# These compile the functions above^, as well as matplotlib's built-in validity functions
+# These compile the functions in validation/functions, as well as matplotlib's built-in validity functions
 # into dictionaries that can be used to validate all the inputs to a dictionary at once
 
 _VALIDATE_PRIMARY = {
@@ -173,7 +171,7 @@ _VALID_BAR_TICK_LOC = get_args(_TYPE_BAR.__annotations__["tick_loc"])
 _VALID_BAR_MINOR_TYPE = get_args(_TYPE_BAR.__annotations__["minor_type"]) 
 
 _VALIDATE_BAR = {
-    "projection":{"func":vf._validate_projection}, # must be a valid CRS
+    "projection":{"func":vf._validate_projection, "kwargs":{"none_ok":False}}, # must be a valid CRS
     "unit":{"func":vf._validate_list, "kwargs":{"list":list(units_standard.keys()), "none_ok":True}}, # any of the listed unit values are accepted
     "rotation":{"func":vf._validate_range, "kwargs":{"min":-360, "max":360, "none_ok":True}}, # between -360 and 360 degrees
     "max":{"func":vf._validate_range, "kwargs":{"min":0, "max":None, "none_ok":True}}, # between 0 and inf