.. include:: ../substitutions

..
    TODO: Replace |pyddg-gitlab| with the package name once the library is on PyPI.

.. |pyddg-gitlab| replace:: git+https://gitlab.discretization.de/python/pyddg@\ |tag|
.. |pyddg-gitlab-different| replace:: git+https://gitlab.discretization.de/python/pyddg@\ |different_tag|


.. _pyddg_installation:

pyddg standalone Installation
-----------------------------

.. contents::
   :local:
   :backlinks: none

.. _basic_linux_installation:

Linux, WSL and MacOS
^^^^^^^^^^^^^^^^^^^^

Create a directory for your project and enter it. Create a virtual environment and activate it.

.. code-block:: bash

    python3 -m venv venv

    source venv/bin/activate

Install the library.

.. parsed-literal::

    pip install |pyddg-gitlab|

Verify the installation.

.. code-block:: bash

    python3 -c 'import ddg; print("Successfully imported ddg!")'

Exit the virtual environment with

.. code-block:: bash

    deactivate

Windows
^^^^^^^

.. note::
    If you prefer to work in a GNU/Linux environment directly on Windows, you can install `WSL <https://learn.microsoft.com/en-us/windows/wsl/install>`_.
    You can then follow the instruction for :ref:`basic_linux_installation`.

Start an elevated terminal (i.e. "Run as administrator" in cmd.exe)

.. image:: windows01.png
    :width: 500

Make sure that you have Python 3.9, 3.10 or 3.11.
You can check if any of the following commands return a version between
Python 3.9 and 3.11, e.g. ``Python 3.10.2``

.. code-block:: doscon

    py --version

.. code-block:: doscon

    python3 --version

.. code-block:: doscon

    python --version

If there is an error, you need to install Python.
You can choose a version and download it
`here <https://www.python.org/downloads/windows/>`_, or directly download
Python 3.10.11
:download:`here <https://www.python.org/ftp/python/3.10.11/python-3.10.11-amd64.exe>`.

Create a directory for your project

.. code-block:: doscon

    mkdir myproject

and enter it with

.. code-block:: doscon

    cd myproject

Create a virtual environment with

.. code-block:: doscon

    py -m venv .\venv

Remember to replace ``py`` by the command working for you, i.e.
``py``, ``python3`` or ``python``.

.. note::

    If the ``Actual  environment location may have moved due to restrictions, ...``
    make sure to change (using the command ``cd``)
    into the new location stated under ``Actual location``, for example

    .. code-block:: doscon

        cd C:\Windows\SysWOW64\myproject

    Make sure to rerun the creation of the venv

    .. code-block:: doscon

        py -m venv .\venv



Activate the virtual environment by

.. code-block:: doscon

    venv\Scripts\activate

Install the library in the virtual environment with

.. parsed-literal::

    pip install |pyddg-gitlab|

.. note::

    You need to have `git installed <https://git-scm.com/download/win>`_ and may have to
    manually
    `add it to your PATH <https://www.delftstack.com/howto/git/add-git-to-path-on-windows/>`_.
    In the guide on how to add git to your PATH you may need to choose
    "edit the **system** environment variables" instead of
    "edit environment variables for **your account**"
    to have the rights to edit the PATH.

Verify the installation, again replace ``py`` by your python version.

.. code-block:: doscon

    py -c 'import ddg; print("Successfully imported ddg!")'

You can also start python in the venv

.. code-block:: doscon

    py

and start writing your python script by importing ``ddg``

.. code-block:: python

    >>> import ddg

To exit python use

.. code-block:: python

    >>> exit()  # doctest: +SKIP

Exit the virtual environment with

.. code-block:: doscon

    deactivate

Updating and switching versions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Choose a different version, e.g. |different_tag|.
Inside the virtual environment, run

.. parsed-literal::

    pip install |pyddg-gitlab-different|

.. warning::
    Updating the version is likely to fail if the library was moved
    after installation. This is due to the setup of
    `virtual environments <https://docs.python.org/3/library/venv.html>`_:
    "[...] environments are inherently non-portable,
    in the general case."

.. TODO how to ugrade?