Merge pull request #54 from GNS-Science/feature/53-odds-and-ends

changed location imports; improved documentation

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.8.2
+current_version = 0.8.3
 commit = True
 tag = True
 

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
+ - import `location.location` functions into base package init for ease of use
+
+### Fixed
+ - docstring for function `nzshm_common.location.location_by_id`
+
 ## [0.8.2] - 2024-09-21
 ### Added
  - within_polygon helper function

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

@@ -1,8 +1,7 @@
 __author__ = "GNS Science"
 __email__ = '[email protected]'
-__version__ = '0.8.2'
+__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 +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, 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
@@ -83,7 +73,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

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 <[email protected]>"]

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