Add missing type annotations and require them in new code

docs/conf.py

@@ -3,6 +3,7 @@
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
+from __future__ import annotations
 
 from sphinxcontrib_django import __version__
 

pyproject.toml

@@ -91,8 +91,16 @@
     # "D",
     "RET",
     "SIM",
+    "ANN",
   ]
   ignore = [
     "D1",   # Missing docstrings
+    "ANN101",  # Annotation for 'self'
   ]
   line-length = 99
+
+[tool.ruff.isort]
+  required-imports = ["from __future__ import annotations"]
+
+[tool.ruff.per-file-ignores]
+  "tests/**/*.py" = ["ANN"] # TODO: tests are missing type annotations

setup.py

@@ -1,4 +1,6 @@
 #!/usr/bin/env python3
+from __future__ import annotations
+
 from setuptools import setup
 
 setup()

sphinxcontrib_django/docstrings/attributes.py

@@ -9,6 +9,7 @@
 from django.db.models.manager import ManagerDescriptor
 from django.db.models.query_utils import DeferredAttribute
 from django.utils.module_loading import import_string
+from sphinx.application import Sphinx
 from sphinx.util.docstrings import prepare_docstring
 
 from .field_utils import get_field_type, get_field_verbose_name
@@ -24,23 +25,18 @@
     PhoneNumberDescriptor = None
 
 
-def improve_attribute_docstring(app, attribute, name, lines):
+def improve_attribute_docstring(
+    app: Sphinx, attribute: object, name: str, lines: list[str]
+) -> None:
     """
     Improve the documentation of various model fields.
 
     This improves the navigation between related objects.
 
     :param app: The Sphinx application object
-    :type app: ~sphinx.application.Sphinx
-
     :param attribute: The instance of the object to document
-    :type attribute: object
-
     :param name: The full dotted path to the object
-    :type name: str
-
     :param lines: The docstring lines
-    :type lines: list [ str ]
     """
     # Save initial docstring lines to append them to the modified lines
     docstring_lines = lines.copy()
@@ -96,19 +92,14 @@ def improve_attribute_docstring(app, attribute, name, lines):
             lines.extend(docstring_lines[:-1])
 
 
-def get_field_details(app, field):
+def get_field_details(app: Sphinx, field: models.Field) -> list[str]:
     """
     This function returns the detail docstring of a model field.
     It includes the field type and the verbose name of the field.
 
     :param app: The Sphinx application object
-    :type app: ~sphinx.application.Sphinx
-
     :param field: The field
-    :type field: ~django.db.models.Field
-
     :return: The field details as list of strings
-    :rtype: list [ str ]
     """
     choices_limit = app.config.django_choices_to_show
 

sphinxcontrib_django/docstrings/config.py

@@ -3,6 +3,8 @@
 (see :event:`autodoc-skip-member`)
 """
 #: Ensure that the __init__ method gets documented (also see :confval:`autoclass_content` setting)
+from __future__ import annotations
+
 INCLUDE_MEMBERS = {"__init__"}
 
 #: Members to hide.

sphinxcontrib_django/docstrings/data.py

@@ -1,18 +1,17 @@
+from __future__ import annotations
+
 import io
 import sys
 
 from pprintpp import pprint as pp
 
 
-def improve_data_docstring(data, lines):
+def improve_data_docstring(data: object, lines: list[str]) -> None:
     """
     Improve the documentation of data by pretty-printing into in the docstring.
 
     :param data: The documented object
-    :type data: object
-
     :param lines: The lines of docstring lines
-    :type lines: list [ str ]
     """
     if isinstance(data, (list, tuple, dict, set)):
         # Redirect stdout to StringIO to catch print

sphinxcontrib_django/docstrings/methods.py

@@ -1,14 +1,16 @@
 """
 This module contains all functions which are used to improve the documentation of methods.
 """
+from __future__ import annotations
+
 import re
 
 RE_GET_FOO_DISPLAY = re.compile(r"\.get_(?P<field>[a-zA-Z0-9_]+)_display$")
 RE_GET_NEXT_BY = re.compile(r"\.get_next_by_(?P<field>[a-zA-Z0-9_]+)$")
 RE_GET_PREVIOUS_BY = re.compile(r"\.get_previous_by_(?P<field>[a-zA-Z0-9_]+)$")
 
 
-def improve_method_docstring(name, lines):
+def improve_method_docstring(name: str, lines: list[str]) -> None:
     """
     Improve the documentation of methods automatically contributed to models by Django:
 
@@ -17,10 +19,7 @@ def improve_method_docstring(name, lines):
     * :meth:`~django.db.models.Model.get_previous_by_FOO`
 
     :param name: The full dotted path to the object.
-    :type name: str
-
     :param lines: The lines of docstring lines
-    :type lines: list [ str ]
     """
     if not lines:
         # Not doing obj.__module__ lookups to avoid performance issues.

sphinxcontrib_django/docstrings/patches.py

@@ -1,6 +1,8 @@
 """
 This module contains patches for Django to improve its interaction with Sphinx.
 """
+from __future__ import annotations
+
 import contextlib
 
 from django import apps, forms, test
@@ -24,7 +26,7 @@
     MPTT = False
 
 
-def patch_django_for_autodoc():
+def patch_django_for_autodoc() -> None:
     """
     Fix the appearance of some classes in autodoc.
     E.g. the absolute path to the base model class is ``django.db.models.base.Model``, but its

tests/conftest.py

@@ -3,6 +3,8 @@
 https://github.com/sphinx-doc/sphinx/issues/7008), so this setup was created using the given code
 snippets and the existing test cases for the autodoc extension.
 """
+from __future__ import annotations
+
 from unittest.mock import Mock
 
 import pytest

tests/roots/test-docstrings/conf.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import os
 import sys
 

tests/roots/test-docstrings/conflicting_sphinx_extension.py

@@ -1,3 +1,6 @@
+from __future__ import annotations
+
+
 def setup(app):
     """
     Sphinx extension which also registers a "setting" directive

tests/roots/test-docstrings/dummy_django_app/settings.py

@@ -1,6 +1,7 @@
 """
 Dummy Django settings file
 """
+from __future__ import annotations
 
 SECRET_KEY = "dummy-key"
 

tests/test_attribute_docstrings.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 
 try:

tests/test_autodoc_skip.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 
 

tests/test_class_docstrings.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 
 

tests/test_data_docstrings.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 
 

tests/test_django_configured.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 
 

tests/test_django_setup.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 from sphinx.errors import ConfigError
 

tests/test_method_docstrings.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 
 

tests/test_roles.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest