Feature: Add poetry as pre-commit hook (#2511)

* add pre-commit hooks for check & lock
* add pre-commit hook for export requirements.txt
* add pre-commit hooks to docs
* add pre-commit hook to check pre-commit-hooks.yaml file

Thanks @graingert and @asottile for pointing out the `files` constraint.
See discussion on #2511.

Co-authored-by: Thomas Grainger <tagrain@gmail.com>
Co-authored-by: Bjorn Neergaard <bjorn@neersighted.com>

.pre-commit-config.yaml

@@ -82,3 +82,8 @@ repos:
         additional_dependencies:
           - types-dataclasses
           - types-requests
+
+  - repo: https://github.com/pre-commit/pre-commit
+    rev: v2.13.0
+    hooks:
+      - id: validate_manifest

.pre-commit-hooks.yaml

+- id: poetry-check
+  name: poetry-check
+  description: run poetry check to validate config
+  entry: poetry check
+  language: python
+  language_version: python3
+  pass_filenames: false
+  files: '^.*/pyproject\.toml$'
+
+- id: poetry-lock
+  name: poetry-lock
+  description: run poetry lock to update lock file
+  entry: poetry lock
+  language: python
+  language_version: python3
+  pass_filenames: false
+
+- id: poetry-export
+  name: poetry-export
+  description: run poetry export to sync lock file with requirements.txt
+  entry: poetry export
+  language: python
+  language_version: python3
+  pass_filenames: false
+  files: '^.*/poetry\.lock$'
+  args: ["-f", "requirements.txt", "-o", "requirements.txt"]

docs/cli.md

@@ -529,6 +529,10 @@ As such, `exit` should be used to properly exit the shell and the virtual enviro
 The `check` command validates the structure of the `pyproject.toml` file
 and returns a detailed report if there are any errors.
 
+{{% note %}}
+This command is also available as a pre-commit hook. See [pre-commit hooks](/docs/pre-commit-hooks#poetry-check) for more information.
+{{% /note %}}
+
 ```bash
 poetry check
 ```
@@ -547,6 +551,7 @@ This command locks (without installing) the dependencies specified in `pyproject
 
 {{% note %}}
 By default, this will lock all dependencies to the latest available compatible versions. To only refresh the lock file, use the `--no-update` option.
+This command is also available as a pre-commit hook. See [pre-commit hooks](/docs/pre-commit-hooks#poetry-lock) for more information.
 {{% /note %}}
 
 ```bash
@@ -595,6 +600,7 @@ poetry export -f requirements.txt --output requirements.txt
 
 {{% note %}}
 Only the `requirements.txt` format is currently supported.
+This command is also available as a pre-commit hook. See [pre-commit hooks](/docs/pre-commit-hooks#poetry-export) for more information.
 {{% /note %}}
 
 ### Options

docs/pre-commit-hooks.md

+---
+title: "pre-commit hooks"
+draft: false
+type: docs
+layout: single
+
+menu:
+  docs:
+    weight: 120
+---
+
+# pre-commit hooks
+
+pre-commit is a framework for building and running
+[git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).
+See the official documentation for more information: [pre-commit.com](https://pre-commit.com/)
+
+This document provides a list of available pre-commit hooks provided by Poetry.
+
+
+{{% note %}}
+If you specify the `args:` for a hook in your `.pre-commit-config.yaml`,
+the defaults are overwritten. You must fully specify all arguments for
+your hook if you make use of `args:`.
+{{% /note %}}
+
+
+## poetry-check
+
+The `poetry-check` hook calls the `poetry check` command
+to make sure the poetry configuration does not get committed in a broken state.
+
+### Arguments
+
+The hook takes the same arguments as the poetry command.
+For more information see the [check command](/docs/cli#check).
+
+
+## poetry-lock
+
+The `poetry-lock` hook calls the `poetry lock` command
+to make sure the lock file is up-to-date when committing changes.
+
+### Arguments
+
+The hook takes the same arguments as the poetry command.
+For more information see the [lock command](/docs/cli#lock).
+
+
+## poetry-export
+
+The `poetry-export` hook calls the `poetry export` command
+to sync your `requirements.txt` file with your current dependencies.
+
+{{% note %}}
+It is recommended to run the [`poetry-lock`](#poetry-lock) hook prior to this one.
+{{% /note %}}
+
+### Arguments
+
+The hook takes the same arguments as the poetry command.
+For more information see the [export command](/docs/cli#export).
+
+The default arguments are `args: ["-f", "requirements.txt", "-o", "requirements.txt"]`,
+which will create/update the requirements.txt file in the current working directory.
+
+You may add `verbose: true` in your `.pre-commit-config.yaml` in order to output to the
+console:
+
+```yaml
+hooks:
+  - id: poetry-export
+    args: ["-f", "requirements.txt"]
+    verbose: true
+```
+
+Also, `--dev` can be added to `args` to write dev-dependencies to `requirements.txt`:
+
+```yaml
+hooks:
+  - id: poetry-export
+    args: ["--dev", "-f", "requirements.txt", "-o", "requirements.txt"]
+```
+
+
+## Usage
+
+For more information on how to use pre-commit please see the [official documentation](https://pre-commit.com/).
+
+A full `.pre-commit-config.yaml` example:
+
+```yaml
+repos:
+  - repo: https://github.com/python-poetry/poetry
+    rev: ''  # add version here
+    hooks:
+      - id: poetry-check
+      - id: poetry-lock
+      - id: poetry-export
+        args: ["-f", "requirements.txt", "-o", "requirements.txt"]
+```