mirror of
https://github.com/actions/setup-python.git
synced 2024-09-20 06:40:03 +07:00
8b89ef08a0
* Use correct Poetry config when collecting Poetry projects When collecting Poetry projects for caching, a '**/poetry.lock' glob is used. However, in order to process the Poetry configuration, the "poetry" command is run from the repo's root directory; this causes Poetry to return an invalid configuration when there is a Poetry project inside an inner directory. Instead of running a single Poetry command, glob for the same pattern, and run a Poetry command for every discovered project. * Fix typo: saveSatetSpy -> saveStateSpy * poetry: Support same virtualenv appearing in multiple projects * Add nested Poetry projects test * poetry: Set up environment for each project individually * tests/cache-restore: Do not look for dependency files outside `data` When the default dependency path is used for cache distributors, they are looking for the dependency file in the project's root (including the source code), which leads to tests taking a significant amount of time, especially on Windows runners. We thus hit sporadic test failures. Change the test cases such that dependency files are always searched for inside of `__tests__/data`, ignoring the rest of the project. * poetry: Simplify `virtualenvs.in-project` boolean check * README: Explain that poetry might create multiple caches * poetry: Run `poetry env use` only after cache is loaded The virtualenv cache might contain invalid entries, such as virtualenvs built in previous, buggy versions of this action. The `poetry env use` command will recreate virtualenvs in case they are invalid, but it has to be run only *after* the cache is loaded. Refactor `CacheDistributor` a bit such that the validation (and possible recreation) of virtualenvs happens only after the cache is loaded. * poetry: Bump cache primary key
96 lines
5.5 KiB
Markdown
96 lines
5.5 KiB
Markdown
# setup-python
|
|
|
|
<p align="left">
|
|
<a href="https://github.com/actions/setup-python"><img alt="GitHub Actions status" src="https://github.com/actions/setup-python/workflows/Main%20workflow/badge.svg"></a>
|
|
</p>
|
|
|
|
This action provides the following functionality for GitHub Actions users:
|
|
|
|
- Installing a version of Python or PyPy and (by default) adding it to the PATH
|
|
- Optionally caching dependencies for pip, pipenv and poetry
|
|
- Registering problem matchers for error output
|
|
|
|
## Basic usage
|
|
|
|
See [action.yml](action.yml)
|
|
|
|
**Python**
|
|
```yaml
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- uses: actions/setup-python@v4
|
|
with:
|
|
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.9'
|
|
- run: python my_script.py
|
|
```
|
|
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 or PyPy version from the PATH will be used. The default version of Python or PyPy in PATH varies between runners and can be changed unexpectedly so we recommend always setting Python version explicitly using the `python-version` or `python-version-file` inputs.
|
|
|
|
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/).
|
|
|
|
For information regarding locally cached versions of Python or PyPy on GitHub hosted runners, check out [GitHub Actions Runner Images](https://github.com/actions/runner-images).
|
|
|
|
## Supported version syntax
|
|
|
|
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-the-python-version-input) of the [Advanced usage](docs/advanced-usage.md) guide.
|
|
|
|
## Supported architectures
|
|
|
|
Using `architecture` input it is possible to specify the required Python or 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 [toolkit/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 that want to be used.
|
|
|
|
- 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 directories -- one for each poetry project found
|
|
|
|
**Caching pip dependencies:**
|
|
|
|
```yaml
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- uses: actions/setup-python@v4
|
|
with:
|
|
python-version: '3.9'
|
|
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 which can lead to an increase in total build time.
|
|
|
|
>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](docs/advanced-usage.md#caching-packages) of the [Advanced usage](docs/advanced-usage.md) guide.
|
|
|
|
## Advanced usage
|
|
|
|
- [Using the python-version input](docs/advanced-usage.md#using-the-python-version-input)
|
|
- [Using the python-version-file input](docs/advanced-usage.md#using-the-python-version-file-input)
|
|
- [Check latest version](docs/advanced-usage.md#check-latest-version)
|
|
- [Caching packages](docs/advanced-usage.md#caching-packages)
|
|
- [Outputs and environment variables](docs/advanced-usage.md#outputs-and-environment-variables)
|
|
- [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` on GHES](docs/advanced-usage.md#using-setup-python-on-ghes)
|
|
|
|
## License
|
|
|
|
The scripts and documentation in this project are released under the [MIT License](LICENSE).
|
|
|
|
## Contributions
|
|
|
|
Contributions are welcome! See our [Contributor's Guide](docs/contributors.md).
|