SAM-147: black format all files

.gitignore

@@ -6,3 +6,4 @@ deploy.cfg
 .coverage
 test/test_temp/
 lib/SampleService/SampleServiceImpl.py.bak*
+kb-sdk

Makefile

@@ -21,20 +21,20 @@ default: compile
 
 all: compile build build-startup-script build-executable-script build-test-script
 
-compile:
+compile: 
 # Don't compile server automatically, overwrites fixes to error handling
 # Temporarily add the next line to the command line args if recompiliation is needed to add
 # methods.
 #		--pysrvname $(SERVICE_CAPS).$(SERVICE_CAPS)Server \
 
-	kb-sdk compile $(SPEC_FILE) \
+	@PATH=${PWD}:${PATH} kb-sdk compile $(SPEC_FILE) \
 		--out $(LIB_DIR) \
 		--pyclname $(SERVICE_CAPS).$(SERVICE_CAPS)Client \
 		--dynservver release \
 		--pyimplname $(SERVICE_CAPS).$(SERVICE_CAPS)Impl;
-	- rm $(LIB_DIR)/$(SERVICE_CAPS)Server.py
+	@- rm $(LIB_DIR)/$(SERVICE_CAPS)Server.py
 
-	kb-sdk compile $(SPEC_FILE) \
+	@PATH=${PWD}:${PATH} kb-sdk compile $(SPEC_FILE) \
 		--out . \
 		--html \
 
@@ -51,6 +51,13 @@ test-sdkless:
 clean:
 	rm -rfv $(LBIN_DIR)
 
+install-sdk: 
+	scripts/install-sdk.sh
+
+format:
+	black lib
+	black test
+
 # Managing development container orchestration
 
 host-start-dev-server:

RELEASE_NOTES.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+* Apply black to all python source in `lib` and `test`
 
 ## 0.2.1
 

SampleService.spec

@@ -339,8 +339,8 @@ module SampleService {
         The static metadata for a metadata key is metadata *about* the key - e.g. it may
         define the key's semantics or denote that the key is linked to an ontological ID.
 
-        The static metadata does not change without the service being restarted. Client caching is
-        recommended to improve performance.
+        The static metadata does not change without the service being restarted. 
+        Client caching is recommended to improve performance.
 
      */
     funcdef get_metadata_key_static_metadata(GetMetadataKeyStaticMetadataParams params)

docs/using-kb-sdk.md

@@ -0,0 +1,57 @@
+# Using `kb_sdk` with this repo
+
+The `sample_service` is based on the code layout and structure established by initializing and managing a codebase with the [KBase App SDK (`kb_sdk`)](https://github.com/kbase/kb_sdk).
+
+It does not adhere strictly to `kb_sdk` practices.
+
+This document describes, in a nutshell, current practice.
+
+> Note that the "KBase App SDK" is known, interchangeably, as `kb_sdk`, which is the name of the repo, and `kb-sdk`, which is the name of the command and the image.
+
+## Differences
+
+### Compilation
+
+This is a Python project, so there is no real code compilation. However, the "compile" command, as configured in the project's `Makefile` and implemented in `kb-sdk`, does more than compile a project which requires compilation. It also generates code.
+
+Typically, a `kb_sdk` service is maintained by updating the "spec file" (`SampleService.spec`) and then running `make compile`. This would:
+
+1. create core utility library files `lib/SampleService/authclient.py`, `lib/SampleService/baseclient.py`
+2. add, modify, or remove method stubs to `lib/SampleService/SampleServiceImpl.py`, depending on changes to the spec file
+3. create the main entrypoint `lib/SampleServiceServer.py`, overwriting the existing file if any
+4. create the spec documentation page `SampleService.html`, overwriting the existing file if any
+
+In this repo, (3) is omitted. See the `Makefile` for how this was done. The Server file needs to be maintained by hand.
+
+The main server entrypoint is `lib/SampleService/SampleServiceServer.py`, rather than `lib/SampleServiceServer.py`.
+
+### Testing
+
+Typically a `kb-sdk` project runs tests through `kb-sdk`, which manages invocation of the tests via a container using an image built from the project's `Dockerfile` and utilizes conventions for directories, configuration, etc.
+
+In this project, the limitations of that test environment preclude using that test framework.
+
+Rather, tests are run via `make test-sdkless`.
+
+## Using `kb-sdk`
+
+The `kb-sdk` command is made available through a docker container, which uses an image based on the latest release of `kb_sdk`.
+
+You can consult the [KBase SDK Docs](https://kbase.github.io/kb_sdk_docs/tutorial/2_install.html) for the official installation procedure, or follow these somewhat simpler and less intrusive instructions:
+
+- install `kb-sdk`:
+  - `make install-sdk`
+- following the instructions printed to the console, adjust the path in your shell:
+  - export PATH=$PWD:$PATH
+
+The typical workflow does not use `kb-sdk` directly.
+
+The primary current usage of `kb-sdk` in this project is compilation, as briefly described above.
+
+The following command:
+
+```sh
+make compile
+```
+
+will run the compilation.

docs/using-pipenv.md

@@ -38,6 +38,8 @@ This section describes how to get `pipenv` up and running on macOS. These instru
 
   `pipenv` will be installed by `pip` into `~/Library/Python/3.7/lib/python/site-packages` (module) and `~/Library/Python/3.7/bin` (executable).
 
+  It will be available to your host user account only.
+
 - ensure `pipenv` is runnable:
 
   If you look for `pipenv` from the command line, you'll find it is not found:
@@ -134,4 +136,4 @@ within the directory in which you ran `pipenv` previously.
 
   - Paste in the copied path and hit Return
 
-
+- You should have have a fully functioning Python development setup for VSC!