From f1c3a1523ca19c05865f0eb8ddae9a05999f7801 Mon Sep 17 00:00:00 2001 From: Tobias Brox Date: Fri, 18 Sep 2026 11:16:46 +0200 Subject: [PATCH] docs(config): document auth_type and other keys The config file page listed only six caldav_ keys and three CALDAV_ environment variables, so auth_type looked unsupported there even though it has been a connection parameter since 3.0. Both tables now carry it, and a note after each says that any other CONNKEYS parameter works the same way - with the two caveats a reader would otherwise hit: auth takes an object and so cannot come from a file, and environment variables are never type-converted, so CALDAV_REQUIRE_TLS=false sets the parameter to the true string "false". Prompt: is auth_type ('basic' vs 'digest' vs 'bearer') configurable today? As a parameter into get_davclient and/or into the configuration file? Followup-Prompt: What version did this go in? Please update the doc [= the config file format documentation] in a separate work-branch and create a draft PR. (...) Assisted-By: Claude Opus 5 --- docs/source/configfile.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/source/configfile.rst b/docs/source/configfile.rst index 464450f7..91d6b7d4 100644 --- a/docs/source/configfile.rst +++ b/docs/source/configfile.rst @@ -60,6 +60,20 @@ The most common ones are: * - ``caldav_ssl_verify_cert`` - ``ssl_verify_cert`` - ``false`` to skip TLS verification + * - ``caldav_auth_type`` + - ``auth_type`` + - ``basic``, ``digest`` or ``bearer``. Usually not needed, but saves a + round-trip to the server, and some servers need it to avoid an HTML + login page being served on the first request. For ``bearer``, the + token goes in ``caldav_password``. + +Any other parameter accepted by the :class:`~caldav.davclient.DAVClient` +constructor can be given the same way, as long as it is listed in +``caldav.config.CONNKEYS`` — currently also ``caldav_headers``, +``caldav_huge_tree``, ``caldav_ssl_cert``, ``caldav_enable_rfc6764`` and +``caldav_require_tls``. (``auth`` is in that list too, but it takes an +authentication object and can therefore only be passed from code, not from a +config file.) The special ``features`` key (not prefixed with ``caldav_``) names a server-compatibility profile — e.g. ``xandikos``, ``radicale``, ``baikal``. @@ -211,11 +225,21 @@ config file. The variables are mapped as follows: - ``username`` * - ``CALDAV_PASSWORD`` or ``CALDAV_PASS`` - ``password`` + * - ``CALDAV_AUTH_TYPE`` + - ``auth_type`` * - ``CALDAV_CONFIG_FILE`` - Path to config file * - ``CALDAV_CONFIG_SECTION`` - Section name (may be a glob) +``CALDAV_`` followed by the upper-cased name of any other connection +parameter works as well. Beware that environment variables are always +strings and are not converted, so the boolean-ish parameters +(``ssl_verify_cert``, ``huge_tree``, ``enable_rfc6764``, ``require_tls``) +cannot be turned off this way — ``CALDAV_REQUIRE_TLS=false`` sets the +parameter to the non-empty, hence true, string ``"false"``. Use the config +file or a keyword argument for those. + Examples ========