Add location tool

docs/Tools/Framework.md

@@ -3,36 +3,61 @@
 The `framework` module contains the infrastructure to support standardized
 implementation of tools in GridLAB-D.
 
+Standard options:
+
+The following options are processed by `read_stdargs()`:
+
+* `--debug`: enable debug traceback on exception
+
+* `--quiet`: suppress error messages
+
+* `--silent`: suppress all error messages
+
+* `--warning`: suppress warning messages
+
+* `--verbose`: enable verbose output, if any
+
 Example:
 
 ~~~
 import framework as app
 
 def main(argv):
 
+    # handle no options case -- typically a cry for help
     if len(argv) == 1:
 
         print("
 ".join([x for x in __doc__.split("
 ") if x.startswith("Syntax: ")]))
         return app.E_SYNTAX
 
-    args = read_stdargs(argv)
+    # handle stardard app arguments --debug, --warning, --verbose, --quiet, --silent
+    args = app.read_stdargs(argv)
 
     for key,value in args:
 
         if key in ["-h","--help","help"]:
             print(__doc__,file=sys.stdout)
+
+        # TODO: add options here
+
         else:
             error(f"'{key}={value}' is invalid")
             return app.E_INVALID
 
+    # TODO: code implementation here, if any
+
     return app.E_OK
 
 if __name__ == "__main__":
 
     try:
 
+        # TODO: development testing -- delete when done writing code
+        if not sys.argv[0]:
+            sys.argv = ["selftest","--debug"]
+
         rc = main(sys.argv)
         exit(rc)
 
@@ -42,12 +67,12 @@ if __name__ == "__main__":
 
     except Exception as exc:
 
-        if DEBUG:
+        if app.DEBUG:
             raise exc
 
-        if not QUIET:
+        if not app.QUIET:
             e_type,e_value,e_trace = sys.exc_info()
-            tb = traceback.TracebackException(e_type,e_value,e_trace).stack[1]
+            tb = app.traceback.TracebackException(e_type,e_value,e_trace).stack[1]
             print(f"EXCEPTION [{app.EXEFILE}@{tb.lineno}]: ({e_type.__name__}) {e_value}",file=sys.stderr)
 
         exit(app.E_EXCEPTION)
@@ -81,6 +106,21 @@ Returns:
 * `complex`: complex value (if form is 'conjugate' or None)
 
 
+---
+
+## `debug() -> None`
+
+Debugging message output
+
+Arguments:
+
+* `msg`: message to output
+
+* `**kwargs`: print options
+
+Messages are enabled when the `--debug` option is used.
+
+
 ---
 
 ## `double_unit() -> float`
@@ -94,6 +134,32 @@ Returns:
 * real value
 
 
+---
+
+## `error() -> None`
+
+Error message output
+
+Arguments:
+
+* `msg`: message to output
+
+* `**kwargs`: print options
+
+Messages are suppressed when the `--quiet` option is used.
+
+
+---
+
+## `exception() -> None`
+
+Exception message output
+
+Arguments:
+
+* `exc`: exception to raise
+
+
 ---
 
 ## `gridlabd() -> Optional`
@@ -153,6 +219,21 @@ Return:
 * File handle to JSON file after conversion from GLM
 
 
+---
+
+## `output() -> None`
+
+General message output
+
+Arguments:
+
+* `msg`: message to output
+
+* `**kwargs`: print options
+
+Messages are suppressed when the `--silent` option is used.
+
+
 ---
 
 ## `read_stdargs() -> list`
@@ -168,6 +249,21 @@ Returns:
 * Remaining arguments
 
 
+---
+
+## `verbose() -> None`
+
+Verbose message output
+
+Arguments:
+
+* `msg`: message to output
+
+* `**kwargs`: print options
+
+Messages are enabled when the `--verbose` option is used.
+
+
 ---
 
 ## `version() -> str`
@@ -178,3 +274,18 @@ Returns:
 
 * GridLAB-D version info
 
+
+---
+
+## `warning() -> None`
+
+Warning message output
+
+Arguments:
+
+* `msg`: message to output
+
+* `**kwargs`: print options
+
+Messages are suppress when the `--warning` option is used.
+

docs/Tools/Location.md

@@ -0,0 +1,180 @@
+[[/Tools/Location]] -- Location tool
+
+Syntax: `gridlabd location [OPTIONS ...] [FILENAME=KEY[:VALUE][,...] ...]`
+
+Options:
+
+* `--debug`: enable debug traceback on exception
+
+* `--find[=KEY[:VALUE][,...]]`: get location settings
+
+* `--format=FORMAT[,OPTION[:VALUE[,...]]]
+
+* `--quiet`: suppress error messages
+
+* `--silent`: suppress all error messages
+
+* `--system[=KEY[:VALUE][,...]]`: get/set the default location
+
+* `--verbose`: enable verbose output, if any
+
+* `--warning`: suppress warning messages
+
+Description:
+
+The `location` tool allows configuration of the location of a model.
+
+The `location` tool `--system` option is used to setup the system's default
+location for models when not location data is not specified in the model.
+When values are change, the location data is returned and the new location
+is stored in `GLD_ETC/location_config.glm
+
+The `location` tool `--find` options can identify the current location of a
+system or a location based on partial information.
+
+Location setting on `FILENAME` will be performed in place, i.e., the file will
+first be read and the it will be written with the new values. The result
+output to stdout will be the previous values.
+
+The keys and globals handled by the `location` tools include the following:
+
+* `latitude`: the location's latitude
+
+* `longitude`: the location's longitude
+
+* `zipcode`: the location's postal code
+
+* `city`: the location's city
+
+* `county`: the location's county
+
+* `state`: the location's state
+
+* `region`: the location's region
+
+* `country`: the location's country
+
+Caveat:
+
+Although the `--find` option allows multiple addresses to be resolved, it is
+certainly not efficient to do more than a few queries this way. If you need
+to resolve large number of addresses then you should use the batch feature of
+the `geocoder` module.
+
+Examples:
+
+Get the current location
+
+    gridlabd location --find
+
+Display the default location
+
+    gridlabd location --system
+
+Set the location in a model file
+
+    gridlabd location ieee123.json=country:US,state:CA,county:Kern,city:Bakersfield
+
+
+
+
+# Classes
+
+## LocationError
+
+Location exception
+
+# Functions
+
+## `find() -> dict`
+
+Find location data
+
+Arguments:
+
+* `kwargs`: Partial location data (see `system()`). None return IP location.
+
+Returns:
+
+* Location data
+
+
+---
+
+## `get_location() -> dict`
+
+Get location data in file
+
+Arguments:
+
+* `file`: file from which to get location data
+
+Returns:
+
+* Current values
+
+
+---
+
+## `main() -> int`
+
+Main location routine
+
+Arguments:
+
+* `argv`: command line argument list
+
+Returns:
+
+* Exit code
+
+
+---
+
+## `set_location() -> dict`
+
+Set location in file
+
+Arguments:
+
+* `file`: file in which to set location data
+
+* `**kwargs`: location data
+
+Returns:
+
+* Previous values
+
+
+---
+
+## `system() -> dict`
+
+Get/set system location settings
+
+Arguments:
+
+* `latitude`: new latitude
+
+* `longitude`: new longitude
+
+* `number`: new street number
+
+* `street`: new street name
+
+* `zipcode`: new zipcode
+
+* `city`: new city
+
+* `county`: new county
+
+* `state`: new state
+
+* `region`: new region
+
+* `country`: new country
+
+Returns:
+
+* previous location settings
+

docs/Tools/Makefile.mk

@@ -1,6 +1,7 @@
 DOCS_UTILITIES += docs/Tools/Framework.md
 DOCS_UTILITIES += docs/Tools/Network.md
 DOCS_UTILITIES += docs/Tools/Edit.md
+DOCS_UTILITIES += docs/Tools/Location.md
 DOCS_UTILITIES += docs/Tools/Mapping.md
 DOCS_UTILITIES += docs/Tools/Moutils.md
 DOCS_UTILITIES += docs/Tools/Unitcalc.md