Skip to content

Commit

Permalink
Improve Advanced Usage examples (#645)
Browse files Browse the repository at this point in the history 
* docs: fix outputs python-version example and description

Description was lacking words, example was misleading (id was set to cp310 which clearly was a reference to CPython 3.10, but the id is referring to the setup-python action!

* docs: copy-editing in advanced-usage.md

Signed-off-by: Stephen L. <[email protected]>

* docs: add example if statement in advanced-usage.md

Signed-off-by: Stephen L. <[email protected]>

* docs: implement changes suggested by @mahabaleshwars (deprecate pypy2.7, 3.7, 3.8, tweak example, remove wildcard *)

Signed-off-by: Stephen L. <[email protected]>

---------

Signed-off-by: Stephen L. <[email protected]>
Signed-off-by: Stephen L. <[email protected]>
  • Loading branch information
@lrq3000
lrq3000 authored Jan 27, 2025
1 parent 709bfa5 commit 4237552
Showing 1 changed file with 18 additions and 17 deletions.
35 changes: 18 additions & 17 deletions docs/advanced-usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ steps:
- run: python my_script.py
```
- **[x-ranges](https://github.com/npm/node-semver#x-ranges-12x-1x-12-)** to specify the latest stable version of Python (for specified major version):
- **[x-ranges](https://github.com/npm/node-semver#x-ranges-12x-1x-12-)** to specify the latest stable version of Python (for the specified major version):
```yaml
steps:
Expand All @@ -120,7 +120,6 @@ The `-v<pypy_version>` parameter is optional and can be skipped. The latest PyPy
```
pypy3.10 or pypy-3.10 # the latest available version of PyPy that supports Python 3.10
pypy3.9 or pypy-3.9 # the latest available version of PyPy that supports Python 3.9
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
pypy3.7-v7.x or pypy-3.7-v7.x # Python 3.7 and the latest available PyPy 7.x
pypy3.7-v7.3.3rc1 or pypy-3.7-v7.3.3rc1 # Python 3.7 and preview version of PyPy
Expand All @@ -145,7 +144,7 @@ jobs:
python-version: ${{ matrix.python-version }}
- run: python my_script.py
```
More details on PyPy syntax can be found in the [Available versions of PyPy](#pypy) section.
More details on the syntax for PyPy can be found in the [Available versions of PyPy](#pypy) section.

### Specifying multiple Python/PyPy versions
The python-version input can get multiple python/pypy versions. The last specified version will be used as a default one.
Expand Down Expand Up @@ -205,15 +204,15 @@ jobs:
### Matrix Testing
Using `setup-python` it's possible to use [matrix syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix) to install several versions of Python or PyPy:
Using `setup-python` it's possible to use the [matrix syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix) to install several versions of Python or PyPy:

```yaml
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ['3.x', 'pypy2.7', 'pypy3.8', 'pypy3.9' ]
python-version: ['3.x', 'pypy3.8', 'pypy3.9' ]
name: Python ${{ matrix.python-version }} sample
steps:
- uses: actions/checkout@v4
Expand All @@ -232,27 +231,29 @@ jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
python-version: ['3.7', '3.8', '3.9', '3.10', 'pypy2.7', 'pypy3.9']
python-version: ['3.9', '3.10', '3.11', 'pypy3.9']
exclude:
- os: macos-latest
python-version: '3.8'
python-version: '3.9'
- os: windows-latest
python-version: '3.8'
python-version: '3.9'
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Display Python version
if: ${{ matrix.python-version != 'pypy3.9' }} # Use single quotes in expressions for input `python-version`
run: python --version
```
## Using the `python-version-file` input

`setup-python` action can read Python or PyPy version from a version file. `python-version-file` input is used for specifying the path to the version file. If the file that was supplied to `python-version-file` input doesn't exist, the action will fail with error.
`setup-python` action can read the Python or PyPy version from a version file. `python-version-file` input is used to specify the path to the version file. If the file that was supplied to `python-version-file` input doesn't exist, the action will fail with an error.

>In case both `python-version` and `python-version-file` inputs are supplied, the `python-version-file` input will be ignored due to its lower priority.

Expand Down Expand Up @@ -289,7 +290,7 @@ steps:
check-latest: true
- run: python my_script.py
```
> Setting `check-latest` to `true` has performance implications as downloading `Python or PyPy` versions is slower than using cached versions.
> Setting `check-latest` to `true` impacts performance as downloading `Python or PyPy` versions is slower than using cached versions.


## Caching packages
Expand Down Expand Up @@ -383,7 +384,7 @@ steps:

### `python-version`

Using **python-version** output it's possible to get the installed by action Python or PyPy version. This output is useful when the input `python-version` is given as a range (e.g. 3.8.0 - 3.12.0 ), but down in a workflow you need to operate with the exact installed version (e.g. 3.12.1).
Using **python-version** output, it's possible to get the precise Python or PyPy version installed by the action. This output is useful when the input `python-version` is given as a range (e.g. 3.9.0 - 3.12.0, 3.x ), but down the line you need to operate (such as in an `if:` statement) with the exact installed version (e.g. 3.12.0).

```yaml
jobs:
Expand All @@ -394,13 +395,13 @@ jobs:
- uses: actions/setup-python@v5
id: cp312
with:
python-version: "3.8.0 - 3.12.0"
python-version: "3.9.0 - 3.12.0"
- run: echo '${{ steps.cp312.outputs.python-version }}'
```

### `python-path`

**python-path** output is available with the absolute path of the Python or PyPy interpreter executable if you need it:
**python-path** output is available to get the absolute path of the Python or PyPy interpreter executable:

```yaml
jobs:
Expand Down Expand Up @@ -449,7 +450,7 @@ 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 or 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 or PyPy is installed and rely on the `python-path` output to run executable.
This can prove useful if you only want the side-effect to ensure that Python or PyPy is installed and rely on the `python-path` output to run the executable.
Such a requirement on side-effect could be because you don't want your composite action messing with your user's workflows.

```yaml
Expand All @@ -469,7 +470,7 @@ Such a requirement on side-effect could be because you don't want your composite

- Preinstalled versions of Python in the tool cache on GitHub-hosted runners.
- For detailed information regarding the available versions of Python that are installed, see [Supported software](https://docs.github.com/en/actions/reference/specifications-for-github-hosted-runners#supported-software).
- For every minor version of Python, expect only the latest patch to be preinstalled.
- For every minor versions of Python, expect only the latest patch to be preinstalled.
- If `3.12.1` is installed for example, and `3.12.2` is released, expect `3.12.1` to be removed and replaced by `3.12.2` in the tool cache.
- If the exact patch version doesn't matter to you, specifying just the major and minor versions will get you the latest preinstalled patch version. In the previous example, the version spec `3.12` will use the `3.12.2` Python version found in the cache.
- Use `-dev` instead of a patch number (e.g., `3.14-dev`) to install the latest patch version release for a given minor version, *alpha and beta releases included*.
Expand Down Expand Up @@ -534,11 +535,11 @@ If you have a supported self-hosted runner and you would like to use `setup-pyth

### Linux

By default runner downloads and installs tools into the folder set up by `RUNNER_TOOL_CACHE` environment variable. The environment variable called `AGENT_TOOLSDIRECTORY` can be set to change this location for Linux self-hosted runners:
By default, the runner downloads and installs tools into the folder set up by `RUNNER_TOOL_CACHE` environment variable. The environment variable called `AGENT_TOOLSDIRECTORY` can be set to change this location for Linux self-hosted runners:
- In the same shell that your runner is using, type `export AGENT_TOOLSDIRECTORY=/path/to/folder`.
- More permanent way of setting the environment variable is to create an `.env` file in the same directory as your runner and to add `AGENT_TOOLSDIRECTORY=/path/to/folder`. This ensures the variable is always set if your runner is configured as a service.

If you're using a non-default tool cache directory be sure that the user starting the runner has write permission to the new tool cache directory. To check the current user and group that the runner belongs type `ls -l` inside the runner's root directory.
If you're using a non-default tool cache directory be sure that the user starting the runner has write permission to the new tool cache directory. To check the current user and group that the runner belongs, type `ls -l` inside the runner's root directory.

The runner can be granted write access to any directory using a few techniques:
- The user starting the runner is the owner, and the owner has write permission.
Expand Down

0 comments on commit 4237552

Please sign in to comment.