Use Black for autoformatting Python

Check to ensure that files are black formatted in static checks

Add pre-commit-config.yaml to run Black as a precommit hook

.nengobones.yml

@@ -150,9 +150,13 @@ docs_conf_py:
   exclude_patterns:
     - tests/test-example.ipynb
   sphinx_options:
-    suppress_warnings: "['image.nonlocal_uri']"
+    suppress_warnings: '["image.nonlocal_uri"]'
   extensions:
     - sphinx_click.ext
   intersphinx_mapping:
     click: https://click.palletsprojects.com/en/7.x
   analytics_id: UA-41658423-2
+
+pre_commit_config_yaml: {}
+
+pyproject_toml: {}

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+# Automatically generated by nengo-bones, do not edit this file directly
+
+repos:
+-   repo: https://github.com/psf/black
+    rev: stable
+    hooks:
+    - id: black
+      exclude: |
+          (?x)(
+                docs/conf.py
+              | setup.py
+          )

CHANGES.rst

@@ -19,14 +19,22 @@ Release History
    - Removed
    - Fixed
 
-0.3.1 (unreleased)
+0.4.0 (unreleased)
 ==================
 
 **Added**
 
 - Added style guide and release instructions to documentation. (`#44`_)
+- Added templates for ``.pre-commit-config.yaml`` and ``pyproject.toml``
+  so downstream repositories can easily adopt Black. (`#49`_)
+
+**Changed**
+
+- We now check that Python source files are autoformatted with Black
+  in the ``static.sh`` script. (`#49`_)
 
 .. _#44: https://github.com/nengo/nengo-bones/pull/44
+.. _#49: https://github.com/nengo/nengo-bones/pull/49
 
 0.3.0 (July 19, 2019)
 =====================

docs/conf.py

@@ -57,7 +57,7 @@
 linkcheck_anchors = True
 default_role = "py:obj"
 pygments_style = "sphinx"
-suppress_warnings = ['image.nonlocal_uri']
+suppress_warnings = ["image.nonlocal_uri"]
 
 project = "Nengo Bones"
 authors = "Applied Brain Research"

docs/examples/configuration.ipynb

@@ -1611,6 +1611,64 @@
     "    \"default_role\", \"pygments_style\", \"an_option\", \"another_option\"])"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## .pre-commit-config.yaml and pyproject.toml configs\n",
+    "\n",
+    "The `.pre-commit-config.yaml` and `pyproject.toml` files\n",
+    "make it easy to install `black`\n",
+    "as a pre-commit hook for your repository\n",
+    "and run it on the correct files.\n",
+    "\n",
+    "The only configuration available for these files is an\n",
+    "`exclude` option that accepts a list of patterns to exclude.\n",
+    "Each entry is a regular expression.\n",
+    "The list should be the same for both files.\n",
+    "\n",
+    "When you add these files to your `.nengobones.yml` file,\n",
+    "you should also add something to your documentation\n",
+    "to indicate that users should configure their\n",
+    "editor to run Black automatically,\n",
+    "and to install `pre-commit`\n",
+    "and run `pre-commit install` inside the repository."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nengobones_yml = \"\"\"\n",
+    "pre_commit_config_yaml:\n",
+    "    exclude:\n",
+    "        - project/ignore_me.py\n",
+    "\"\"\"\n",
+    "write_yml(nengobones_yml)\n",
+    "\n",
+    "!bones-generate pre-commit-config-yaml\n",
+    "display_contents(\".pre-commit-config.yaml\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nengobones_yml = \"\"\"\n",
+    "pyproject_toml:\n",
+    "    exclude:\n",
+    "        - project/ignore_me.py\n",
+    "\"\"\"\n",
+    "write_yml(nengobones_yml)\n",
+    "\n",
+    "!bones-generate pyproject-toml\n",
+    "display_contents(\"pyproject.toml\")"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

docs/style.rst

@@ -11,6 +11,25 @@ and follow it when working on Nengo projects.
 Python
 ======
 
+We use ``black`` for automated formatting.
+We recommend that you set up your editor to run ``black``
+when you save a Python file;
+see `Black editor integration
+<https://github.com/psf/black#editor-integration>`__
+for details on how to do that.
+
+Whether you set up ``black`` with your editor or not,
+we require that you run ``black`` through a pre-commit hook.
+To do this, first `install pre-commit <https://pre-commit.com/#install>`__.
+Then, run
+
+.. code-block:: bash
+
+   pre-commit install
+
+to install ``black`` and any other pre-commit hooks
+that a project is using.
+
 We use ``flake8`` and ``pylint`` for automated checks.
 The exact options may vary from project to project,
 so the easiest way to run these checks is to

nengo_bones/config.py

@@ -238,4 +238,6 @@ def construct_mapping(loader, node):
     "contributors_rst": "CONTRIBUTORS.rst",
     "license_rst": "LICENSE.rst",
     "manifest_in": "MANIFEST.in",
+    "pre_commit_config_yaml": ".pre-commit-config.yaml",
+    "pyproject_toml": "pyproject.toml",
 }

nengo_bones/scripts/generate_bones.py

@@ -176,5 +176,21 @@ def docs_conf_py(ctx):
     render_template(ctx, "docs/conf.py")
 
 
+@main.command()
+@click.pass_context
+def pre_commit_config_yaml(ctx):
+    """Generate .pre-commit-config.yaml file."""
+
+    render_template(ctx, ".pre-commit-config.yaml")
+
+
+@main.command()
+@click.pass_context
+def pyproject_toml(ctx):
+    """Generate pyproject.toml file."""
+
+    render_template(ctx, "pyproject.toml")
+
+
 if __name__ == "__main__":
     main(obj={})  # pragma: no cover pylint: disable=no-value-for-parameter

nengo_bones/templates.py

@@ -46,6 +46,7 @@ def __init__(self, output_file, env):
         section = output_file.lstrip(".")
         section = section.replace(".", "_")
         section = section.replace("/", "_")
+        section = section.replace("-", "_")
         section = section.lower()
         self.section = section
 

nengo_bones/templates/.pre-commit-config.yaml.template

@@ -0,0 +1,15 @@
+# Automatically generated by nengo-bones, do not edit this file directly
+
+repos:
+-   repo: https://github.com/psf/black
+    rev: stable
+    hooks:
+    - id: black
+      exclude: |
+          (?x)(
+                docs/conf.py
+              | setup.py
+              {% for pattern in exclude %}
+              | {{ pattern }}
+              {% endfor %}
+          )

nengo_bones/templates/pyproject.toml.template

@@ -0,0 +1,16 @@
+# Automatically generated by nengo-bones, do not edit this file directly
+
+[build-system]
+requires = ["setuptools", "wheel"]
+
+[tool.black]
+target-version = ['py35']
+exclude = '''
+(
+      docs/conf.py
+    | setup.py
+    {% for pattern in exclude %}
+    | {{ pattern }}
+    {% endfor %}
+)
+'''

nengo_bones/templates/setup.cfg.template

@@ -52,6 +52,7 @@ ignore =
     {{ ignore }}
     {% endfor %}
 max-complexity = 10
+max-line-length = 88
 
 [tool:pytest]
 {% if pytest.addopts %}
@@ -144,7 +145,7 @@ known-third-party =
     {% for third_party in pylint.known_third_party %}
     {{ third_party }},
     {% endfor %}
-max-line-length = 79
+max-line-length = 88
 valid-metaclass-classmethod-first-arg = metacls
 reports = no
 score = no

nengo_bones/templates/setup.py.template

@@ -12,7 +12,8 @@ except ImportError:
     raise ImportError(
         "'setuptools' is required but not installed. To install it, "
         "follow the instructions at "
-        "https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py")
+        "https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py"
+    )
 
 
 def read(*filenames, **kwargs):
@@ -26,8 +27,7 @@ def read(*filenames, **kwargs):
 
 
 root = os.path.dirname(os.path.realpath(__file__))
-version = runpy.run_path(os.path.join(
-    root, "{{ pkg_name }}", "version.py"))["version"]
+version = runpy.run_path(os.path.join(root, "{{ pkg_name }}", "version.py"))["version"]
 
 {% block install_req %}
 install_req = [

nengo_bones/templates/static.sh.template

@@ -8,7 +8,7 @@ shopt -s globstar
 
 {% block install %}
 {{ super() }}
-    exe pip install "jupyter>=1.0.0" "pylint>=1.9.2" "codespell>=1.12.0" "gitlint>=0.1.2" "collective.checkdocs>=0.2" "flake8>=3.7.7"
+    exe pip install "jupyter>=1.0.0" "pylint>=1.9.2" "codespell>=1.12.0" "gitlint>=0.1.2" "collective.checkdocs>=0.2" "flake8>=3.7.7" "black>=19.3b0"
 {% endblock %}
 
 {% block script %}
@@ -33,6 +33,7 @@ shopt -s globstar
                 -- "${nb_file%.ipynb}.py"
         done
     fi
+    exe black --check {{ pkg_name }}
     exe pylint docs --rcfile=setup.cfg --disable=missing-docstring,trailing-whitespace,wrong-import-position,unnecessary-semicolon
     exe flake8 docs --extend-ignore=E402,E703,W291,W293,W391
     for nb_file in docs/**/*.ipynb; do

nengo_bones/version.py

@@ -14,7 +14,7 @@
 """
 
 name = "nengo-bones"
-version_info = (0, 3, 1)  # (major, minor, patch)
+version_info = (0, 4, 0)  # (major, minor, patch)
 dev = 0
 
 version = "{v}{dev}".format(

pyproject.toml

@@ -0,0 +1,13 @@
+# Automatically generated by nengo-bones, do not edit this file directly
+
+[build-system]
+requires = ["setuptools", "wheel"]
+
+[tool.black]
+target-version = ['py35']
+exclude = '''
+(
+      docs/conf.py
+    | setup.py
+)
+'''

setup.cfg

@@ -44,6 +44,7 @@ ignore =
     F401
     W503
 max-complexity = 10
+max-line-length = 88
 
 [tool:pytest]
 xfail_strict = False
@@ -106,7 +107,7 @@ known-third-party =
     nengo,
     numpy,
     pytest,
-max-line-length = 79
+max-line-length = 88
 valid-metaclass-classmethod-first-arg = metacls
 reports = no
 score = no

setup.py

@@ -12,7 +12,8 @@
     raise ImportError(
         "'setuptools' is required but not installed. To install it, "
         "follow the instructions at "
-        "https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py")
+        "https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py"
+    )
 
 
 def read(*filenames, **kwargs):
@@ -26,8 +27,7 @@ def read(*filenames, **kwargs):
 
 
 root = os.path.dirname(os.path.realpath(__file__))
-version = runpy.run_path(os.path.join(
-    root, "nengo_bones", "version.py"))["version"]
+version = runpy.run_path(os.path.join(root, "nengo_bones", "version.py"))["version"]
 
 install_req = [
     "click>=7.0",