feat: add option to generate the boilerplate for a CLI

.github/workflows/ci.yml

@@ -57,8 +57,13 @@ jobs:
           - run: "poetry run make html"
             dir: "docs"
             name: "docs"
+        extra_options:
+          - label: "no extra options"
+            value: ""
+          - label: "with CLI"
+            value: "--data 'has_cli=yes' --data 'cli_name=mycli'"
     runs-on: ubuntu-latest
-    name: "Generated: ${{ matrix.script.name }}"
+    name: "Generated: ${{ matrix.script.name }} ${{ matrix.extra_options.label }}"
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
@@ -77,6 +82,7 @@ jobs:
           --data 'project_name=My Amazing Project' \
           --data 'project_short_description=Just a great project' \
           --data 'open_source_license=MIT' \
+          ${{ matrix.extra_options.value }} \
           --defaults
         shell: bash
       - run: cat pyproject.toml

README.md

@@ -9,8 +9,9 @@ Project template for a Python Package using Copier.
 ## Features
 
 - Project for Python 3.8+.
-- Testing with Pytest using Github actions.
-- Packaging powered by [poetry]
+- Testing with Pytest using GitHub actions.
+- Packaging powered by [poetry].
+- Optionally generates a CLI entry point powered by [Typer] and [Rich].
 - Follows the [black] style guide.
 - Uses [Ruff] for linting.
 - Comes with [pre-commit] hook config for [black] and [Ruff].
@@ -138,7 +139,9 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
 
-[poetry]: https://python-poetry.org/
+[poetry]: https://python-poetry.org
+[Typer]: https://typer.tiangolo.com
+[Rich]: https://rich.readthedocs.io
 [black]: https://github.com/psf/black
 [Ruff]: https://pypi.org/project/ruff/
 [pre-commit]: https://pre-commit.com/

copier.yml

@@ -51,6 +51,17 @@ documentation:
   help: "Generate documentation?"
   default: yes
 
+has_cli:
+  type: bool
+  help: "Does the project have a CLI?"
+  default: no
+
+cli_name:
+  type: str
+  help: "The name of the CLI"
+  default: "{{ project_slug }}"
+  when: "{{ has_cli }}"
+
 run_poetry_install:
   type: bool
   help: "Run poetry install after {{ package_name }} generation?"

project/README.md.jinja

@@ -52,13 +52,22 @@ Install this via pip (or your favourite package manager):
 {%- if not documentation  %}
 
 ## Usage
+{%- if has_cli  %}
+
+Call the command line interface:
+
+```bash
+{{ cli_name }} --help
+```
+{%- else  %}
 
 Start by importing it:
 
 ```python
 import {{ package_name }}
 ```
 {%- endif %}
+{%- endif %}
 
 ## Contributors ✨
 

project/docs/usage.md.jinja

@@ -2,10 +2,21 @@
 
 # Usage
 
-Assuming that you've followed the {ref}`installations steps <installation>`, you're now ready to use this package. Start by importing it:
+Assuming that you've followed the {ref}`installations steps <installation>`, you're now ready to use this package.
+{%- if has_cli  %}
+
+Call the command line interface:
+
+```bash
+{{ cli_name }} --help
+```
+{%- else  %}
+
+Start by importing it:
 
 ```python
 import {{ package_name }}
 ```
+{%- endif %}
 
 TODO: Document usage

project/pyproject.toml.jinja

@@ -23,9 +23,18 @@ packages = [
 [tool.poetry.urls]
 "Bug Tracker" = "https://github.com/{{ github_username }}/{{ project_slug }}/issues"
 "Changelog" = "https://github.com/{{ github_username }}/{{ project_slug }}/blob/main/CHANGELOG.md"
+{%- if has_cli %}
+
+[tool.poetry.scripts]
+{{ cli_name }} = "{{ package_name }}.cli:app"
+{%- endif  %}
 
 [tool.poetry.dependencies]
 python = "^3.8"
+{%- if has_cli  %}
+rich = ">=10"
+typer = {extras = ["all"], version = "^0.9.0"}
+{%- endif %}
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.0"

project/src/{{package_name}}/{% if has_cli %}__main__.py{% endif %}.jinja

@@ -0,0 +1,4 @@
+"""Make the CLI runnable using python -m {{ package_name }}."""
+from .cli import app
+
+app(prog_name="{{ cli_name }}")

project/src/{{package_name}}/{% if has_cli %}cli.py{% endif %}.jinja

@@ -0,0 +1,12 @@
+import typer
+from rich import print
+
+from .main import add
+
+app = typer.Typer()
+
+
+@app.command()
+def main(n1: int, n2: int) -> None:
+    """Add the arguments and print the result."""
+    print(add(n1, n2))

project/tests/test_main.py.jinja

@@ -2,4 +2,5 @@ from {{ package_name }}.main import add
 
 
 def test_add():
+    """Adding two number works as expected."""
     assert add(1, 1) == 2

project/tests/{% if has_cli %}test_cli.py{% endif %}.jinja

@@ -0,0 +1,12 @@
+from typer.testing import CliRunner
+
+from {{ package_name }}.cli import app
+
+runner = CliRunner()
+
+
+def test_help():
+    """The help message includes the CLI name."""
+    result = runner.invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "Add the arguments and print the result" in result.stdout

project/tests/{% if has_cli %}test_dunder_main.py{% endif %}.jinja

@@ -0,0 +1,13 @@
+import subprocess
+import sys
+
+
+def test_can_run_as_python_module():
+    """Run the CLI as a Python module."""
+    result = subprocess.run(
+        [sys.executable, "-m", "{{ package_name }}", "--help"],  # noqa S603,S607
+        check=True,
+        capture_output=True,
+    )
+    assert result.returncode == 0
+    assert b"{{ cli_name }} [OPTIONS]" in result.stdout

tests/test_generate_project.py

@@ -174,3 +174,48 @@ def test_documentation(
             dst_path / "pyproject.toml",
             unexpect_strs=["[tool.poetry.group.docs]"],
         )
+
+
+@pytest.mark.parametrize(
+    ("has_cli", "cli_name"),
+    [
+        (True, "mycli"),
+        (False, ""),
+    ],
+)
+def test_cli(
+    tmp_path: Path,
+    base_answers: dict[str, str | bool],
+    has_cli: bool,
+    cli_name: str,
+):
+    dst_path = tmp_path / "snake-farm"
+    copier.run_copy(
+        src_path=str(PROJECT_ROOT),
+        dst_path=dst_path,
+        data={**base_answers, "has_cli": has_cli, "cli_name": cli_name},
+        defaults=True,
+        unsafe=True,
+    )
+
+    assert tmp_path.exists()
+    if has_cli:
+        _check_file_contents(
+            dst_path / "src" / "snake_farm" / "__main__.py",
+            expected_strs=['app(prog_name="mycli")'],
+        )
+        _check_file_contents(
+            dst_path / "src" / "snake_farm" / "cli.py",
+            expected_strs=["app = typer.Typer()"],
+        )
+        _check_file_contents(
+            dst_path / "pyproject.toml",
+            expected_strs=["[tool.poetry.scripts]", 'mycli = "snake_farm.cli:app"'],
+        )
+    else:
+        assert not (dst_path / "src" / "snake_farm" / "__main__.py").exists()
+        assert not (dst_path / "src" / "snake_farm" / "cli.py").exists()
+        _check_file_contents(
+            dst_path / "pyproject.toml",
+            unexpect_strs=["[tool.poetry.scripts]", 'mycli = "snake_farm.cli:app"'],
+        )