Merge pull request #62 from nautobot/u/snaselj-napps-137-ruff

Replace pydocstyle with ruff

docs/dev/contributing.md

@@ -5,7 +5,7 @@ The project is packaged with a light [development environment](dev_environment.m
 
 The project is following Network to Code software development guidelines and is leveraging the following:
 
-- Python linting and formatting: `black`, `pylint`, `bandit`, `flake8`, and `pydocstyle`.
+- Python linting and formatting: `black`, `pylint`.
 - YAML linting is done with `yamllint`.
 - Django unit test to ensure the app is working properly.
 
@@ -43,4 +43,4 @@ When a new release of any kind (e.g. from `develop` to `main`, or a release of a
 - A post release PR is created:
     - Change the version from `<major>.<minor>.<patch>` to `<major>.<minor>.<patch + 1>-beta` in pyproject.toml.
     - Set the PR to the proper branch, e.g. either `develop` or `stable-<major>.<minor>`.
-    - Once tests pass, merge.
+    - Once tests pass, merge.

docs/dev/dev_environment.md

@@ -105,7 +105,7 @@ Each command can be executed with `invoke <command>`. All commands support the a
   bandit           Run bandit to validate basic static code security analysis.
   black            Run black to check that Python files adhere to its style standards.
   flake8           Run flake8 to check that Python files adhere to its style standards.
-  pydocstyle       Run pydocstyle to validate docstring formatting adheres to NTC defined standards.
+  ruff             Run ruff to validate docstring formatting adheres to NTC defined standards.
   pylint           Run pylint code analysis.
   tests            Run all tests for this app.
   unittest         Run Django unit tests for the app.
@@ -312,6 +312,6 @@ To run an individual test, you can run any or all of the following:
 ➜ invoke bandit
 ➜ invoke black
 ➜ invoke flake8
-➜ invoke pydocstyle
+➜ invoke ruff
 ➜ invoke pylint
 ```

nautobot-app-chatops/{{ cookiecutter.project_slug }}/pyproject.toml

@@ -40,10 +40,10 @@ django-debug-toolbar = "*"
 flake8 = "*"
 invoke = "*"
 ipython = "*"
-pydocstyle = "*"
 pylint = "*"
 pylint-django = "*"
 pylint-nautobot = "*"
+ruff = "*"
 yamllint = "*"
 toml = "*"
 Markdown = "*"
@@ -113,17 +113,35 @@ supported_nautobot_versions = [
     "{{ cookiecutter.min_nautobot_version }}"
 ]
 
-[tool.pydocstyle]
-convention = "google"
-inherit = false
-match = "(?!__init__).*\\.py"
-match-dir = "(?!tests|migrations|development)[^\\.].*"
-# D212 is enabled by default in google convention, and complains if we have a docstring like:
-# """
-# My docstring is on the line after the opening quotes instead of on the same line as them.
-# """
-# We've discussed and concluded that we consider this to be a valid style choice.
-add_ignore = "D212"
+[tool.ruff]
+line-length = 120
+target-version = "py38"
+exclude = [
+    "migrations",
+]
+
+[tool.ruff.lint]
+select = [
+    "D1",  # pydocstyle
+    "D2",  # pydocstyle
+    "D3",  # pydocstyle
+    "D4",  # pydocstyle
+]
+ignore = [
+    # warning: `one-blank-line-before-class` (D203) and `no-blank-line-before-class` (D211) are incompatible.
+    "D203",  # 1 blank line required before class docstring
+
+    # D212 is enabled by default in google convention, and complains if we have a docstring like:
+    # """
+    # My docstring is on the line after the opening quotes instead of on the same line as them.
+    # """
+    # We've discussed and concluded that we consider this to be a valid style choice.
+    "D212",  # Multi-line docstring summary should start at the first line
+    "D213",  # Multi-line docstring summary should start at the second line
+
+    # Produces a lot of issues in the current codebase.
+    "D401",  # First line of docstring should be in imperative mood
+]
 
 [build-system]
 requires = ["poetry_core>=1.0.0"]

nautobot-app-ssot/{{ cookiecutter.project_slug }}/pyproject.toml

@@ -37,10 +37,10 @@ django-debug-toolbar = "*"
 flake8 = "*"
 invoke = "*"
 ipython = "*"
-pydocstyle = "*"
 pylint = "*"
 pylint-django = "*"
 pylint-nautobot = "*"
+ruff = "*"
 yamllint = "*"
 toml = "*"
 Markdown = "*"
@@ -110,17 +110,35 @@ supported_nautobot_versions = [
     "{{ cookiecutter.min_nautobot_version }}"
 ]
 
-[tool.pydocstyle]
-convention = "google"
-inherit = false
-match = "(?!__init__).*\\.py"
-match-dir = "(?!tests|migrations|development)[^\\.].*"
-# D212 is enabled by default in google convention, and complains if we have a docstring like:
-# """
-# My docstring is on the line after the opening quotes instead of on the same line as them.
-# """
-# We've discussed and concluded that we consider this to be a valid style choice.
-add_ignore = "D212"
+[tool.ruff]
+line-length = 120
+target-version = "py38"
+exclude = [
+    "migrations",
+]
+
+[tool.ruff.lint]
+select = [
+    "D1",  # pydocstyle
+    "D2",  # pydocstyle
+    "D3",  # pydocstyle
+    "D4",  # pydocstyle
+]
+ignore = [
+    # warning: `one-blank-line-before-class` (D203) and `no-blank-line-before-class` (D211) are incompatible.
+    "D203",  # 1 blank line required before class docstring
+
+    # D212 is enabled by default in google convention, and complains if we have a docstring like:
+    # """
+    # My docstring is on the line after the opening quotes instead of on the same line as them.
+    # """
+    # We've discussed and concluded that we consider this to be a valid style choice.
+    "D212",  # Multi-line docstring summary should start at the first line
+    "D213",  # Multi-line docstring summary should start at the second line
+
+    # Produces a lot of issues in the current codebase.
+    "D401",  # First line of docstring should be in imperative mood
+]
 
 [build-system]
 requires = ["poetry_core>=1.0.0"]

nautobot-app/{{ cookiecutter.project_slug }}/.github/workflows/ci.yml

@@ -38,7 +38,7 @@ jobs:
         uses: "networktocode/gh-action-setup-poetry-environment@v4"
       - name: "Linting: bandit"
         run: "poetry run invoke bandit"
-  pydocstyle:
+  ruff:
     runs-on: "ubuntu-22.04"
     env:
       INVOKE_{{ cookiecutter.app_name.upper() }}_LOCAL: "True"
@@ -47,8 +47,8 @@ jobs:
         uses: "actions/checkout@v4"
       - name: "Setup environment"
         uses: "networktocode/gh-action-setup-poetry-environment@v4"
-      - name: "Linting: pydocstyle"
-        run: "poetry run invoke pydocstyle"
+      - name: "Linting: ruff"
+        run: "poetry run invoke ruff"
   check-docs-build:
     runs-on: "ubuntu-22.04"
     env:
@@ -96,7 +96,7 @@ jobs:
   pylint:
     needs:
       - "bandit"
-      - "pydocstyle"
+      - "ruff"
       - "flake8"
       - "poetry"
       - "yamllint"
@@ -139,7 +139,7 @@ jobs:
   check-migrations:
     needs:
       - "bandit"
-      - "pydocstyle"
+      - "ruff"
       - "flake8"
       - "poetry"
       - "yamllint"

nautobot-app/{{ cookiecutter.project_slug }}/docs/dev/contributing.md

@@ -7,7 +7,7 @@ The project is packaged with a light [development environment](dev_environment.m
 
 The project is following Network to Code software development guidelines and is leveraging the following:
 
-- Python linting and formatting: `black`, `pylint`, `bandit`, `flake8`, and `pydocstyle`.
+- Python linting and formatting: `black`, `pylint`, `bandit`, `flake8`, and `ruff`.
 - YAML linting is done with `yamllint`.
 - Django unit test to ensure the app is working properly.
 

nautobot-app/{{ cookiecutter.project_slug }}/docs/dev/dev_environment.md

@@ -126,7 +126,7 @@ Each command can be executed with `invoke <command>`. All commands support the a
   bandit           Run bandit to validate basic static code security analysis.
   black            Run black to check that Python files adhere to its style standards.
   flake8           Run flake8 to check that Python files adhere to its style standards.
-  pydocstyle       Run pydocstyle to validate docstring formatting adheres to NTC defined standards.
+  ruff             Run ruff to validate docstring formatting adheres to NTC defined standards.
   pylint           Run pylint code analysis.
   tests            Run all tests for this app.
   unittest         Run Django unit tests for the app.
@@ -467,6 +467,6 @@ To run an individual test, you can run any or all of the following:
 ➜ invoke bandit
 ➜ invoke black
 ➜ invoke flake8
-➜ invoke pydocstyle
+➜ invoke ruff
 ➜ invoke pylint
 ```

nautobot-app/{{ cookiecutter.project_slug }}/pyproject.toml

@@ -36,10 +36,10 @@ django-debug-toolbar = "*"
 flake8 = "*"
 invoke = "*"
 ipython = "*"
-pydocstyle = "*"
 pylint = "*"
 pylint-django = "*"
 pylint-nautobot = "*"
+ruff = "*"
 yamllint = "*"
 toml = "*"
 Markdown = "*"
@@ -109,17 +109,35 @@ supported_nautobot_versions = [
     "{{ cookiecutter.min_nautobot_version }}"
 ]
 
-[tool.pydocstyle]
-convention = "google"
-inherit = false
-match = "(?!__init__).*\\.py"
-match-dir = "(?!tests|migrations|development)[^\\.].*"
-# D212 is enabled by default in google convention, and complains if we have a docstring like:
-# """
-# My docstring is on the line after the opening quotes instead of on the same line as them.
-# """
-# We've discussed and concluded that we consider this to be a valid style choice.
-add_ignore = "D212"
+[tool.ruff]
+line-length = 120
+target-version = "py38"
+exclude = [
+    "migrations",
+]
+
+[tool.ruff.lint]
+select = [
+    "D1",  # pydocstyle
+    "D2",  # pydocstyle
+    "D3",  # pydocstyle
+    "D4",  # pydocstyle
+]
+ignore = [
+    # warning: `one-blank-line-before-class` (D203) and `no-blank-line-before-class` (D211) are incompatible.
+    "D203",  # 1 blank line required before class docstring
+
+    # D212 is enabled by default in google convention, and complains if we have a docstring like:
+    # """
+    # My docstring is on the line after the opening quotes instead of on the same line as them.
+    # """
+    # We've discussed and concluded that we consider this to be a valid style choice.
+    "D212",  # Multi-line docstring summary should start at the first line
+    "D213",  # Multi-line docstring summary should start at the second line
+
+    # Produces a lot of issues in the current codebase.
+    "D401",  # First line of docstring should be in imperative mood
+]
 
 [build-system]
 requires = ["poetry_core>=1.0.0"]

nautobot-app/{{ cookiecutter.project_slug }}/tasks.py

@@ -23,7 +23,8 @@
 def is_truthy(arg):
     """Convert "truthy" strings into Booleans.
 
-    Examples:
+    Examples
+    --------
         >>> is_truthy('yes')
         True
     Args:
@@ -111,6 +112,7 @@ def docker_compose(context, command, **kwargs):
     """Helper function for running a specific docker compose command with all appropriate parameters and environment.
 
     Args:
+    ----
         context (obj): Used to run specific commands
         command (str): Command string to append to the "docker compose ..." command, such as "build", "up", etc.
         **kwargs: Passed through to the context.run() call.
@@ -666,12 +668,34 @@ def pylint(context):
     run_command(context, command)
 
 
-@task
-def pydocstyle(context):
-    """Run pydocstyle to validate docstring formatting adheres to NTC defined standards."""
-    # We exclude the /migrations/ directory since it is autogenerated code
-    command = "pydocstyle ."
-    run_command(context, command)
+@task(aliases=("a",))
+def autoformat(context):
+    """Run code autoformatting."""
+    black(context, autoformat=True)
+    ruff(context, action="both", fix=True)
+
+
+@task(
+    help={
+        "action": "One of 'lint', 'format', or 'both'",
+        "fix": "Automatically fix selected action. May not be able to fix all.",
+        "output_format": "see https://docs.astral.sh/ruff/settings/#output-format",
+    },
+)
+def ruff(context, action="lint", fix=False, output_format="text"):
+    """Run ruff to perform code formatting and/or linting."""
+    if action != "lint":
+        command = "ruff format"
+        if not fix:
+            command += " --check"
+        command += " ."
+        run_command(context, command)
+    if action != "format":
+        command = "ruff check"
+        if fix:
+            command += " --fix"
+        command += f" --output-format {output_format} ."
+        run_command(context, command)
 
 
 @task
@@ -686,6 +710,7 @@ def yamllint(context):
     """Run yamllint to validate formatting adheres to NTC defined YAML standards.
 
     Args:
+    ----
         context (obj): Used to run specific commands
     """
     command = "yamllint . --format standard"
@@ -760,12 +785,12 @@ def tests(context, failfast=False, keepdb=False, lint_only=False):
     # Sorted loosely from fastest to slowest
     print("Running black...")
     black(context)
+    print("Running ruff...")
+    ruff(context)
     print("Running flake8...")
     flake8(context)
     print("Running bandit...")
     bandit(context)
-    print("Running pydocstyle...")
-    pydocstyle(context)
     print("Running yamllint...")
     yamllint(context)
     print("Running poetry check...")