Add resource tool

Makefile.am

@@ -307,6 +307,8 @@ $(prefix)/src:
 	@chmod -R 775 $(prefix)/src
 
 index: weather library template
+	@echo Updating file index...
+	@git ls-files | grep -v '^\.' | grep -v '/\.' > index
 
 html-local: module-html developer-html troubleshooting-html
 	@mkdir -p $(prefix)/share/doc/developer

docs/Tools/Framework.md

@@ -22,15 +22,12 @@ Example:
 ~~~
 import framework as app
 
-def main(argv):
+def main(argv:list[str]) -> int:
 
     # 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
+        app.syntax(__doc__)
 
     # handle stardard app arguments --debug, --warning, --verbose, --quiet, --silent
     args = app.read_stdargs(argv)
@@ -40,45 +37,30 @@ def main(argv):
         if key in ["-h","--help","help"]:
             print(__doc__,file=sys.stdout)
 
-        # TODO: add options here
+        # add your options here
 
         else:
-            error(f"'{key}={value}' is invalid")
+
+            app.error(f"'{key}={value}' is invalid")
             return app.E_INVALID
 
-    # TODO: code implementation here, if any
+    # implement your code here
 
+    # normal termination condigion
     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)
-
-    except KeyboardInterrupt:
-
-        exit(app.E_INTERRUPT)
-
-    except Exception as exc:
+    app.run(main)
+~~~
 
-        if app.DEBUG:
-            raise exc
 
-        if not app.QUIET:
-            e_type,e_value,e_trace = sys.exc_info()
-            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)
-~~~
+# Classes
 
+## ApplicationError
 
+Application exception
 
 # Functions
 
@@ -148,6 +130,10 @@ Arguments:
 
 Messages are suppressed when the `--quiet` option is used.
 
+If `--debug` is enabled, an exception is raised with a traceback.
+
+If the exit `code` is specified, exit is called with the code.
+
 
 ---
 
@@ -159,6 +145,8 @@ Arguments:
 
 * `exc`: exception to raise
 
+If `exc` is a string, an `ApplicationError` exception is raised.
+
 
 ---
 
@@ -172,6 +160,8 @@ Arguments:
 
 * `bin`: enable direct call to gridlabd binary (bypasses shell and faster)
 
+* `output_to`: run postprocessor on output to stdout
+
 * `kwargs`: options to pass to `subpocess.run`
 
 Returns:
@@ -249,6 +239,38 @@ Returns:
 * Remaining arguments
 
 
+---
+
+## `run() -> None`
+
+Run a main function under this app framework
+
+Arguments:
+
+* `main`: the main function to run
+
+* `exit`: the exit function to call (default is `exit`)
+
+* `print`: the print funtion to call on exceptions (default is `print`)
+
+This function does not return. When the app is done it calls exit.
+
+
+---
+
+## `syntax() -> None`
+
+Print syntax message
+
+Arguments:
+
+* `docs`: the application's __doc__ string
+
+* `print`: the print function to use (default is `print`)
+
+This function does not return. When the function is done it calls exit(E_SYNTAX)
+
+
 ---
 
 ## `verbose() -> None`

docs/Tools/Makefile.mk

@@ -4,4 +4,5 @@ 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/Resource.md
 DOCS_UTILITIES += docs/Tools/Unitcalc.md

docs/Tools/Mapping.md

@@ -58,6 +58,12 @@ See also:
 
 # Classes
 
+## ApplicationError
+
+Application exception
+
+---
+
 ## Map
 
 Mapping class
@@ -244,6 +250,10 @@ Arguments:
 
 Messages are suppressed when the `--quiet` option is used.
 
+If `--debug` is enabled, an exception is raised with a traceback.
+
+If the exit `code` is specified, exit is called with the code.
+
 
 ---
 
@@ -255,6 +265,8 @@ Arguments:
 
 * `exc`: exception to raise
 
+If `exc` is a string, an `ApplicationError` exception is raised.
+
 
 ---
 
@@ -285,6 +297,8 @@ Arguments:
 
 * `bin`: enable direct call to gridlabd binary (bypasses shell and faster)
 
+* `output_to`: run postprocessor on output to stdout
+
 * `kwargs`: options to pass to `subpocess.run`
 
 Returns:
@@ -377,6 +391,38 @@ Returns:
 * Remaining arguments
 
 
+---
+
+## `run() -> None`
+
+Run a main function under this app framework
+
+Arguments:
+
+* `main`: the main function to run
+
+* `exit`: the exit function to call (default is `exit`)
+
+* `print`: the print funtion to call on exceptions (default is `print`)
+
+This function does not return. When the app is done it calls exit.
+
+
+---
+
+## `syntax() -> None`
+
+Print syntax message
+
+Arguments:
+
+* `docs`: the application's __doc__ string
+
+* `print`: the print function to use (default is `print`)
+
+This function does not return. When the function is done it calls exit(E_SYNTAX)
+
+
 ---
 
 ## `verbose() -> None`

docs/Tools/Resource.md

@@ -0,0 +1,140 @@
+[[/Tools/Resource]] -- Online resource accessor
+
+Syntax: `gridlabd resource [OPTIONS ...]`
+
+Options:
+
+* `--content=RESOURCE,INDEX`: download RESOURCE located at INDEX
+
+* `--debug`: enable traceback on exceptions
+
+* `-h|--help|help`: get this help
+
+* `--format=[raw|csv|json]`: output format
+
+* `--index=RESOURCE`: get index for RESOURCE
+
+* `--list[=FORMAT[,OPTIONS[,...]]`: list the available resources
+
+* `--quiet`: suppress error output
+
+* `--properties=RESOURCE`: get a list of resource properties
+
+* `--silent`: suppress all output exception results
+
+* `--test[=PATTERN]`: test resources matching pattern (default is '.*')
+
+* `--verbose`: enable verbose output
+
+* `--warning`: disable warning output
+
+Description:
+
+The online resource accessor delivers online resources to GridLAB-D applications.
+
+Valid formats include `json` and `csv` (the default is 'raw').
+
+Examples:
+
+The following command lists the released versions
+
+    gridlabd resource --index=version
+
+The following command lists the properties on the online weather resources
+
+    gridlabd resource --properties=weather
+
+The following command retrieves the online weather data for the specified location
+
+    gridlabd resource --content=weather,WA-Seattle_Seattletacoma_Intl_A.tmy3
+
+
+
+# Classes
+
+## Resource
+
+Resource class
+
+### `Resource()`
+
+Construct resource object
+
+Arguments:
+
+* `file`: resource file (default is $GLD_ETC/resource.csv)
+
+
+### `Resource.content(kwargs:dict) -> str`
+
+Get resource content
+
+Arguments:
+
+* `**kwargs`: options (see `properties()`)
+
+Returns:
+
+* Resource contents
+
+
+### `Resource.headers(kwargs:dict) -> Union`
+
+Get resource header
+
+
+
+### `Resource.index(kwargs:dict) -> Union`
+
+Get resource index (if any)
+
+
+
+### `Resource.list(pattern:str) -> list`
+
+Get a list of available resources
+
+Argument
+
+
+### `Resource.properties(passthru:str, kwargs:dict) -> dict`
+
+Get resource properties
+
+
+
+---
+
+## ResourceError
+
+Resource exception
+
+# Functions
+
+## `main() -> int`
+
+Resource tool main routine
+
+Arguments:
+
+* `argv`: command line arguments
+
+Returns:
+
+* Exit code
+
+
+---
+
+## `test() -> None`
+
+Run tests on resources that match the specified pattern
+
+Arguments:
+
+* `pattern`: the resource name as a regular expression
+
+Returns:
+
+* Exit code: E_OK on success, E_FAILED on failure
+

docs/makemd.py

@@ -19,7 +19,7 @@
 E_SYNTAX = 3
 E_EXCEPTION = 9
 
-IGNORE = ['TypeVar']
+IGNORE = ['TypeVar','Union']
 
 class MakemdError(Exception):
     def __init__(self,msg,exitcode=None):
@@ -48,7 +48,7 @@ def __init__(self,msg,exitcode=None):
         # output classes
         first = True
         for item in [getattr(module,x) for x in dir(module) if inspect.isclass(getattr(module,x))]:
-            if not item.__doc__ or item.__name__ in IGNORE:
+            if not item.__doc__ or item.__name__ in IGNORE or isinstance(item,type(os)):
                 continue
             if first:
                 print("\n# Classes",file=md)