Simplify, unify and document pre_push, CIs and pre-commit hooks to all use consistent tools, versions and config

.github/CONTRIBUTING.md

@@ -26,16 +26,24 @@ One of the simplest ways to help with PRAW is by answering others'
 questions. When responding, always be positive. While something may be obvious
 to you, it likely is not to the person asking the question.
 
-## Pull Request Creation
+## Creating Pull Requests
 
 0. If you are fixing an already filed issue, please indicate your intentions by
    commenting on the issue. This act will hopefully minimize any duplicate
    work.
 
-0. Prior to creating a pull request run the `pre_push.py` script. This script
-   depends on the tools `black` `flake8`, `pylint`, `pydocstyle`, `sphinx` and `sphinx_rtd_theme`. They can
-   be installed via `pip install black flake8 pydocstyle pylint sphinx sphinx_rtd_theme` or via
-   `pip install praw[lint]`.
+0. Before commiting, make sure to install [Pre-Commit](https://pre-commit.com/)
+   and the pre-commit hooks, which ensure any new code conforms to PRAW's
+   quality and style guidelines. To do so, install the linting dependencies
+   with `pip install praw[lint]`, then by the hooks with `pre-commit install`.
+   They will now run automatically every time you commit. If one of the formatters
+   (e.g. Black, isort) changes one or more files, the commit will automatically abort
+   so you can double-check the changes. If everything looks good, just `git add .` and
+   commit again.
+
+0. Prior to creating a pull request, run the `pre_push.py` script.
+   This runs the pre-commit suite on all files, as well as builds the docs.
+   You'll need to have installed the linting dependencies first (see previous).
 
 0. Add yourself as a contributor to the ``AUTHORS.rst``.
 

.github/workflows/ci.yml

@@ -25,24 +25,10 @@ jobs:
           v0-${{ runner.os }}-pip-
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
+        python -m pip install --upgrade pip setuptools wheel
         pip install .[lint]
-    - name: Check other phrase usages
-      run: python ./tools/static_word_checks.py
-    - name: Check documentation
-      run: python ./tools/check_documentation.py
-    - name: Run black
-      run: black --check --verbose .
-    - name: Run docstrfmt
-      run: docstrfmt -cvp pyproject.toml -e docs/examples .
-    - name: Run flake8
-      run: flake8 --exclude docs --statistics
-    - name: Run flynt
-      run: flynt -vdf -tc -ll 1000 .
-    - name: Run isort
-      run: isort -cv .
-    - name: Run pydocstyle
-      run: pydocstyle praw
+    - name: Run pre-commit hooks
+      uses: pre-commit/action@v2.0.3
     - name: Run sphinx
       run: sphinx-build -W --keep-going docs/ /tmp/foo
     strategy:

.pre-commit-config.yaml

@@ -27,12 +27,12 @@ repos:
   - repo: https://github.com/psf/black
     hooks:
       - id: black
-        language_version: python3
     rev: 21.9b0
 
   - repo: https://github.com/LilSpazJoekp/docstrfmt
     hooks:
       - id: docstrfmt
+        require_serial: true
     rev: v1.4.1
 
   - repo: https://github.com/pycqa/flake8
@@ -47,7 +47,6 @@ repos:
           - '-ll'
           - '1000'
           - '-tc'
-        language_version: python3.8
     rev: '0.69'
 
   - repo: https://github.com/pycqa/isort

docs/package_info/contributing.rst

@@ -5,22 +5,21 @@ PRAW gladly welcomes new contributions. As with most larger projects, we have an
 established consistent way of doing things. A consistent style increases readability,
 decreases bug-potential and makes it faster to understand how everything works together.
 
-PRAW follows :PEP:`8` and :PEP:`257`. The ``pre_push.py`` script can be used to test for
-compliance with these PEPs in addition to providing a few other checks. The following
-are PRAW-specific guidelines in addition to those PEP's.
+PRAW follows :PEP:`8` and :PEP:`257`. `Pre-Commit <https://pre-commit.com>` is used to
+manage a suite of pre-commit hooks that enforce conformance with these PEPs along with
+several other checks. Additionally, the ``pre_push.py`` script can be used to run the
+full pre-commit suite and the docs build prior to submitting a Pull Request. The
+following are PRAW-specific guidelines in addition to those PEPs.
 
 .. note::
 
-    Python 3.6+ is needed to run the script.
-
-.. note::
-
-    In order to install the dependencies needed to run the script, you can install the
-    ``[dev]`` package of praw, like so:
+    In order to use the pre-commit hooks and the ``pre_push.py`` dependencies, install
+    PRAW's ``[lint]`` extra, followed by the appropriate Pre-Commit command:
 
     .. code-block:: bash
 
-        pip install praw[dev]
+        pip install praw[lint]
+        pre-commit install
 
 Code
 ----
@@ -78,9 +77,9 @@ The environment variables are (listed in bash export format):
     export prawtest_username=myusername
     export prawtest_user_agent=praw_pytest
 
-By setting these environment variables prior to running ``python setup.py test``, when
-adding or updating cassettes, instances of ``mypassword`` will be replaced by the
-placeholder text ``<PASSWORD>`` and similar for the other environment variables.
+By setting these environment variables prior to running ``pytest``, when adding or
+updating cassettes, instances of ``mypassword`` will be replaced by the placeholder text
+``<PASSWORD>`` and similar for the other environment variables.
 
 To use tokens instead of username/password set ``prawtest_refresh_token`` instead of
 ``prawtest_password`` and ``prawtest_username``.
@@ -104,8 +103,9 @@ Static Checker
 ~~~~~~~~~~~~~~
 
 PRAW's test suite comes with a checker tool that can warn you of using incorrect
-documentation styles (using ``.. code-block::`` instead of ``.. code::``, using ``/r/``
-instead of ``r/``, etc.).
+documentation styles (using ``.. code::`` instead of ``.. code-block::``, using ``/r/``
+instead of ``r/``, etc.). This is run automatically by the pre-commit hooks and the
+``pre_push.py`` script.
 
 .. autoclass:: tools.static_word_checks.StaticChecker
     :inherited-members:

pre_push.py

@@ -3,12 +3,8 @@
 
 import argparse
 import sys
-from os import path
-from shutil import rmtree
 from subprocess import CalledProcessError, check_call
-from tempfile import mkdtemp
-
-current_directory = path.abspath(path.join(__file__, ".."))
+from tempfile import TemporaryDirectory
 
 
 def do_process(args, shell=False):
@@ -41,35 +37,10 @@ def run_static():
 
     """
     success = True
-    # Formatters
-    success &= do_process(
-        [
-            sys.executable,
-            path.join(current_directory, "tools", "static_word_checks.py"),
-            "--replace",
-        ]
-    )
-    success &= do_process(["flynt", "-q", "-tc", "-ll", "1000", "."])
-    # needs to be first because flynt is not black compliant
-    success &= do_process(["black", "."])
-    success &= do_process(["docstrfmt", "."])
-    success &= do_process(["isort", "."])
-    # Linters
-    success &= do_process(
-        [
-            sys.executable,
-            path.join(current_directory, "tools", "check_documentation.py"),
-        ]
-    )
-    success &= do_process(["flake8"])
-    success &= do_process(["pydocstyle", "praw"])
-    # success &= do_process(["pylint", "--rcfile=.pylintrc", "praw"])
+    success &= do_process(["pre-commit", "run", "--all-files"])
 
-    tmp_dir = mkdtemp()
-    try:
+    with TemporaryDirectory() as tmp_dir:
         success &= do_process(["sphinx-build", "-W", "--keep-going", "docs", tmp_dir])
-    finally:
-        rmtree(tmp_dir)
 
     return success
 

setup.py

@@ -15,14 +15,9 @@
 
 extras = {
     "ci": ["coveralls"],
-    "dev": ["packaging", "pre-commit"],
+    "dev": ["packaging"],
     "lint": [
-        "black",
-        "docstrfmt",
-        "flake8",
-        "flynt",
-        "isort",
-        "pydocstyle",
+        "pre-commit",
         "sphinx",
         "sphinx_rtd_theme",
     ],