Merge pull request #47 from WhyNotHugo/typing

Add a few more type hints

Author: timobrembeck

sphinxcontrib_django/__init__.py

@@ -1,20 +1,24 @@
 """
 This is a sphinx extension which improves the documentation of Django apps.
 """
+
+from __future__ import annotations
+
 __version__ = "2.4"
 
+from sphinx.application import Sphinx
+
 from . import docstrings, roles
 
 
-def setup(app):
+def setup(app: Sphinx) -> dict:
     """
     Allow this module to be used as sphinx extension.
 
     Setup the two sub-extensions :mod:`~sphinxcontrib_django.docstrings` and
     :mod:`~sphinxcontrib_django.roles` which can also be imported separately.
 
     :param app: The Sphinx application object
-    :type app: ~sphinx.application.Sphinx
     """
     docstrings.setup(app)
     roles.setup(app)

sphinxcontrib_django/docstrings/attributes.py

@@ -1,6 +1,8 @@
 """
 This module contains all functions which are used to improve the documentation of attributes.
 """
+from __future__ import annotations
+
 from django.db import models
 from django.db.models.fields import related_descriptors
 from django.db.models.fields.files import FileDescriptor

sphinxcontrib_django/docstrings/classes.py

@@ -1,47 +1,39 @@
 """
 This module contains all functions which are used to improve the documentation of classes.
 """
+from __future__ import annotations
 
 from django import forms
 from django.db import models
+from sphinx.application import Sphinx
 from sphinx.pycode import ModuleAnalyzer
 
 from .field_utils import get_field_type, get_field_verbose_name
 
 
-def improve_class_docstring(app, cls, lines):
+def improve_class_docstring(app: Sphinx, cls: type, lines: list[str]) -> None:
     """
     Improve the documentation of a class if it's a Django model or form
 
     :param app: The Sphinx application object
-    :type app: ~sphinx.application.Sphinx
-
     :param cls: The instance of the class to document
-    :type cls: object
-
     :param lines: The docstring lines
-    :type lines: list [ str ]
     """
     if issubclass(cls, models.Model):
         improve_model_docstring(app, cls, lines)
     elif issubclass(cls, forms.BaseForm):
         improve_form_docstring(cls, lines)
 
 
-def improve_model_docstring(app, model, lines):
+def improve_model_docstring(app: Sphinx, model: models.Model, lines: list[str]) -> None:
     """
     Improve the documentation of a Django :class:`~django.db.models.Model` subclass.
 
     This adds all model fields as parameters to the ``__init__()`` method.
 
     :param app: The Sphinx application object
-    :type app: ~sphinx.application.Sphinx
-
     :param model: The instance of the model to document
-    :type model: ~django.db.models.Model
-
     :param lines: The docstring lines
-    :type lines: list [ str ]
     """
 
     # Add database table name
@@ -115,18 +107,13 @@ def improve_model_docstring(app, model, lines):
         lines.append(".. inheritance-diagram::")  # pragma: no cover
 
 
-def add_db_table_name(app, model, lines):
+def add_db_table_name(app: Sphinx, model: models.Model, lines: list[str]) -> None:
     """
     Format and add table name by extension configuration.
 
     :param app: The Sphinx application object
-    :type app: ~sphinx.application.Sphinx
-
     :param model: The instance of the model to document
-    :type model: ~django.db.models.Model
-
     :param lines: The docstring lines
-    :type lines: list [ str ]
     """
     if model._meta.abstract and not app.config.django_show_db_tables_abstract:
         return
@@ -136,18 +123,15 @@ def add_db_table_name(app, model, lines):
     lines.insert(0, f"**Database table:** ``{table_name}``")
 
 
-def add_model_parameters(fields, lines, field_docs):
+def add_model_parameters(
+    fields: list[models.Field], lines: list[str], field_docs: dict
+) -> None:
     """
     Add the given fields as model parameter with the ``:param:`` directive
 
     :param fields: The list of fields
-    :type fields: list [ ~django.db.models.Field ]
-
     :param lines: The list of current docstring lines
-    :type lines: list [ str ]
-
     :param field_docs: The attribute docstrings of the model
-    :type field_docs: dict
     """
     for field in fields:
         # Add docstrings if they are found
@@ -165,16 +149,13 @@ def add_model_parameters(fields, lines, field_docs):
         lines.append(f":type {field.name}: {get_field_type(field, include_role=False)}")
 
 
-def improve_form_docstring(form, lines):
+def improve_form_docstring(form: forms.Form, lines: list[str]) -> None:
     """
     Improve the documentation of a Django :class:`~django.forms.Form` class.
     This highlights the available fields in the form.
 
     :param form: The form object
-    :type form: ~django.forms.Form
-
     :param lines: The list of existing docstring lines
-    :type lines: list [ str ]
     """
     lines.append("**Form fields:**")
     lines.append("")

sphinxcontrib_django/docstrings/field_utils.py

@@ -3,24 +3,21 @@
 :mod:`~sphinxcontrib_django.docstrings.attributes` and
 :mod:`~sphinxcontrib_django.docstrings.classes` modules.
 """
+from __future__ import annotations
+
 from django.apps import apps
 from django.contrib import contenttypes
 from django.db import models
 from django.utils.encoding import force_str
 
 
-def get_field_type(field, include_role=True):
+def get_field_type(field: models.Field, include_role: bool = True) -> str:
     """
     Get the type of a field including the correct intersphinx mappings.
 
     :param field: The field
-    :type field: ~django.db.models.Field
-
     :param include_directive: Whether or not the role :any:`py:class` should be included
-    :type include_directive: bool
-
     :return: The type of the field
-    :rtype: str
     """
     if isinstance(field, models.fields.related.RelatedField):
         to = field.remote_field.model
@@ -46,7 +43,7 @@ def get_field_type(field, include_role=True):
     return f"~{type(field).__module__}.{type(field).__name__}"
 
 
-def get_field_verbose_name(field):
+def get_field_verbose_name(field: models.Field) -> str:
     """
     Get the verbose name of the field.
     If the field has a ``help_text``, it is also included.
@@ -55,7 +52,6 @@ def get_field_verbose_name(field):
     For reverse related fields, the originating field is linked.
 
     :param field: The field
-    :type field: ~django.db.models.Field
     """
     help_text = ""
     # Check whether the field is a reverse related field
@@ -137,18 +133,13 @@ def get_field_verbose_name(field):
     return verbose_name
 
 
-def get_model_from_string(field, model_string):
+def get_model_from_string(field: models.Field, model_string: str) -> type[models.Model]:
     """
     Get a model class from a string
 
     :param field: The field
-    :type field: ~django.db.models.Field
-
     :param model_string: The string label of the model
-    :type model_string: str
-
     :return: The class of the model
-    :rtype: type
     """
     if "." in model_string:
         model = apps.get_model(model_string)

sphinxcontrib_django/roles.py

@@ -21,16 +21,20 @@
         "sphinxcontrib_django.roles",
     ]
 """
+from __future__ import annotations
+
 import logging
 
+from sphinx.application import Sphinx
+from sphinx.config import Config
 from sphinx.errors import ExtensionError
 
 from . import __version__
 
 logger = logging.getLogger(__name__)
 
 
-def setup(app):
+def setup(app: Sphinx) -> dict:
     """
     Allow this module to be used as Sphinx extension.
 
@@ -39,7 +43,6 @@ def setup(app):
     It adds cross-reference types via :meth:`~sphinx.application.Sphinx.add_crossref_type`.
 
     :param app: The Sphinx application object
-    :type app: ~sphinx.application.Sphinx
     """
     # Load sphinx.ext.intersphinx extension
     app.setup_extension("sphinx.ext.intersphinx")
@@ -65,18 +68,15 @@ def setup(app):
     }
 
 
-def add_default_intersphinx_mappings(app, config):
+def add_default_intersphinx_mappings(app: Sphinx, config: Config) -> None:
     """
     This function provides a default intersphinx mapping to the documentations of Python, Django
     and Sphinx if ``intersphinx_mapping`` is not given in ``conf.py``.
 
     Called on the :event:`config-inited` event.
 
     :param app: The Sphinx application object
-    :type app: ~sphinx.application.Sphinx
-
     :param config: The Sphinx configuration
-    :type config: ~sphinx.config.Config
     """
     DEFAULT_INTERSPHINX_MAPPING = {
         "python": ("https://docs.python.org/", None),
@@ -87,4 +87,5 @@ def add_default_intersphinx_mappings(app, config):
         ),
     }
     if not config.intersphinx_mapping:
-        config.intersphinx_mapping = DEFAULT_INTERSPHINX_MAPPING
+        # TYPING: type hints are missing `.intersphinx_mapping` attribute.
+        config.intersphinx_mapping = DEFAULT_INTERSPHINX_MAPPING  # type: ignore[attr-defined ]

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

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from django import forms
 
 from .models import SimpleModel
@@ -7,7 +9,7 @@ class SimpleForm(forms.ModelForm):
     test1 = forms.CharField(label="Test1")
     test2 = forms.CharField(help_text="Test2")
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args, **kwargs) -> None:
         """
         This is a custom init method
         """

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

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from django.contrib.contenttypes.fields import GenericForeignKey
 from django.contrib.contenttypes.models import ContentType
 from django.db import models
@@ -108,7 +110,7 @@ class TaggedItem(models.Model):
     object_id = models.PositiveIntegerField()
     content_object = GenericForeignKey("content_type", "object_id")
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.tag