From a109b145e8f02dbc007eba59a7a36ccd1dee5835 Mon Sep 17 00:00:00 2001 From: chrisdicaprio Date: Wed, 9 Oct 2024 12:00:04 +1300 Subject: [PATCH 1/6] change name of lat lon function; fix error in docstring --- nzshm_common/location/location.py | 8 ++++---- tests/test_location.py | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/nzshm_common/location/location.py b/nzshm_common/location/location.py index 35c48bc..a69433a 100644 --- a/nzshm_common/location/location.py +++ b/nzshm_common/location/location.py @@ -63,7 +63,7 @@ } -def _lat_lon(_id) -> Optional[LatLon]: +def lat_lon_by_id(_id) -> Optional[LatLon]: loc = location_by_id(_id) if loc: return LatLon(loc['latitude'], loc['longitude']) @@ -83,7 +83,7 @@ def _load_csv(locations_filepath, resolution): def location_by_id(location_code: str) -> Optional[Dict[str, Any]]: """ - Get the CodedLocation for a location identified by an id. + Get the information for a location identified by an id. Parameters: location_code: the code (e.g. "WLG") for the location @@ -125,10 +125,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(location_id), resolution)) # type: ignore + coded_locations.append(CodedLocation(*lat_lon_by_id(location_id), resolution)) # type: ignore elif LOCATION_LISTS.get(location_id): location_ids = LOCATION_LISTS[location_id]["locations"] - coded_locations += [CodedLocation(*_lat_lon(_id), resolution) for _id in location_ids] # type: ignore + coded_locations += [CodedLocation(*lat_lon_by_id(_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 5314f34..e46119c 100644 --- a/tests/test_location.py +++ b/tests/test_location.py @@ -53,4 +53,4 @@ def get_lat_lon(id): def test_missing_lat_lon_returns_None(): - assert location._lat_lon("missingid") is None, "An unknown ID should return a None" + assert location.lat_lon_by_id("missingid") is None, "An unknown ID should return a None" From 4ac203d217ca1f5d750e476621ec5331a64a15a8 Mon Sep 17 00:00:00 2001 From: chrisdicaprio Date: Wed, 9 Oct 2024 12:02:43 +1300 Subject: [PATCH 2/6] update changelog --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 78f4735..c156165 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.8.3] - 2024-10-09 + +### Changed + - name of function in `nzshm_common.location` from `_lat_lon` to `lat_lon_by_id` + +### Fixed + - docstring for function `nzshm_common.location.location_by_id` + ## [0.8.2] - 2024-09-21 ### Added - within_polygon helper function From e789c157665ead8d421492986e4b74c03032fbb5 Mon Sep 17 00:00:00 2001 From: chrisdicaprio Date: Wed, 9 Oct 2024 12:02:55 +1300 Subject: [PATCH 3/6] =?UTF-8?q?Bump=20version:=200.8.2=20=E2=86=92=200.8.3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .bumpversion.cfg | 2 +- nzshm_common/__init__.py | 2 +- pyproject.toml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.bumpversion.cfg b/.bumpversion.cfg index 58e98b7..9e7ff9b 100644 --- a/.bumpversion.cfg +++ b/.bumpversion.cfg @@ -1,5 +1,5 @@ [bumpversion] -current_version = 0.8.2 +current_version = 0.8.3 commit = True tag = True diff --git a/nzshm_common/__init__.py b/nzshm_common/__init__.py index 780ff2f..ccd2d3f 100644 --- a/nzshm_common/__init__.py +++ b/nzshm_common/__init__.py @@ -1,6 +1,6 @@ __author__ = "GNS Science" __email__ = 'nshm@gns.cri.nz' -__version__ = '0.8.2' +__version__ = '0.8.3' from .location import location diff --git a/pyproject.toml b/pyproject.toml index 476d8cc..bdf7937 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "nzshm-common" -version = "0.8.2" +version = "0.8.3" homepage = "https://github.com/GNS-Science/nzshm-common-py" description = "A small pure python library for shared NZ NSHM data like locations." authors = ["GNS Science "] From c32c13fe3ac3ed7b3fad4de6dc1c41feae4bd57b Mon Sep 17 00:00:00 2001 From: chrisdicaprio Date: Tue, 19 Nov 2024 10:12:02 +1300 Subject: [PATCH 4/6] import location functions into package init --- CHANGELOG.md | 1 + nzshm_common/location/__init__.py | 1 + 2 files changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c156165..4709334 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - name of function in `nzshm_common.location` from `_lat_lon` to `lat_lon_by_id` + - import `location.location` functions into base package init for ease of use ### Fixed - docstring for function `nzshm_common.location.location_by_id` diff --git a/nzshm_common/location/__init__.py b/nzshm_common/location/__init__.py index 77f3d47..860d82c 100644 --- a/nzshm_common/location/__init__.py +++ b/nzshm_common/location/__init__.py @@ -1 +1,2 @@ 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 9b58e421592f740eee66718eeae82f81e3dad299 Mon Sep 17 00:00:00 2001 From: chrisdicaprio Date: Tue, 19 Nov 2024 13:50:16 +1300 Subject: [PATCH 5/6] 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" From 006a116a2dbeec26e0d165d4eaeb15e48c72b7f4 Mon Sep 17 00:00:00 2001 From: chrisdicaprio Date: Wed, 20 Nov 2024 11:07:07 +1300 Subject: [PATCH 6/6] fix chagnelog --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4709334..fce37bd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [0.8.3] - 2024-10-09 ### Changed - - name of function in `nzshm_common.location` from `_lat_lon` to `lat_lon_by_id` - import `location.location` functions into base package init for ease of use ### Fixed