Noxfile tooling and ruff implementation

.github/workflows/docs.yml

@@ -8,13 +8,13 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4.5.0
         with:
-          python-version: "3.8"
+          python-version: "3.9"
       - run: |
           pip install --constraint=.github/workflows/constraints.txt pip
           pip install --constraint=.github/workflows/constraints.txt nox
       - name: Build documentation
         run: nox --force-color --session=docs
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: docs
           path: docs/_build

docs/conf.py

@@ -5,7 +5,7 @@
 
 project = "Hypermodern Python Cookiecutter"
 author = "Claudio Jolowicz"
-copyright = f"{datetime.now().year}, {author}"
+copyright = f"{datetime.now().year}, {author}"  # noqa: A001
 extensions = ["sphinx.ext.intersphinx", "myst_parser"]
 intersphinx_mapping = {"mypy": ("https://mypy.readthedocs.io/en/stable/", None)}
 language = "en"

docs/guide.md

@@ -2666,10 +2666,10 @@ You can also read the articles on [this blog][hypermodern python blog].
 [nox]: https://nox.thea.codes/
 [package metadata]: https://packaging.python.org/en/latest/specifications/core-metadata/
 [pep 257]: http://www.python.org/dev/peps/pep-0257/
-[pep 440]: https://www.python.org/dev/peps/pep-0440/
-[pep 517]: https://www.python.org/dev/peps/pep-0517/
-[pep 518]: https://www.python.org/dev/peps/pep-0518/
-[pep 561]: https://www.python.org/dev/peps/pep-0561/
+[pep 440]: https://peps.python.org/pep-0440/
+[pep 517]: https://peps.python.org/pep-0517/
+[pep 518]: https://peps.python.org/pep-0518/
+[pep 561]: https://peps.python.org/pep-0561/
 [pep 8]: http://www.python.org/dev/peps/pep-0008/
 [pep8-naming codes]: https://github.com/pycqa/pep8-naming#pep-8-naming-conventions
 [pep8-naming]: https://github.com/pycqa/pep8-naming
@@ -2740,6 +2740,6 @@ You can also read the articles on [this blog][hypermodern python blog].
 [versions and constraints]: https://python-poetry.org/docs/dependency-specification/
 [virtual environment]: https://docs.python.org/3/tutorial/venv.html
 [virtualenv]: https://virtualenv.pypa.io/
-[wheel]: https://www.python.org/dev/peps/pep-0427/
+[wheel]: https://peps.python.org/pep-0427/
 [xdoctest]: https://github.com/Erotemic/xdoctest
 [yaml]: https://yaml.org/

noxfile.py

@@ -1,5 +1,7 @@
 """Nox sessions."""
 
+from __future__ import annotations
+
 from pathlib import Path
 import shutil
 
@@ -8,25 +10,97 @@
 from nox.sessions import Session
 
 
+python_versions = ["3.12", "3.11", "3.10", "3.9"]
+
 nox.options.sessions = ["docs"]
-owner, repository = "cjolowicz", "cookiecutter-hypermodern-python"
+owner, repository = "56kyle", "cookiecutter-hypermodern-python"
 labels = "cookiecutter", "documentation"
 bump_paths = "README.md", "docs/guide.rst", "docs/index.rst", "docs/quickstart.md"
 
-REPO_ROOT: Path = Path(__file__).parent
-NEXTGEN_STARTER_CACHE_FOLDER: Path = platformdirs.user_cache_path(
-    appname="cookiecutter-hypermodern-python",
-    appauthor="56kyle",
-    ensure_exists=True
-)
+REPO_ROOT: Path = Path(__file__).parent.resolve()
+TEMPLATE_FOLDER: Path = REPO_ROOT / "{{cookiecutter.project_name}}"
+
+
+COOKIECUTTER_HYPERMODERN_PYTHON_CACHE_FOLDER: Path = Path(
+    platformdirs.user_cache_path(
+        appname="cookiecutter-hypermodern-python",
+        appauthor="56kyle",
+        ensure_exists=True,
+    )
+).resolve()
 
-PROJECT_DEMOS_FOLDER: Path = NEXTGEN_STARTER_CACHE_FOLDER / "project_demos"
+PROJECT_DEMOS_FOLDER: Path = COOKIECUTTER_HYPERMODERN_PYTHON_CACHE_FOLDER / "project_demos"
 DEFAULT_DEMO_NAME: str = "demo-project"
+DEMO_ROOT_FOLDER: Path = PROJECT_DEMOS_FOLDER / DEFAULT_DEMO_NAME
 
+GENERATE_DEMO_PROJECT_OPTIONS: tuple[str, ...] = (
+    *("--repo-folder", REPO_ROOT),
+    *("--demos-cache-folder", PROJECT_DEMOS_FOLDER),
+    *("--demo-name", DEFAULT_DEMO_NAME),
+)
+
+SYNC_POETRY_WITH_DEMO_OPTIONS: tuple[str, ...] = (
+    *("--template-folder", TEMPLATE_FOLDER),
+    *("--demos-cache-folder", PROJECT_DEMOS_FOLDER),
+    *("--demo-name", DEFAULT_DEMO_NAME),
+)
 
-@nox.session(name="generate-demo-project")
-def generate_demo_project(session: Session) -> Session:
-    pass
+
+@nox.session(name="generate-demo-project", python=python_versions[-1])
+def generate_demo_project(session: Session) -> None:
+    session.install("cookiecutter", "platformdirs", "loguru")
+    session.run(
+        "python",
+        "tools/generate-demo-project.py",
+        *GENERATE_DEMO_PROJECT_OPTIONS,
+        external=True,
+    )
+
+
+@nox.session(name="sync-poetry-with-demo", python=python_versions[-1])
+def sync_poetry_with_demo(session: Session) -> None:
+    session.install("cookiecutter", "platformdirs", "loguru")
+    session.run(
+        "python",
+        "tools/sync-poetry-with-demo.py",
+        *SYNC_POETRY_WITH_DEMO_OPTIONS,
+        external=True,
+    )
+
+
+@nox.session(name="poetry-in-demo", python=python_versions[-1])
+def poetry_in_demo(session: Session) -> None:
+    session.install("cookiecutter", "platformdirs", "loguru")
+    session.run(
+        "python",
+        "tools/generate-demo-project.py",
+        *GENERATE_DEMO_PROJECT_OPTIONS,
+        external=True,
+    )
+    original_dir: Path = Path.cwd()
+    session.cd(DEMO_ROOT_FOLDER)
+    session.run("poetry", *session.posargs)
+    session.cd(original_dir)
+    session.run(
+        "python",
+        "tools/sync-poetry-with-demo.py",
+        *SYNC_POETRY_WITH_DEMO_OPTIONS,
+        external=True,
+    )
+
+
+@nox.session(name="poetry-lock")
+def poetry_lock(session: Session) -> None:
+    """Shorthand for poetry-in-demo -- lock."""
+    session._runner.posargs = ["lock", *session.posargs]
+    poetry_in_demo(session)
+
+
+@nox.session(name="poetry-update")
+def poetry_update(session: Session) -> None:
+    """Shorthand for poetry-in-demo -- update."""
+    session._runner.posargs = ["update", *session.posargs]
+    poetry_in_demo(session)
 
 
 @nox.session(name="prepare-release")
@@ -77,7 +151,14 @@ def docs(session: Session) -> None:
 @nox.session
 def linkcheck(session: Session) -> None:
     """Build the documentation."""
-    args = session.posargs or ["-b", "linkcheck", "-W", "--keep-going", "docs", "docs/_build"]
+    args = session.posargs or [
+        "-b",
+        "linkcheck",
+        "-W",
+        "--keep-going",
+        "docs",
+        "docs/_build",
+    ]
 
     builddir = Path("docs", "_build")
     if builddir.exists():

tools/dependencies-table.py

@@ -52,16 +52,11 @@ def main() -> None:
         if package["name"] in dependencies
     }
 
-    table = {
-        format_dependency(dependency): descriptions[dependency]
-        for dependency in sorted(dependencies)
-    }
+    table = {format_dependency(dependency): descriptions[dependency] for dependency in sorted(dependencies)}
 
     width = max(len(name) for name in table)
     width2 = max(len(description) for description in table.values())
-    separator = LINE_FORMAT.format(
-        name="=" * width, width=width, description="=" * width2
-    )
+    separator = LINE_FORMAT.format(name="=" * width, width=width, description="=" * width2)
 
     print(separator)
 

tools/generate-demo-project.py

@@ -1,34 +1,29 @@
-import shutil
-import sys
-from pathlib import Path
+"""Python script for generating a demo project."""
 
 import shutil
 import sys
+from pathlib import Path
 
 import click
 
 from cookiecutter.main import cookiecutter
-from loguru import logger
 
-from tools.util import DEFAULT_DEMO_NAME
-from tools.util import PROJECT_DEMOS_FOLDER
-from tools.util import REPO_ROOT
+
+FOLDER_TYPE: click.Path = click.Path(dir_okay=True, file_okay=False, resolve_path=True, path_type=Path)
 
 
-def generate_demo_project() -> Path:
-    """Generates a demo project and returns its Path."""
-    PROJECT_DEMOS_FOLDER.mkdir(exist_ok=True)
-    _remove_any_existing_demo(PROJECT_DEMOS_FOLDER)
+def generate_demo_project(repo_folder: Path, demos_cache_folder: Path, demo_name: str) -> Path:
+    """Generates a demo project and returns its root path."""
+    demos_cache_folder.mkdir(exist_ok=True)
+    _remove_any_existing_demo(demos_cache_folder)
     cookiecutter(
-        template=str(REPO_ROOT),
+        template=str(repo_folder),
         no_input=True,
-        extra_context={
-            "project_name": DEFAULT_DEMO_NAME,
-        },
+        extra_context={"project_name": demo_name},
         overwrite_if_exists=True,
-        output_dir=str(PROJECT_DEMOS_FOLDER)
+        output_dir=str(demos_cache_folder),
     )
-    return PROJECT_DEMOS_FOLDER / DEFAULT_DEMO_NAME
+    return demos_cache_folder / demo_name
 
 
 def _remove_any_existing_demo(parent_path: Path) -> None:
@@ -38,14 +33,17 @@ def _remove_any_existing_demo(parent_path: Path) -> None:
 
 
 @click.command()
-def main() -> None:
-    """Geneates a demo project."""
+@click.option("--repo-folder", "-r", required=True, type=FOLDER_TYPE)
+@click.option("--demos-cache-folder", "-c", required=True, type=FOLDER_TYPE)
+@click.option("--demo-name", "-d", required=True, type=str)
+def main(repo_folder: Path, demos_cache_folder: Path, demo_name: str) -> None:
+    """Updates the poetry.lock file."""
     try:
-        generate_demo_project()
+        generate_demo_project(repo_folder=repo_folder, demos_cache_folder=demos_cache_folder, demo_name=demo_name)
     except Exception as error:
         click.secho(f"error: {error}", fg="red")
         sys.exit(1)
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main(prog_name="generate-demo-project")

tools/prepare-github-release.py

@@ -13,9 +13,7 @@
 
 def git(*args: str, **kwargs: Any) -> str:
     try:
-        process = subprocess.run(
-            ["git", *args], check=True, capture_output=True, text=True
-        )
+        process = subprocess.run(["git", *args], check=True, capture_output=True, text=True)
         return process.stdout
     except subprocess.CalledProcessError as error:
         print(error.stdout, end="")

tools/publish-github-release.py

@@ -13,18 +13,14 @@ def publish_release(*, owner: str, repository_name: str, token: str, tag: str) -
     try:
         [pull_request] = list(repository.pull_requests(head=f"{owner}:release-{tag}"))
     except ValueError:
-        raise RuntimeError(
-            f"there should be exactly one pull request for {owner}:release-{tag}"
-        )
+        raise RuntimeError(f"there should be exactly one pull request for {owner}:release-{tag}")
 
     pull_request = repository.pull_request(pull_request.number)
 
     try:
         [*_, commit] = pull_request.commits()
     except ValueError:
-        raise RuntimeError(
-            f"there should be at least one commit associated with #{pull_request.number}"
-        )
+        raise RuntimeError(f"there should be at least one commit associated with #{pull_request.number}")
 
     try:
         [release] = [release for release in repository.releases() if release.draft]