rationalize import of location functions to package level, update doc…

…umentation

docs/api/location/index.md

@@ -0,0 +1,3 @@
+::: nzshm_common.location
+    options:
+        filters: ["!^_"]

mkdocs.yml

@@ -16,6 +16,7 @@ nav:
     - grids (package):
       - region_grid (module): api/grids/region_grid.md
     - location (package):
+      - api/location/index.md
       - coded_location (module): api/location/coded_location.md
       - location (module): api/location/location.md
       - types (module): api/location/types.md

nzshm_common/__init__.py

@@ -2,7 +2,6 @@
 __email__ = '[email protected]'
 __version__ = '0.8.3'
 
-from .location import location
 
 # Common classes at the top level for convenience
 from .location.coded_location import CodedLocation, CodedLocationBin

nzshm_common/location/__init__.py

@@ -1,2 +1,28 @@
+"""
+This package provides classes and functions to handle geographical locations. There are a number of
+pre-set locations of interest to the NZ NSHM made availabe in this package. They can be accessed via
+the "location lists." See examples below.
+
+Classes:
+ CodedLocation: a location defined by a latitude, longitude pair at a given resolution
+ CodedLocationBin: a collection of CodedLocations bined at a given resolution (genrally lower than
+ the resolution of the CodedLocations themselves)
+
+Functions:
+ get_location_list_names: get the names of the "location lists" which are lists of pre-set locations
+ get_location_list: get all locations from one or more location lists as CodedLocations
+ commonly used in the analysis of the NZ NSHM.
+ get_locations: convert a variety of location identifiers into an iterable of CodedLocations
+ location_by_id: get information about a particular location in any of the "location lists"
+
+Example:
+    ```py
+    >>> all_locations = get_location_list(get_location_list_names())
+    >>> nz_cities = get_location_list(["NZ"])
+    >>> wellington = location_by_id("WLG")
+    >>> locs = get_locations(["WLG", "CHC"])
+    ```
+"""
+
 from .coded_location import CodedLocation, CodedLocationBin
-from .location import get_location_list, get_location_list_names, get_locations, lat_lon_by_id, location_by_id
+from .location import get_location_list, get_location_list_names, get_locations, location_by_id

nzshm_common/location/location.py

@@ -1,15 +1,5 @@
 """
 This module contains constants and functions for referring to location or list of locations by an identifier.
-
-Constants:
-    LOCATION_LISTS - a dictionary of location lists
-
-Examples:
-    >>> from nzhsm_common.location.location import LOCATION_LISTS, location_by_id
-    >>> LOCATION_LISTS["NZ"]["locations"][0]
-    'AKL'
-    >>> location_by_id(LOCATION_LISTS["NZ"]["locations"][0])
-    {'id': 'AKL', 'name': 'Auckland', 'latitude': -36.87, 'longitude': 174.77}
 """
 
 import csv
@@ -63,7 +53,7 @@
 }
 
 
-def lat_lon_by_id(_id) -> Optional[LatLon]:
+def _lat_lon(_id) -> Optional[LatLon]:
     loc = location_by_id(_id)
     if loc:
         return LatLon(loc['latitude'], loc['longitude'])
@@ -125,10 +115,10 @@ def get_locations(locations: Iterable[str], resolution: float = DEFAULT_RESOLUTI
             lat, lon = location_id.split('~')
             coded_locations.append(CodedLocation(float(lat), float(lon), resolution))
         elif location_by_id(location_id):
-            coded_locations.append(CodedLocation(*lat_lon_by_id(location_id), resolution))  # type: ignore
+            coded_locations.append(CodedLocation(*_lat_lon(location_id), resolution))  # type: ignore
         elif LOCATION_LISTS.get(location_id):
             location_ids = LOCATION_LISTS[location_id]["locations"]
-            coded_locations += [CodedLocation(*lat_lon_by_id(_id), resolution) for _id in location_ids]  # type: ignore
+            coded_locations += [CodedLocation(*_lat_lon(_id), resolution) for _id in location_ids]  # type: ignore
         else:
             try:
                 coded_locations += [CodedLocation(*loc, resolution) for loc in load_grid(location_id)]  # type: ignore

tests/test_location.py

@@ -1,4 +1,4 @@
-from nzshm_common import location
+from nzshm_common.location import location
 from nzshm_common.location.coded_location import CodedLocation
 
 
@@ -53,4 +53,4 @@ def get_lat_lon(id):
 
 
 def test_missing_lat_lon_returns_None():
-    assert location.lat_lon_by_id("missingid") is None, "An unknown ID should return a None"
+    assert location._lat_lon("missingid") is None, "An unknown ID should return a None"