# poetry-plugin-hook
[](https://pypi.org/project/poetry-plugin-hook/)
[](https://pypi.org/project/poetry-plugin-hook/)
[](https://pypi.org/project/poetry-plugin-hook/)
[](https://raw.githubusercontent.com/d-chris/poetry-plugin-hook/main/LICENSE)
[](https://github.com/d-chris/poetry-plugin-hook/actions/workflows/pytest.yml)
[](https://d-chris.github.io/poetry-plugin-hook)
[](https://github.com/d-chris/poetry-plugin-hook)
[](https://raw.githubusercontent.com/d-chris/poetry-plugin-hook/main/.pre-commit-config.yaml)
[](https://codecov.io/gh/d-chris/poetry-plugin-hook)
---
[`poetry`](https://python-poetry.org/) plugin to register wrapped commands to use as [`pre-commit-hooks`](https://pre-commit.com/). all hook commands return zero on success and non-zero on failure.
## install
```cmd
$ pip install poetry-plugin-hook
```
or with `poetry`
> Especially on [Windows](https://python-poetry.org/docs/cli/#self), self commands that update or remove packages may be problematic.
```cmd
$ poetry self add poetry-plugin-hook
```
## hook bump
Extends `poetry version` command, to also bump `__version__` strings in python files.
```cmd
$ poetry hook bump --help
Description:
Update the version in pyproject.toml and synchronize it into files.
Usage:
hook bump [options] [--] [<version>]
Arguments:
version The version number or the rule to update the version.
Options:
-f, --file=FILE Specify the files to update the __version__ string. [default: ["__init__.py"]] (multiple values allowed)
--dry-run Do not update pyproject.toml file
--next-phase Increment the phase of the current version
-h, --help Display help for the given command. When no command is given display help for the list command.
-q, --quiet Do not output any message.
-V, --version Display this application version.
--ansi Force ANSI output.
--no-ansi Disable ANSI output.
-n, --no-interaction Do not ask any interactive question.
--no-plugins Disables plugins.
--no-cache Disables Poetry source caches.
-C, --directory=DIRECTORY The working directory for the Poetry command (defaults to the current working directory).
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.
Help:
Update the version from package and also bumps __version__ strings in any given file.
poetry hook bump --next-phase patch --file __init__.py
The new version should ideally be a valid semver string or a valid bump rule:
patch, minor, major, prepatch, preminor, premajor, prerelease.
If no next-phase or version is provied the version from the pyproject.toml file will be
synced into the files.
```
## hook latest
Wrapper for `poetry show -o -T` command.
Exit code represents the number of outdated packages.
```cmd
$ poetry hook latest --help
Description:
Check if all top-level dependencies are up-to-date.
Usage:
hook latest [options] [--] [<package>]
Arguments:
package The package to inspect
Options:
--without=WITHOUT The dependency groups to ignore. (multiple values allowed)
--with=WITH The optional dependency groups to include. (multiple values allowed)
--only=ONLY The only dependency groups to include. (multiple values allowed)
-l, --latest Show the latest version. (option is always True)
-o, --outdated Show the latest version but only for packages that are outdated. (option is always True)
-T, --top-level Show only top-level dependencies. (option is always True)
-h, --help Display help for the given command. When no command is given display help for the list command.
-q, --quiet Do not output any message.
-V, --version Display this application version.
--ansi Force ANSI output.
--no-ansi Disable ANSI output.
-n, --no-interaction Do not ask any interactive question.
--no-plugins Disables plugins.
--no-cache Disables Poetry source caches.
-C, --directory=DIRECTORY The working directory for the Poetry command (defaults to the current working directory).
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.
Help:
To check if all top-level dependencies of your package are up-to-date
poetry hook latest --only=main
If a specific package is outdated
poetry hook latest <package>
```
## hook sync
Wrapper for `poetry install --sync` command.
With `--exit` option, the command returns the corresponding value as exit code. With it's default `--exit=any` the sum of *installs*, *updates* and *removals* is returned.
```cmd
$ poetry hook sync --help
Description:
Synchronize the environment with the locked packages and the specified groups.
Usage:
hook sync [options]
Options:
--exit=EXIT Specify the value to return as exitcode. choices=['any', 'installs', 'updates', 'removals'] [default: "any"]
--without=WITHOUT The dependency groups to ignore. (multiple values allowed)
--with=WITH The optional dependency groups to include. (multiple values allowed)
--only=ONLY The only dependency groups to include. (multiple values allowed)
--sync Synchronize the environment with the locked packages and the specified groups. (option is always True)
--no-root Do not install the root package (the current project).
--no-directory Do not install any directory path dependencies; useful to install dependencies without source code, e.g. for caching of Docker layers)
--dry-run Output the operations but do not execute anything (implicitly enables --verbose).
-E, --extras=EXTRAS Extra sets of dependencies to install. (multiple values allowed)
--all-extras Install all extra dependencies.
--only-root Exclude all dependencies.
-h, --help Display help for the given command. When no command is given display help for the list command.
-q, --quiet Do not output any message.
-V, --version Display this application version.
--ansi Force ANSI output.
--no-ansi Disable ANSI output.
-n, --no-interaction Do not ask any interactive question.
--no-plugins Disables plugins.
--no-cache Disables Poetry source caches.
-C, --directory=DIRECTORY The working directory for the Poetry command (defaults to the current working directory).
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.
Help:
To check if your environment is synchronized without making any changes
poetry hook sync --dry-run
```
## pre-commit-config
Add the following to your `.pre-commit-config.yaml` file.
```yaml
default_install_hook_types:
- pre-commit
- pre-push
default_stages:
- pre-commit
repos:
- repo: https://github.com/d-chris/poetry-plugin-hook
rev: v1.2.1
hooks:
- id: poetry-hook-bump
- id: poetry-hook-latest
args: ["--only=main"]
- id: poetry-hook-sync
args: ["--dry-run"]
```
### usage
1. Make sure pre-commit is installed, see [official documentation](https://pre-commit.com/#installation).
```cmd
$ pre-commit --version
pre-commit 3.7.1
```
2. `cd` into your project and register hooks and install them. this may take a while.
```cmd
$ pre-commit install --install-hooks
pre-commit installed at .git\hooks\pre-commit
pre-commit installed at .git\hooks\pre-push
```
3. Test the pre-push hook.
```cmd
$ pre-commit run poetry-hook-latest --all-files --hook-stage pre-push
poetry-hook-latest.......................................................Failed
- hook id: poetry-hook-latest
- exit code: 1
pytest-cov 5.0.0 6.0.0 Pytest plugin for measuring coverage.
```
4. Test the pre-commit hooks.
```cmd
$ pre-commit run poetry-hook-sync --all-files
poetry-hook-sync.........................................................Failed
- hook id: poetry-hook-sync
- exit code: 1
Installing dependencies from lock file
Package operations: 0 installs, 1 update, 0 removals
- Downgrading pytest-cov (6.0.0 -> 5.0.0)
Installing the current project: poetry-plugin-hook (0.0.0)
```
## pre-commit-hooks
```yaml
- id: poetry-hook-bump
name: poetry-hook-bump
description: Bump the version of the package and also in files.
entry: poetry hook bump
language: system
pass_filenames: false
always_run: true
stages: [pre-push]
- id: poetry-hook-latest
name: poetry-hook-latest
description: Check if all top-level dependencies are up-to-date.
entry: poetry hook latest
language: system
pass_filenames: false
always_run: true
stages: [pre-push]
- id: poetry-hook-sync
name: poetry-hook-sync
description: Synchronize the environment with the locked packages and the specified groups.
entry: poetry hook sync
language: system
pass_filenames: false
files: ^(.*/)?(poetry\.lock|pyproject\.toml)$
```
## Dependencies
[](https://pypi.org/project/cleo/)
[](https://pypi.org/project/poetry/)
---
Raw data
{
"_id": null,
"home_page": null,
"name": "poetry-plugin-hook",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "poetry, pre-commit, plugin, hook",
"author": "Christoph D\u00f6rrer",
"author_email": "d-chris@web.de",
"download_url": "https://files.pythonhosted.org/packages/ad/8a/67ea2a4faab168c56d55fdefb7df675f9a2b11bbe4f3d6ce7406efddcc68/poetry_plugin_hook-1.3.0.tar.gz",
"platform": null,
"description": "# poetry-plugin-hook\n\n[](https://pypi.org/project/poetry-plugin-hook/)\n[](https://pypi.org/project/poetry-plugin-hook/)\n[](https://pypi.org/project/poetry-plugin-hook/)\n[](https://raw.githubusercontent.com/d-chris/poetry-plugin-hook/main/LICENSE)\n[](https://github.com/d-chris/poetry-plugin-hook/actions/workflows/pytest.yml)\n[](https://d-chris.github.io/poetry-plugin-hook)\n[](https://github.com/d-chris/poetry-plugin-hook)\n[](https://raw.githubusercontent.com/d-chris/poetry-plugin-hook/main/.pre-commit-config.yaml)\n[](https://codecov.io/gh/d-chris/poetry-plugin-hook)\n\n---\n\n[`poetry`](https://python-poetry.org/) plugin to register wrapped commands to use as [`pre-commit-hooks`](https://pre-commit.com/). all hook commands return zero on success and non-zero on failure.\n\n## install\n\n```cmd\n$ pip install poetry-plugin-hook\n```\n\nor with `poetry`\n\n> Especially on [Windows](https://python-poetry.org/docs/cli/#self), self commands that update or remove packages may be problematic.\n\n```cmd\n$ poetry self add poetry-plugin-hook\n```\n\n## hook bump\n\nExtends `poetry version` command, to also bump `__version__` strings in python files.\n\n```cmd\n$ poetry hook bump --help\n\n Description:\n Update the version in pyproject.toml and synchronize it into files.\n\n Usage:\n hook bump [options] [--] [<version>]\n\n Arguments:\n version The version number or the rule to update the version.\n\n Options:\n -f, --file=FILE Specify the files to update the __version__ string. [default: [\"__init__.py\"]] (multiple values allowed)\n --dry-run Do not update pyproject.toml file\n --next-phase Increment the phase of the current version\n -h, --help Display help for the given command. When no command is given display help for the list command.\n -q, --quiet Do not output any message.\n -V, --version Display this application version.\n --ansi Force ANSI output.\n --no-ansi Disable ANSI output.\n -n, --no-interaction Do not ask any interactive question.\n --no-plugins Disables plugins.\n --no-cache Disables Poetry source caches.\n -C, --directory=DIRECTORY The working directory for the Poetry command (defaults to the current working directory).\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.\n\n Help:\n Update the version from package and also bumps __version__ strings in any given file.\n\n poetry hook bump --next-phase patch --file __init__.py\n\n The new version should ideally be a valid semver string or a valid bump rule:\n patch, minor, major, prepatch, preminor, premajor, prerelease.\n\n If no next-phase or version is provied the version from the pyproject.toml file will be\n synced into the files.\n```\n\n## hook latest\n\nWrapper for `poetry show -o -T` command.\n\nExit code represents the number of outdated packages.\n\n```cmd\n$ poetry hook latest --help\n\n Description:\n Check if all top-level dependencies are up-to-date.\n\n Usage:\n hook latest [options] [--] [<package>]\n\n Arguments:\n package The package to inspect\n\n Options:\n --without=WITHOUT The dependency groups to ignore. (multiple values allowed)\n --with=WITH The optional dependency groups to include. (multiple values allowed)\n --only=ONLY The only dependency groups to include. (multiple values allowed)\n -l, --latest Show the latest version. (option is always True)\n -o, --outdated Show the latest version but only for packages that are outdated. (option is always True)\n -T, --top-level Show only top-level dependencies. (option is always True)\n -h, --help Display help for the given command. When no command is given display help for the list command.\n -q, --quiet Do not output any message.\n -V, --version Display this application version.\n --ansi Force ANSI output.\n --no-ansi Disable ANSI output.\n -n, --no-interaction Do not ask any interactive question.\n --no-plugins Disables plugins.\n --no-cache Disables Poetry source caches.\n -C, --directory=DIRECTORY The working directory for the Poetry command (defaults to the current working directory).\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.\n\n Help:\n To check if all top-level dependencies of your package are up-to-date\n poetry hook latest --only=main\n\n If a specific package is outdated\n poetry hook latest <package>\n```\n\n## hook sync\n\nWrapper for `poetry install --sync` command.\n\nWith `--exit` option, the command returns the corresponding value as exit code. With it's default `--exit=any` the sum of *installs*, *updates* and *removals* is returned.\n\n```cmd\n$ poetry hook sync --help\n\n Description:\n Synchronize the environment with the locked packages and the specified groups.\n\n Usage:\n hook sync [options]\n\n Options:\n --exit=EXIT Specify the value to return as exitcode. choices=['any', 'installs', 'updates', 'removals'] [default: \"any\"]\n --without=WITHOUT The dependency groups to ignore. (multiple values allowed)\n --with=WITH The optional dependency groups to include. (multiple values allowed)\n --only=ONLY The only dependency groups to include. (multiple values allowed)\n --sync Synchronize the environment with the locked packages and the specified groups. (option is always True)\n --no-root Do not install the root package (the current project).\n --no-directory Do not install any directory path dependencies; useful to install dependencies without source code, e.g. for caching of Docker layers)\n --dry-run Output the operations but do not execute anything (implicitly enables --verbose).\n -E, --extras=EXTRAS Extra sets of dependencies to install. (multiple values allowed)\n --all-extras Install all extra dependencies.\n --only-root Exclude all dependencies.\n -h, --help Display help for the given command. When no command is given display help for the list command.\n -q, --quiet Do not output any message.\n -V, --version Display this application version.\n --ansi Force ANSI output.\n --no-ansi Disable ANSI output.\n -n, --no-interaction Do not ask any interactive question.\n --no-plugins Disables plugins.\n --no-cache Disables Poetry source caches.\n -C, --directory=DIRECTORY The working directory for the Poetry command (defaults to the current working directory).\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.\n\n Help:\n To check if your environment is synchronized without making any changes\n poetry hook sync --dry-run\n```\n\n## pre-commit-config\n\nAdd the following to your `.pre-commit-config.yaml` file.\n\n```yaml\ndefault_install_hook_types:\n - pre-commit\n - pre-push\ndefault_stages:\n - pre-commit\nrepos:\n - repo: https://github.com/d-chris/poetry-plugin-hook\n rev: v1.2.1\n hooks:\n - id: poetry-hook-bump\n - id: poetry-hook-latest\n args: [\"--only=main\"]\n - id: poetry-hook-sync\n args: [\"--dry-run\"]\n```\n\n### usage\n\n1. Make sure pre-commit is installed, see [official documentation](https://pre-commit.com/#installation).\n ```cmd\n $ pre-commit --version\n\n pre-commit 3.7.1\n ```\n2. `cd` into your project and register hooks and install them. this may take a while.\n ```cmd\n $ pre-commit install --install-hooks\n\n pre-commit installed at .git\\hooks\\pre-commit\n pre-commit installed at .git\\hooks\\pre-push\n ```\n3. Test the pre-push hook.\n ```cmd\n $ pre-commit run poetry-hook-latest --all-files --hook-stage pre-push\n\n poetry-hook-latest.......................................................Failed\n - hook id: poetry-hook-latest\n - exit code: 1\n\n pytest-cov 5.0.0 6.0.0 Pytest plugin for measuring coverage.\n ```\n4. Test the pre-commit hooks.\n ```cmd\n $ pre-commit run poetry-hook-sync --all-files\n\n poetry-hook-sync.........................................................Failed\n - hook id: poetry-hook-sync\n - exit code: 1\n\n Installing dependencies from lock file\n\n Package operations: 0 installs, 1 update, 0 removals\n\n - Downgrading pytest-cov (6.0.0 -> 5.0.0)\n\n Installing the current project: poetry-plugin-hook (0.0.0)\n ```\n\n## pre-commit-hooks\n\n```yaml\n- id: poetry-hook-bump\n name: poetry-hook-bump\n description: Bump the version of the package and also in files.\n entry: poetry hook bump\n language: system\n pass_filenames: false\n always_run: true\n stages: [pre-push]\n- id: poetry-hook-latest\n name: poetry-hook-latest\n description: Check if all top-level dependencies are up-to-date.\n entry: poetry hook latest\n language: system\n pass_filenames: false\n always_run: true\n stages: [pre-push]\n- id: poetry-hook-sync\n name: poetry-hook-sync\n description: Synchronize the environment with the locked packages and the specified groups.\n entry: poetry hook sync\n language: system\n pass_filenames: false\n files: ^(.*/)?(poetry\\.lock|pyproject\\.toml)$\n```\n\n## Dependencies\n\n[](https://pypi.org/project/cleo/)\n[](https://pypi.org/project/poetry/)\n\n---\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "poetry plugin to register wrapped commands to use as pre-commit-hooks",
"version": "1.3.0",
"project_urls": {
"documentation": "https://d-chris.github.io/poetry-plugin-hook",
"repository": "https://github.com/d-chris/poetry-plugin-hook"
},
"split_keywords": [
"poetry",
" pre-commit",
" plugin",
" hook"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1f6dced301007ab02dd1c3e2ebe85e3eca0b6d115dfdd3199294a5b7ea2528c0",
"md5": "bdfc39f616abae29f17d8ead368c117a",
"sha256": "2ac1c4054260e008e070643ecf682cfe4693fe76b6ab66014bf9619466a19a9e"
},
"downloads": -1,
"filename": "poetry_plugin_hook-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bdfc39f616abae29f17d8ead368c117a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 10943,
"upload_time": "2024-11-24T11:32:32",
"upload_time_iso_8601": "2024-11-24T11:32:32.799417Z",
"url": "https://files.pythonhosted.org/packages/1f/6d/ced301007ab02dd1c3e2ebe85e3eca0b6d115dfdd3199294a5b7ea2528c0/poetry_plugin_hook-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ad8a67ea2a4faab168c56d55fdefb7df675f9a2b11bbe4f3d6ce7406efddcc68",
"md5": "87e48fb052ca8842f8adedcedd407ad5",
"sha256": "0012574c7eeccc67a623b4c783ea34079e0efb76ca06b638fe3ac7d4dfabbabd"
},
"downloads": -1,
"filename": "poetry_plugin_hook-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "87e48fb052ca8842f8adedcedd407ad5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 10617,
"upload_time": "2024-11-24T11:32:33",
"upload_time_iso_8601": "2024-11-24T11:32:33.744284Z",
"url": "https://files.pythonhosted.org/packages/ad/8a/67ea2a4faab168c56d55fdefb7df675f9a2b11bbe4f3d6ce7406efddcc68/poetry_plugin_hook-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-24 11:32:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "d-chris",
"github_project": "poetry-plugin-hook",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "poetry-plugin-hook"
}
JSON
