#88: Ruff - Enable A through D (#109)

* 88: enable flake8-builtins.

* add comment to flake8-annotations, we'll revisit after the rest.

* #88: enable flake8-unused-arguments.

* #88: enable flake8-bugbear.

* #88: enable flake8-blind-except

* #88: enable flake8-comprehensions.

* #88: enable pydocstyle.

* undo extra, outside-pr-scope work.

* update lint workflows to use ruff instead of isort, pylint, and flake8.

* update dependencies.

* #88: update tests after exception message update.

.github/workflows/lint.yml

@@ -32,15 +32,9 @@ jobs:
       - name: Lint with black
         run: |
           black --check --diff screenpy
-      - name: Lint with isort
-        run: |
-          isort --check-only --diff screenpy
-      - name: Lint with flake8
-        run: |
-          flake8 --exit-zero screenpy
       - name: Lint with mypy
         run: |
           mypy screenpy
-      - name: Lint with pylint
+      - name: Lint with ruff
         run: |
-          pylint screenpy
+          ruff .

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ repos:
     language_version: python3.11
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.0.291
+  rev: v0.0.292
   hooks:
     - id: ruff
 - repo: https://github.com/pre-commit/mirrors-mypy

pyproject.toml

@@ -36,6 +36,7 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
 ]
 
+
 # It's possible to add optional dependencies with the poetry CLI tool using:
 #   poetry add --optional some_dev_pkg
 # This will set `optional = true` flag in [tool.poetry.dependencies], as seen below
@@ -72,6 +73,7 @@ screenpy-selenium = {version = "^4.0.3", optional = true}
 sphinx = {version = "^6.1.3", optional = true}
 tox = {version = "*", optional = true}
 
+
 [tool.poetry.extras]
 allure = ["screenpy-adapter-allure"]
 appium = ["screenpy-appium"]
@@ -107,17 +109,18 @@ test = [
     "pytest",
 ]
 
+
 [tool.ruff]
 target-version = "py38"  # minimum supported version
 line-length = 88  # same as Black.
 select = [
-    # "A",  # flake8-builtins
-    # "ANN",  # flake8-annotations
-    # "ARG",  # flake8-unused-arguments
-    # "B",  # flake8-bugbear
-    # "BLE",  # flake8-blind-except
-    # "C4",  # flake8-comprehensions
-    # "D",  # pydocstyle
+    "A",  # flake8-builtins
+    # "ANN",  # flake8-annotations  # coming back to this one later to compare against mypy
+    "ARG",  # flake8-unused-arguments
+    "B",  # flake8-bugbear
+    "BLE",  # flake8-blind-except
+    "C4",  # flake8-comprehensions
+    "D",  # pydocstyle
     # "E",  # pycodestyle error
     # "EM",  # flake8-errmsg
     # "ERA",  # eradicate
@@ -171,11 +174,13 @@ exclude = [
     "PLR",  # likewise using specific numbers and strings in tests.
 ]
 
+
 [tool.ruff.isort]
 combine-as-imports = true
 split-on-trailing-comma = true
 known-first-party = ["screenpy", "tests"]
 
+
 [tool.ruff.flake8-pytest-style]
 mark-parentheses = false
 

screenpy/actions/__init__.py

@@ -1,6 +1,4 @@
-"""
-Actions are what the Actors do, possibly requiring use of their Abilities.
-"""
+"""Actions are what the Actors do, possibly requiring use of their Abilities."""
 
 from .attach_the_file import AttachTheFile
 from .debug import Debug

screenpy/actions/attach_the_file.py

@@ -1,6 +1,4 @@
-"""
-Attach a file.
-"""
+"""Attach a file."""
 
 import os
 from typing import Any

screenpy/actions/debug.py

@@ -1,7 +1,8 @@
-"""
-Launch a debugger either using the debugger set in the PYTHONBREAKPOINT
-environment variable or pdb. (See more information in PEP-553
-https://www.python.org/dev/peps/pep-0553/)
+"""Debug a performance.
+
+Launch a debugger either using pdb or the debugger set in the PYTHONBREAKPOINT
+environment variable.
+(See more information in PEP-553 https://www.python.org/dev/peps/pep-0553/)
 """
 
 import pdb
@@ -40,7 +41,6 @@ def describe(self) -> str:
     @beat("{} assumes direct control...")
     def perform_as(self, _: Actor) -> None:
         """Direct the Actor to activate a debugger."""
-
         try:
             # Hello! To get to the perform loop and step through the remaining
             # Actions, you will need to go "up" about 3 times.

screenpy/actions/either.py

@@ -1,5 +1,6 @@
-"""
-try/accept logic using screenplay pattern
+"""Attempt one of two different performances.
+
+Simulates a try/except control flow, but in Screenplay Pattern.
 """
 
 from __future__ import annotations
@@ -16,9 +17,13 @@
 
 
 class Either:
-    """Either performs followup action if the first one fails.
+    """Perform one of two branching performances.
+
+    Simulates a try/except block while still following Screenplay Pattern.
 
-    Allows actors to perform try/except blocks while still using screenplay pattern.
+    By default, ``Either`` catches AssertionErrors, so you can use
+    :class:`~screenpy.actions.See` to decide which path to follow. Use the
+    :meth:`~screenpy.actions.Either.ignoring` method to ignore other exceptions.
 
     Examples::
 
@@ -30,6 +35,7 @@ class Either:
             )
         )
 
+        # using a custom Task which raises AssertionError
         the_actor.will(
             Either(CheckIfOnDomain(URL())).or_(Open.their_browser_on(URL())
         )
@@ -39,7 +45,7 @@ class Either:
     ignore_exceptions: tuple[type[BaseException], ...]
 
     def perform_as(self, the_actor: Actor) -> None:
-        """Direct the Actor to do one of two actions using try/accept."""
+        """Direct the Actor to perform one of two performances."""
         # kinking the cable before the attempt
         # avoids explaning what the actor tries to do.
         # logs the first attempt only if it succeeds
@@ -71,7 +77,7 @@ def or_(self, *except_performables: Performable) -> Either:
     except_ = else_ = otherwise = alternatively = failing_that = or_
 
     def ignoring(self, *ignored_exceptions: type[BaseException]) -> Either:
-        """Set the expception classes to Ignore"""
+        """Set the expception classes to ignore."""
         self.ignore_exceptions = ignored_exceptions
         return self
 

screenpy/actions/eventually.py

@@ -1,6 +1,4 @@
-"""
-Eventually perform a Task or Action, trying until a set timeout.
-"""
+"""Eventually perform a Task or Action, trying until a set timeout."""
 
 import time
 from traceback import format_tb
@@ -47,10 +45,7 @@ class Eventually:
     timeout: float
 
     class _TimeframeBuilder:
-        """
-        Allows caller of Eventually to tack on waiting for specific time
-        frames in seconds or milliseconds.
-        """
+        """Build a timeframe, combining numbers and units."""
 
         def __init__(
             self, eventually: "Eventually", amount: float, attribute: str
@@ -137,7 +132,7 @@ def perform_as(self, the_actor: Actor) -> None:
                 try:
                     the_actor.attempts_to(self.performable)
                     return
-                except Exception as exc:  # pylint: disable=broad-except
+                except Exception as exc:  # noqa: BLE001
                     self.caught_error = exc
                     if not any(same_exception(exc, c) for c in self.unique_errors):
                         self.unique_errors.append(exc)
@@ -165,10 +160,10 @@ def __init__(self, performable: Performable):
         self.poll = settings.POLLING
 
 
-def same_exception(a: BaseException, b: BaseException) -> bool:
-    """compare exceptions to see if they match"""
+def same_exception(exc1: BaseException, exc2: BaseException) -> bool:
+    """Compare two exceptions to see if they match."""
     return (
-        isinstance(a, type(b))
-        and (str(a) == str(b))
-        and (format_tb(a.__traceback__) == format_tb(b.__traceback__))
+        isinstance(exc1, type(exc2))
+        and (str(exc1) == str(exc2))
+        and (format_tb(exc1.__traceback__) == format_tb(exc2.__traceback__))
     )

screenpy/actions/log.py

@@ -1,13 +1,11 @@
-"""
-Log the answer to a Question or other Answerable.
-"""
+"""Log the answer to a Question or other Answerable, or a value."""
 
 from typing import Type, TypeVar
 
 from screenpy.actor import Actor
 from screenpy.pacing import aside, beat
 from screenpy.protocols import Answerable
-from screenpy.speech_tools import get_additive_description
+from screenpy.speech_tools import get_additive_description, represent_prop
 
 from .see import T_Q
 
@@ -18,7 +16,7 @@ class Log:
     """Log the answer to a Question, or anything.
 
     Probably most useful for debugging a test, or for announcing the
-    answer to a question for the record.
+    answer to a Question for the record.
 
     Examples::
         the_actor.attempts_to(Log(HowManyBirdsAreInTheSky()))
@@ -37,8 +35,8 @@ def perform_as(self, the_actor: Actor) -> None:
         if isinstance(self.question, Answerable):
             self.question.answered_by(the_actor)
         else:
-            # must be a value instead of a question!
-            aside(f"the value is: {self.question}")
+            # must be a value instead of a Question!
+            aside(f"the value is: {represent_prop(self.question)}")
 
     def __init__(self, question: T_Q) -> None:
         self.question = question

screenpy/actions/make_note.py

@@ -1,6 +1,4 @@
-"""
-Make a quick note about the answer to a Question.
-"""
+"""Make a quick note about the answer to a Question."""
 
 from typing import Optional, Type, TypeVar, Union
 

screenpy/actions/pause.py

@@ -1,6 +1,4 @@
-"""
-Pause test execution for a specific time frame.
-"""
+"""Pause test execution for a specific time frame."""
 
 import re
 from time import sleep

screenpy/actions/see.py

@@ -1,6 +1,4 @@
-"""
-Make an assertion using a Question and a Resolution.
-"""
+"""Make an assertion using a Question/value and a Resolution."""
 
 from typing import Type, TypeVar, Union
 
@@ -19,7 +17,7 @@
 class See:
     """See if a value or the answer to a Question matches the Resolution.
 
-    This is a very important Action in ScreenPy. It is the way to perform
+    This is a very important Action in ScreenPy; it is the way to perform
     test assertions. For more information, see the documentation for
     :ref:`Questions` and :ref:`Resolutions`.
 

screenpy/actions/see_all_of.py

@@ -1,7 +1,4 @@
-"""
-Make several assertions using any number of Question and Resolution tuples,
-all of which are expected to be true.
-"""
+"""Make several assertions, all of which are expected to be True."""
 
 from typing import Tuple, Type, TypeVar
 

screenpy/actions/see_any_of.py

@@ -1,7 +1,4 @@
-"""
-Make several assertions using any number of Question and Resolution tuples,
-at least one of which is expected to be true.
-"""
+"""Make several assertions, at least one of which is expected to be True."""
 
 from typing import Tuple, Type, TypeVar