chore: add docstring formatting + linting

.git-blame-ignore-revs

@@ -1,5 +1,5 @@
 # change black settings
 0e4cd56b69e8f83166cd262f762802b7f18c3d21
 
-# apply ruff format across the codebase
-07e8ac9d98c535ade20040883a04734b4c9d04b8
+# apply ruff format across the codebase (#1566)
+5814077ee7ef79eaa4df6e4602260c179536a814

examples/django/manage.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
 """Django's command-line utility for administrative tasks."""
+
 import os
 import sys
 

examples/django/myslackapp/asgi.py

@@ -1,5 +1,4 @@
-"""
-ASGI config for myslackapp project.
+"""ASGI config for myslackapp project.
 
 It exposes the ASGI callable as a module-level variable named ``application``.
 

examples/django/myslackapp/settings.py

@@ -1,5 +1,4 @@
-"""
-Django settings for myslackapp project.
+"""Django settings for myslackapp project.
 
 Generated by 'django-admin startproject' using Django 3.2.3.
 
@@ -9,6 +8,7 @@
 For the full list of settings and their values, see
 https://docs.djangoproject.com/en/3.2/ref/settings/
 """
+
 import os
 from pathlib import Path
 

examples/django/myslackapp/urls.py

@@ -1,7 +1,8 @@
-"""myslackapp URL Configuration
+"""myslackapp URL Configuration.
 
 The `urlpatterns` list routes URLs to views. For more information please see:
     https://docs.djangoproject.com/en/3.2/topics/http/urls/
+
 Examples:
 Function views
     1. Add an import:  from my_app import views
@@ -13,6 +14,7 @@
     1. Import the include() function: from django.urls import include, path
     2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
 """
+
 from django.contrib import admin  # noqa: F401
 from django.urls import path
 

examples/django/myslackapp/wsgi.py

@@ -1,5 +1,4 @@
-"""
-WSGI config for myslackapp project.
+"""WSGI config for myslackapp project.
 
 It exposes the WSGI callable as a module-level variable named ``application``.
 

examples/django/oauth_app/migrations/0001_initial.py

@@ -4,7 +4,6 @@
 
 
 class Migration(migrations.Migration):
-
     initial = True
 
     dependencies = []

examples/django/oauth_app/migrations/0002_token_rotation.py

@@ -5,7 +5,6 @@
 
 
 class Migration(migrations.Migration):
-
     dependencies = [
         ("oauth_app", "0001_initial"),
     ]

examples/google_cloud_functions/oauth_main.py

@@ -52,6 +52,7 @@ def event_test(body, say, logger):
 # Cloud Function
 def hello_bolt_app(req: Request):
     """HTTP Cloud Function.
+
     Args:
         req (flask.Request): The request object.
         <https://flask.palletsprojects.com/en/1.1.x/api/#incoming-request-data>

examples/google_cloud_functions/simple_main.py

@@ -32,6 +32,7 @@ def event_test(body, say, logger):
 # Cloud Function
 def hello_bolt_app(req: Request):
     """HTTP Cloud Function.
+
     Args:
         req (flask.Request): The request object.
         <https://flask.palletsprojects.com/en/1.1.x/api/#incoming-request-data>

examples/message_events.py

@@ -46,8 +46,7 @@ def reply_in_thread(body: dict, say: Say):
     event={"type": "message", "subtype": "message_deleted"},
     matchers=[
         # Skip the deletion of messages by this listener
-        lambda body: "You've deleted a message: "
-        not in body["event"]["previous_message"]["text"]
+        lambda body: "You've deleted a message: " not in body["event"]["previous_message"]["text"]
     ],
 )
 def detect_deletion(say: Say, body: dict):

pyproject.toml

@@ -42,8 +42,28 @@ universal = true
 line-length = 125
 
 [tool.ruff.lint]
-select = ["E", "W", "F"]
-ignore = ["F841", "F821", "E402"]
+select = ["E", "W", "F", "D"]
+ignore = [
+	"F841",
+	"F821",
+	"E402",
+	# missing-docstring: do not add docstrings where none exist (the only D rules ignored)
+	"D100",
+	"D101",
+	"D102",
+	"D103",
+	"D104",
+	"D105",
+	"D106",
+	"D107",
+]
+
+[tool.ruff.lint.pydocstyle]
+# Keep `select = ["D"]` a bare category select; listing explicit D codes would override this convention.
+convention = "google"
+
+[tool.ruff.format]
+docstring-code-format = true
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

scripts/format.sh

@@ -11,4 +11,4 @@ if [[ "$1" != "--no-install" ]]; then
 fi
 
 ruff check --fix slack_bolt/ examples/
-ruff format slack_bolt/ tests/
+ruff format slack_bolt/ tests/ examples/

scripts/lint.sh

@@ -10,3 +10,4 @@ if [[ "$1" != "--no-install" ]]; then
 fi
 
 ruff check slack_bolt/ examples/
+ruff format --check slack_bolt/ tests/ examples/

slack_bolt/__init__.py

@@ -1,5 +1,4 @@
-"""
-A Python framework to build Slack apps in a flash with the latest platform features.Read the [getting started guide](https://docs.slack.dev/tools/bolt-python/creating-an-app) and look at our [code examples](https://github.com/slackapi/bolt-python/tree/main/examples) to learn how to build apps using Bolt.
+"""A Python framework to build Slack apps in a flash with the latest platform features. Read the [getting started guide](https://docs.slack.dev/tools/bolt-python/creating-an-app) and look at our [code examples](https://github.com/slackapi/bolt-python/tree/main/examples) to learn how to build apps using Bolt.
 
 * Website: https://docs.slack.dev/tools/bolt-python/
 * GitHub repository: https://github.com/slackapi/bolt-python

slack_bolt/adapter/asgi/aiohttp/__init__.py

@@ -12,6 +12,7 @@ class AsyncSlackRequestHandler(SlackRequestHandler):
 
     def __init__(self, app: AsyncApp, path: str = "/slack/events"):
         """Setup Bolt as an ASGI web framework, this will make your application compatible with ASGI web servers.
+
         This can be used for production deployment.
 
         With the default settings, `http://localhost:3000/slack/events`

slack_bolt/adapter/asgi/base_handler.py

@@ -18,15 +18,15 @@ class BaseSlackRequestHandler:
     path: str
 
     async def dispatch(self, request: AsgiHttpRequest) -> BoltResponse:
-        """Dispatches a request to the Bolt App"""
+        """Dispatches a request to the Bolt App."""
         raise NotImplementedError
 
     async def handle_installation(self, request: AsgiHttpRequest) -> BoltResponse:
-        """Handles installation of the OAuthFlow"""
+        """Handles installation of the OAuthFlow."""
         raise NotImplementedError
 
     async def handle_callback(self, request: AsgiHttpRequest) -> BoltResponse:
-        """Handles the callback of the OAuthFlow"""
+        """Handles the callback of the OAuthFlow."""
         raise NotImplementedError
 
     async def _get_http_response(self, method: str, path: str, request: AsgiHttpRequest) -> AsgiHttpResponse:

slack_bolt/adapter/asgi/builtin/__init__.py

@@ -11,6 +11,7 @@
 class SlackRequestHandler(BaseSlackRequestHandler):
     def __init__(self, app: App, path: str = "/slack/events"):
         """Setup Bolt as an ASGI web framework, this will make your application compatible with ASGI web servers.
+
         This can be used for production deployment.
 
         With the default settings, `http://localhost:3000/slack/events`

slack_bolt/adapter/django/handler.py

@@ -72,6 +72,7 @@ def release_thread_local_connections(logger: Logger, execution_timing: str):
 
 class DjangoListenerStartHandler(ListenerStartHandler):
     """Django sets DB connections as a thread-local variable per thread.
+
     If the thread is not managed on the Django app side, the connections won't be released by Django.
     This handler releases the connections every time a ThreadListenerRunner execution completes.
     """
@@ -82,6 +83,7 @@ def handle(self, request: BoltRequest, response: Optional[BoltResponse]) -> None
 
 class DjangoListenerCompletionHandler(ListenerCompletionHandler):
     """Django sets DB connections as a thread-local variable per thread.
+
     If the thread is not managed on the Django app side, the connections won't be released by Django.
     This handler releases the connections every time a ThreadListenerRunner execution completes.
     """

slack_bolt/adapter/falcon/async_resource.py

@@ -12,8 +12,7 @@
 
 
 class AsyncSlackAppResource:
-    """
-    For use with ASGI Falcon Apps.
+    """For use with ASGI Falcon Apps.
 
     from slack_bolt.async_app import AsyncApp
     app = AsyncApp()

slack_bolt/adapter/falcon/resource.py

@@ -11,7 +11,8 @@
 
 
 class SlackAppResource:
-    """
+    """For use with WSGI Falcon Apps.
+
     from slack_bolt import App
     app = App()
 

slack_bolt/adapter/socket_mode/aiohttp/__init__.py

@@ -1,4 +1,4 @@
-"""[`aiohttp`](https://pypi.org/project/aiohttp/) based implementation / asyncio compatible"""
+"""[`aiohttp`](https://pypi.org/project/aiohttp/) based implementation / asyncio compatible."""
 
 import os
 from logging import Logger
@@ -35,7 +35,7 @@ def __init__(
         proxy: Optional[str] = None,
         ping_interval: float = 10,
     ):
-        """Socket Mode adapter for Bolt apps
+        """Socket Mode adapter for Bolt apps.
 
         Args:
             app: The Bolt app

slack_bolt/adapter/socket_mode/async_base_handler.py

@@ -1,4 +1,4 @@
-"""The base class of asyncio-based Socket Mode client implementation"""
+"""The base class of asyncio-based Socket Mode client implementation."""
 
 import asyncio
 import logging
@@ -26,20 +26,20 @@ async def handle(self, client: AsyncBaseSocketModeClient, req: SocketModeRequest
         raise NotImplementedError()
 
     async def connect_async(self):
-        """Establishes a new connection with the Socket Mode server"""
+        """Establishes a new connection with the Socket Mode server."""
         await self.client.connect()
 
     async def disconnect_async(self):
-        """Disconnects the current WebSocket connection with the Socket Mode server"""
+        """Disconnects the current WebSocket connection with the Socket Mode server."""
         await self.client.disconnect()
 
     async def close_async(self):
-        """Disconnects from the Socket Mode server and cleans the resources this instance holds up"""
+        """Disconnects from the Socket Mode server and cleans the resources this instance holds up."""
         await self.client.close()
 
     async def start_async(self):
-        """Establishes a new connection and then starts infinite sleep
-        to prevent the termination of this process.
+        """Establishes a new connection and then starts infinite sleep to prevent the termination of this process.
+
         If you don't want to have the sleep, use `#connect()` method instead.
         """
         await self.connect_async()

slack_bolt/adapter/socket_mode/async_internals.py

@@ -1,4 +1,4 @@
-"""Internal functions"""
+"""Internal functions."""
 
 import json
 import logging

slack_bolt/adapter/socket_mode/base_handler.py

@@ -1,4 +1,5 @@
 """The base class of Socket Mode client implementation.
+
 If you want to build asyncio-based ones, use `AsyncBaseSocketModeHandler` instead.
 """
 
@@ -28,20 +29,20 @@ def handle(self, client: BaseSocketModeClient, req: SocketModeRequest) -> None:
         raise NotImplementedError()
 
     def connect(self):
-        """Establishes a new connection with the Socket Mode server"""
+        """Establishes a new connection with the Socket Mode server."""
         self.client.connect()
 
     def disconnect(self):
-        """Disconnects the current WebSocket connection with the Socket Mode server"""
+        """Disconnects the current WebSocket connection with the Socket Mode server."""
         self.client.disconnect()
 
     def close(self):
-        """Disconnects from the Socket Mode server and cleans the resources this instance holds up"""
+        """Disconnects from the Socket Mode server and cleans the resources this instance holds up."""
         self.client.close()
 
     def start(self):
-        """Establishes a new connection and then blocks the current thread
-        to prevent the termination of this process.
+        """Establishes a new connection and then blocks the current thread to prevent the termination of this process.
+
         If you don't want to block the current thread, use `#connect()` method instead.
         """
         self.connect()

slack_bolt/adapter/socket_mode/builtin/__init__.py

@@ -1,4 +1,4 @@
-"""The built-in implementation, which does not have any external dependencies"""
+"""The built-in implementation, which does not have any external dependencies."""
 
 import os
 from logging import Logger
@@ -36,7 +36,7 @@ def __init__(
         receive_buffer_size: int = 1024,
         concurrency: int = 10,
     ):
-        """Socket Mode adapter for Bolt apps
+        """Socket Mode adapter for Bolt apps.
 
         Args:
             app: The Bolt app

slack_bolt/adapter/socket_mode/internals.py

@@ -1,4 +1,4 @@
-"""Internal functions"""
+"""Internal functions."""
 
 import json
 import logging

slack_bolt/adapter/socket_mode/websocket_client/__init__.py

@@ -1,4 +1,4 @@
-"""[`websocket-client`](https://pypi.org/project/websocket-client/) based implementation"""
+"""[`websocket-client`](https://pypi.org/project/websocket-client/) based implementation."""
 
 import os
 from logging import Logger
@@ -34,7 +34,7 @@ def __init__(
         proxy_type: Optional[str] = None,
         trace_enabled: bool = False,
     ):
-        """Socket Mode adapter for Bolt apps
+        """Socket Mode adapter for Bolt apps.
 
         Args:
             app: The Bolt app

slack_bolt/adapter/socket_mode/websockets/__init__.py

@@ -1,4 +1,4 @@
-"""[`websockets`](https://pypi.org/project/websockets/) based implementation  / asyncio compatible"""
+"""[`websockets`](https://pypi.org/project/websockets/) based implementation  / asyncio compatible."""
 
 import os
 from logging import Logger

slack_bolt/adapter/wsgi/handler.py

@@ -14,6 +14,7 @@
 class SlackRequestHandler:
     def __init__(self, app: App, path: str = "/slack/events"):
         """Setup Bolt as a WSGI web framework, this will make your application compatible with WSGI web servers.
+
         This can be used for production deployments.
 
         With the default settings, `http://localhost:3000/slack/events`

slack_bolt/adapter/wsgi/http_request.py

@@ -7,8 +7,7 @@
 
 
 class WsgiHttpRequest:
-    """This Class uses the PEP 3333 standard to extract request information
-    from the WSGI web server running the application
+    """Extracts request information from the WSGI web server using the PEP 3333 standard.
 
     PEP 3333: https://peps.python.org/pep-3333/
     """

slack_bolt/adapter/wsgi/http_response.py

@@ -5,8 +5,7 @@
 
 
 class WsgiHttpResponse:
-    """This Class uses the PEP 3333 standard to adapt bolt response information
-    for the WSGI web server running the application
+    """Adapts bolt response information for the WSGI web server using the PEP 3333 standard.
 
     PEP 3333: https://peps.python.org/pep-3333/
     """