Clarify ruff functionality. (#403)

* Clarify ruff functionality.

* Code review comments.

Author: delucchi-cmu

copier.yml

@@ -78,10 +78,11 @@ python_versions:
 enforce_style:
     help: What tooling set would you like to use to enforce code style? Use SPACE to highlight all that apply.
     type: str
-    default: [ruff]
+    default: [ruff_lint, ruff_format]
     multiselect: true
     choices:
-        ruff: ruff
+        ruff linting: ruff_lint
+        ruff auto-formatter: ruff_format
         pylint: pylint
         black: black
         isort: isort

docs/practices/ci_precommit.rst

@@ -22,7 +22,8 @@ For each pull request, our ``pre-commit.ci`` workflow will:
 * Analyze the src code style and report code that doesn't adhere, using 
   the options you selected for your tooling set:
 
-  * "ruff": checks for linting rules, sorts imports, auto-formats code
+  * "ruff linting": checks for linting rules, and import order
+  * "ruff auto-formatter": auto-formats code
   * "pylint": checks for compliance with pylint rules
   * "black": auto-formats code (including notebooks)
   * "isort": Sort imports using ``isort``

docs/practices/linting.rst

@@ -44,7 +44,7 @@ The template currently offers three tools for auto-formatting:
 
 - **black** - general code formatting
 - **isort** - import statement sorting and organizing
-- **ruff** - does it all
+- **ruff format** - general code formatting
 
 Different formatters share a lot of the same opinions, but we recommend picking
 a single standard for your project and sticking to it.

docs/practices/precommit.rst

@@ -59,7 +59,11 @@ of these that are not useful for your project.
      - Runs black to enforce a particular code style on .py, .pyi and .ipynb files. 
        One can add more file extensions by editing this hook on ``.pre-commit-config.yaml`` 
        directly. *(Optionally installed when project is created.)*
-   * - Format and lint code using ruff
+   * - Lint code using ruff
+     - Runs ruff to enforce a particular code style on .py, .pyi and .ipynb files. 
+       One can add more file extensions by editing this hook on ``.pre-commit-config.yaml`` 
+       directly. *(Optionally installed when project is created.)*
+   * - Format code using ruff
      - Runs ruff to enforce a particular code style on .py, .pyi and .ipynb files. 
        One can add more file extensions by editing this hook on ``.pre-commit-config.yaml`` 
        directly. *(Optionally installed when project is created.)*

docs/source/new_project.rst

@@ -62,7 +62,7 @@ questions:
        We provide several compatible options for linters and autoformatters.
        Choosing a formatter or linter will include it as a project dependency and include it in the
        :doc:`pre-commit <../practices/precommit>` hooks.
-       Defaults to ``ruff`` during simple installation. 
+       Defaults to ``ruff`` (linting and autoformatting) during simple installation. 
    * - *How would you like to receive workflow failure notifications?*
      - See :doc:`/practices/ci_testing`. 
        Some github workflows are not loud about their failures, so we have some configuration

python-project-template/.github/workflows/code_style.yml.jinja

@@ -55,9 +55,13 @@ jobs:
         pylint -rn -sn --recursive=y ./benchmarks --rcfile=./tests/.pylintrc
 {%- endif -%}
 {%- endif -%}
-{%- if 'ruff' in enforce_style %}
-    - name: Analyze code with ruff
+{%- if 'ruff_lint' in enforce_style %}
+    - name: Analyze code with ruff formatter
       run: |
        ruff format --check
+{%- endif -%}
+{%- if 'ruff_format' in enforce_style %}
+    - name: Analyze code with ruff linter
+      run: |
        ruff check
 {%- endif -%}

python-project-template/.pre-commit-config.yaml.jinja

@@ -94,13 +94,23 @@ repos:
         # https://pre-commit.com/#top_level-default_language_version
         language_version: python3.10
 {%- endif %}
-{%- if 'ruff' in enforce_style %}
+{%- if 'ruff_lint' in enforce_style %}
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.1.3
+    rev: v0.2.1
     hooks:
       - id: ruff
-        name: Format and lint code using ruff
+        name: Lint code using ruff; sort and organize imports 
+        types_or: [ python, pyi, jupyter ]
+        args: ["--fix"]
+{%- endif %}
+{%- if 'ruff_format' in enforce_style %}
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.2.1
+    hooks:
+      - id: ruff-format
+        name: Format code using ruff
         types_or: [ python, pyi, jupyter ]
 {%- endif %}
 {%- if mypy_type_checking != 'none' %}

python-project-template/pyproject.toml.jinja

@@ -45,7 +45,7 @@ dev = [
 {%- if 'black'  in enforce_style %}
     "black", # Used for static linting of files
 {%- endif %}
-{%- if 'ruff' in enforce_style %}
+{%- if 'ruff_lint' in enforce_style or 'ruff_format' in enforce_style %}
     "ruff", # Used for static linting of files
 {%- endif %}
 {%- if mypy_type_checking != 'none' %}

tests/test_package_creation.py

@@ -2,22 +2,24 @@
 import pytest_copie
 import subprocess
 
+
 def successfully_created_project(result):
     """Basic assertions that indicate the copier was able to create a project"""
     return result.exit_code == 0 and result.exception is None and result.project_dir.is_dir()
 
 
-def directory_structure_is_correct(result, package_name = "example_package"):
+def directory_structure_is_correct(result, package_name="example_package"):
     """Test to ensure that the default directory structure ws created correctly"""
-    return (result.project_dir / f"src/{package_name}").is_dir() and (result.project_dir / f"tests/{package_name}").is_dir()
+    return (result.project_dir / f"src/{package_name}").is_dir() and (
+        result.project_dir / f"tests/{package_name}"
+    ).is_dir()
 
 
 def black_runs_successfully(result):
     """Test to ensure that the black linter runs successfully on the project"""
     # run black with `--check` to look for lint errors, but don't fix them.
     black_results = subprocess.run(
-        ["python", "-m", "black", "--check", (result.project_dir / "src")],
-        cwd=result.project_dir
+        ["python", "-m", "black", "--check", (result.project_dir / "src")], cwd=result.project_dir
     )
 
     return black_results.returncode == 0
@@ -27,27 +29,21 @@ def pylint_runs_successfully(result):
     """Test to ensure that the pylint linter runs successfully on the project"""
     # run pylint to ensure that the hydrated files are linted correctly
     pylint_results = subprocess.run(
-        ["python", "-m", "pylint",
-         "--recursive=y",
-         "--rcfile=./src/.pylintrc",
-         (result.project_dir / "src")],
-        cwd=result.project_dir
+        ["python", "-m", "pylint", "--recursive=y", "--rcfile=./src/.pylintrc", (result.project_dir / "src")],
+        cwd=result.project_dir,
     )
 
     return pylint_results.returncode == 0
 
 
-def unit_tests_in_project_run_successfully(result, package_name = "example_package"):
+def unit_tests_in_project_run_successfully(result, package_name="example_package"):
     """Test to ensure that the unit tests run successfully on the project
 
     !!! NOTE - This doesn't currently work because we need to `pip install` the hydrated
     project before running the tests. And we don't have a way to create a temporary
     virtual environment for the project.
     """
-    pytest_results = subprocess.run(
-        ["python", "-m", "pytest"],
-        cwd=result.project_dir
-    )
+    pytest_results = subprocess.run(["python", "-m", "pytest"], cwd=result.project_dir)
 
     return pytest_results.returncode == 0
 
@@ -73,10 +69,10 @@ def test_all_defaults(copie):
     # check to see if the README file was hydrated with copier answers.
     found_line = False
     with open(result.project_dir / "README.md") as f:
-       for line in f:
-           if "example_project" in line:
-               found_line = True
-               break
+        for line in f:
+            if "example_project" in line:
+                found_line = True
+                break
     assert found_line
 
 
@@ -107,15 +103,43 @@ def test_use_black_and_no_example_modules(copie):
     # check to see if the pyproject.toml file has the expected dependencies
     found_line = False
     with open(result.project_dir / "pyproject.toml") as f:
-       for line in f:
-           if "\"black\", # Used for static linting of files" in line:
-               found_line = True
-               break
+        for line in f:
+            if '"black", # Used for static linting of files' in line:
+                found_line = True
+                break
     assert found_line
 
     assert black_runs_successfully(result)
 
 
+@pytest.mark.parametrize(
+    "enforce_style",
+    [
+        [],
+        ["ruff_lint"],
+        ["ruff_format"],
+        ["ruff_lint", "pylint"],
+        ["ruff_format", "black"],
+        ["black", "pylint", "isort"],
+        ["ruff_lint", "ruff_format"],
+        ["black", "pylint", "isort", "ruff_lint", "ruff_format"],
+    ],
+)
+def test_code_style_combinations(copie, enforce_style):
+    """Test that various combinations of code style enforcement will
+    still result in a valid project being created."""
+
+    # provide a dictionary of the non-default answers to use
+    extra_answers = {
+        "enforce_style": enforce_style,
+    }
+    result = copie.copy(extra_answers=extra_answers)
+    assert successfully_created_project(result)
+    assert directory_structure_is_correct(result)
+    # black would still run successfully.
+    assert black_runs_successfully(result)
+
+
 def test_smoke_test_notification(copie):
     """Confirm we can generate a "smoke_test.yaml" file, with all
     notification mechanisms selected."""
@@ -130,4 +154,4 @@ def test_smoke_test_notification(copie):
 
     assert successfully_created_project(result)
     assert directory_structure_is_correct(result)
-    assert black_runs_successfully(result)
+    assert black_runs_successfully(result)