csspin_python.python

The python plugin is the core plugin of the csspin-python plugin-package. It is not only used for creating a virtual environment which serves as location for all spin-related tooling and plugin-dependencies, it also enables the dynamic installation and access of/to tools.

Please note that the python plugin is required and used by all plugins within the csspin-python plugin-package.

How to setup the python plugin?

For using the python plugin, a project’s spinfile.yaml must at least contain the following configuration.

Minimal configuration of spinfile.yaml to leverage python

plugin_packages:
    - csspin-python
plugins:
    - csspin_python.python
python:
    version: "3.11.9"

The provisioning of the required virtual environment as well as the plugins dependencies can be done via the well-known spin provision-task.

Update the environment

The environment the csspin_python.python plugin creates can be updated easily by running spin provision anew.

In case the version of python.version changed since the last provision call, the current environment will be removed and a new one will be created, using the new Python version. All python.requirements will be installed into the new environment afterwards.

In the other case when the python.version has not changed since the las provision call, the csspin_python.python plugin will update the Python packages installed in the environment.

Note

Please keep in mind that the SimpleProvisioner will only ever install packages but never uninstall them.

Note

In case spin provision is being called while python.python already exists the building of JS during wheel building will be suppressed. To avoid suppression, set python.skip_js_build to False.

Installing python packages

Using a static index URL

The default index for installing Python packages is https://pypi.org/simple. To be able to install packages from another index, for example the dev-index for the development of CE16 components, the plugin’s configuration can be adjusted by extending the project’s spinfile.yaml like this:

Using a custom index URL, e.g. for installing cs-packages

...
python:
    version: "3.11.9"
    index_url: <URL to retrieve the CE packages from>

    # Additional requirements can be used to install further Python-packages
    # into the virtual environment created by the python plugin.
    requirements:
        - cs.admin
        - cs.platform[postgres]

Using AWS Codeartifact Repository

csspin-python provides an extra named aws_auth that installs the command-line tool csaccess to authenticate with the AWS Codeartifact Python package index for CONTACT Software GmbH.

To install csspin-python using this extra make sure it is enabled in the project’s spinfile.yaml:

spinfile.yaml enabling csspin-python[aws_auth]

...
plugin_packages:
    - csspin-python[aws_auth]

python:
    aws_auth:
        enabled: True
...

When provisioning a project using the extra installed and enabled, make sure to have the following environment variables in place:

• CS_AWS_OIDC_CLIENT_SECRET

CONTACT Software GmbH will provide every customer with OIDC credentials during onboarding and the Cloud team can be contacted in case there are any questions.

Provisioning the project will result in a modified python.index_url that allows to install packages from the CodeArtifact registry.

Running spin provision with enabled aws_auth

spin provision
spin: mkdir /home/developer/src/my_project/.spin
spin: mkdir /home/developer/src/my_project/.spin/plugins
...
spin: python -mpip -q --disable-pip-version-check install --index-url https://aws:*******@contact-373369985286.d.codeartifact.eu-central-1.amazonaws.com/pypi/16.0/simple/ -U pip
...

How to use an existing Python interpreter, instead of provisioning another one?

Sometimes downloading and installing a Python interpreter can be annoying, in case there is already an existing interpreter that should be used in the context of csspin. For this case, the configuration tree property python.use can be set via command-line, the environment or within spinfile.yaml to enforce the usage of the passed interpreter.

Using an existing Python interpreter

spin -p python.use=python provision
...
spin -p python.use=/usr/bin/python <task>

How to activate the virtual environment provisioned by csspin manually?

Attention

The activation script presented by spin env doesn’t lead to same environment in which spin run <command> is executed, since plugins’ hooks are not run through when activating an environment by hand! For more information, please refer to Python Virtual Environment.

Retrieving the path to activate the virtual environment created by the python plugin is as easy as follows:

Retrieving the activate script of the virtual environment provisioned by csspin

# Unix-style shells:
spin env
. /home/developer/src/qs/spin/csspin_python/.spin/venv/bin/activate

# Powershell 7:
spin env
C:\Users\developer\Desktop\csspin\.spin\venv\Scripts\activate.ps1

Activating the virtual environment can be done by sourcing the activate script:

Activating the virtual environment provisioned by csspin

# Unix-style shells:
$(spin env)

# Powershell 7:
& (spin env)

How to inject a custom pip configuration within the scope of the environment?

Adding a site-specific pip.conf / pip.ini into the Python virtual environment can be achieved by leveraging the python.pipconf property as follows:

Using a site-specific configuration for pip

...
python:
    pipconf: |
        [global]
        find-links = {HOME}/.custom_wheel_cache

How to build a wheel?

Building a wheel for the current package can be done by using the following command:

spin python:wheel .

If python.build_wheels is not specified within the spinfile.yaml, the same could be achieved with spin python:wheel (without the path argument).

python.build_wheel allows building multiple wheels with a single spin python:wheel command:

# spinfile.yaml
...
python:
    ...
    build_wheels:
        - '{spin.project_root}' # for building the current package
        - cs.componenttest
        - path/to/another/package

Supported Python versions

Note

The version limitations mentioned here are only valid if the SimpleProvisioner of the csspin_python.python plugin is used. Other provisioners might have different limitations.

Some Python versions might not be available for provision on all platforms. If a certain version is not available on the current platform, the provisioning will fail with an appropriate error message.

To check which Python versions are supported for provision by the csspin_python.python plugin, please refer to https://www.nuget.org/packages/python for Windows or run pyenv install --list on Linux.

If a desired version is missing, the use of a pre-provisioned interpreter via python.use is recommended.

---

python: 'object'

python.pyenv: 'object'

Configuration related to pyenv is used for provisioning the Python interpreter

python.pyenv.url: 'str'

URL to install pyenv from

python.pyenv.path: 'path'

Path to cache the pyenv sources

python.pyenv.cache: 'path'

Path to cache the Python sources downloaded by pyenv

python.pyenv.python_build: 'path'

Path to the python-build builtin plugin of pyenv

python.user_pyenv: 'bool'

If False install pyenv from sources, otherwise use the pyenv from PATH

python.nuget: 'object'

Configuration related to the Python provision on Windows using nuget

python.nuget.url: 'str'

URL to install nuget from

python.nuget.exe: 'path'

Path to nuget executable

python.nuget.source: 'str'

Index to use for nuget sources

python.version: 'str'

The Python version to use for the whole project when using in the context of spin

python.use: 'str'

The use property can be used to specify an alternative Python source to use. This is useful to rather use the system Python than the one defined in spinfile.yaml

python.inst_dir: 'path'

Path to the installation directory of Python.

python.interpreter: 'path'

The path to the Python interpreter of the instance to use.

python.venv: 'path'

Path to the virtual environment which is used exclusively for the project spin is running on

python.memo: 'path'

Path to the memoizer used to list installed packages

python.bindir: 'path'

Path of the virtual environment’s binary directory on Linux; equals “{python.venv}” on Windows

python.scriptdir: 'path'

Directory containing the executables of the Python virtual environment

python.python: 'path'

The python property defines the path to the Python interpreter to use.

python.pipconf: 'str'

Content of the pip.conf/pip.ini configuration file that will be written into the environment.

python.site_packages: 'path internal'

The path to the virtual environments site-packages directory.

python.requirements: 'list'

The list of this project’s external Python requirements, that have to be installed into the project’s virtual environment. This excludes requirements stated as ‘install_requires’ in setup.py/setup.cfg. Note that editable installs with -e or requirement files with -r can also be used here.

python.constraints: 'list'

The list of constraint files that should be used when installing packages into the virtual environment.

python.index_url: 'str'

The index url from where packages should get installed into the venv. This value will also be put into cfg.python.pipconf, if not already mentioned there.

python.build_wheels: 'list'

A list of packages that will be built along with the current project when executing python:wheel.

python.aws_auth: 'object'

Configuration for the ‘aws_auth’ extra.

python.aws_auth.enabled: 'bool'

Whether to enable AWS authentication for retrieving packages from CodeArtifact.

python.aws_auth.memo: 'path'

Path to the memoized information regarding the aws_auth extra.

python.aws_auth.key_duration: 'int'

Time in seconds defining how long the plugin should consider the authentication token as valid before issuing a new one.

python.aws_auth.static_oidc: 'bool'

Whether to static OIDC when authenticating with AWS CodeArtifact.

python.aws_auth.index: 'str'

The CodeArtifact repository index (e.g. “16.0/simple”).

python.aws_auth.client_id: 'str'

The OIDC client ID to use.

python.aws_auth.client_secret: 'secret'

The OIDC client secret to use, defaults to the environment variable ‘CS_AWS_OIDC_CLIENT_SECRET’.

python.aws_auth.role_arn: 'str'

The role ARN to assume when authenticating.

python.skip_js_build: 'bool'

If true the build_js part of setuptools_ce will be skipped during provision.

python.schema: 'object'

python.provisioner: 'object'

python.provisioner_memo: 'str'

python.requires: 'object'

python.requires.python: 'list'

python._requires: 'list'