Format code with black and isort (#839)

* add black to pyproject.toml

* reformat files with black

* add isort for import sorting

* reformat files with isort

* restore test file formatting

* fix exclusions and make otter generate render templates correctly

* add workflow for checking formatting

* use different poetry setup action

* pin fica>=0.4.1

* fixing lsp complaints

* fix args and kwargs type hints

.github/workflows/check-formatting.yml

@@ -0,0 +1,52 @@
+name: Check formatting
+
+on:
+  push:
+    branches:
+      - master
+      - beta
+      - release
+  pull_request:
+    branches:
+      - master
+      - beta
+      - release
+      - temp
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Check formatting
+    runs-on: ubuntu-latest
+
+    env:
+      TAR: /bin/tar
+
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          virtualenvs-path: .venv
+          installer-parallel: true
+
+      - name: Install dependencies
+        run: |
+          poetry install --with dev --no-root
+
+      - name: Run formatters
+        run: |
+          source .venv/bin/activate
+          make format CI=true

.github/workflows/release.yml

@@ -35,7 +35,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          poetry install
+          poetry install --with dev --no-root
 
       - name: Update versions
         run: |

.github/workflows/run-docker-tests-beta.yml

@@ -74,7 +74,7 @@ jobs:
         if: ${{ steps.check-branch.outputs.run == 'true' }}
         run: |
           micromamba activate otter-grader
-          poetry install --with test --all-extras
+          poetry install --with dev,test --all-extras
 
       - name: Install ottr
         if: ${{ steps.check-branch.outputs.run == 'true' }}

.github/workflows/run-docker-tests.yml

@@ -57,7 +57,7 @@ jobs:
       - name: Install dependencies
         run: |
           micromamba activate otter-grader
-          poetry install --with test --all-extras
+          poetry install --with dev,test --all-extras
 
       - name: Install ottr
         run: |

.github/workflows/run-tests.yml

@@ -51,7 +51,7 @@ jobs:
       - name: Install dependencies
         run: |
           micromamba activate otter-grader
-          poetry install --with test --all-extras
+          poetry install --with dev,test --all-extras
 
       - name: Install ottr
         run: |

CONTRIBUTING.md

@@ -22,7 +22,7 @@ To install development dependencies, use [`poetry`](https://python-poetry.org/)
 
 ```
 mamba activate otter-grader
-poetry install
+poetry install --with dev,test
 ```
 
 

Makefile

@@ -5,8 +5,15 @@ COVERAGE         = coverage
 DOCKER           = true
 SLOW             = true
 CLEANUP          = true
+ISORT            = isort
+ISORTOPTS        =
+BLACK            = black
+BLACKOPTS        =
+CI               = false
 
 _PYTESTOPTS      := -vv --durations=0 --html=pytest-report.html --self-contained-html
+_ISORTOPTS       :=
+_BLACKOPTS       :=
 
 ifeq ($(DOCKER), false)
 	_PYTESTOPTS := $(_PYTESTOPTS) -m "not docker"
@@ -20,6 +27,11 @@ ifeq ($(CLEANUP), false)
 	_PYTESTOPTS := $(_PYTESTOPTS) --nocleanup
 endif
 
+ifeq ($(CI), true)
+	_ISORTOPTS := --check --diff
+	_BLACKOPTS := --check --diff
+endif
+
 _PYTESTOPTS := $(_PYTESTOPTS) $(PYTESTOPTS)
 
 .PHONY: test
@@ -41,3 +53,7 @@ tutorial:
 	zip -r tutorial.zip submissions demo.ipynb requirements.txt -x "*.DS_Store"; \
 	cp tutorial.zip ../_static; \
 	rm tutorial.zip
+
+format:
+	$(ISORT) $(_ISORTOPTS) $(ISORTOPTS) .
+	$(BLACK) $(_BLACKOPTS) $(BLACKOPTS) .

docs/conf.py

@@ -15,29 +15,31 @@
 import os
 import sys
 
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath(".."))
 
 import nbconvert
 
 from glob import glob
 from jinja2 import Template
+
 from otter.generate import CondaEnvironment
 from otter.utils import print_full_width
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'Otter-Grader'
-copyright = '2019-2023, UC Berkeley Data Science Education Program'
-author = 'UC Berkeley Data Science Education Program Infrastructure Team'
+project = "Otter-Grader"
+copyright = "2019-2023, UC Berkeley Data Science Education Program"
+author = "UC Berkeley Data Science Education Program Infrastructure Team"
 
 # The short X.Y version
-version = ''
+version = ""
 # The full version, including alpha/beta/rc tags
-release = ''
+release = ""
 
 
 # -- General configuration ---------------------------------------------------
@@ -50,22 +52,22 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.githubpages',
-    'sphinx.ext.coverage', 
-    'sphinx.ext.napoleon',
-    'sphinx_markdown_tables',
-    'IPython.sphinxext.ipython_console_highlighting',
-    'IPython.sphinxext.ipython_directive',
-    'sphinx_click',
-    'fica.sphinx',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.coverage",
+    "sphinx.ext.napoleon",
+    "sphinx_markdown_tables",
+    "IPython.sphinxext.ipython_console_highlighting",
+    "IPython.sphinxext.ipython_directive",
+    "sphinx_click",
+    "fica.sphinx",
 ]
 
 napoleon_google_docstring = True
 napoleon_numpy_docstring = False
 
-apidoc_module_dir = '../otter'
-apidoc_output_dir = '.'
+apidoc_module_dir = "../otter"
+apidoc_output_dir = "."
 apidoc_excluded_paths = []
 
 autosummary_generate = False
@@ -77,46 +79,46 @@
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ['.rst']
+source_suffix = [".rst"]
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
-github_doc_root = 'https://github.com/ucbds-infra/otter-grader/tree/master/docs/'
+github_doc_root = "https://github.com/ucbds-infra/otter-grader/tree/master/docs/"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = 'en'
+language = "en"
 
-# List of patterns, relative to source directory, that match files and
+# list of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'modules.rst', 'otter*.rst', 'modules.rst']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "modules.rst", "otter*.rst", "modules.rst"]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_book_theme'
-html_logo = '../logo/otter-logo-smallest.png'
+html_theme = "sphinx_book_theme"
+html_logo = "../logo/otter-logo-smallest.png"
 
 html_theme_options = {
-    'github_url': 'https://github.com/ucbds-infra/otter-grader',
-    'repository_url': 'https://github.com/ucbds-infra/otter-grader'
+    "github_url": "https://github.com/ucbds-infra/otter-grader",
+    "repository_url": "https://github.com/ucbds-infra/otter-grader",
 }
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -128,9 +130,9 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-html_css_files = ['style.css']
-html_favicon = '_static/favicon.ico'
+html_static_path = ["_static"]
+html_css_files = ["style.css"]
+html_favicon = "_static/favicon.ico"
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -146,7 +148,7 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'otterdoc'
+htmlhelp_basename = "otterdoc"
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -155,48 +157,53 @@
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
 }
 
-# Grouping the document tree into LaTeX files. List of tuples
+# Grouping the document tree into LaTeX files. list of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'otterdoc.tex', 'Otter-Grader Documentation',
-     'UCBDS Infrastructure Team', 'manual'),
+    (
+        master_doc,
+        "otterdoc.tex",
+        "Otter-Grader Documentation",
+        "UCBDS Infrastructure Team",
+        "manual",
+    ),
 ]
 
 
 # -- Options for manual page output ------------------------------------------
 
-# One entry per manual page. List of tuples
+# One entry per manual page. list of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'Otter-Grader', 'Otter-Grader Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "Otter-Grader", "Otter-Grader Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------------
 
-# Grouping the document tree into Texinfo files. List of tuples
+# Grouping the document tree into Texinfo files. list of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'Otter-Grader', 'Otter-Grader Documentation',
-     author, 'Otter-Grader', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "Otter-Grader",
+        "Otter-Grader Documentation",
+        author,
+        "Otter-Grader",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]
 
 

otter/__init__.py

@@ -4,3 +4,6 @@
 from .check import logs
 from .check.notebook import Notebook
 from .version import __version__
+
+
+__all__ = ["api", "logs", "Notebook", "__version__"]