DOC: describe configuration

examples/pycaosdb.ini

@@ -4,34 +4,57 @@
 # - the location given in the env variable PYCAOSDBINI
 
 [Connection]
-url=https://demo.indiscale.com/
-
-## For local installations, enter your server address and SSL certificate here.
+# URL of the CaosDB server
+# url=https://demo.indiscale.com/
+# For local installations this typically is
 # url=https://localhost:10443/
-# cacert=/path/to/caosdb.ca.pem
-
-## If this option is set, the SSL certificate will be ignored.  Use with care!
-# ssl_insecure=1
 
-username=admin
-
-## 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`, with this method the password must
-## be saved as plain text.
+# User name used for authentication with the server
+# username=admin
+
+# The password input method defines how the password is supplied that is used
+# for authentication with the server.
+#
+# DEFAULT: `input` 
+# The username is optional in this case.  The password is entered directly by the user.
+# password_method=input
+#
+# OR: `plain` 
+# This implies that the password must # be saved as plain text in a 
+# configuration under the 'password' key.
 # password_method=plain
 # password=caosdb
+#
+# OR `pass`
+# The password is retrieved from the "pass" password manager
+# This password manager uses identifiers to distinguish passwords. Supply this
+# identifier under the key 'password_identifier'.
+# password_method=pass
+# password_identifier=caosdb_password
+#
+# OR: `keyring` 
+# Using the system keyring/wallet (macOS, GNOME, KDE, Windows)
+# requires installation of the keyring python package (pip install keyring).
+# password_method=keyring
 
-## OR: `input`: username is optional, password is entered directly by the user.
-## The default password for the demo server is `caosdb`.
-password_method=input
+# Using an authentication token to connect with the server. This setting is
+# not recommended for users.
+# auth_token=TOKEN
 
-## OR: `pass`: password is retrieved from the "pass" password manager
-# password_method=pass
-# password_identifier=...
+# If the server's SSL certificate cannot be validated by your installed 
+# certificates (default or installed by your admins), you may also need to 
+# supply the matching key (pem file):
+# cacert=/path/to/caosdb.ca.pem
 
-## OR: `keyring`: using the system keyring/wallet (macOS, GNOME, KDE, Windows)
-## requires installation of the keyring python package:
-## pip install keyring
-# password_method=keyring
+# If this option is set, the SSL certificate will be ignored.  Use with care!
+# ssl_insecure=True
+
+# You may define the ssl version to be used. It has to be the name of the 
+# corresponding attribute in the Python ssl module.
+# ssl_version=PROTOCOL_TLS
+
+# You can define a socket proxy to be used.
+# socket_proxy=
+
+# You can define the connection implementation to be used.
+# implementation

src/caosdb/connection/connection.py

@@ -246,7 +246,7 @@ def _make_conf(*conf):
 
 
 _DEFAULT_CONF = {
-    "password_method": "plain",
+    "password_method": "input",
     "implementation": _DefaultCaosDBServerConnection,
     "timeout": 210,
     "cacert": resource_filename("caosdb", 'cert/indiscale.ca.crt')

src/doc/configuration.md

 # Configuration of pycaosdb #
-
-The behavior of pycaosdb is defined via the [configuration](https://caosdb.gitlab.io/caosdb-pylib/_apidoc/caosdb.html#module-caosdb.configuration) module, initial values are taken from
-the configuration files.
-
+The behavior of pycaosdb is defined via a configuration that is provided using configuration files.
 Pycaosdb tries to read from the inifile specified in the environment variable `PYCAOSDBINI` or
 alternatively in `~/.pycaosdb.ini` upon import.  After that, the ini file `pycaosdb.ini` in the
 current working directory will be read additionally, if it exists.
@@ -14,9 +11,9 @@ can be changed by setting `password_method`:
 
 * with `password_method=input` password (and possibly user) will be queried on demand (**default**)
 * use the password manager [pass](https://www.passwordstore.org) by using `pass` as value, see also the [ArchWiki
-  entry](https://wiki.archlinux.org/index.php/Pass#Basic_usage). This also requires ```password_identifier``` which refers to the identifier within pass
+  entry](https://wiki.archlinux.org/index.php/Pass#Basic_usage). This also requires `password_identifier` which refers to the identifier within pass
   for the desired password.
-* install the python package [keyring](https://pypi.org/project/keyring), to use the system keychain/wallet (macOS, GNOME, KDE,
+* install the python package [keyring](https://pypi.org/project/keyring), to use the system keyring/wallet (macOS, GNOME, KDE,
   Windows). The password will be queried on first usage.
 * with `password_method=plain` (**strongly discouraged**)
 
@@ -50,4 +47,8 @@ cacert=/path/to/caosdb.ca.pem
 `debug=0` ensures that debug information is **not** printed to the terminal every time you interact
 with CaosDB which makes the experience much less verbose. Set it to 1 or 2 in case you want to help
 debugging (which I hope will not be necessary for this tutorial) or if you want to learn more about
-the internals of the procotol
+the internals of the protocol. 
+
+A complete list of options can be found in the 
+[pycaosdb.ini file](https://gitlab.com/caosdb/caosdb-pylib/-/blob/master/examples/pycaosdb.ini) in 
+the examples folder of the source code.