refactor(lint): Update Linting Checks and fix missed lint errors (#159)

Author: holtskinner

.github/linters/.jscpd.json

@@ -1,5 +1,5 @@
 {
-  "ignore": ["**/.github/**", "**/.git/**", "**/tests/**", "**/examples/**"],
+  "ignore": ["**/.github/**", "**/.git/**", "**/tests/**"],
   "threshold": 3,
   "reporters": ["html", "markdown"]
 }

.ruff.toml renamed to .github/linters/.ruff.toml

@@ -13,19 +13,22 @@ target-version = "py310" # Minimum Python version
 
 [lint]
 ignore = [
-    "COM812",
-    "FBT001",
-    "FBT002",
-    "D203",
-    "D213",
-    "D100", # Ignore Missing docstring in public module (often desired at top level __init__.py)
-    "D104", # Ignore Missing docstring in public package (often desired at top level __init__.py)
-    "D107", # Ignore Missing docstring in __init__ (use class docstring)
-    "TD002", # Ignore Missing author in TODOs (often not required)
-    "TD003", # Ignore Missing issue link in TODOs (often not required/available)
-    "T201", # Ignore print presence
+    "COM812", # Trailing comma missing.
+    "FBT001", # Boolean positional arg in function definition
+    "FBT002", # Boolean default value in function definition
+    "D203",   # 1 blank line required before class docstring (Google: 0)
+    "D213",   # Multi-line docstring summary should start at the second line (Google: first line)
+    "D100",   # Ignore Missing docstring in public module (often desired at top level __init__.py)
+    "D104",   # Ignore Missing docstring in public package (often desired at top level __init__.py)
+    "D107",   # Ignore Missing docstring in __init__ (use class docstring)
+    "TD002",  # Ignore Missing author in TODOs (often not required)
+    "TD003",  # Ignore Missing issue link in TODOs (often not required/available)
+    "T201",   # Ignore print presence
     "RUF012", # Ignore Mutable class attributes should be annotated with `typing.ClassVar`
-    "RUF013", # Ignore implicit optional
+    "E501",   # Ignore line length (handled by Ruff's dynamic line length)
+    "ANN002",
+    "ANN003",
+    "ANN401",
 ]
 
 select = [
@@ -46,12 +49,14 @@ select = [
     "PTH",# flake8-use-pathlib (use pathlib instead of os.path where possible)
     "PL", # Pylint rules ported to Ruff (PLC, PLE, PLR, PLW)
     "PIE",# flake8-pie (misc code improvements, e.g., no-unnecessary-pass)
-    "RUF",# Ruff-specific rules (e.g., RUF001-003 ambiguous unicode)
+    "RUF",# Ruff-specific rules (e.g., RUF001-003 ambiguous unicode, RUF013 implicit optional)
     "RET",# flake8-return (consistency in return statements)
     "SLF",# flake8-self (check for private member access via `self`)
     "TID",# flake8-tidy-imports (relative imports, banned imports - configure if needed)
     "YTT",# flake8-boolean-trap (checks for boolean positional arguments, truthiness tests - Google Style §3.10)
     "TD", # flake8-todos (check TODO format - Google Style §3.7)
+    "TCH",# flake8-type-checking (helps manage TYPE_CHECKING blocks and imports)
+    "PYI",# flake8-pyi (best practices for .pyi stub files, some rules are useful for .py too)
 ]
 
 exclude = [
@@ -76,7 +81,7 @@ exclude = [
     "node_modules",
     "venv",
     "*/migrations/*",
-    "test_*",
+    "noxfile.py",
 ]
 
 [lint.isort]
@@ -94,6 +99,8 @@ lines-between-types = 1
 
 [lint.pydocstyle]
 convention = "google"
+ignore-decorators = ["typing.overload", "abc.abstractmethod"]
+ignore-var-parameters = true
 
 [lint.flake8-annotations]
 mypy-init-return = true
@@ -113,11 +120,26 @@ inline-quotes = "single"
 
 [lint.per-file-ignores]
 "__init__.py" = ["F401", "D", "ANN"]  # Ignore unused imports in __init__.py
-"*_test.py" = ["D", "ANN"]  # Ignore docstring and annotation issues in test files
-"test_*.py" = ["D", "ANN"]  # Ignore docstring and annotation issues in test files
+"*_test.py" = [
+    "D",      # All pydocstyle rules
+    "ANN",    # Missing type annotation for function argument
+    "RUF013", # Implicit optional type in test function signatures
+    "S101",   # Use of `assert` detected (expected in tests)
+    "PLR2004",
+    "SLF001",
+]
+"test_*.py" = [
+    "D",
+    "ANN",
+    "RUF013",
+    "S101",
+    "PLR2004",
+    "SLF001",
+]
 "types.py" = ["D", "E501", "N815"]  # Ignore docstring and annotation issues in types.py
 
 [format]
+exclude = ["types.py"]
 docstring-code-format = true
 docstring-code-line-length = "dynamic" # Or set to 80
 quote-style = "single"

.github/workflows/linter.yaml

@@ -63,5 +63,5 @@ jobs:
           VALIDATE_TYPESCRIPT_STANDARD: false
           VALIDATE_GIT_COMMITLINT: false
           PYTHON_MYPY_CONFIG_FILE: .mypy.ini
-          FILTER_REGEX_INCLUDE: "^src/**"
+          FILTER_REGEX_INCLUDE: ".*src/**/*"
           PYTHON_RUFF_CONFIG_FILE: .ruff.toml

.vscode/settings.json

@@ -7,8 +7,17 @@
     "editor.defaultFormatter": "charliermarsh.ruff",
     "editor.formatOnSave": true,
     "editor.codeActionsOnSave": {
-      "source.organizeImports": "always"
+      "source.organizeImports": "always",
+      "source.fixAll.ruff": "explicit"
     }
   },
-  "ruff.importStrategy": "fromEnvironment"
+  "ruff.importStrategy": "fromEnvironment",
+  "ruff.lint.args": [
+    "--config",
+    ".github/linters/.ruff.toml"
+  ],
+  "ruff.format.args": [
+    "--config",
+    ".github/linters/.ruff.toml"
+  ]
 }

noxfile.py

@@ -36,7 +36,7 @@
 
 
 @nox.session(python=DEFAULT_PYTHON_VERSION)
-def format(session):
+def format(session) -> None:
     """Format Python code using autoflake, pyupgrade, and ruff."""
     # Sort Spelling Allowlist
     spelling_allow_file = '.github/actions/spelling/allow.txt'
@@ -141,10 +141,14 @@ def format(session):
             'ruff',
             'check',
             '--fix-only',
+            '--config',
+            '.github/linters/.ruff.toml',
             *lint_paths_py,
         )
         session.run(
             'ruff',
             'format',
+            '--config',
+            '.github/linters/.ruff.toml',
             *lint_paths_py,
         )

src/a2a/auth/user.py

@@ -21,9 +21,11 @@ class UnauthenticatedUser(User):
     """A representation that no user has been authenticated in the request."""
 
     @property
-    def is_authenticated(self):
+    def is_authenticated(self) -> bool:
+        """Returns whether the current user is authenticated."""
         return False
 
     @property
     def user_name(self) -> str:
+        """Returns the user name of the current user."""
         return ''

src/a2a/server/agent_execution/agent_executor.py

@@ -12,7 +12,9 @@ class AgentExecutor(ABC):
     """
 
     @abstractmethod
-    async def execute(self, context: RequestContext, event_queue: EventQueue):
+    async def execute(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
         """Execute the agent's logic for a given request context.
 
         The agent should read necessary information from the `context` and
@@ -27,7 +29,9 @@ async def execute(self, context: RequestContext, event_queue: EventQueue):
         """
 
     @abstractmethod
-    async def cancel(self, context: RequestContext, event_queue: EventQueue):
+    async def cancel(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
         """Request the agent to cancel an ongoing task.
 
         The agent should attempt to stop the task identified by the task_id

src/a2a/server/agent_execution/context.py

@@ -20,7 +20,7 @@ class RequestContext:
     tasks.
     """
 
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         request: MessageSendParams | None = None,
         task_id: str | None = None,
@@ -37,6 +37,7 @@ def __init__(
             context_id: The ID of the context explicitly provided in the request or path.
             task: The existing `Task` object retrieved from the store, if any.
             related_tasks: A list of other tasks related to the current request (e.g., for tool use).
+            call_context: The server call context associated with this request.
         """
         if related_tasks is None:
             related_tasks = []
@@ -64,7 +65,7 @@ def __init__(
             else:
                 self._check_or_generate_context_id()
 
-    def get_user_input(self, delimiter='\n') -> str:
+    def get_user_input(self, delimiter: str = '\n') -> str:
         """Extracts text content from the user's message parts.
 
         Args:
@@ -80,7 +81,7 @@ def get_user_input(self, delimiter='\n') -> str:
 
         return get_message_text(self._params.message, delimiter)
 
-    def attach_related_task(self, task: Task):
+    def attach_related_task(self, task: Task) -> None:
         """Attaches a related task to the context.
 
         This is useful for scenarios like tool execution where a new task

src/a2a/server/agent_execution/request_context_builder.py

@@ -6,7 +6,7 @@
 
 
 class RequestContextBuilder(ABC):
-    """Builds request context to be supplied to agent executor"""
+    """Builds request context to be supplied to agent executor."""
 
     @abstractmethod
     async def build(

src/a2a/server/agent_execution/simple_request_context_builder.py

@@ -7,13 +7,22 @@
 
 
 class SimpleRequestContextBuilder(RequestContextBuilder):
-    """Builds request context and populates referred tasks"""
+    """Builds request context and populates referred tasks."""
 
     def __init__(
         self,
         should_populate_referred_tasks: bool = False,
         task_store: TaskStore | None = None,
     ) -> None:
+        """Initializes the SimpleRequestContextBuilder.
+
+        Args:
+            should_populate_referred_tasks: If True, the builder will fetch tasks
+                referenced in `params.message.referenceTaskIds` and populate the
+                `related_tasks` field in the RequestContext. Defaults to False.
+            task_store: The TaskStore instance to use for fetching referred tasks.
+                Required if `should_populate_referred_tasks` is True.
+        """
         self._task_store = task_store
         self._should_populate_referred_tasks = should_populate_referred_tasks
 
@@ -25,6 +34,23 @@ async def build(
         task: Task | None = None,
         context: ServerCallContext | None = None,
     ) -> RequestContext:
+        """Builds the request context for an agent execution.
+
+        This method assembles the RequestContext object. If the builder was
+        initialized with `should_populate_referred_tasks=True`, it fetches all tasks
+        referenced in `params.message.referenceTaskIds` from the `task_store`.
+
+        Args:
+            params: The parameters of the incoming message send request.
+            task_id: The ID of the task being executed.
+            context_id: The ID of the current execution context.
+            task: The primary task object associated with the request.
+            context: The server call context, containing metadata about the call.
+
+        Returns:
+            An instance of RequestContext populated with the provided information
+            and potentially a list of related tasks.
+        """
         related_tasks: list[Task] | None = None
 
         if (

src/a2a/server/apps/__init__.py

@@ -1,6 +1,6 @@
 """HTTP application components for the A2A server."""
 
-from .jsonrpc import (
+from a2a.server.apps.jsonrpc import (
     A2AFastAPIApplication,
     A2AStarletteApplication,
     CallContextBuilder,

src/a2a/server/apps/jsonrpc/__init__.py

@@ -1,8 +1,11 @@
 """A2A JSON-RPC Applications."""
 
-from .fastapi_app import A2AFastAPIApplication
-from .jsonrpc_app import CallContextBuilder, JSONRPCApplication
-from .starlette_app import A2AStarletteApplication
+from a2a.server.apps.jsonrpc.fastapi_app import A2AFastAPIApplication
+from a2a.server.apps.jsonrpc.jsonrpc_app import (
+    CallContextBuilder,
+    JSONRPCApplication,
+)
+from a2a.server.apps.jsonrpc.starlette_app import A2AStarletteApplication
 
 
 __all__ = [

src/a2a/server/apps/jsonrpc/fastapi_app.py

@@ -2,13 +2,15 @@
 
 from typing import Any
 
-from fastapi import FastAPI, Request
+from fastapi import FastAPI, Request, Response
 
+from a2a.server.apps.jsonrpc.jsonrpc_app import (
+    CallContextBuilder,
+    JSONRPCApplication,
+)
 from a2a.server.request_handlers.jsonrpc_handler import RequestHandler
 from a2a.types import AgentCard
 
-from .jsonrpc_app import CallContextBuilder, JSONRPCApplication
-
 
 logger = logging.getLogger(__name__)
 
@@ -50,8 +52,8 @@ def __init__(
     def build(
         self,
         agent_card_url: str = '/.well-known/agent.json',
-        extended_agent_card_url: str = '/agent/authenticatedExtendedCard',
         rpc_url: str = '/',
+        extended_agent_card_url: str = '/agent/authenticatedExtendedCard',
         **kwargs: Any,
     ) -> FastAPI:
         """Builds and returns the FastAPI application instance.
@@ -68,17 +70,17 @@ def build(
         app = FastAPI(**kwargs)
 
         @app.post(rpc_url)
-        async def handle_a2a_request(request: Request):
+        async def handle_a2a_request(request: Request) -> Response:
             return await self._handle_requests(request)
 
         @app.get(agent_card_url)
-        async def get_agent_card(request: Request):
+        async def get_agent_card(request: Request) -> Response:
             return await self._handle_get_agent_card(request)
 
         if self.agent_card.supportsAuthenticatedExtendedCard:
 
             @app.get(extended_agent_card_url)
-            async def get_extended_agent_card(request: Request):
+            async def get_extended_agent_card(request: Request) -> Response:
                 return await self._handle_get_authenticated_extended_agent_card(
                     request
                 )