Getting started

Note

Plugin does not install python and pip itself and use globally installed python (by default). It's easier to prepare python manually because python have good compatibility (from user perspective) and does not need to be updated often.

installation

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'ru.vyarus:gradle-use-python-plugin:4.0.0'
    }
}
apply plugin: 'ru.vyarus.use-python'

OR

plugins {
    id 'ru.vyarus.use-python' version '4.0.0'
}

Compatibility matrix

Python & Pip

Make sure python and pip are installed:

python --version  
pip --version

On *nix python usually reference python2. For python3:

python3 --version  
pip3 --version

Install python if required.

Docker

If you have docker installed, you can use python from docker container:

python.docker.use = true

In this case, global python installation is not required.

Pip modules

If additional pip modules required configure them:

python.pip 'module1:1.0', 'module2:1.0'

or

python {
    pip 'module1:1.0'
    pip 'module2:1.0'
}

Important

Version ranges are not allowed for reproducible builds! (but, eventually, there would be problems in any case because of transitive dependencies)

Module features and VCS modules supported.

Behaviour

Default behaviour:

• if venv or virtualenv module installed (virtualenv could be installed automatically): manage pip dependencies per project (env .gradle/python created)
• if no virtualenv - use user scope (--user pip flag): pip modules are installed only for current user (this avoid permission problems on linux)

Tip

Venv used by default because it is bundled with python since python 3.3. On linux distibutions, venv might be installed as a separate package (python3-venv), but, usually, it also installed by default. When venv is not found, plugin would try to fall back to virtualenv.

Note

It is not a problem if your project environment was created with virtualenv and now, by default, venv would be used. Existing environment is used directly - venv/virtualev used only for environment creation.

To change defaults:

python.scope = VIRTUALENV

• GLOBAL - install modules globally (this may not work on linux due to permissions)
• USER - use --user flag to install for current user only
• VIRTUALENV_OR_USER - default
• VIRTUALENV - use venv / virtualenv (if module not installed - error thrown)

Note

For multi-module projects, by default, plugin will create virtualenv inside the root project directory in order to share the same environment for all modules (but this could be changed).

Venv support could be disabled with python.useVenv = false option (virtualenv would be used in this case).

Usage

Call python command:

tasks.register('cmd', PythonTask) {
    command = "-c print('sample')"
}

called: python -c print('sample') on win and python -c exec("print('sample')") on *nix (exec applied automatically for compatibility)

Note

Each PythonTask would depend on checkPython and pipInstall tasks which would prepare python environment before actual execution.

Call multi-line command:

tasks.register('cmd', PythonTask) {
    command = "-c \"import sys; print(sys.prefix)\""
}

called: python -c "import sys; print(sys.prefix)" on win and python -c exec("import sys; print(sys.prefix)") on *nix

Note

It is important to wrap script with space in quotes (otherwise parser will incorrectly parse arguments).

See command parsing specifics and env variables usage

String command is used for simplicity, but it could be array/collection of args:

tasks.register('script', PythonTask) { 
    command = ['path/to/script.py', '1', '2'] 
}

Module

tasks.register('mod', PythonTask) {
    module = 'sample' 
    command = "mod args"
}

called: python -m sample mod args

Script

tasks.register('script', PythonTask) { 
    command = "path/to/script.py 1 2"
}

called: python path/to/script.py 1 2 (arguments are optional, just for demo)

Non-default python

Python task would use python selected by checkPython task (global or detected virtualenv). If you need to use completely different python for some task, then it should be explicitly stated with useCustomPython property:

tasks.register('script', PythonTask) {
    // global python (it would select python3 automatically on linux)
    pythonPath = null
    // force custom python for task
    useCustomPython = true
    command = ['path/to/script.py', '1', '2'] 
}