update docs

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017, Vyacheslav Rusakov
+Copyright (c) 2017-2024, Vyacheslav Rusakov
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

src/doc/docs/about/compatibility.md

@@ -1,10 +1,11 @@
 # Gradle compatibility
 
-Plugin compiled for java 8, compatible with java 11.
+Plugin compiled for java 8, compatible with java 11 and 17.
 Works with python 2 and 3 (but python 2 not tested anymore) on windows and linux (and macos).
 
 Gradle | Version
 --------|-------
-5.3-8     | 3.0.0
+7.0     | 4.0.0
+5.3     | 3.0.0
 5-5.2     | 2.3.0
 4.x     | [1.2.0](https://github.com/xvik/gradle-use-python-plugin/tree/1.2.0)

src/doc/docs/about/history.md

@@ -1,3 +1,30 @@
+### [4.0.0](http://xvik.github.io/gradle-use-python-plugin/4.0.0) (2024-04-13)
+* (breaking) Drop gradle 5 and 6 support
+* (breaking) All plugin tasks become abstract, so any custom task types should be abstract too
+* (breaking) All tasks use lazy properties instead of convention mapping (affects custom tasks)
+* Fix `alwaysInstallModules = true` not triggers pipInstall for non-strict requirements file (#94)
+  (required for case when requirements file links other files, which changes are not tracked)
+* Add requirements file references (-r file) support under strict mode (#94)
+* Configuration cache compatibility (#89)
+* Changed virtualenv version installed by default (python.virtualenvVersion) from 20.4.2 to 20.25.1
+  (supports python 3.7 - 3.12)
+* Changed default docker image (python.docker.image) from python:3.10.8-alpine3.15 to python:3.11.8-alpine3.19
+* New options (python.):
+  - breakSystemPackages: adds --break-system-packages for pip install
+    May be required on linux to install virtualenv on apt-managed python (e.g. python3.12)
+  - docker.useHostNetwork: use host network for docker
+    Works only on linux. When enabled, all container ports automatically exposed on host
+    and configured port mappings ignored
+  - printStats: show all executed python commands (including plugin internal) at the end of the build (with timings)
+  - useVenv: use venv instead of virtualenv (enabled by default)
+    Venv is installed by default since python 3.3 which removes requirement to install virtualenv. (#77)
+    Fallback to virtualenv when venv not found. All current environments created with virtualenv
+    will still be working correctly.
+* Add user home dir ("~/") support for the environment path (python.envPath)
+* To use different python for PythonTask useCustomPython = true must be declared now
+  (otherwise, pythonPath select by checkPython task would be used (and task's pythonPath ignored))
+
+
 ### [3.0.0](http://xvik.github.io/gradle-use-python-plugin/3.0.0) (2022-10-22)
 * (breaking) Drop gradle 5.0-5.2 support (minimum required gradle is 5.3)
 * Add docker support (python could be started in docker container without local python)

src/doc/docs/about/license.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017-2022, Vyacheslav Rusakov
+Copyright (c) 2017-2024, Vyacheslav Rusakov
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

src/doc/docs/getting-started.md

@@ -58,7 +58,7 @@ If you have docker installed, you can use python from [docker container](guide/d
 python.docker.use = true
 ```
 
-In this case global python installation is not required.
+In this case, global python installation is not required.
 
 ## Pip modules
 
@@ -87,10 +87,19 @@ python {
 
 Default behaviour:
 
-* if [`virtualenv`](https://virtualenv.pypa.io/en/stable/) module installed (or [automatically installed](guide/configuration.md#virtualenv)):
+* if [venv](https://docs.python.org/3/library/venv.html) or [`virtualenv`](https://virtualenv.pypa.io/en/stable/) module installed (virtualenv could be [installed automatically](guide/configuration.md#virtualenv)):
   manage pip dependencies per project (env `.gradle/python` created)
 * if no virtualenv - use user scope ([`--user`](https://pip.pypa.io/en/stable/user_guide/#user-installs) 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:
 
@@ -101,12 +110,14 @@ 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 `virtualenv` (if module not installed - error thrown)
+* `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](guide/multimodule.md)).
 
+Venv support could be disabled with `python.useVenv = false` option (virtualenv would be used in this case).
+
 ## Usage
 
 Call python command:
@@ -166,3 +177,20 @@ tasks.register('script', PythonTask) {
 ```
 
 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:
+
+```groovy
+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'] 
+}
+```

src/doc/docs/guide/ci.md

@@ -22,6 +22,12 @@ jobs:
     strategy:
       matrix:
         java: [8, 11]
+        python: ['3.8', '3.12']
+
+      # reduce matrix, if required
+      exclude:
+          - java: 8
+            python: '3.12'  
 
     steps:
       - uses: actions/checkout@v3
@@ -31,10 +37,10 @@ jobs:
         with:
           java-version: {{ '${{ matrix.java }}' }}
 
-      - name: Set up Python
+      - name: Set up Python ${{ matrix.python }}
         uses: actions/setup-python@v4
         with:
-          python-version: 3.10
+          python-version: ${{matrix.python}}
 
       - name: Build
         run: |
@@ -54,8 +60,13 @@ To make plugin work on [appveyour](https://www.appveyor.com/) you'll need to add
 ```yaml
 environment:
     matrix:
-        - JAVA_HOME: C:\Program Files\Java\jdk1.8.0
-          PYTHON: "C:\\Python36-x64"
+        - job_name: Java 8, python 3.8
+          JAVA_HOME: C:\Program Files\Java\jdk1.8.0
+          PYTHON: "C:\\Python38-x64"
+        - job_name: Java 17, python 3.12
+          JAVA_HOME: C:\Program Files\Java\jdk17
+          appveyor_build_worker_image: Visual Studio 2019
+          PYTHON: "C:\\Python312-x64"  
 
 install:
   - set PATH=%PYTHON%;%PYTHON%\\Scripts;%PATH%
@@ -64,12 +75,6 @@ install:
 
 Now plugin would be able to find python binary.
 
-To use python 3.9 you'll need to switch image:
-
-```yaml
-image: Visual Studio 2019
-```
-
 See [available pythons matrix](https://www.appveyor.com/docs/windows-images-software/#python) for more info.
 
 ## Travis
@@ -95,3 +100,43 @@ before_install:
 ``` 
 
 It will be python 3.6 by default (for bionic).
+
+## Environment caching
+
+To avoid creating virtual environments on each execution, it makes sense to move
+environment location from the default `.gradle/python` (inside project) outside the project:
+
+```groovy
+python.envPath = '~/.myProjectEnv'
+```
+
+Virtual environment created inside the user directory and so could be easily cached now.
+
+NOTE: Only `envPath` property supports home directory reference (`~/`). If you need it in other places
+then use manual workaround: `'~/mypath/'.replace('~', System.getProperty("user.home"))`
+
+## System packages
+
+On linux distributions, some python packages could be managed with external packages
+(like python3-venv, python3-virtualenv, etc.).
+
+If your build is **not using virtual environment** and still needs to install such packages,
+it would lead to error:
+
+```
+error: externally-managed-environment
+
+× This environment is externally managed
+╰─> To install Python packages system-wide, try apt install
+    python3-xyz, where xyz is the package you are trying to
+    install.
+```
+
+To work around this problem, use [breakSystemPackages](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-break-system-packages) option:
+
+
+```groovy
+python {
+    breakSystemPackages = true
+}
+```