Document the AkismetArguments dictionary.

Author: ubernostrum

docs/changelog.rst

@@ -68,6 +68,9 @@ Version 25.10.0
   synchronous :class:`~akismet.SyncClient` or asynchronous
   :class:`~akismet.AsyncClient` is now mandatory. The legacy ``Akismet`` client
   class had been deprecated and raising warnings since version 1.3.
+* Added the :class:`~akismet.AkismetArguments` typed dictionary to represent
+  the set of optional keyword arguments accepted by the comment-check, submit-ham,
+  and submit-spam API operations.
 
 
 Version 24.11.0

docs/misc.rst

@@ -9,6 +9,36 @@ Other code and data
 The following additional items are part of the publicly-exported API of this
 module:
 
+.. class:: AkismetArguments
+
+   A :class:`~typing.TypedDict` representing the optional keyword arguments
+   accepted by the comment-check, submit-ham, and submit-spam Akismet API
+   operations.
+
+   The names and types of these optional arguments are:
+
+   * ``blog_charset``: :class:`str`
+   * ``blog_lang``: :class:`str`
+   * ``comment_author``: :class:`str`
+   * ``comment_author_email``: :class:`str`
+   * ``comment_author_url``: :class:`str`
+   * ``comment_content``: :class:`str`
+   * ``comment_context``: :class:`str`
+   * ``comment_date_gmt``: :class:`str`
+   * ``comment_post_modified_gmt``: :class:`str`
+   * ``comment_type``: :class:`str`
+   * ``honeypot_field_name``: :class:`str`
+   * ``is_test``: :class:`bool`
+   * ``permalink``: :class:`str`
+   * ``recheck_reason``: :class:`str`
+   * ``referrer``: :class:`str`
+   * ``user_agent``: :class:`str`
+   * ``user_role``: :class:`str`
+
+   For the meanings of these arguments, see `the Akismet web service
+   documentation <https://akismet.com/developers/detailed-docs/comment-check/>`_.
+
+
 .. class:: CheckResponse
 
    Possible response values from an Akismet content check, including the

src/akismet/_async_client.py

@@ -280,7 +280,7 @@ async def _post_request(
         version: str,
         endpoint: str,
         user_ip: str,
-        **kwargs: Unpack[_common.AkismetArguments],
+        **kwargs: Unpack[akismet.AkismetArguments],
     ) -> httpx.Response:
         """
         Make a POST request to the Akismet API and return the response.
@@ -315,7 +315,7 @@ async def _post_request(
         )
 
     async def _submit(
-        self, endpoint: str, user_ip: str, **kwargs: Unpack[_common.AkismetArguments]
+        self, endpoint: str, user_ip: str, **kwargs: Unpack[akismet.AkismetArguments]
     ) -> bool:
         """
         Submit ham or spam to the Akismet API.
@@ -340,7 +340,7 @@ async def _submit(
     # ----------------------------------------------------------------------------
 
     async def comment_check(
-        self, user_ip: str, **kwargs: Unpack[_common.AkismetArguments]
+        self, user_ip: str, **kwargs: Unpack[akismet.AkismetArguments]
     ) -> akismet.CheckResponse:
         """
         Check a piece of user-submitted content to determine whether it is spam.
@@ -391,7 +391,7 @@ async def comment_check(
         )
 
     async def submit_ham(
-        self, user_ip: str, **kwargs: Unpack[_common.AkismetArguments]
+        self, user_ip: str, **kwargs: Unpack[akismet.AkismetArguments]
     ) -> bool:
         """
         Inform Akismet that a piece of user-submitted comment is not spam.
@@ -433,7 +433,7 @@ async def submit_ham(
         return await self._submit(_common._SUBMIT_HAM, user_ip, **kwargs)
 
     async def submit_spam(
-        self, user_ip: str, **kwargs: Unpack[_common.AkismetArguments]
+        self, user_ip: str, **kwargs: Unpack[akismet.AkismetArguments]
     ) -> bool:
         """
         Inform Akismet that a piece of user-submitted comment is spam.

src/akismet/_common.py

@@ -54,7 +54,7 @@
 class AkismetArguments(TypedDict, total=False):
     """
     A :class:`~typing.TypedDict` representing the optional keyword arguments accepted by
-    most Akismet API operations.
+    the comment-check, submit-ham, and submit-spam Akismet API operations.
 
     """
 

src/akismet/_sync_client.py

@@ -279,7 +279,7 @@ def _post_request(
         version: str,
         endpoint: str,
         user_ip: str,
-        **kwargs: Unpack[_common.AkismetArguments],
+        **kwargs: Unpack[akismet.AkismetArguments],
     ) -> httpx.Response:
         """
         Make a POST request to the Akismet API and return the response.
@@ -314,7 +314,7 @@ def _post_request(
         )
 
     def _submit(
-        self, endpoint: str, user_ip: str, **kwargs: Unpack[_common.AkismetArguments]
+        self, endpoint: str, user_ip: str, **kwargs: Unpack[akismet.AkismetArguments]
     ) -> bool:
         """
         Submit ham or spam to the Akismet API.
@@ -337,7 +337,7 @@ def _submit(
     # ----------------------------------------------------------------------------
 
     def comment_check(
-        self, user_ip: str, **kwargs: Unpack[_common.AkismetArguments]
+        self, user_ip: str, **kwargs: Unpack[akismet.AkismetArguments]
     ) -> akismet.CheckResponse:
         """
         Check a piece of user-submitted content to determine whether it is spam.
@@ -388,7 +388,7 @@ def comment_check(
         )
 
     def submit_ham(
-        self, user_ip: str, **kwargs: Unpack[_common.AkismetArguments]
+        self, user_ip: str, **kwargs: Unpack[akismet.AkismetArguments]
     ) -> bool:
         """
         Inform Akismet that a piece of user-submitted comment is not spam.
@@ -430,7 +430,7 @@ def submit_ham(
         return self._submit(_common._SUBMIT_HAM, user_ip, **kwargs)
 
     def submit_spam(
-        self, user_ip: str, **kwargs: Unpack[_common.AkismetArguments]
+        self, user_ip: str, **kwargs: Unpack[akismet.AkismetArguments]
     ) -> bool:
         """
         Inform Akismet that a piece of user-submitted comment is spam.