.. _configure_popy:

Configure |popy|
################

The machine-level settings of your |popy| installation are stored in
``<PoPy installation folder>\popy_config.pyml`` which can be modified
in your chosen text editor.

We recommend, however, that you do not alter this file unless you know 
exactly what you are doing; the default settings should be sufficient for 
most users.

Should you edit your 'popy_config.pyml' and |popy| stops functioning correctly, 
please restore to the following default settings:

.. literalinclude:: config_pyml_default.inc
    :language: yaml

Upon running |popy| for the first time, a user-level configuration file will
also (on Microsoft Windows only) be created in the user's roaming profile which is
typically found at 

.. code-block::

    C:\Users\<username>\AppData\Roaming\PoPy\<SHA>-config.pyml

where `<username>` is the user's login username and `<SHA>` is the unique
identifier for the version of |popy| being configured, as displayed when
running `popy info`. 
Settings in the user's local configurations override those in the global 
configuration.
In this way, we provide user- and installation-specific configuration of 
|popy| for finer-grained control over |popy|'s behaviour.
 

Sharing |popy| Among Users 
==========================

By default, |popy| is installed for a single user on a given machine, and
the path to |popy| scripts will be added to the Path environment variable
of the user who installed |popy|.

If another user wants to use the same installation of |popy|, they should 
run :ref:`popy-cmd` from the installation folder where they will be 
asked whether they wish to add |popy| to their user path, and will be given
three options.

* Answering "Y" (for Yes) to this question will add |popy| to their path so that
they can then call popy commands from any Command Prompt, not just the 
:ref:`popy-cmd` prompt. We recommend this choice.

* Answering "N" (for No) will continue running |popy| but will ask again for
subsequent calls to |popy| (including subscripts of scripts). An alternative
for skipping this check is to add the `--skip-path-check` argument when calling
|popy|, e.g.,

.. code-block::

    popy info --skip-path-check

* Answering "V" (for neVer) will skip the path check on this call *and all subsequent
calls* to |popy|, recording this choice in the user's local configuration file.
