seapagan / poetry-plugin-check-yanked

A Poetry plugin to check for yanked packages in the poetry.lock file.

Poetry Plugin : Check for Yanked Packages

This is a plugin for the Poetry dependency management tool that adds a new command to check if any of the dependencies in the pyproject.toml file have been yanked.

This plugin was written to learn how to write a Poetry plugin and to scratch an itch I had for a tool like this. I have more ideas for features and improvements, and I welcome any contributions or suggestions.

• Installation
• Usage
  • Available options
  • Configuration
• Use as a GitHub Action
• Development setup and Contributing
• License
• Credits

Installation

The easiest way to install this Poetry plugin is via the self add command of Poetry.

poetry self add poetry-plugin-check-yanked

If you used pipx to install Poetry you can add the plugin via the pipx inject command.

pipx inject poetry poetry-plugin-check-yanked

Otherwise, if you used pip to install Poetry you can add the plugin packages via the pip install command.

pip install poetry-plugin-check-yanked

Usage

The plugin adds a new command to Poetry, check-yanked, which can be used to check if any of the dependencies in the pyproject.toml file have been yanked from PyPI by their maintainers. There is usually a pretty good reason for a package to be yanked, so it's a good idea to check for yanked packages in your project.

When you check for yanked packages, the plugin will download the latest metadata for each package in the poetry.lock file and check if any of them are yanked. If any are found, the command will return a non-zero exit code and list the yanked packages along with the reason for the yank. Once a specific package verison has been checked, it will be cached for a period of time (default 1 day) to minimize the number of requests to PyPI (and speed up future runs).

Note

This plugin uses the poetry.lock file to determine the exact versions of the dependencies to check, so it will also check for any yanked dependencies of the dependencies you have specified in the pyproject.toml file.

poetry check-yanked

The command will return a non-zero exit code if any dependencies have been yanked along with a list of the yanked dependencies and the reason for the yank.

Available options

• --full - Check each project dependency package again, even if it is already in the cache.
• --refresh - Refesh the entire cache and exit, no not check for yanked packages.
• --no-progress - Don't show the progress bar when checking for yanked packages, useful for CI/CD environments.
• --quiet - Don't show any output, just return a non-zero exit code if any dependencies are yanked.
• --verbose - Show more detailed output, including each dependency and it's yank status. This disables the progress bar.

Configuration

At this time, the only configuration option is the cache timeout, which is set to 1 day by default. This can be changed by adding a [tool.check-yanked] section to the pyproject.toml file with a cache_expiry key. This value is in seconds. and the default is 86400 (1 day). Future versions of the plugin will offer pre-defined cache times (e.g. 1 hour, 1 day, 1 week, etc.) as well as the ability to disable the cache entirely.

[tool.check-yanked]
cache_expiry = 3600 # 1 hour

Use as a GitHub Action

This plugin can be used as a GitHub Action to check for yanked packages automatically as part of your CI. Here is an example workflow:

name: Check for Yanked Packages

on: [push, pull_request]

jobs:
  check-yanked:
    runs-on: ubuntu-latest

    steps:
      - name: Run poetry check-yanked
        uses: seapagan/check-yanked-packages@v1

There are two optional inputs that can be used to configure the action:

• path - The path to the directory containing the poetry.lock file. This defaults to the root of the repository.
• python-version - The version of Python to use when running the action. This defaults to the latest version of Python 3.x available on the runner.
  • If you are using the actions/setup-python action, this will be ignored, and the version of Python installed by that will be used instead.

These can be set in the workflow file like so:

- name: Run poetry check-yanked
  uses: seapagan/check-yanked-packages@v1
  with:
    python-version: '3.10'
    path: 'path/to/directory'

See the check-yanked-packages action for more information on using this plugin as a GitHub Action. The cache-expiry option is not available when using the action, as the cache is not persisted between runs.

Development setup and Contributing

Check CONTRIBUTING.md for full instructions on how to set up the project for development, and CODE_OF_CONDUCT.md for the project code of conduct.

License

This project is released under the terms of the MIT license.

Credits

The original Python boilerplate for this package was created using Pymaker by Grant Ramsay