diff --git a/README.md b/README.md index 56cfaa0c..841d82a7 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ steps: python-version: 'pypy3.9' - run: python my_script.py ``` -The `python-version` input is optional. If not supplied, the action will try to resolve version from the default `.python-version` file. If `.python-version` file doesn't exist 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 `python-version` input is optional. If not supplied, the action will try to resolve the version from the default `.python-version` file. If the `.python-version` file doesn't exist Python/PyPy version from the PATH will be used. The default version of Python/PyPy in PATH varies between runners and can be changed unexpectedly so we recommend always using `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/). @@ -45,15 +45,15 @@ The `python-version` input supports the [Semantic Versioning Specification](http ## Supported architectures -Using `architecture` input it is possible to specify required Python/PyPy interpreter architecture: `x86` or `x64`. If input is not specified the architecture defaults to `x64`. +Using `architecture` input it is possible to specify the required Python/PyPy interpreter architecture: `x86` or `x64`. If the input is not specified the architecture defaults to `x64`. ## Caching packages dependencies The action has built-in functionality for caching and restoring dependencies. It uses [actions/cache](https://github.com/actions/toolkit/tree/main/packages/cache) under the hood for caching dependencies but requires less configuration settings. Supported package managers are `pip`, `pipenv` and `poetry`. The `cache` input is optional, and caching is turned off by default. -The action defaults to searching for a dependency file (`requirements.txt` for pip, `Pipfile.lock` for pipenv or `poetry.lock` for poetry) in the repository, and uses its hash as a part of the cache key. Input `cache-dependency-path` is used for cases when multiple dependency files are used, they are located in different subdirectories or different files for the hash want to be used. +The action defaults to searching for a dependency file (`requirements.txt` for pip, `Pipfile.lock` for pipenv or `poetry.lock` for poetry) in the repository, and uses its hash as a part of the cache key. Input `cache-dependency-path` is used for cases when multiple dependency files are used, they are located in different subdirectories or different files for the hash that want to be used. - - For `pip`, the action will cache global cache directory + - For `pip`, the action will cache the global cache directory - For `pipenv`, the action will cache virtualenv directory - For `poetry`, the action will cache virtualenv directory @@ -68,9 +68,9 @@ steps: cache: 'pip' # caching pip dependencies - run: pip install -r requirements.txt ``` ->**Note:** Restored cache will not be used if the requirements.txt file is not updated for a long time and a newer version of the dependency is available that can lead to an increase in total build time. +>**Note:** Restored cache will not be used if the requirements.txt file is not updated for a long time and a newer version of the dependency is available which can lead to an increase in total build time. ->The requirements file format allows to specify dependency versions using logical operators (for example chardet>=3.0.4) or specify dependencies without any versions. In this case the pip install -r requirements.txt command will always try to install the latest available package version. To be sure that the cache will be used, please stick to a specific dependency version and update it manually if necessary. +>The requirements file format allows for specifying dependency versions using logical operators (for example chardet>=3.0.4) or specifying dependencies without any versions. In this case the pip install -r requirements.txt command will always try to install the latest available package version. To be sure that the cache will be used, please stick to a specific dependency version and update it manually if necessary. See examples of using `cache` and `cache-dependency-path` for `pipenv` and `poetry` in the section: [Caching packages data](docs/advanced-usage.md#caching-packages-data) of the [Advanced usage](docs/advanced-usage.md) guide. @@ -83,7 +83,7 @@ See examples of using `cache` and `cache-dependency-path` for `pipenv` and `poet - [Environment variables and action's outputs](docs/advanced-usage.md#environment-variables-and-actions-outputs) - [Available versions of Python and PyPy](docs/advanced-usage.md#available-versions-of-python-and-pypy) - [Hosted tool cache](docs/advanced-usage.md#hosted-tool-cache) -- [Using `setup-python` with a self hosted runner](docs/advanced-usage.md#using-setup-python-with-a-self-hosted-runner) +- [Using `setup-python` with a self-hosted runner](docs/advanced-usage.md#using-setup-python-with-a-self-hosted-runner) - [Using `setup-python` on GHES](docs/advanced-usage.md#using-setup-python-on-ghes) ## License diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index e3f65437..4edb5495 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -1,21 +1,21 @@ # Table of contents -- [Using python-version input](#using-python-version-file-input) - - [Specifying a Python version](#specifying-a-python-version) - - [Specifying a PyPy version](#specifying-a-pypy-version) - - [Matrix Testing](#matrix-testing) -- [Using python-version-file input](#using-python-version-file-input) -- [Check latest version](#check-latest-version) -- [Caching packages data](#caching-packages-data) -- [Environment variables and action's outputs](#environment-variables-and-actions-outputs) -- [Available versions of Python and PyPy](#available-versions-of-python-and-pypy) - - [Python](#python) - - [PyPy](#pypy) -- [Hosted tool cache](#hosted-tool-cache) -- [Using `setup-python` with a self hosted runner](#using-setup-python-with-a-self-hosted-runner) - - [Windows](#windows) - - [Linux](#linux) - - [MacOS](#macos) -- [Using `setup-python` on GHES](#using-setup-python-on-ghes) +- [Using python-version input](advanced-usage.md#using-python-version-file-input) + - [Specifying a Python version](advanced-usage.md#specifying-a-python-version) + - [Specifying a PyPy version](advanced-usage.md#specifying-a-pypy-version) + - [Matrix Testing](advanced-usage.md#matrix-testing) +- [Using python-version-file input](advanced-usage.md#using-python-version-file-input) +- [Check latest version](advanced-usage.md#check-latest-version) +- [Caching packages data](advanced-usage.md#caching-packages-data) +- [Environment variables and action's outputs](advanced-usage.md#environment-variables-and-actions-outputs) +- [Available versions of Python and PyPy](advanced-usage.md#available-versions-of-python-and-pypy) + - [Python](advanced-usage.md#python) + - [PyPy](advanced-usage.md#pypy) +- [Hosted tool cache](advanced-usage.md#hosted-tool-cache) +- [Using `setup-python` with a self-hosted runner](advanced-usage.md#using-setup-python-with-a-self-hosted-runner) + - [Windows](advanced-usage.md#windows) + - [Linux](advanced-usage.md#linux) + - [MacOS](advanced-usage.md#macos) +- [Using `setup-python` on GHES](advanced-usage.md#using-setup-python-on-ghes) # Using python-version input @@ -33,7 +33,7 @@ steps: python-version: '3.7.5' - run: python my_script.py ``` - - 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. + - 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 can specify **only a major and minor version** if you are okay with the most recent patch version being used: @@ -48,9 +48,9 @@ steps: ``` - There will be a single patch version already installed on each runner for every minor version of Python that is supported. - The patch version that will be preinstalled, will generally be the latest and every time there is a new patch released, the older version that is preinstalled will be replaced. - - Using the most recent patch version will result in a very quick setup since no downloads will be required since a locally installed version Python on the runner will be used. + - Using the most recent patch version will result in a very quick setup since no downloads will be required since a locally installed version of Python on the runner will be used. -You can specify version with **prerelease tag** to download and set up an accurate pre-release version of Python: +You can specify the version with **prerelease tag** to download and set up an accurate pre-release version of Python: ```yaml steps: @@ -179,9 +179,9 @@ jobs: # Using python-version-file input -`setup-python` action has ability to read Python/PyPy version from a version file. `python-version-file` input is used for specifying path to the version file. If `.python-version` file doesn't exist, action will fail with error. +`setup-python` action can read Python/PyPy version from a version file. `python-version-file` input is used for specifying the path to the version file. If the `.python-version` file doesn't exist, the action will fail with an error. ->In case both `python-version` and `python-version-file` inputs are supplied, `python-version-file` input will be ignored due to its lower priority. +>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. ```yaml steps: @@ -285,7 +285,7 @@ steps: ### `python-version` -Using **python-version** output it's possible to get the installed by action Python/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). +Using **python-version** output it's possible to get the installed by action Python/PyPy version. This output is useful when the input `python-version` is 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: @@ -318,7 +318,7 @@ jobs: ``` ### `cache-hit` -**cache-hit** output is available with a boolean value that indicates whether a cache hit occured on the primary key: +**cache-hit** output is available with a boolean value that indicates whether a cache hit occurred on the primary key: ``` jobs: @@ -334,7 +334,7 @@ jobs: - run: echo '${{ steps.cp310.outputs.cache-hit }}' # true if cache-hit occured on the primary key ``` -## Evironment variables +## Environment variables These environment variables become available after setup-python action execution: @@ -373,13 +373,13 @@ Such a requirement on side-effect could be because you don't want your composite - 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. - If `3.8.1` is installed for example, and `3.8.2` is released, expect `3.8.1` to be removed and replaced by `3.8.2` in the tool cache. - - If the exact patch version doesn't matter to you, specifying just the major and minor version will get you the latest preinstalled patch version. In the previous example, the version spec `3.8` will use the `3.8.2` Python version found in the 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.8` will use the `3.8.2` Python version found in the cache. - Use `-dev` instead of a patch number (e.g., `3.11-dev`) to install the latest patch version release for a given minor version, *alpha and beta releases included*. - Downloadable Python versions from GitHub Releases ([actions/python-versions](https://github.com/actions/python-versions/releases)). - All available versions are listed in the [version-manifest.json](https://github.com/actions/python-versions/blob/main/versions-manifest.json) file. - If there is a specific version of Python that is not available, you can open an issue here ->**Note:** Python versions used in this action are generated in the [python-versions](https://github.com/actions/python-versions) repository. For macOS and Ubuntu images python versions are built from the source code. For Windows the python-versions repository uses installation executable. For more information please refer to the [python-versions](https://github.com/actions/python-versions) repository. +>**Note:** Python versions used in this action are generated in the [python-versions](https://github.com/actions/python-versions) repository. For MacOS and Ubuntu images, python versions are built from the source code. For Windows, the python-versions repository uses installation executable. For more information please refer to the [python-versions](https://github.com/actions/python-versions) repository. ## PyPy @@ -410,7 +410,7 @@ GitHub virtual environments are set up in [actions/virtual-environments](https:/ - Tool cache setup for Windows: [Install-Toolset.ps1](https://github.com/actions/virtual-environments/blob/main/images/win/scripts/Installers/Install-Toolset.ps1) [Configure-Toolset.ps1](https://github.com/actions/virtual-environments/blob/main/images/win/scripts/Installers/Configure-Toolset.ps1) -# Using `setup-python` with a self hosted runner +# Using `setup-python` with a self-hosted runner Python distributions are only available for the same [environments](https://github.com/actions/virtual-environments#available-environments) that GitHub Actions hosted environments are available for. If you are using an unsupported version of Ubuntu such as `19.04` or another Linux distribution such as Fedora, `setup-python` may not work. @@ -421,13 +421,13 @@ If you have a supported self-hosted runner and you would like to use `setup-pyth - Your runner needs to be running with administrator privileges so that the appropriate directories and files can be set up when downloading and installing a new version of Python for the first time. - If your runner is configured as a service, make sure the account that is running the service has the appropriate write permissions so that Python can get installed. The default `NT AUTHORITY\NETWORK SERVICE` should be sufficient. -- You need `7zip` installed and added to your `PATH` so that the downloaded versions of Python files can be extracted properly during first-time setup. +- You need `7zip` installed and added to your `PATH` so that the downloaded versions of Python files can be extracted properly during the first-time setup. - MSI installers are used when setting up Python on Windows. A word of caution as MSI installers update registry settings. - The 3.8 MSI installer for Windows will not let you install another 3.8 version of Python. If `setup-python` fails for a 3.8 version of Python, make sure any previously installed versions are removed by going to "Apps & Features" in the Settings app. > 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 Windows self-hosted runners. ->If you are experiencing problems while configuring Python on your self-hosted runner, turn on [step debugging](https://github.com/actions/toolkit/blob/main/docs/action-debugging.md#step-debug-logs) to see addition logs. +>If you are experiencing problems while configuring Python on your self-hosted runner, turn on [step debugging](https://github.com/actions/toolkit/blob/main/docs/action-debugging.md#step-debug-logs) to see additional logs. ## Linux @@ -435,7 +435,7 @@ By default runner downloads and installs tools into the folder set up by `RUNNER - 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 non-default tool cache directory be sure that the user starting the runner have write permission to the new tool cache directory. To check the current user and group that the runner belongs type `ls -l` inside the runners 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. @@ -450,12 +450,12 @@ One quick way to grant access is to change the user and group of the non-default ## MacOS - The Python packages for MacOS that are downloaded from `actions/python-versions` are originally compiled from source in `/Users/runner/hostedtoolcache`. Due to the fixed shared library path, these Python packages are non-relocatable and require to be installed only in `/Users/runner/hostedtoolcache`. Before use of `setup-python` on the MacOS self-hosted runner: + The Python packages for MacOS that are downloaded from `actions/python-versions` are originally compiled from the source in `/Users/runner/hostedtoolcache`. Due to the fixed shared library path, these Python packages are non-relocatable and require to be installed only in `/Users/runner/hostedtoolcache`. Before the use of `setup-python` on the MacOS self-hosted runner: - Create a directory called `/Users/runner/hostedtoolcache` - Change the permissions of `/Users/runner/hostedtoolcache` so that the runner has write access -You can check the current user and group that the runner belongs to by typing `ls -l` inside the runners root directory. +You can check the current user and group that the runner belongs to by typing `ls -l` inside the runner's root directory. The runner can be granted write access to the `/Users/runner/hostedtoolcache` directory using a few techniques: - The user starting the runner is the owner, and the owner has write permission - The user starting the runner is in the owning group, and the owning group has write permission @@ -469,6 +469,6 @@ One quick way to grant access is to change the user and group of `/Users/runner/ # Using `setup-python` on GHES -`setup-python` comes pre-installed on the appliance with GHES if Actions is enabled. When dynamically downloading Python distributions, `setup-python` downloads distributions from [`actions/python-versions`](https://github.com/actions/python-versions) on github.com (outside of the appliance). These calls to `actions/python-versions` are made via unauthenticated requests, which are limited to [60 requests per hour per IP](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting). If more requests are made within the time frame, then you will start to see rate-limit errors during download that read `##[error]API rate limit exceeded for...`. +`setup-python` comes pre-installed on the appliance with GHES if Actions is enabled. When dynamically downloading Python distributions, `setup-python` downloads distributions from [`actions/python-versions`](https://github.com/actions/python-versions) on github.com (outside of the appliance). These calls to `actions/python-versions` are made via unauthenticated requests, which are limited to [60 requests per hour per IP](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting). If more requests are made within the time frame, then you will start to see rate-limit errors during downloading that looks like: `##[error]API rate limit exceeded for...`. To avoid hitting rate-limit problems, we recommend [setting up your own runner tool cache](https://docs.github.com/en/enterprise-server@2.22/admin/github-actions/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access#about-the-included-setup-actions-and-the-runner-tool-cache).