[py]: consolidate and document linting changes; enable linting in gh actions

Author: symonk

.github/workflows/ci-python.yml

@@ -20,7 +20,7 @@ jobs:
     with:
       bazel-target-prefix: '//py'
 
-  tox_flake8:
+  tox_linting:
     if: ${{ needs.check_workflow.outputs.result == 'true' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || contains(toJson(github.event.commits), '[run python]') == true }}
     needs: check_workflow
     runs-on: ubuntu-latest
@@ -38,7 +38,7 @@ jobs:
       - name: Test with tox
         run: tox -c py/tox.ini
         env:
-          TOXENV: flake8
+          TOXENV: linting
 
   tox_docs:
     if: ${{ needs.check_workflow.outputs.result == 'true' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || contains(toJson(github.event.commits), '[run python]') == true }}

py/docs/source/index.rst

@@ -144,3 +144,16 @@ View source code online:
 +-----------+------------------------------------------------------+
 | official: | https://github.com/SeleniumHQ/selenium/tree/trunk/py |
 +-----------+------------------------------------------------------+
+
+
+Contributing
+=============
+
+ - Create a branch for your work
+ - Ensure `tox` is installed (using a `virtualenv` is recommended)
+ - `python3.7 -m venv .venv && . .venv/bin/activate && pip install tox`
+ - After making changes, before committing execute `tox -e linting`
+ - If tox exits `0`, commit and push otherwise fix the newly introduced breakages.
+ - `flake8` requires manual fixes
+ - `black` will often rewrite the breakages automatically, however the files are unstaged and should staged again.
+ - `isort` will often rewrite the breakages automatically, however the files are unstaged and should staged again.

py/tox.ini

@@ -9,12 +9,6 @@ deps =
 
 commands = sphinx-build -b html -d ../build/doctrees docs/source ../build/docs/api/py {posargs}
 
-[testenv:flake8]
-skip_install = true
-deps = flake8
-       flake8-typing-imports
-commands = flake8 {posargs} --min-python-version=3.7
-
 
 [testenv:mypy]
 skip_install = true
@@ -35,18 +29,18 @@ profile = black
 py_version=37
 force_single_line = True
 
-[testenv:isort]
-skip_install = true
-deps =
-  isort==5.10.1
-commands = isort selenium/ test/
 
-[testenv:black]
-; black is a common python code formatter.  This allows us to keep code completely
-; consistent throughout all contributions and reduce merge conflicts in future.
-; Right now it is opt in and not enforced in CI but will be in future.
+[testenv:linting]
+; A consolidated linting based recipe, responsible for executing linting tools across the code base.
+; This encompasses isort for imports, black for general formatting and flake8.
+; IMPORTANT: black & isort rewrite files, flake8 merely alerts to the failure.
 skip_install = true
 deps =
+  isort==5.10.1
   black==22.8.0
+  flake8==5.0.4
+  flake8-typing-imports==1.13.0
 commands =
+  isort selenium/ test/
   black test/ -l 120
+  flake8 selenium/ test/ --min-python-version=3.7