DOC: Better documentation of the `input` password method.

examples/pycaosdb.ini

@@ -6,17 +6,28 @@
 [Connection]
 cacert=/path/to/caosdb.ca.pem
 url=https://localhost:10443/
+
+## If this option is set, the SSL certtificate will be ignored.  Use with care!
+# ssl_insecure=1
+
 username=admin
 
-## optional: password in plain text
+## The password input method can be chosen with the `password_method` setting,
+## which by default is set to `plain`.
+##
+## DEFAULT: the password method is `plain`, now the password must be saved as
+## plain text.
 password_method=plain
 password=caosdb
 
-## OR: password using "pass" password manager
+## OR: `input`: username is optional, password is entered by the user directly
+# password_method=input
+
+## OR: `pass`: password is retrieved from the "pass" password manager
 # password_method=pass
 # password_identifier=...
 
-## OR: using the system keyring/wallet (macOS, GNOME, KDE, Windows)
+## OR: `keyring`: using the system keyring/wallet (macOS, GNOME, KDE, Windows)
 ## requires installation of the keyring python package:
 ## pip install keyring
 # password_method=keyring

src/caosdb/connection/connection.py

@@ -167,7 +167,10 @@ class _DefaultCaosDBServerConnection(CaosDBServerConnection):
         context.verify_mode = ssl.CERT_REQUIRED
 
         if config.get("ssl_insecure"):
-            print("Relaxed SSL mode.")
+            print("*** Warning! ***\n"
+                  "Insecure SSL mode, certificate will not be checked! "
+                  "Please consider removing the `ssl_insecure` configuration option.\n"
+                  "****************")
             context.verify_mode = ssl.CERT_NONE
 
         if (not context.verify_mode == ssl.CERT_NONE and
@@ -281,7 +284,7 @@ def _get_authenticator(**config):
 
 
 def configure_connection(**kwargs):
-    """Configures the caosdb connection and return the Connection object.
+    """Configures the caosdb connection and returns the Connection object.
 
     The effective configuration is governed by the default values (see
     'Parameters'), the global configuration (see `caosdb.get_config()`) and the
@@ -296,12 +299,23 @@ def configure_connection(**kwargs):
     implementation : CaosDBServerConnection
         The class which implements the connection. (Default:
         _DefaultCaosDBServerConnection)
+
     password_method : str
         The name of a submodule of caosdb.connection.authentication which
         implements the AbstractAuthenticator interface. (Default: 'plain')
+        Possible values are, for example:
+        - "plain"    Need username and password arguments.
+        - "input"    Asks for the password.
+        - "pass"     Uses the `pass` password manager.
+        - "keyring"  Uses the `keyring` library.
+
     timeout : int
         A connection timeout in seconds. (Default: 210)
 
+    ssl_insecure : bool
+        Whether SSL certificate warnings should be ignored. Only use this for
+        development purposes! (Default: False)
+
     Returns
     -------
     _Connection