Merge branch 'test-venv' into 'master'

  py/cso_colhub.py

v2.12

-----

Support running CSO within a virtual environment.

It is updated automatically when changes are pushed.

For first introduction, see in particular the [Tutorial](https://cams.ci.tno.nl/cso/tutorial.html) chapter.

Eventually create a local version of the documentation from its source files using:

    make docu

which is usually part of your python distribution.

Installation from source

------------------------

Running CSO within your own Python environment

----------------------------------------------

The CSO tools could be started within your own Python environment.

You should then ensure that the required (versions of) packages have been installed correctly.

To test CSO within your environment, try for example run the example from the Tutorial:

    ./bin/cso config/tutorial/tutorial.rc

CSO can be installed from source in either conda or virtual environments.

**Pip**

The file py_project.toml contains the dependencies needed by CSO.  

Running CSO within a virtual environment

----------------------------------------

A *virtual environment* could be created that has all required (versions) of Python packages installed.

For this, the `py_project.toml` file is included which contains the dependencies needed by CSO.  

To create a new virtual enviroment run:

    python3 -m venv --prompt cso .venv

This will create a new Python evironment folder called `cso`. To activate it run

This will create a new Python evironment folder called `.venv`.

To activate it run:

    source .venv/bin/activate

You may need to updated pip with the command

The terminal prompt will then be preceded by `(cso)` which holds the name specified above 

with the `--prompt` argument.

You may need to upgrade `pip` with the command:

    pip install -U pip

    pip install --upgrade pip

We can then install CSO and its dependencies simply using pip

We can then install CSO and its dependencies into the virtual environment using:

    pip install -e .

    pip install --editable .

The `-e` flag installs CSO in editable mode, meaning that the user can change the source code and run CSO anywhere using these changes.

The `--editable` flag installs CSO in editable mode, meaning that the user can change the source code 

in the `src/` directory and run CSO anywhere using these changes.

Test the installation using the Tutorial settings:

Tutorial

--------

    ./bin/cso config/tutorial/tutorial.rc

A tutorial is included in the documentation.

When finished, leave from the virtual environment using:

For the impatient:

    deactivate

    ./bin/cso rc/tutorial.rc

# prefix of CSO installation:

prefix = os.path.abspath(os.path.join(os.path.dirname(sys.argv[0]), os.pardir))

# extend path:

sys.path.insert(0, os.path.join(prefix, "py"))

sys.path.insert(0, os.path.join(prefix, "src"))

sys.path.insert(0, os.path.join(prefix, "src", "utopya"))

sys.path.insert(0, os.path.join(prefix, "src", "cso"))

# tools:

import utopya

! run jobs in foreground:

*.script.class                      :  utopya.UtopyaJobScriptForeground

! dummy value, will be defined when running in virtrual environment:

VIRTUAL_ENV                         :

! running in virutual envionment?

#if "${VIRTUAL_ENV}" > ""

! interpretor from virtual enviornment, the system path is set automatically:

*.shell                             :  ${VIRTUAL_ENV}/bin/python3

#else

! search path for python modules:

*.pypath                            :  ${CSO_PREFIX}/py

*.pypath                            :  ${CSO_PREFIX}/src:${CSO_PREFIX}/src/utopya:${CSO_PREFIX}/src/cso

#endif

! work directory for jobs; 

*.workdir                           :  ${my.work}/__NAME2PATH__

! full time range:

cso.tutorial.inquire-table-dataspace.timerange.start        :  2018-01-01 00:00:00

cso.tutorial.inquire-table-dataspace.timerange.end          :  2024-01-01 00:00:00

cso.tutorial.inquire-table-dataspace.timerange.end          :  2025-01-01 00:00:00

!! ... testing ...

!cso.tutorial.inquire-table-dataspace.timerange.start        :  2018-06-01 00:00:00

!cso.tutorial.inquire-table-dataspace.timerange.end          :  2018-07-01 00:00:00

! API url:

cso.tutorial.inquire-table-dataspace.url                    :  https://catalogue.dataspace.copernicus.eu/resto/api

#

import os

import sys

sys.path.insert(0, os.path.abspath(os.path.join(os.pardir, os.pardir, "py")))

#

sys.path.insert(0, os.path.abspath(os.path.join(os.pardir, os.pardir, "src")))

sys.path.insert(0, os.path.abspath(os.path.join(os.pardir, os.pardir, "src", "utopya")))

sys.path.insert(0, os.path.abspath(os.path.join(os.pardir, os.pardir, "src", "cso")))

# -- Project information -----------------------------------------------------

copyright = "2020-2025, Arjo Segers"

author = "Arjo Segers"

# The full version, including alpha/beta/rc tags

release = "v2.11"

# extract the version id from the project file:

ppfile = os.path.join(os.pardir, os.pardir, "pyproject.toml")

# check ..

if not os.path.isfile(ppfile):

    # info ...

    print(f"WARNING - could not find '{ppfile}' to extract release tag ...")

    # dummy:

    release = "vx.y"

else:

    # modules:

    import toml

    # open file:

    with open(ppfile, "r") as f:

        config = toml.load(f)

    # extrract:

    release = config["project"]["version"]

#endif

# -- General configuration ---------------------------------------------------