From 9b58e421592f740eee66718eeae82f81e3dad299 Mon Sep 17 00:00:00 2001 From: chrisdicaprio Date: Tue, 19 Nov 2024 13:50:16 +1300 Subject: [PATCH] rationalize import of location functions to package level, update documentation --- docs/api/location/index.md | 3 +++ mkdocs.yml | 1 + nzshm_common/__init__.py | 1 - nzshm_common/location/__init__.py | 28 +++++++++++++++++++++++++++- nzshm_common/location/location.py | 16 +++------------- tests/test_location.py | 4 ++-- 6 files changed, 36 insertions(+), 17 deletions(-) create mode 100644 docs/api/location/index.md diff --git a/docs/api/location/index.md b/docs/api/location/index.md new file mode 100644 index 0000000..ffc357c --- /dev/null +++ b/docs/api/location/index.md @@ -0,0 +1,3 @@ +::: nzshm_common.location + options: + filters: ["!^_"] \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 77c9e15..681921d 100644 --- a/mkdocs.yml +++ b/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 diff --git a/nzshm_common/__init__.py b/nzshm_common/__init__.py index ccd2d3f..1440949 100644 --- a/nzshm_common/__init__.py +++ b/nzshm_common/__init__.py @@ -2,7 +2,6 @@ __email__ = 'nshm@gns.cri.nz' __version__ = '0.8.3' -from .location import location # Common classes at the top level for convenience from .location.coded_location import CodedLocation, CodedLocationBin diff --git a/nzshm_common/location/__init__.py b/nzshm_common/location/__init__.py index 860d82c..c0a69cc 100644 --- a/nzshm_common/location/__init__.py +++ b/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 diff --git a/nzshm_common/location/location.py b/nzshm_common/location/location.py index a69433a..39e13a3 100644 --- a/nzshm_common/location/location.py +++ b/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 diff --git a/tests/test_location.py b/tests/test_location.py index e46119c..4e2fe9c 100644 --- a/tests/test_location.py +++ b/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"