Opt into all pydocstyle rules by default

Most of the changes here were applied automatically (and are just
newlines), but a few were done by hand. In any case, it's sensible to
lint into the ruleset by default, *then* ignore what we don't need (had
we been doing this from the start, we would have been opted into the new
& helpful rule D205 for enforcing one blank line between summary &
description, per https://peps.python.org/pep-0257/#multi-line-docstrings

Author: DavidCain

pyproject.toml

@@ -9,6 +9,7 @@ lint.select = [
   "C4",    # flake8-comprehensions
   "C90",   # mccabe
   "COM",   # flake8-commas
+  "D",     # pydocstyle
   "DJ",    # flake8-django
   "DTZ",   # flake8-datetimez
   "E",     # pycodestyle error
@@ -46,12 +47,6 @@ lint.select = [
   "W",     # pycodestyle warning
   "YTT",   # flake8-2020
 
-  # Docstring normalization
-  "D404",  # Don't start docstrings with "This"
-  "D200",  # One-line docstrings on one line
-  "D210",  # No superfluous whitespace
-  "D212",  # Multi-line docstrings start on first line
-
   # Interesting, should perhaps turn on later:
   # "PTH",  # flake8-use-pathlib
   # "FLY",  # flynt
@@ -82,7 +77,14 @@ lint.ignore = [
   "D100",     # Not all public classes need docstrings.
   "D101",     # Not all public classes need docstrings.
   "D102",     # Not all public methods need docstrings.
+  "D103",     # Not all public methods need docstrings.
+  "D104",     # Not all packages need docstrings.
+  "D105",     # Not all magic methods need docstrings.
+  "D106",     # Not all public classes need docstrings.
   "D107",     # Not all `__init__` methods need docstrings.
+  "D400",     # I don't care if summary lines are sentences
+  "D401",     # I don't care how summary lines are conjugated
+  "D415",     # I don't care if summary lines are sentences
   "N806",     # Function arguments are frequently uppercase in migrations.
   "PLR2004",  # Tests & simple logic extensively use "magic values"
   "PT009",    # I intentionally use `unittest`-style tests.
@@ -103,6 +105,10 @@ lint.ignore = [
   "ISC001",
   "COM812",   # Formatter manages commas.
   "E501",     # Formatter manages line length.
+
+  # Errors that conflict with *other* rules in their own ruleset
+  "D213",     # Method summaries can go on the first line (conflicts with D212)
+  "D203",     # No blank line before class (conflicts with D211)
 ]
 
 # By default, `ruff` will respect `.gitignore`

ws/api_views.py

@@ -301,7 +301,6 @@ def post(self, request, *args, **kwargs):
         - Participant has never signed up for the trip, will be placed
         - Participant has signed up before, but is not on the trip
         """
-
         postdata = json.loads(self.request.body)
         par_pk = postdata.get("participant_id")
         notes = postdata.get("notes", "")
@@ -562,7 +561,6 @@ def dispatch(self, request, *args, **kwargs):
 class UpdateMembershipView(JWTView):
     def post(self, request, *args, **kwargs):
         """Receive a message that the user's membership was updated."""
-
         participant = models.Participant.from_email(self.payload["email"])
         if not participant:  # Not in our system, nothing to do
             return JsonResponse({})
@@ -592,7 +590,6 @@ def post(self, request, *args, **kwargs):
 class OtherVerifiedEmailsView(JWTView):
     def get(self, request, *args, **kwargs):
         """Return any other verified emails that tie to the same user."""
-
         email = self.payload["email"]
 
         addr = EmailAddress.objects.filter(email=email, verified=True).first()

ws/templatetags/form_tags.py

@@ -12,8 +12,7 @@ def readonly_form(form):
 
 @register.filter
 def instances_and_widgets(bound_field):
-    """Yields two-tuples of instances and widgets, designed to
-    be used with ModelMultipleChoiceField and CheckboxSelectMultiple widgets.
+    """Yields instances and widgets for use with ModelMultipleChoiceField & CheckboxSelectMultiple.
 
     Allows templates to loop over a multiple checkbox field and display the
     related model instance, such as for a table with checkboxes.

ws/templatetags/rental_tags.py

@@ -6,7 +6,6 @@
 @register.inclusion_tag("for_templatetags/trip_rental_table.html")
 def trip_rental_table(trip, leader_on_trip, items_by_par, show_serial=False):
     """Display a table of all items rented by participants."""
-
     # Enforce items are only those rented before the trip itself
     # (Items rented by participants _after_ the trip has ended were not for the trip)
     items_by_par = [

ws/tests/lottery/test_graphs.py

@@ -201,9 +201,9 @@ def test_multiple_cycles(self):
     def test_graph_is_a_tree(self):
         r"""Test when the directed graph is just a tree (has no cycles)
 
-             A ---> B --> C
-                    \
-                     \--> D
+        A ---> B --> C
+               \
+                 \--> D
         """
         a, b, c, d = (
             factories.ParticipantFactory.create(name=letter) for letter in "ABCD"

ws/tests/messages/test_lottery.py

@@ -57,7 +57,6 @@ def test_no_lottery_info(self):
     @freeze_time("2017-01-17 12:00:00 EST")
     def test_driver_with_no_info(self):
         """We ask participants who said they could drive to supply info."""
-
         par = factories.ParticipantFactory.create()
         factories.LotteryInfoFactory.create(participant=par, car_status="own")
         self.assertIsNone(par.car)

ws/tests/test_settings.py

@@ -46,7 +46,6 @@ def _reimport_if_needed(name, *args):
 
     def _fresh_settings_load(self):
         """Do a fresh re-import of the settings module!"""
-
         with mock.patch("builtins.__import__", side_effect=self._reimport_if_needed):
             reload(settings)
 
@@ -108,7 +107,6 @@ def fake_toolbar(name, *args):
     def test_local_development_without_debug_toolbar(self):
         """We configure installed applications properly when debug toolbar is absent.
 
-
         In most test builds, we won't have `debug_toolbar` installed, but this guarantees
         coverage of behavior when we do not.
         """
@@ -146,7 +144,6 @@ def test_production_security(self):
 
     def test_sentry_not_initialized_if_envvar_present(self):
         """During local development, we can disable Sentry."""
-
         with mock.patch.dict("os.environ", {"WS_DJANGO_LOCAL": "1"}, clear=True):
             with mock.patch.object(settings.sentry_sdk, "init") as init_sentry:
                 self._fresh_settings_load()

ws/tests/utils/test_dates.py

@@ -236,7 +236,6 @@ def test_past_trips(self):
 
     def test_future_trips(self):
         """When there are no past trips, but there are upcoming trips."""
-
         self._create_ws_trip(date(2018, 1, 5))
         self._create_ws_trip(date(2018, 1, 6))
 

ws/tests/utils/test_forms.py

@@ -18,7 +18,6 @@ def test_normal_case(self):
 
     def test_mixed_named_groups(self):
         """It works mixing named groups & non-groups."""
-
         choices = [
             (
                 "Undergraduate student",
@@ -43,7 +42,6 @@ def test_mixed_named_groups(self):
 
     def test_nested_groups(self):
         """Nested named groups are handled properly."""
-
         choices = [
             (
                 "MIT",

ws/tests/utils/test_perms.py

@@ -80,7 +80,6 @@ def setUpClass(cls) -> None:
 
     def test_activity_chair(self):
         """The admin can be considered an activity chair in some contexts."""
-
         self.assertTrue(perm_utils.chair_or_admin(self.admin, enums.Activity.HIKING))
         self.assertTrue(perm_utils.is_chair(self.admin, enums.Activity.HIKING))
         self.assertTrue(

ws/tests/views/test_api_views.py

@@ -163,7 +163,6 @@ def test_normal_participant(self):
 
     def test_user_without_participant(self):
         """We handle the case of a user who never completed a participant record."""
-
         factories.UserFactory.create(email="[email protected]")
         response = self._query_for("[email protected]")
         self.assertEqual(response.status_code, 200)

ws/unsubscribe.py

@@ -81,9 +81,11 @@ def generate_unsubscribe_token(participant: models.Participant) -> str:
 def unsign_token(token: str) -> UnsubscribeTarget:
     """Extract the participant & desired unsubscribe topics from a signed payload.
 
-    Raises:
+    Raises
+    ------
         signing.SignatureExpired: Token is >30 days old
         signing.BadSignature: Token is invalid (or just >30 days old)
+
     """
     payload: TokenPayload = _get_signer().unsign_object(
         token,
@@ -108,8 +110,10 @@ def _bad_token_reason(exception: signing.BadSignature) -> str:
 def unsubscribe_from_token(token: str) -> models.Participant:
     """Attempt to unsubscribe the participant based on an (assumed valid) token.
 
-    Raises:
+    Raises
+    ------
         InvalidTokenError: Expired token, invalid token, or participant gone
+
     """
     # Any exceptions this method raises have messages meant to be consumed by humans.
     # We don't need the full traceback.

ws/utils/member_stats.py

@@ -115,7 +115,6 @@ def fetch_geardb_stats_for_all_members(
     cache_strategy: CacheStrategy,
 ) -> MemberStatsResponse:
     """Report emails & rental activity for all members with current dues."""
-
     acceptable_staleness = timedelta(
         hours=(0 if cache_strategy == CacheStrategy.BYPASS else 1)
     ).total_seconds()

ws/utils/ratings.py

@@ -40,7 +40,6 @@ def activity_enum(self) -> enums.Activity:
 
     def activity_chairs(self) -> QuerySet[User]:
         """Return the chairs for this activity."""
-
         # It's important that this remain a method, not stored at init.
         # This way, views that want to get activity from self.kwargs can inherit from the mixin
         return perm_utils.activity_chairs(self.activity_enum)

ws/views/participant.py

@@ -87,7 +87,8 @@ def has_car(self) -> bool:
         return "has_car" in self.request.POST
 
     def get_context_data(self, **kwargs: Any) -> dict[str, Any]:
-        """Return a dictionary primarily of forms to for template rendering.
+        """Return a dictionary primarily of forms for template rendering.
+
         Also includes a value for the "I have a car" checkbox.
 
         Outputs three types of forms: