Add spelling and docstring enforcement (#1929)

.github/workflows/docs.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install texlive-plain-generic inkscape texlive-xetex latexmk
+          sudo apt-get install texlive-plain-generic inkscape texlive-xetex latexmk enchant-2
 
           # pandoc is not up to date in the ubuntu repos, so we install directly
           wget https://github.com/jgm/pandoc/releases/download/2.14.2/pandoc-2.14.2-1-amd64.deb && sudo dpkg -i pandoc-2.14.2-1-amd64.deb

.github/workflows/tests.yml

@@ -68,7 +68,7 @@ jobs:
       -  name: Run Linters
          run: |
           hatch run lint:style
-          pipx run 'validate-pyproject[all]' pyproject.toml
+          pipx run interrogate -v .
           pipx run doc8 --max-line-length=200  --ignore-path=docs/source/other/full-config.rst
 
   check_release:

.pre-commit-config.yaml

@@ -5,17 +5,17 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0
     hooks:
-      - id: end-of-file-fixer
       - id: check-case-conflict
+      - id: check-ast
+      - id: check-docstring-first
       - id: check-executables-have-shebangs
-      - id: requirements-txt-fixer
       - id: check-added-large-files
       - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-json
       - id: check-toml
       - id: check-yaml
-      - id: debug-statements
-      - id: forbid-new-submodules
-      - id: check-builtin-literals
+      - id: end-of-file-fixer
       - id: trailing-whitespace
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
@@ -36,7 +36,7 @@ repos:
       - id: black
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.0.181
+    rev: v0.0.189
     hooks:
       - id: ruff
         args: ["--fix"]

check_requirements.py

@@ -1,4 +1,4 @@
-# Verify that the "all" reqs are in sync.
+"""Verify that the "all" reqs are in sync."""
 import sys
 
 from tomli import load

docs/source/conf.py

@@ -45,6 +45,13 @@
     "IPython.sphinxext.ipython_console_highlighting",
 ]
 
+try:
+    import enchant  # type:ignore  # noqa
+
+    extensions += ["sphinxcontrib.spelling"]
+except ImportError:
+    pass
+
 myst_enable_extensions = ["html_image"]
 
 # Add any paths that contain templates here, relative to this directory.

hatch_build.py

@@ -75,7 +75,10 @@ def _get_css_files():
 
 
 class CustomHook(BuildHookInterface):
+    """A custom build hook for nbconvert."""
+
     def initialize(self, version, build_data):
+        """Initialize the hook."""
         if self.target_name not in ["wheel", "sdist"]:
             return
         _get_css_files()

nbconvert/__main__.py

@@ -1,3 +1,4 @@
+"""nbconvert cli entry point."""
 from .nbconvertapp import main
 
 main()

nbconvert/_version.py

@@ -1,3 +1,4 @@
+"""nbconvert version info."""
 import re
 from typing import List
 

nbconvert/conftest.py

@@ -1,3 +1,4 @@
+"""pytest configuration."""
 import asyncio
 import os
 

nbconvert/exporters/base.py

@@ -31,10 +31,14 @@
 
 
 class ExporterNameError(NameError):
+    """An exporter name error."""
+
     pass
 
 
 class ExporterDisabledError(ValueError):
+    """An exporter disabled error."""
+
     pass
 
 

nbconvert/exporters/exporter.py

@@ -22,7 +22,10 @@
 
 
 class ResourcesDict(collections.defaultdict):
+    """A default dict for resources."""
+
     def __missing__(self, key):
+        """Handle missing value."""
         return ""
 
 
@@ -33,6 +36,7 @@ class FilenameExtension(Unicode):
     info_text = "a filename extension, beginning with a dot"
 
     def validate(self, obj, value):
+        """Validate the file name."""
         # cast to proper unicode
         value = super().validate(obj, value)
 

nbconvert/exporters/html.py

@@ -204,10 +204,12 @@ def markdown2html(self, context, source):
         return MarkdownWithMath(renderer=renderer).render(source)
 
     def default_filters(self):
+        """Get the default filters."""
         yield from super().default_filters()
         yield ("markdown2html", self.markdown2html)
 
     def from_notebook_node(self, nb, resources=None, **kw):
+        """Convert from notebook node."""
         langinfo = nb.metadata.get("language_info", {})
         lexer = langinfo.get("pygments_lexer", langinfo.get("name", None))
         highlight_code = self.filters.get(
@@ -255,11 +257,13 @@ def resources_include_lab_theme(name):
             return markupsafe.Markup(code)
 
         def resources_include_js(name):
+            """Get the resources include JS for a name."""
             env = self.environment
             code = """<script>\n%s</script>""" % (env.loader.get_source(env, name)[0])
             return markupsafe.Markup(code)
 
         def resources_include_url(name):
+            """Get the resources include url for a name."""
             env = self.environment
             mime_type, encoding = mimetypes.guess_type(name)
             try:

nbconvert/exporters/latex.py

@@ -35,6 +35,7 @@ def _template_name_default(self):
     output_mimetype = "text/latex"
 
     def default_filters(self):
+        """Get the default filters."""
         yield from super().default_filters()
         yield ("resolve_references", resolve_references)
 
@@ -64,6 +65,7 @@ def default_config(self):
         return c
 
     def from_notebook_node(self, nb, resources=None, **kw):
+        """Convert from notebook node."""
         langinfo = nb.metadata.get("language_info", {})
         lexer = langinfo.get("pygments_lexer", langinfo.get("name", None))
         highlight_code = self.filters.get(

nbconvert/exporters/notebook.py

@@ -32,6 +32,7 @@ def _file_extension_default(self):
     export_from_notebook = "Notebook"
 
     def from_notebook_node(self, nb, resources=None, **kw):
+        """Convert from notebook node."""
         nb_copy, resources = super().from_notebook_node(nb, resources, **kw)
         if self.nbformat_version != nb_copy.nbformat:
             resources["output_suffix"] = ".v%i" % self.nbformat_version

nbconvert/exporters/pdf.py

@@ -22,12 +22,15 @@ class LatexFailed(IOError):  # noqa
     """
 
     def __init__(self, output):
+        """Initialize the error."""
         self.output = output
 
     def __unicode__(self):
+        """Unicode representation."""
         return "PDF creating failed, captured latex output:\n%s" % self.output
 
     def __str__(self):
+        """String representation."""
         u = self.__unicode__()
         return u
 
@@ -178,6 +181,7 @@ def log_error(command, out):
         return self.run_command(self.bib_command, filename, 1, log_error, raise_on_failure)
 
     def from_notebook_node(self, nb, resources=None, **kw):
+        """Convert from notebook node."""
         latex, resources = super().from_notebook_node(nb, resources=resources, **kw)
         # set texinputs directory, so that local files will be found
         if resources and resources.get("metadata", {}).get("path"):

nbconvert/exporters/qt_exporter.py

@@ -1,3 +1,4 @@
+"""A qt exporter."""
 import os
 import sys
 import tempfile
@@ -8,6 +9,7 @@
 
 
 class QtExporter(HTMLExporter):
+    """A qt exporter."""
 
     paginate = None
 
@@ -45,6 +47,7 @@ def _run_pyqtwebengine(self, html):
         return s.data
 
     def from_notebook_node(self, nb, resources=None, **kw):
+        """Convert from notebook node."""
         self._check_launch_reqs()
         html, resources = super().from_notebook_node(nb, resources=resources, **kw)
 

nbconvert/exporters/qt_screenshot.py

@@ -1,3 +1,4 @@
+"""A qt screenshot exporter."""
 import os
 
 try:
@@ -17,11 +18,15 @@
         APP = QApplication([])
 
     class QtScreenshot(QWebEngineView):
+        """A qt screenshot exporter."""
+
         def __init__(self):
+            """Initialize the exporter."""
             super().__init__()
             self.app = APP
 
         def capture(self, url, output_file, paginate):
+            """Capture the screenshot."""
             self.output_file = output_file
             self.paginate = paginate
             self.load(QtCore.QUrl(url))
@@ -34,6 +39,7 @@ def capture(self, url, output_file, paginate):
                 self.export = self.export_pdf
 
                 def cleanup(*args):
+                    """Cleanup the app."""
                     self.app.quit()
                     self.get_data()
 
@@ -46,12 +52,14 @@ def cleanup(*args):
             self.app.exec()
 
         def on_loaded(self):
+            """Handle app load."""
             self.size = self.page().contentsSize().toSize()
             self.resize(self.size)
             # Wait for resize
             QtCore.QTimer.singleShot(1000, self.export)
 
         def export_pdf(self):
+            """Export to pdf."""
             if self.paginate:
                 page_size = QPageSize(QPageSize.A4)
                 page_layout = QPageLayout(page_size, QPageLayout.Portrait, QtCore.QMarginsF())
@@ -66,11 +74,13 @@ def export_pdf(self):
             self.page().printToPdf(self.output_file, pageLayout=page_layout)
 
         def export_png(self):
+            """Export to png."""
             self.grab().save(self.output_file, "PNG")
             self.app.quit()
             self.get_data()
 
         def get_data(self):
+            """Get output data."""
             if os.path.exists(self.output_file):
                 with open(self.output_file, "rb") as f:
                     self.data = f.read()

nbconvert/exporters/script.py

@@ -15,6 +15,8 @@
 
 
 class ScriptExporter(TemplateExporter):
+    """A script exporter."""
+
     # Caches of already looked-up and instantiated exporters for delegation:
     _exporters = Dict()
     _lang_exporters = Dict()
@@ -46,6 +48,7 @@ def _get_language_exporter(self, lang_name):
         return self._lang_exporters[lang_name]
 
     def from_notebook_node(self, nb, resources=None, **kw):
+        """Convert from notebook node."""
         langinfo = nb.metadata.get("language_info", {})
 
         # delegate to custom exporter, if specified

nbconvert/exporters/templateexporter.py

@@ -101,6 +101,7 @@ def recursive_update(target, new):
 
 # define function at the top level to avoid pickle errors
 def deprecated(msg):
+    """Emit a deprecation warning."""
     warnings.warn(msg, DeprecationWarning)
 
 
@@ -114,10 +115,12 @@ class ExtensionTolerantLoader(BaseLoader):
     """
 
     def __init__(self, loader, extension):
+        """Initialize the loader."""
         self.loader = loader
         self.extension = extension
 
     def get_source(self, environment, template):
+        """Get the source for a template."""
         try:
             return self.loader.get_source(environment, template)
         except TemplateNotFound:
@@ -126,6 +129,7 @@ def get_source(self, environment, template):
             return self.loader.get_source(environment, template + self.extension)
 
     def list_templates(self):
+        """List available templates."""
         return self.loader.list_templates()
 
 
@@ -567,14 +571,15 @@ def _template_paths(self, prune=True, root_dirs=None):
 
     @classmethod
     def get_compatibility_base_template_conf(cls, name):
+        """Get the base template config."""
         # Hard-coded base template confs to use for backwards compatibility for 5.x-only templates
         if name == "display_priority":
             return {"base_template": "base"}
         if name == "full":
             return {"base_template": "classic", "mimetypes": {"text/html": True}}
 
     def get_template_names(self):
-        # finds a list of template names where each successive template name is the base template
+        """Finds a list of template names where each successive template name is the base template"""
         template_names = []
         root_dirs = self.get_prefix_root_dirs()
         base_template = self.template_name
@@ -635,6 +640,7 @@ def get_template_names(self):
         return template_names
 
     def get_prefix_root_dirs(self):
+        """Get the prefix root dirs."""
         # We look at the usual jupyter locations, and for development purposes also
         # relative to the package directory (first entry, meaning with highest precedence)
         root_dirs = []

nbconvert/exporters/webpdf.py

@@ -89,6 +89,7 @@ def run_pyppeteer(self, html):
         """Run pyppeteer."""
 
         async def main(temp_file):
+            """Run main pyppeteer script."""
             args = ["--no-sandbox"] if self.disable_sandbox else []
             browser = await self._check_launch_reqs()(
                 handleSIGINT=False, handleSIGTERM=False, handleSIGHUP=False, args=args
@@ -139,6 +140,7 @@ async def main(temp_file):
             # TODO: when dropping Python 3.6, use
             # pdf_data = pool.submit(asyncio.run, main(temp_file)).result()
             def run_coroutine(coro):
+                """Run an internal coroutine."""
                 loop = asyncio.new_event_loop()
                 asyncio.set_event_loop(loop)
                 return loop.run_until_complete(coro)
@@ -150,6 +152,7 @@ def run_coroutine(coro):
         return pdf_data
 
     def from_notebook_node(self, nb, resources=None, **kw):
+        """Convert from a notebook node."""
         self._check_launch_reqs()
         html, resources = super().from_notebook_node(nb, resources=resources, **kw)