<commit_before>:github_url:

.. _configuration:

.. index::
	pair: python; version
	triple: python; arch; architecture
	triple: wine; arch; architecture
	triple: log; level; write
	statement: zugbruecke.current_session.set_parameter
	module: zugbruecke.core.config

Configuration
=============

*zugbruecke* can configure itself or can be configured with files or can
be (re-) configured during run-time. The configuration allows you to fine-tune
its verbosity, architecture and other relevant parameters on a per-session basis.

During import, the *zugbruecke* module starts a default session which is referenced as
``zugbruecke.current_session``. Alternatively, you can create your own sessions with
``zugbruecke.session()``. See the :ref:`chapter on the session model <session>` for details.

.. _configconstructor:

Configuring the session constructor
-----------------------------------

If you chose to start your own session with ``zugbruecke.session()``, the session
constructor can be provided with a dictionary containing parameters.

Configuration files
-------------------

*zugbuecke* uses ``JSON`` configuration files named ``.zugbruecke.json``.
They are expected in the following locations (in that order):

* The current working directory
* A directory specified in the ``ZUGBRUECKE`` environment variable
* The *zugbuecke* root directory (``~/.zugbruecke`` by default)
* ``/etc/zugbruecke``

Parameters passed directly into the *zugbuecke* session constructor will
always be given priority. Beyond that, missing parameters are being looked for
location after location in the above listed places. If, after checking for
configuration files in all those locations, there are still parameters
left unconfigured, *zugbuecke* will fill them with its defaults. A parameter
found in a location higher in the list will always be given priority over
a the same parameter with different content found in a location further down the list.

.. _reconfiguration:

Re-configuration during run-time
--------------------------------

Every session exposes a ``set_parameter`` method, which accepts a dictionary
containing parameters.

.. _configparameter:

Configurable parameters
-----------------------

``id`` (str)
^^^^^^^^^^^^

Every *zugbuecke* ``session`` has a unique ``id``, which allows easier debugging
and keeping track of multiple simultaneously running sessions. If no session
id is provided by the user, *zugbuecke* will automatically generate a random
hash ``string`` for every new session. Only manually configure this if absolutely
necessary.

``stdout`` (bool)
^^^^^^^^^^^^^^^^^

Tells *zugbuecke* to show messages its sub-processes write to ``stdout``.
``True`` by default.

``stderr`` (bool)
^^^^^^^^^^^^^^^^^

Tells *zugbuecke* to show messages its sub-processes write to ``stderr``.
``True`` by default.

``logwrite`` (bool)
^^^^^^^^^^^^^^^^^^^

Tells *zugbuecke* to write its logs to disk into the current working directory.
``False`` by default.

``log_level`` (int)
^^^^^^^^^^^^^^^^^^^

Changes the verbosity of *zugbuecke*. ``0`` for no logs, ``10`` for maximum logs.
``0`` by default.

``arch`` (str)
^^^^^^^^^^^^^^

Defines the architecture of *Wine* & *Wine* *Python*. It can be set to ``win32`` or ``win64``.
Default is ``win32``, even on 64-bit systems. It appears to be a more stable configuration.

``version`` (str)
^^^^^^^^^^^^^^^^^

The ``version`` parameter tells *zugbuecke* what version of the *Windows* *CPython* interpreter
it should use. By default, it is set to ``3.5.3``.

Please not that 3.4 and earlier are not supported. In the opposite direction, at the time of
writing, 3.6 (and later) does not work under *Wine* due to a `bug in Wine`_.

.. _bug in Wine: https://github.com/pleiszenburg/zugbruecke/issues/13

``dir`` (str)
^^^^^^^^^^^^^

This parameter defines the root directory of *zugbruecke*. It is where *zugbruecke*'s
own *Wine* profile folder is stored (``WINEPREFIX``) and where the :ref:`Wine Python environment <wineenv>`
resides. By default, it is set to ``~/.zugbruecke``.<commit_msg>fixed spelling and grammar in cfg doc chapter<commit_after>:github_url:

.. _configuration:

.. index::
	pair: python; version
	triple: python; arch; architecture
	triple: wine; arch; architecture
	triple: log; level; write
	statement: zugbruecke.current_session.set_parameter
	module: zugbruecke.core.config

Configuration
=============

*zugbruecke* can configure itself or can be configured with files or can
be (re-) configured during run-time. The configuration allows you to fine-tune
its verbosity, architecture and other relevant parameters on a per-session basis.

During import, the *zugbruecke* module starts a default session which is referenced as
``zugbruecke.current_session``. Alternatively, you can create your own sessions with
``zugbruecke.session()``. See the :ref:`chapter on the session model <session>` for details.

.. _configconstructor:

Configuring the session constructor
-----------------------------------

If you chose to start your own session with ``zugbruecke.session()``, the session
constructor can be provided with a dictionary containing parameters.

Configuration files
-------------------

*zugbuecke* uses ``JSON`` configuration files named ``.zugbruecke.json``.
They are expected in the following locations (in that order):

* The current working directory
* A directory specified in the ``ZUGBRUECKE`` environment variable
* The *zugbuecke* root directory (``~/.zugbruecke`` by default)
* ``/etc/zugbruecke``

Parameters passed directly into the *zugbuecke* session constructor will
always be given priority. Beyond that, missing parameters are being looked for
location after location in the above listed places. If, after checking for
configuration files in all those locations, there are still parameters
left undefined, *zugbuecke* will fill them with its defaults. A parameter
found in a location higher in the list will always be given priority over
a the same parameter with different content found in a location further down the list.

.. _reconfiguration:

Re-configuration during run-time
--------------------------------

Every session exposes a ``set_parameter`` method, which accepts a dictionary
containing parameters.

.. _configparameter:

Configurable parameters
-----------------------

``id`` (str)
^^^^^^^^^^^^

Every *zugbuecke* ``session`` has a unique ``id``, which allows easier debugging
and keeping track of multiple simultaneously running sessions. If no session
id is provided by the user, *zugbuecke* will automatically generate a random
hash ``string`` for every new session. Only manually configure this if absolutely
necessary.

``stdout`` (bool)
^^^^^^^^^^^^^^^^^

Tells *zugbuecke* to show messages its sub-processes are writing to ``stdout``.
``True`` by default.

``stderr`` (bool)
^^^^^^^^^^^^^^^^^

Tells *zugbuecke* to show messages its sub-processes are writing to ``stderr``.
``True`` by default.

``logwrite`` (bool)
^^^^^^^^^^^^^^^^^^^

Tells *zugbuecke* to write its logs to disk into the current working directory.
``False`` by default.

``log_level`` (int)
^^^^^^^^^^^^^^^^^^^

Changes the verbosity of *zugbuecke*. ``0`` for no logs, ``10`` for maximum logs.
``0`` by default.

``arch`` (str)
^^^^^^^^^^^^^^

Defines the architecture of *Wine* & *Wine* *Python*. It can be set to ``win32`` or ``win64``.
Default is ``win32``, even on 64-bit systems. It appears to be a more stable configuration.

``version`` (str)
^^^^^^^^^^^^^^^^^

The ``version`` parameter tells *zugbuecke* what version of the *Windows* *CPython* interpreter
it should use. By default, it is set to ``3.5.3``.

Please note that 3.4 and earlier are not supported. In the opposite direction, at the time of
writing, 3.6 (and later) does not work under *Wine* due to a `bug in Wine`_.

.. _bug in Wine: https://github.com/pleiszenburg/zugbruecke/issues/13

``dir`` (str)
^^^^^^^^^^^^^

This parameter defines the root directory of *zugbruecke*. This is where *zugbruecke*'s
own *Wine* profile folder is stored (``WINEPREFIX``) and where the :ref:`Wine Python environment <wineenv>`
resides. By default, it is set to ``~/.zugbruecke``.
{'fraction_non_alphanumeric': 0.15036855036855037, 'fraction_numerical': 0.005159705159705159, 'mean_word_length': 4.355921052631579, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5486861', 'n_tokens_mistral': 2320, 'n_tokens_neox': 2266, 'n_words': 1008}