Configuration Strategy and Parameters

Hierarchy

zugbruecke retrieves configuration parameters from a number of places. It follows a hierarchy from highest to lowest priority, in the following order:

  • Environment variables

  • Keyword arguments provided by the user to the constructor of zugbruecke.CtypesSession

  • Configuration files

  • Default values

Warning

Environment variables are overwriting literally everything, including parameters passed directly into the zugbruecke session constructor!

Via Environment Variables

All configurable parameters of zugbruecke can directly be overridden with environment variables. Values from environment variables will always take precedence. Environment variables are named using a combination of the ZUGBRUECKE_ prefix and the name of the parameter in question converted to upper case. The pythonversion could for instance be configured as follows: ZUGBRUECKE_PYTHONVERSION=3.7.9

Via Files

zugbruecke uses JSON configuration files. They are expected in the following locations, from highest to lowest priority:

  • file specified in the ZUGBRUECKE environment variable: {os.environ.get("ZUGBRUECKE")}

  • directory specified in the ZUGBRUECKE environment variable: {os.environ.get("ZUGBRUECKE")}/.zugbruecke.json

  • current working directory: {os.getcwd()}/.zugbruecke.json

  • user profile folder: {os.path.expanduser("~")}/.zugbruecke.json

  • etc folder: /etc/zugbruecke.json

  • etc folder (deprecated): /etc/.zugbruecke.json

  • etc folder: /etc/zugbruecke

A configuration file may only deal with a subset of configuration parameters. For instance, a configuration file could only be used to specify a version of Windows Python:

{"pythonversion": "3.7.9"}

Parameters

The following parameters can be configured:

name

type

description

default

id

str

Unique, only configure it if necessary.

Random hash

stdout

bool

Show Windows Python stdout output.

True

stderr

bool

Show Windows Python stderr output.

True

log_write

bool

Write log to current working directory.

False

log_level

int

Verbosity, from 0 to 50.

0

arch

str

Windows Python architecture, win32 or win64.

win32

pythonversion

PythonVersion

Version / build of Windows Python, >= 3.7.

3.7.4

timeout_start

int

Wait seconds for Windows Python to show up.

30

timeout_stop

int

Wait seconds for Windows Python to terminate.

30

copy_modules

bool

Copy zugbruecke and wenv modules into wenv instead of symlink.

False

Note

(Only) log_level and log_write can be changed at run-time. log_level follows Python’s logging module’s log levels, i.e. DEBUG == 10, INFO == 20, WARNING == 30, ERROR == 40 and CRITICAL == 50. Default is 0 for no logs as per NOTSET.

Note

pythonversion accepts wenv.PythonVersion objects, see relevant section of wenv documentation. Version 3.6 and earlier are not supported. You can only specify versions / builds for which an “Windows embeddable zip file” is available, see python.org for details. wenv.get_available_python_builds (see here) and wenv.get_latest_python_build (also see here) can be used to automatically query available builds.

Note

Next to the parameters listed above, zugbruecke also accepts every valid wenv configuration parameter and passes them on to wenv itself. See relevant chapter of wenv documentation for details.