Make the whole codebase pass pyright cleanly and enforce it in CI (#798)

* Make the whole codebase pass pyright cleanly and enforce it in CI

Fix all 102 pyright (1.1.410, standard mode) errors across the library,
tests, and maps scripts, then pin and enforce the zero-errors bar:

- postgres.py: make the optional psycopg import TYPE_CHECKING-aware so
  the module is properly typed while keeping the runtime install-hint
  fallback; import psycopg.types.json explicitly as psycopg_json (the
  old psycopg_types.json attribute access only worked because psycopg
  imports the submodule eagerly); have _connect()/_ensure_connected()
  return the live connection so save methods use a non-Optional local;
  type the DDL list as list[LiteralString] to match psycopg's execute()
  overloads.
- kafkaclient.py: resolve the kafka-python 2.x/3.x bootstrap-error
  fallback statically via TYPE_CHECKING (kafka-python 3.0 removed
  NoBrokersAvailable), which also fixes _BootstrapError's import
  resolution in tests.
- syslog.py: go through getattr/setattr for SysLogHandler.socket
  (absent from typeshed); type the save_* methods with the report
  TypedDicts (single or list, matching cli.py call sites — gelf.py gets
  the same signatures); raise ValueError when retry_attempts < 1
  instead of falling through and registering a None handler (bug fix,
  with a regression test and a CHANGELOG entry).
- elastic.py / opensearch.py: human_result params are Optional[str].
- maps scripts: sort_csv declared a return type but never returned
  (now -> None); seen_sort_field_values was possibly unbound;
  convert_to_utf8's src_encoding is Optional[str].
- tests: cast sample-report dict helpers to their TypedDicts; mark
  deliberate wrong-type calls with targeted pyright ignores; add
  narrowing asserts for Optional results; access the mocked
  KafkaProducer through a cast helper; match the mailsuite
  fetch_message base signature (**kwargs); patch the renamed
  parsedmarc.postgres.psycopg_json in test_postgres's setUpModule.

Enforcement: [tool.pyright] in pyproject.toml (include parsedmarc,
tests, docs; standard mode), pyright==1.1.410 pinned in the [build]
extra (pinned exactly so a new pyright release can't break CI without a
code change), and a "Check types" step in the lint CI job — which now
also runs ruff format --check and installs the [postgresql] extra so
the optional psycopg import resolves. Documented in AGENTS.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Set session headers via update() instead of replacing the dict

requests 2.34 ships inline type annotations, and Session.headers is a
CaseInsensitiveDict[str] — assigning a plain dict fails pyright there
(the CI runner resolved 2.34.2; the local venv's untyped 2.32.4 hid
it). headers.update() is correctly typed against both versions, and is
the documented requests idiom: it overrides User-Agent and the
client-specific headers while keeping the session's defaults
(Accept-Encoding, Connection) instead of wiping them.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Sean WhalenandClaude Fable 5 authored and GitHub committed 2026-06-12 21:33:01 -04:00
1 parent 0c456d44ed
commit eaeea4f53d
20 files changed
+236 -130

No files matched your search

+27 -21
View File
@@ -2,6 +2,7 @@
import json
import unittest
from typing import cast
from unittest.mock import MagicMock, patch
from kafka.errors import UnknownTopicOrPartitionError
@@ -9,6 +10,11 @@ from kafka.errors import UnknownTopicOrPartitionError
from parsedmarc.kafkaclient import KafkaClient, KafkaError, _BootstrapError
def _producer(client: KafkaClient) -> MagicMock:
"""The patched KafkaProducer as a MagicMock, for assertion access."""
return cast(MagicMock, client.producer)
def _aggregate_report():
return {
"report_metadata": {
@@ -121,15 +127,15 @@ class TestSaveAggregateReportsToKafka(unittest.TestCase):
client = self._client()
client.save_aggregate_reports_to_kafka(_aggregate_report(), "dmarc-aggregate")
# 2 records in the sample report → 2 producer.send calls.
self.assertEqual(client.producer.send.call_count, 2)
self.assertEqual(_producer(client).send.call_count, 2)
# Topic is forwarded verbatim.
for call in client.producer.send.call_args_list:
for call in _producer(client).send.call_args_list:
self.assertEqual(call.args[0], "dmarc-aggregate")
def test_each_slice_carries_metadata(self):
client = self._client()
client.save_aggregate_reports_to_kafka(_aggregate_report(), "topic")
sent = [call.args[1] for call in client.producer.send.call_args_list]
sent = [call.args[1] for call in _producer(client).send.call_args_list]
for slice_ in sent:
self.assertEqual(slice_["org_name"], "TestOrg")
self.assertEqual(slice_["org_email"], "test@example.com")
@@ -144,32 +150,32 @@ class TestSaveAggregateReportsToKafka(unittest.TestCase):
def test_empty_list_is_a_noop(self):
client = self._client()
client.save_aggregate_reports_to_kafka([], "topic")
client.producer.send.assert_not_called()
_producer(client).send.assert_not_called()
def test_dict_input_normalized_to_list(self):
"""Single-report dict input is wrapped to a list."""
client = self._client()
client.save_aggregate_reports_to_kafka(_aggregate_report(), "topic")
# 2 records still sent (one report with 2 records, not multiple reports).
self.assertEqual(client.producer.send.call_count, 2)
self.assertEqual(_producer(client).send.call_count, 2)
def test_unknown_topic_translates_to_kafka_error(self):
client = self._client()
client.producer.send.side_effect = UnknownTopicOrPartitionError()
_producer(client).send.side_effect = UnknownTopicOrPartitionError()
with self.assertRaises(KafkaError) as ctx:
client.save_aggregate_reports_to_kafka(_aggregate_report(), "missing")
self.assertIn("Unknown topic or partition", str(ctx.exception))
def test_generic_send_exception_translates_to_kafka_error(self):
client = self._client()
client.producer.send.side_effect = RuntimeError("transport failure")
_producer(client).send.side_effect = RuntimeError("transport failure")
with self.assertRaises(KafkaError) as ctx:
client.save_aggregate_reports_to_kafka(_aggregate_report(), "topic")
self.assertIn("transport failure", str(ctx.exception))
def test_flush_exception_translates_to_kafka_error(self):
client = self._client()
client.producer.flush.side_effect = RuntimeError("flush failure")
_producer(client).flush.side_effect = RuntimeError("flush failure")
with self.assertRaises(KafkaError) as ctx:
client.save_aggregate_reports_to_kafka(_aggregate_report(), "topic")
self.assertIn("flush failure", str(ctx.exception))
@@ -186,35 +192,35 @@ class TestSaveFailureReportsToKafka(unittest.TestCase):
client = self._client()
reports = [{"id": "f1"}, {"id": "f2"}]
client.save_failure_reports_to_kafka(reports, "dmarc-failure")
client.producer.send.assert_called_once_with("dmarc-failure", reports)
_producer(client).send.assert_called_once_with("dmarc-failure", reports)
def test_dict_input_normalized_to_list(self):
client = self._client()
client.save_failure_reports_to_kafka({"id": "single"}, "topic")
# The send payload is wrapped to a single-element list.
args = client.producer.send.call_args.args
args = _producer(client).send.call_args.args
self.assertEqual(args[1], [{"id": "single"}])
def test_empty_list_is_a_noop(self):
client = self._client()
client.save_failure_reports_to_kafka([], "topic")
client.producer.send.assert_not_called()
_producer(client).send.assert_not_called()
def test_unknown_topic_translates_to_kafka_error(self):
client = self._client()
client.producer.send.side_effect = UnknownTopicOrPartitionError()
_producer(client).send.side_effect = UnknownTopicOrPartitionError()
with self.assertRaises(KafkaError):
client.save_failure_reports_to_kafka([{"a": 1}], "missing")
def test_generic_send_error_translates_to_kafka_error(self):
client = self._client()
client.producer.send.side_effect = OSError("net")
_producer(client).send.side_effect = OSError("net")
with self.assertRaises(KafkaError):
client.save_failure_reports_to_kafka([{"a": 1}], "topic")
def test_flush_error_translates_to_kafka_error(self):
client = self._client()
client.producer.flush.side_effect = OSError("flush")
_producer(client).flush.side_effect = OSError("flush")
with self.assertRaises(KafkaError):
client.save_failure_reports_to_kafka([{"a": 1}], "topic")
@@ -228,34 +234,34 @@ class TestSaveSmtpTlsReportsToKafka(unittest.TestCase):
client = self._client()
reports = [{"organization_name": "x"}]
client.save_smtp_tls_reports_to_kafka(reports, "smtp-tls")
client.producer.send.assert_called_once_with("smtp-tls", reports)
_producer(client).send.assert_called_once_with("smtp-tls", reports)
def test_dict_input_normalized_to_list(self):
client = self._client()
client.save_smtp_tls_reports_to_kafka({"organization_name": "x"}, "topic")
args = client.producer.send.call_args.args
args = _producer(client).send.call_args.args
self.assertEqual(args[1], [{"organization_name": "x"}])
def test_empty_list_is_a_noop(self):
client = self._client()
client.save_smtp_tls_reports_to_kafka([], "topic")
client.producer.send.assert_not_called()
_producer(client).send.assert_not_called()
def test_unknown_topic_translates_to_kafka_error(self):
client = self._client()
client.producer.send.side_effect = UnknownTopicOrPartitionError()
_producer(client).send.side_effect = UnknownTopicOrPartitionError()
with self.assertRaises(KafkaError):
client.save_smtp_tls_reports_to_kafka([{"a": 1}], "missing")
def test_generic_send_error_translates_to_kafka_error(self):
client = self._client()
client.producer.send.side_effect = RuntimeError("oops")
_producer(client).send.side_effect = RuntimeError("oops")
with self.assertRaises(KafkaError):
client.save_smtp_tls_reports_to_kafka([{"a": 1}], "topic")
def test_flush_error_translates_to_kafka_error(self):
client = self._client()
client.producer.flush.side_effect = RuntimeError("flush")
_producer(client).flush.side_effect = RuntimeError("flush")
with self.assertRaises(KafkaError):
client.save_smtp_tls_reports_to_kafka([{"a": 1}], "topic")
@@ -265,7 +271,7 @@ class TestKafkaClientClose(unittest.TestCase):
with patch("parsedmarc.kafkaclient.KafkaProducer"):
client = KafkaClient(kafka_hosts=["b"])
client.close()
client.producer.close.assert_called_once()
_producer(client).close.assert_called_once()
class TestKafkaBackwardCompatAlias(unittest.TestCase):