feat!: use Poetry (#151)

* build: move to Poetry

First step - moving `pyproject.toml`.

* fix(build): include from `src/`

* fix(build): version variable

* fix(tools): ignore `.venv`

* chore(deps): separate Python and other deps

* build(deps): remove direct dep of `mypy-extensions`

Mypy itself already depends on it.

* build(deps): remove `toml`

* fix(deps): downgrade `semver`

Was incompatible with `python-semantic-release`

* build(deps): `poetry.lock`

* chore: `tool.ruff.target-version`

It doesn't understand Poetry's Python version setting.

* build(dev-deps): create linting group

* test: Nox with Poetry

* build(ci): Poetry pre-commit hooks

* build(ci): use Poetry

* build(ci): `poetry shell`

* build(ci): use `snok/install-poetry`

* build(ci): run on any PR, push to main

* build(ci): experimenting

* build(ci): force color

* build(ci): force color

* build(ci): remove redundant actions

* build(ci): Poetry `--ansi` results in spam

* build(ci): specify Python version

* chore: delete `constraints.txt`

* build(ci): move pre-commit inside Nox

* build(ci): don't install setuptools, wheel

* build(ci): pre-commit colors

* fix: Black wouldn't run if Ruff failed

* build(ci): workflows

* chore: `poetry.lock`

* build(cd): use PyPI Trusted Publishing

* build(docs): install with Poetry

* docs: Poetry

* chore: remove `semver` dep

* build(deps): update lockfile

* build: install Poetry to build

* build(release): write permissions

* 0.1.0

Automatically generated by python-semantic-release

* Revert "0.1.0"

This reverts commit 1ef6a06490382a95356be453072751a858da36d6.

* 0.1.0

Automatically generated by python-semantic-release

* Revert "0.1.0"

This reverts commit c6547ada54f35a9a9d8a055593c09f38b5c3b447.

* 0.1.0

Automatically generated by python-semantic-release

* docs(readme): fix action badge

* build(docs): fix Poetry install command

* build: fix URLs

* build: remove version classifiers, Poetry will add

* build(release): `build_command = "python -m build"`

* build(release): fix build command

* 0.1.1

Automatically generated by python-semantic-release

* chore: delete CHANGELOG.md

* chore: fix

---------

Co-authored-by: github-actions <[email protected]>

{{cookiecutter.project_distribution_name}}/.editorconfig

@@ -19,5 +19,9 @@ indent_size = 4
 indent_style = space
 indent_size = 2
 
+[*.{yml, yaml}]
+indent_style = space
+indent_size = 2
+
 [Makefile]
 indent_style = tab

{{cookiecutter.project_distribution_name}}/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+env:
+  FORCE_COLOR: 1
+  CLICOLOR_FORCE: 1  # https://github.com/astral-sh/ruff/issues/5499
+  PRE_COMMIT_COLOR: "always"  # https://github.com/pre-commit/pre-commit/issues/2918
+
+jobs:
+  Nox:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: snok/install-poetry@v1
+      - uses: daisylb/[email protected]
+      - run: nox

{{cookiecutter.project_distribution_name}}/.github/workflows/codecov_action.yml

@@ -10,21 +10,28 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python
-      uses: actions/setup-python@v4
-      with:
-        python-version: '3.11'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -c constraints.txt -e .[tests]
-    - name: Generate coverage report
-      run: |
-        pytest --cov --cov-report=xml
-    - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
-      with:
-        token: {{ "${{ secrets.CODECOV_TOKEN }}" }}
-        file: ./coverage.xml
-        flags: unittests
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-in-project: true
+
+      - name: Install project
+        run: poetry install --no-interaction --only=main,tests
+
+      - name: Generate coverage report
+        run: |
+          poetry run pytest --cov --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          token: ${{"{{"}} secrets.CODECOV_TOKEN {{"}}"}}
+          file: ./coverage.xml
+          flags: unittests

{{cookiecutter.project_distribution_name}}/.github/workflows/semantic-release.yml

@@ -1,22 +1,38 @@
 name: Semantic Release
 
 on:
-  workflow_run:
-    workflows: ["Test with Nox"]
-    branches: [main]
-    types:
-      - completed
+  push:
+    branches:
+      - main
+      - rc
 
 jobs:
-  release:
+  Release:
     runs-on: ubuntu-latest
+    concurrency: release
+
+    permissions:
+      id-token: write
+      contents: write
 
     steps:
-    - uses: actions/checkout@v3
-      with:
-        fetch-depth: 0
-    - name: Python Semantic Release
-      uses: python-semantic-release/python-semantic-release@master
-      with:
-        github_token: {{ "${{ secrets.GITHUB_TOKEN }}" }}
-        pypi_token: {{ "${{ secrets.PYPI_TOKEN }}" }}
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/[email protected]
+        with:
+          github_token: ${{"{{"}} secrets.GITHUB_TOKEN {{"}}"}}
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        if: steps.release.outputs.released == 'true'
+
+      - name: Publish package to GitHub
+        uses: python-semantic-release/upload-to-gh-release@main
+        if: steps.release.outputs.released == 'true'
+        with:
+          github_token: ${{"{{"}} secrets.GITHUB_TOKEN {{"}}"}}
+          tag: ${{"{{"}} steps.release.outputs.tag {{"}}"}}

{{cookiecutter.project_distribution_name}}/.pre-commit-config.yaml

@@ -8,6 +8,11 @@ repos:
     rev: '23.3.0'
     hooks:
     -   id: black
+-   repo: https://github.com/python-poetry/poetry
+    rev: '1.5.1'
+    hooks:
+    -   id: poetry-check
+    -   id: poetry-lock
 -   repo: https://github.com/pre-commit/pre-commit-hooks
     rev: 'v4.4.0'
     hooks:

{{cookiecutter.project_distribution_name}}/.readthedocs.yaml

@@ -4,6 +4,13 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.11"
+  jobs:
+    # https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-poetry
+    post_create_environment:
+      - pip install poetry
+      - poetry config virtualenvs.create false
+    post_install:
+      - poetry install --only main,docs --all-extras
 
 # Build from the docs/ directory with Sphinx
 sphinx:
@@ -12,11 +19,3 @@ sphinx:
 formats:
   - pdf
   - epub
-
-# Explicitly set the version of Python and its requirements
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs

{{cookiecutter.project_distribution_name}}/docs/CONTRIBUTING.md

@@ -63,7 +63,7 @@ Here is a summary of the steps to follow:
 ```bash
 $ git checkout main
 $ git pull upstream main
-$ pip install -U -c constraints.txt -e .[dev]
+$ poetry install --sync --all-extras
 ```
 3. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix:
 ```bash
@@ -103,7 +103,7 @@ To ensure consistency and quality, all documentation modifications must:
   - an external concept or feature, i.e. Create a [GitHub release](https://help.github.com/articles/creating-releases)
   - a package or module, i.e. The [`@{{ cookiecutter.__github_path }}`]({{ cookiecutter.__github_url }}) module
 - Use the [single backtick `code` quoting](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) for:
-  - commands inside sentences, i.e. the `pip` command
+  - commands inside sentences, i.e. the `poetry` command
   - programming language keywords, i.e. `for`, `with`, `dict`
   - packages or modules, i.e. The [`@{{ cookiecutter.__github_path }}`]({{ cookiecutter.__github_url }}) module
 - Use the [triple backtick `code` formatting](https://help.github.com/articles/creating-and-highlighting-code-blocks) for:
@@ -208,18 +208,8 @@ git clone {{ cookiecutter.__github_url }}
 # Navigate to the newly cloned directory
 cd {{ cookiecutter.project_distribution_name }}
 
-# Set up the virtual environment
-python -m venv venv
-# Replace `python` with `python3` if necessary
-
-# Activate the virtual environment (Unix)
-source venv/bin/activate
-
-# Activate the virtual environment (Windows)
-.\venv\Scripts\activate
-
-# Install the dependencies
-pip install -U -c constraints.txt -e .[dev]
+# Set up the environment
+poetry install --sync --all-extras
 
 # Set up pre-commit hooks
 pre-commit install
@@ -273,24 +263,19 @@ make html
 
 ### Requirements
 
-All requirements should be on [`pyproject.toml`](../pyproject.toml), on their respective sections.
-Constraints should be maintained in [`constraints.txt`](../constraints.txt).
+Read the Poetry commands docs [here](https://python-poetry.org/docs/cli/).
 
-To see which installed packages are outdated, run `pip list --outdated`.
+All requirements should be listed in the `pyproject.toml` file, under their respective sections.
 
-To update installed packages, run `pip install --upgrade <package name>`.
+To add a new requirement, run `poetry add <package name>`.
 
-To generate a list of the currently installed packages and their versions, do the following:
-
-```bash
-pip freeze > requirements-current.txt
-```
+To see which installed packages are outdated, run `poetry show --outdated`.
 
-That will create a new file, `requirements-current.txt`, with them.
+To update installed packages, run `poetry update <package name>`.
 
-You can then compare it with the current requirements listed in the other files, and update them as needed.
+Always lock the dependencies after updating them, by running `poetry lock`.
 
-When updating development requirements, make sure to also update the related pre-commit hooks.
+When updating development requirements, make sure to also update the related pre-commit hooks in [`.pre-commit-config.yaml`](../.pre-commit-config.yaml).
 
 ### Updating template
 
@@ -300,7 +285,7 @@ When updating development requirements, make sure to also update the related pre
 cruft update
 ```
 
-After updating, the versions of dependencies might change, so use `pip` to reinstall the requirements with the `--upgrade` option.
+After updating, the versions of dependencies might change, so use `poetry install --sync --all-extras`.
 
 ## Add yourself as a contributor