Install Poetry Action: A Comprehensive Guide
Overview
The Install Poetry Action is a GitHub action designed to simplify the process of installing and configuring Poetry, a popular dependency management tool for Python. This action automates the setup of Poetry, making it an accessible tool for developers looking to leverage its capabilities without manual installation and configuration steps.
Key Features
- Automatic Installation: The action automatically installs Poetry on runners, adding necessary executables to the system path.
- Custom Configuration: Users can customize Poetry settings by specifying desired configurations directly in the workflow file.
- Version Control: Supports installing specific versions of Poetry, allowing flexibility and compatibility with existing projects.
- Compatibility: Fully tested on macOS and Ubuntu, with support for running on Windows with additional setup.
Usage
To use the Install Poetry Action within a GitHub workflow, a basic configuration can be added:
- name: Install Poetry
uses: snok/install-poetry@v1
For a more customized setup, users can specify additional configurations:
- name: Install and configure Poetry
uses: snok/install-poetry@v1
with:
version: 1.5.1
virtualenvs-create: true
virtualenvs-in-project: false
virtualenvs-path: ~/my-custom-path
installer-parallel: true
This flexibility allows developers to adapt the installation process to meet their specific needs.
Default Settings
The default settings for Install Poetry Action include:
- Latest Poetry version
- Virtual environments created by default
- Virtual environments stored outside the project directory
- Parallel installation enabled
These defaults provide a robust starting point for most projects.
Examples and Best Practices
Basic Testing Workflow
A simple workflow to run tests using Poetry might look like this:
name: test
on: pull_request
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up python
uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install Poetry
uses: snok/install-poetry@v1
- name: Install dependencies
run: poetry install --no-root
- name: Run tests
run: |
source .venv/bin/activate
pytest tests/
Advanced Testing with Matrices
To test across multiple environments, a matrix setup can be used:
name: test
on: pull_request
jobs:
test:
strategy:
matrix:
os: [ "ubuntu-latest", "macos-latest" ]
python-version: [ "3.8", "3.9", "3.12" ]
runs-on: ${{ matrix.os }}
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up python
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install Poetry
uses: snok/install-poetry@v1
- name: Run tests
run: |
source .venv/bin/activate
pytest tests/
Caching
To improve performance, both poetry installations and dependencies can be cached. This reduces the need for repeated downloads and speeds up the process:
- name: Load cached Poetry installation
uses: actions/cache@v4
with:
path: ~/.local
key: poetry-cache
Running on Windows
When running on Windows, it is important to set the default shell to bash and manage different folder structures across operating systems:
defaults:
run:
shell: bash
Custom environment variables can facilitate this setup across different environments.
Installation of Plugins
For versions 1.2 and later, Poetry plugins can be installed as part of the action:
- uses: snok/install-poetry@v1
with:
plugins: poetry-plugin-a poetry-plugin-b
Conclusion
The Install Poetry Action is a powerful tool for automating Python dependency management, making it easier to implement, configure, and maintain robust workflows on GitHub. Whether a project requires basic setup or complex matrix testing, this action provides the necessary support with flexibility and efficiency. For contributions, the project welcomes PR submissions, and it is licensed under the MIT license for wide usability. Don't forget to star the repository if you find it useful!