Merge pull request #698 from NLeSC/typing

Typing

Author: sverhoeven

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Added
 
+- Typing support. [#698](https://github.com/NLeSC/python-template/pull/698)
+
 ### Changed
 
 ### Removed

CONTRIBUTING.md

@@ -33,7 +33,7 @@ in line with what is recommended there. If not, please [contribute to the guide]
 1. (**important**) wait until some kind of consensus is reached about your idea being a good idea;
 1. if needed, fork the repository to your own Github profile and create your own feature branch off of the latest main commit. While working on your feature branch, make sure to stay up to date with the main branch by pulling in changes, possibly from the 'upstream' repository (follow the instructions [here](https://help.github.com/articles/configuring-a-remote-for-a-fork/) and [here](https://help.github.com/articles/syncing-a-fork/));
 1. install dependencies (see the [development documentation](README.dev.md#create-a-virtual-environment));
-1. make sure the existing tests still work by running ``pytest``. If project tests fail use ``pytest --keep-baked-projects`` to keep generated project files in `/tmp/pytest-*` and investigate;
+1. make sure the existing tests still work by running ``pytest``. If project tests fail use ``pytest --keep-copied-projects`` to keep generated project files in `/tmp/pytest-*` and investigate;
 1. add your own tests (if necessary);
 1. update or expand the documentation;
 1. update the `CHANGELOG.md` file with your change;

copier/questions/features_code_quality.yml

@@ -7,7 +7,7 @@ SelectCodeQualityFeatures:
   type: yaml
   default: |-
     {% if template_profile == 'recommended' %}
-      [AddLocalTests_flag, SelectGitHubActions_flag, AddLinting_flag, AddSonarCloud_flag, AddEditorConfig_flag]
+      [AddLocalTests_flag, SelectGitHubActions_flag, AddLinting_flag, AddSonarCloud_flag, AddEditorConfig_flag, AddTyping_flag]
     {%- else -%}
       []
     {%- endif %}
@@ -32,7 +32,8 @@ SelectCodeQualityFeatures:
     Editorconfig:
       value: AddEditorConfig_flag
       # validator: "{% if something != 'AnotherThing' %}BlaBla{% endif %}"
-
+    Typing (select type checker later):
+      value: AddTyping_flag
 
 # Sub-menus
 SelectGitHubActions:
@@ -54,6 +55,27 @@ SelectGitHubActions:
       value: AddLinkCheck_flag
       # validator: "{% if something != 'AnotherThing' %}BlaBla{% endif %}"
 
+AddTyping:
+  type: bool
+  default: "{{ 'AddTyping_flag' in SelectCodeQualityFeatures }}"
+  when: false
+
+SelectTypeChecker:
+  when: "{{ template_profile != 'minimum' and AddTyping }}"
+  type: str
+  default: pyright
+  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
+
+# TODO add runtime type checking (using pydantic or typeguard)
+
+# TODO ask how strict to typecheck
 
 # computed features
 AddLocalTests:

copier/questions/features_documentation.yml

@@ -44,3 +44,7 @@ AddGitHubActionDocumentation:
   type: bool
   default: "{{ 'AddGitHubActionDocumentation_flag' in SelectDocumentationFeatures }}"
   when: false
+AddTypingInDocs:
+  type: bool
+  default: "{{ AddTyping and AddLocalDocumentation }}"
+  when: false

template/README.md.jinja

@@ -29,6 +29,14 @@
 {% if AddLinkCheck -%}
 | Link checker              | [![link-check]({{repository_url}}/actions/workflows/link-check.yml/badge.svg)]({{repository_url}}/actions/workflows/link-check.yml) |
 {%- endif -%}
+{% if AddTyping -%}
+{% 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 -%}
+{%- endif %}
 
 ## How to use {{ package_name }}
 

template/pyproject.toml.jinja

@@ -58,13 +58,22 @@ dev = [
     {%- endif %}
     "tox",
     "myst_parser",
+    {% if AddTyping and SelectTypeChecker -%}
+    "{{ SelectTypeChecker }}",
+    {%- endif %}
+    {%- if AddTypingInDocs %}
+    "sphinx-autodoc-typehints",
+    {%- endif %}
 ]
 {%- if AddLocalDocumentation %}
 docs = [
     "sphinx",
     "sphinx_rtd_theme",
     "sphinx-autoapi",
     "myst_parser",
+    {%- if AddTypingInDocs %}
+    "sphinx-autodoc-typehints",
+    {%- endif %}
 ]
 {%- endif %}
 publishing = [
@@ -147,6 +156,17 @@ known-first-party = ["{{ package_name }}"]
 force-single-line = true
 no-lines-before = ["future","standard-library","third-party","first-party","local-folder"]
 
+{% if AddTyping -%}
+{% if SelectTypeChecker == 'pyright' -%}
+[tool.pyright]
+include = ["src"]
+{%- endif %}
+{% if SelectTypeChecker == 'mypy' -%}
+[tool.mypy]
+files = ["src"]
+{%- endif %}
+{%- 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 AddTyping %}py.typed{% endif %}

@@ -87,6 +87,26 @@ git config --local core.hooksPath .githooks
 ```
 {%- endif -%}
 
+{% if AddTyping %}
+## 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.