Configuration

The scripts in the project’s root directory use a configuration interface from the ws.config submodule, which relies on the argparse and configparser Python modules.

All options can be passed as command line arguments, the special --help option prints all available options for a particular script:

$ python print-namespaces.py -h
...

optional arguments:
  -h, --help            show this help message and exit
  -c PATH_OR_NAME, --config PATH_OR_NAME
                        path to the config file, or a base file name for config files looked up as
                        /home/lahwaacz/.config/wiki-scripts/<name>.conf (default: default)
  --no-config           do not read any config file
  --log-level {debug,info,warning,error,critical}
                        the verbosity level for terminal logging (default: info)
  -d, --debug           shortcut for '--log-level debug'
  -q, --quiet           shortcut for '--log-level warning'

Connection parameters:
  --api-url URL         the URL to the wiki's api.php
  --index-url URL       the URL to the wiki's index.php
  --connection-max-retries CONNECTION_MAX_RETRIES
                        maximum number of retries for each connection (default: 3)
  --connection-timeout CONNECTION_TIMEOUT
                        connection timeout in seconds (default: 60)
  --cookie-file PATH    path to cookie file (default: None)

The long arguments that start with -- can be set in a configuration file specified by the -c/--config option. The configuration file uses an extended INI format as implemented by the configparser Python module. The configuration file contains a key-value pairs, where keys correspond to the long argument names without the -- prefix. Options from the configuration file are internally processed by adding them to the command line, so debug = true in a config file is equivalent to passing --debug on the command line. Values passed on the command line take precedence over those specified in a configuration file.

Note

Although it is possible to set all long arguments in a configuration file, setting all arguments this way may not be a good idea – for example setting the help argument from the configuration file does not make sense.

Configuration file location

The value of the -c/--config option can be either a path to the configuration file (which must have a .conf suffix), or a name of the configuration which is looked up in the $XDG_CONFIG_HOME/wiki-scripts/ directory as <name>.conf. The default value of the -c/--config option is default, i.e., the default configuration file path is $XDG_CONFIG_HOME/wiki-scripts/default.conf.

Tip

To quickly switch between default configurations, you can create a symbolic link from $XDG_CONFIG_HOME/wiki-scripts/default.conf to a different configuration file.

Configuration file format

The configuration file contains a top-level [DEFAULT] section which contains global options that are applied to all scripts:

# Default options (applicable to all scripts).
[DEFAULT]
api-url = https://wiki.archlinux.org/api.php
index-url = https://wiki.archlinux.org/index.php
cookie-file = ~/.local/share/wiki-scripts/ArchWiki.cookie

Options can be applied only to a specific script by defining them in a section named after the script, i.e., options from the [script] section are read by a script named script.py. Options defined in a specific section also override corresponding options from the [DEFAULT] section. For example:

# Default options (applicable to all scripts).
[DEFAULT]
api-url = https://wiki.archlinux.org/api.php
index-url = https://wiki.archlinux.org/index.php
cookie-file = ~/.local/share/wiki-scripts/ArchWiki.cookie

# Script-specific options.
[update-pkg-templates]
cookie-file = ~/.local/share/wiki-scripts/ArchWiki.bot.cookie

To avoid duplicating option values, configparser supports sharing common parts with the interpolation syntax (wiki-scripts uses the ExtendedInterpolation handler). Note that you can also define custom keys in the configuration file, which do not correspond to wiki-scripts options, but are used for the interpolation. The previous example can be simplified into:

# Default options (applicable to all scripts).
[DEFAULT]
# custom options for interpolation
site = ArchWiki
data-dir = ~/.local/share/wiki-scripts/

# wiki-scripts options.
api-url = https://wiki.archlinux.org/api.php
index-url = https://wiki.archlinux.org/index.php
cookie-file = ${data-dir}/${site}.cookie

# Script-specific options.
[update-pkg-templates]
cookie-file = ${data-dir}/${site}.bot.cookie

The full example of a configuration file is available as sample.conf.

Migrating configuration from pre-2.0 versions

Versions up to 1.3 used the ConfigArgParse and configfile libraries for handling configuration, which were replaced with standard Python modules (argparse and configparser) in version 2.0. This section helps users to migrate their configuration for the new implementation.

Firstly, the default path for the -c/--config option is different:

  • Old path: $XDG_CONFIG_HOME/wiki-scripts/wiki-scripts.conf

  • New path: $XDG_CONFIG_HOME/wiki-scripts/default.conf

Next, the configuration needs to be updated from the configfile syntax to the configparser syntax. Note that the features supported by these two libraries differ:

Also note that the --site and --cache-dir options have become unused and were removed. Hence, the main things that will need to be changed are:

  • Start the configuration with a [DEFAULT] section.

  • Avoid nested sections. For example, if you had a configuration for --site ArchWiki, move all options from [ArchWiki] into [DEFAULT] and remove ArchWiki. from all sections starting with this prefix.

  • Update the interpolation syntax. For example, use ${option} instead of ${option$}.

The structuring that was previously achieved by the --site option can now be done with the --config option. For example, if you had a non-default configuration for --site Wikipedia, you can create a configuration file at $XDG_CONFIG_HOME/wiki-scripts/Wikipedia.conf containing all former [Wikipedia.*] sections (but without the Wikipedia. prefix in section names) and select it with --config Wikipedia.

For more insights into the migration, you can compare the sample.conf file with its 1.3 version.

Finally, note that some options may have different behaviour (e.g., different default value) in the new version compared to version 1.3, but we did not keep an exact list of differences. Most notably, the --cookie-file option lost its default value, so it has to be set explicitly in the configuration file for persistent authenticated session.