From 746f28a2d3a31986ee65499d2e8b626b2e14fe29 Mon Sep 17 00:00:00 2001 From: IvanZosimov Date: Wed, 13 Jul 2022 11:15:35 +0200 Subject: [PATCH] Update REAMDE.md and advanced-usage.md --- README.md | 15 +++++++++-- docs/advanced-usage.md | 61 ++++++++++++++++++++++++++---------------- 2 files changed, 51 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 4d8d55a..da0dd30 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ This action provides the following functionality for GitHub Actions users: See [action.yml](action.yml) +**Python** ```yaml steps: - uses: actions/checkout@v3 @@ -32,6 +33,16 @@ steps: python-version: '3.10' - run: python my_script.py ``` + +**PyPy** +```yaml +steps: +- uses: actions/checkout@v3 +- uses: actions/setup-python@v4 + with: + python-version: 'pypy3.7' +- run: python my_script.py +``` The `python-version` input is optional. If not supplied, the Python/PyPy version from the PATH will be used. The default version of Python/PyPy in PATH vary between runners and can be changed unexpectedly so we recommend always use `setup-python`. The action will first check the local [tool cache](docs/advanced-usage.md#hosted-tool-cache) for a [semver](https://github.com/npm/node-semver#versions) match. If unable to find a specific version in the tool cache, the action will attempt to download a version of Python from [GitHub Releases](https://github.com/actions/python-versions/releases) and for PyPy from the official [PyPy's dist](https://downloads.python.org/pypy/). @@ -40,11 +51,11 @@ For information regarding locally cached versions of Python/PyPy on GitHub hoste ## Supported version syntax -The `python-version` input supports the [Semantic Versioning Specification](https://github.com/npm/node-semver#versions) and some special version notations (e.g. `x.y-dev`), for detailed examples please refer to the section: [Using python-version input](docs/advanced-usage.md#using-python-version-input) of the [Advanced usage](docs/advanced-usage.md) guide. +The `python-version` input supports the [Semantic Versioning Specification](https://semver.org/) and some special version notations (e.g. `semver ranges`, `x.y-dev syntax`, etc), for detailed examples please refer to the section: [Using python-version input](docs/advanced-usage.md#using-python-version-input) of the [Advanced usage](docs/advanced-usage.md) guide. ## Supported architectures -Using `architecture` input it's possible to specify required python's interpreter architecture: `x86` or `x64`. If input is not specified it defaults to `x64`. +Using `architecture` input it's possible to specify required python's interpreter architecture: `x86` or `x64`. If input is not specified the architecture defaults to `x64`. ## Caching packages dependencies diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index 9c2d20c..a1944d4 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -36,7 +36,7 @@ steps: - The only downside to this is that set up will take a little longer since the exact version will have to be downloaded if the exact version is not already installed on the runner due to more recent versions. - MSI installers are used on Windows for this, so runs will take a little longer to set up vs MacOS and Linux. -You should specify **only a major and minor version** if you are okay with the most recent patch version being used: +You can specify **only a major and minor version** if you are okay with the most recent patch version being used: ```yaml steps: @@ -72,7 +72,7 @@ steps: - run: python my_script.py ``` -You can also use several types of ranges that are specified in [Semantic Versioning Specification](https://github.com/npm/node-semver#ranges), for instance: +You can also use several types of ranges that are specified in [semver](https://github.com/npm/node-semver#ranges), for instance: - **[hyphen ranges](https://github.com/npm/node-semver#hyphen-ranges-xyz---abc)** to download and set up the latest available version of Python (includes both pre-release and stable versions): @@ -95,14 +95,13 @@ steps: python-version: '3.x' - run: python my_script.py ``` -Please refer to the [Advanced range syntax section](https://github.com/npm/node-semver#advanced-range-syntax) of the [Semantic Versioning Specification](https://github.com/npm/node-semver) to check other available range syntaxes. +Please refer to the [Advanced range syntax section](https://github.com/npm/node-semver#advanced-range-syntax) of the [semver](https://github.com/npm/node-semver) to check other available range syntaxes. ## Specifying a PyPy version The version of PyPy should be specified in the format `pypy[-v]` or `pypy-[-v]`. The `-v` parameter is optional and can be skipped. The latest PyPy version will be used in this case. ``` -pypy3.7 or pypy-3.7 # the latest available version of PyPy that supports Python 3.7 pypy3.8 or pypy-3.8 # the latest available version of PyPy that supports Python 3.8 pypy2.7 or pypy-2.7 # the latest available version of PyPy that supports Python 2.7 pypy3.7-v7.3.3 or pypy-3.7-v7.3.3 # Python 3.7 and PyPy 7.3.3 @@ -122,7 +121,6 @@ jobs: python-version: - 'pypy3.7' # the latest available version of PyPy that supports Python 3.7 - 'pypy3.7-v7.3.3' # Python 3.7 and PyPy 7.3.3 - - 'pypy3.8' # the latest available version of PyPy that supports Python 3.8 steps: - uses: actions/checkout@v3 - uses: actions/setup-python@v4 @@ -130,7 +128,7 @@ jobs: python-version: ${{ matrix.python-version }} - run: python my_script.py ``` -More details on PyPy syntax and examples of using preview / nightly versions of PyPy can be found in the [Available versions of PyPy](#pypy) section. +More details on PyPy syntax can be found in the [Available versions of PyPy](#pypy) section. ## Matrix Testing @@ -239,17 +237,6 @@ steps: - run: poetry install - run: poetry run pytest ``` -**Using wildcard patterns to cache dependencies** -```yaml -steps: -- uses: actions/checkout@v3 -- uses: actions/setup-python@v4 - with: - python-version: '3.9' - cache: 'pip' - cache-dependency-path: '**/requirements-dev.txt' -- run: pip install -r subdirectory/requirements-dev.txt -``` **Using a list of file paths to cache dependencies** ```yaml @@ -266,6 +253,17 @@ steps: run: curl https://raw.githubusercontent.com/pypa/pipenv/master/get-pipenv.py | python - run: pipenv install ``` +**Using wildcard patterns to cache dependencies** +```yaml +steps: +- uses: actions/checkout@v3 +- uses: actions/setup-python@v4 + with: + python-version: '3.9' + cache: 'pip' + cache-dependency-path: '**/requirements-dev.txt' +- run: pip install -r subdirectory/requirements-dev.txt +``` **Using a list of wildcard patterns to cache dependencies** ```yaml @@ -287,7 +285,7 @@ steps: ### `python-version` -Using **python-version** output it's possible to get the installed by action python's version. This output is useful when the input `python-version` given as a range (e.g. 3.8.0 - 3.10.0 ), but down in a workflow you need to operate with exact installed version (e.g. 3.10.1). +Using **python-version** output it's possible to get the installed by action Pytho/PyPy version. This output is useful when the input `python-version` given as a range (e.g. 3.8.0 - 3.10.0 ), but down in a workflow you need to operate with the exact installed version (e.g. 3.10.1). ```yaml jobs: @@ -304,7 +302,7 @@ jobs: ### `python-path` -**python-path** output is available with the absolute path of the python interpreter executable if you need it: +**python-path** output is available with the absolute path of the Python/PyPy interpreter executable if you need it: ```yaml jobs: @@ -318,12 +316,29 @@ jobs: python-version: "3.10" - run: pipx run --python '${{ steps.cp310.outputs.python-path }}' nox --version ``` +### `cache-hit` + +**cache-hit** output is available with a boolean value that indicates whether a cache hit occured on the primary key: + +``` +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + id: cp310 + with: + python-version: "3.8.0" + cache: "poetry" + - run: echo '${{ steps.cp310.outputs.cache-hit }}' # true if cache-hit occured on the primary key +``` ## Evironment variables These environment variables become available after setup-python action execution: -| Env.Variable | Description | +| **Env.variable** | **Description** | | ----------- | ----------- | | pythonLocation |Contains the absolute path to the folder where the requested version of Python or PyPy is installed| | Python_ROOT_DIR | https://cmake.org/cmake/help/latest/module/FindPython.html#module:FindPython | @@ -333,10 +348,10 @@ These environment variables become available after setup-python action execution ## Using `update-environment` flag The `update-environment` flag defaults to `true`. -With this setting, the action will add/update environment variables (e.g. `PATH`, `PKG_CONFIG_PATH`, `pythonLocation`) for `python` to just work out of the box. +With this setting, the action will add/update environment variables (e.g. `PATH`, `PKG_CONFIG_PATH`, `pythonLocation`) for Python/PyPy to just work out of the box. If `update-environment` is set to `false`, the action will not add/update environment variables. -This can prove useful if you want the only side-effect to be to ensure python is installed and rely on the `python-path` output to run python. +This can prove useful if you want the only side-effect to be to ensure Python/PyPy is installed and rely on the `python-path` output to run executable. Such a requirement on side-effect could be because you don't want your composite action messing with your user's workflows. ```yaml @@ -382,7 +397,7 @@ Such a requirement on side-effect could be because you don't want your composite # Hosted tool cache -GitHub hosted runners have a tool cache that comes with a few versions of Python + PyPy already installed. This tool cache helps speed up runs and tool setup by not requiring any new downloads. There is an environment variable called `RUNNER_TOOL_CACHE` on each runner that describes the location of this tool cache and there is where you will find Python and PyPy installed. `setup-python` works by taking a specific version of Python or PyPy in this tool cache and adding it to PATH. +GitHub hosted runners have a tool cache that comes with a few versions of Python + PyPy already installed. This tool cache helps speed up runs and tool setup by not requiring any new downloads. There is an environment variable called `RUNNER_TOOL_CACHE` on each runner that describes the location of the tool cache with Python and PyPy installed. `setup-python` works by taking a specific version of Python or PyPy from this tool cache and adding it to PATH. || Location | |------|-------|