Typing questiones for py.typed + mypy or pyright + ci + docs

Fixes #230

Author: sverhoeven

copier.yml

@@ -30,6 +30,10 @@
 # community features
 !include copier/questions/features_community.yml
 
+---
+# typing features
+!include copier/questions/features_typing.yml
+
 ---
 # global flags
 !include copier/global_flags.yml

copier/global_flags.yml

@@ -12,5 +12,6 @@ HasWorkflows:
     or AddOnlineDocumentation
     or AddSonarCloud
     or AddZenodo
-    or AddLinting }}"
+    or AddLinting
+    or AddGithubActionTypeCheck }}"
   when: false

copier/questions/features_typing.yml

@@ -0,0 +1,57 @@
+---
+# Questions for typing features
+
+# the main menu
+SelectTypingFeatures:
+  when: "{{ template_profile != 'minimum' }}"
+  type: yaml
+  default: |-
+    {% if template_profile == 'recommended' %}
+      [AddTyping_flag, AddTypingInDocs_flag, AddGitHubActionTypeCheck_flag]
+    {%- else -%}
+      []
+    {%- endif %}
+  help: Select typing features
+  multiselect: true
+  choices:
+    Support Typing (add py.typed file):
+      value: AddTyping_flag
+    GitHub Action to type check:
+      value: AddGitHubActionTypeCheck_flag
+    Typing in API documentation:
+      value: AddTypingInDocs_flag
+
+# TODO add runtime type checking (using pydantic or typeguard)
+
+SelectTypeChecker:
+  when: "{{ template_profile != 'minimum' and 'AddTyping_flag' in SelectTypingFeatures }}"
+  type: str
+  default: |-
+    {%- if template_profile == 'recommended' -%}
+    pyright
+    {%- endif %}
+  help: Select a type checker
+  choices:
+    Mypy:
+      value: mypy
+    Pyright:
+      value: pyright
+    # TODO add pyrefly https://pyrefly.org/
+    # TODO add ty https://github.com/astral-sh/ty
+
+AddPyTyped:
+  type: bool
+  default: "{{ 'AddTyping_flag' in SelectTypingFeatures }}"
+  when: false
+
+AddGithubActionTypeCheck:
+  type: bool
+  default: "{{ 'AddGitHubActionTypeCheck_flag' in SelectTypingFeatures and SelectTypeChecker != '' }}"
+  when: false
+
+AddTypingInDocs:
+  type: bool
+  default: "{{ 'AddTypingInDocs_flag' in SelectTypingFeatures }}"
+  when: false
+
+# TODO ask how strict to typecheck

template/README.md.jinja

@@ -29,6 +29,12 @@
 {% if AddLinkCheck -%}
 | Link checker              | [![link-check]({{repository_url}}/actions/workflows/link-check.yml/badge.svg)]({{repository_url}}/actions/workflows/link-check.yml) |
 {%- endif -%}
+{% if SelectTypeChecker == 'pyright' -%}
+| Type checker                       | [![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/) |
+{%- endif -%}
+{% if SelectTypeChecker == 'mypy' -%}
+| Type checker                       | [![Checked with mypy](https://mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/) |
+{%- endif -%}
 
 ## How to use {{ package_name }}
 

template/pyproject.toml.jinja

@@ -58,13 +58,22 @@ dev = [
     {%- endif %}
     "tox",
     "myst_parser",
+    {% if SelectTypeChecker -%}
+    "{{ SelectTypeChecker }}",
+    {%- endif %}
+    {%- if 'AddTypingInDocs_flag' in SelectTypingFeatures %}
+    "sphinx-autodoc-typehints",
+    {%- endif %}
 ]
 {%- if AddLocalDocumentation %}
 docs = [
     "sphinx",
     "sphinx_rtd_theme",
     "sphinx-autoapi",
     "myst_parser",
+    {%- if 'AddTypingInDocs_flag' in SelectTypingFeatures %}
+    "sphinx-autodoc-typehints",
+    {%- endif %}
 ]
 {%- endif %}
 publishing = [
@@ -147,6 +156,15 @@ known-first-party = ["{{ package_name }}"]
 force-single-line = true
 no-lines-before = ["future","standard-library","third-party","first-party","local-folder"]
 
+{% if SelectTypeChecker == 'pyright' -%}
+[tool.pyright]
+include = ["src"]
+{%- endif %}
+{% if SelectTypeChecker == 'mypy' -%}
+[tool.mypy]
+files = ["src"]
+{%- endif %}
+
 [tool.bumpversion]
 current_version = "{{ version }}"
 

template/src/{{package_name}}/my_module.py.jinja

@@ -8,10 +8,10 @@ def hello(name: str) -> str:
     Function docstring using Google docstring style.
 
     Args:
-        name (str): Name to say hello to
+        name{% if not AddTypingInDocs %} (str){% endif %}: Name to say hello to
 
     Returns:
-        str: Hello message
+        {% if not AddTypingInDocs %}str: {% endif %}Hello message
 
     Raises:
         ValueError: If `name` is equal to `nobody`

template/src/{{package_name}}/{% if AddPyTyped %}py.typed{% endif %}

@@ -87,6 +87,27 @@ git config --local core.hooksPath .githooks
 ```
 {%- endif -%}
 
+{%- if SelectTypeChecker -%}
+## Type checking
+
+{% if SelectTypeChecker == 'pyright' -%}
+We use [pyright](https://microsoft.github.io/pyright/) for type checking.
+
+```shell
+pyright
+```
+
+{% endif -%}
+{% if SelectTypeChecker == 'mypy' -%}
+We use [mypy](http://mypy-lang.org/) for type checking.
+
+```shell
+mypy .
+```
+
+{% endif -%}
+{% endif -%}
+
 ## Generating the API docs
 
 ```shell

template/{% if AddDevDoc %}README.dev.md{% endif %}.jinja

@@ -46,6 +46,9 @@ extensions = [
     "sphinx.ext.viewcode",
     "autoapi.extension",
     "myst_parser",
+    {%- if AddTypingInDocs %}
+    "sphinx_autodoc_typehints",
+    {%- endif %}
 ]
 
 # Add any paths that contain templates here, relative to this directory.

template/{% if AddLocalDocumentation %}docs{% endif %}/conf.py.jinja

@@ -9,6 +9,8 @@ echo "Starting ruff analysis..."
 ruff check --fix
 ruff format
 
+# TODO add type checker
+
 # use return code to abort commit if necessary
 if [ $? != "0" ]; then
     echo "Commit aborted. Fix linter issues found by ruff before committing."