docstring for Portal

dcicutils/portal_utils.py

@@ -17,7 +17,22 @@
 
 
 class Portal:
-
+    """
+    This is meant to be an uber wrapper for Portal access. It can be created in a variety of ways:
+    1. From a (Portal) .ini file (e.g. development.ini)
+    2. From a key dictionary, containing "key" and "secret" property values.
+    3. From a key tuple, containing (in order) a key and secret values.
+    4. From a keys file assumed to reside in ~/.{app}-keys.json where the given "app" value is either "smaht", "cgap",
+       or "fourfront"; and where this file is assumed to contain a dictionary with a key equal to the given "env"
+       value (e.g. smaht-localhost) and with a dictionary value containing "key" and "secret" property values; if
+       an "app" value is not specified but the given "env" value begins with one of the app values then that value
+       will be used, i.e. e.g. if env is "smaht-localhost" and app is unspecified than it is assumed to be "smaht".
+    5. From a keys file as described above (#4) but rather than be identified by the given "env" value it
+       is looked up by the given "server" name and the "server" key dictionary value in the key file.
+    6. From a given "vapp" value (which is assumed to be a TestApp or VirtualApp).
+    7. From another Portal object.
+    8. From a a pyramid Router object.
+    """
     def __init__(self,
                  arg: Optional[Union[VirtualApp, TestApp, Router, Portal, dict, tuple, str]] = None,
                  env: Optional[str] = None, app: Optional[OrchestratedApp] = None, server: Optional[str] = None,