More documentation cleanup/updates.

ubernostrum · Feb 20, 2024 · eb1dead · eb1dead
1 parent 36a166c
commit eb1dead
Show file tree

Hide file tree

Showing 8 changed files with 105 additions and 89 deletions.
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -143,7 +143,7 @@ The Akismet web service documentation recommends sending a string identifying
 the application or platform with version, and Akismet plugin/implementation
 name with version. In accordance with this, ``akismet`` sends an HTTP
 ``User-Agent`` based on the versions of Python and ``akismet`` in use. For
-example, ``akismet`` 1.3 on Python 3.10.4 will send ``akismet/1.3 | Python
+example, ``akismet`` 1.3 on Python 3.10.4 will send ``akismet.py/1.3 | Python
 3.10.4``.
 
 

diff --git a/docs/install.rst b/docs/install.rst
@@ -21,20 +21,20 @@ on the following versions of Python:
 Installing ``akismet``
 ----------------------
 
-To install ``akismet``, run the following command from a command
-prompt/terminal:
+To install the latest stable released version of ``akismet``, run the following
+command from a command prompt/terminal:
 
 .. tab:: macOS/Linux/other Unix
 
    .. code-block:: shell
 
-      python -m pip install akismet
+      python -m pip install --upgrade akismet
 
 .. tab:: Windows
 
    .. code-block:: shell
 
-      py -m pip install akismet
+      py -m pip install --upgrade akismet
 
 This will use ``pip``, the standard Python package-installation tool. If you
 are using a supported version of Python, your installation of Python should

diff --git a/docs/testing.rst b/docs/testing.rst
@@ -16,14 +16,14 @@ be done from the root of your git checkout of ``akismet``:
 
    .. code-block:: shell
 
-      python -m pip install nox
+      python -m pip install --upgrade nox
       python -m nox
 
 .. tab:: Windows
 
    .. code-block:: shell
 
-      py -m pip install nox
+      py -m pip install --upgrade nox
       py -m nox
 
 Note that to run the full test matrix you will need to have each supported

diff --git a/docs/usage.rst b/docs/usage.rst
@@ -228,7 +228,7 @@ use, it's available as :data:`akismet.USER_AGENT`.
 
       akismet_client = akismet.SyncClient.validated_client(
           http_client=httpx.Client(
-              proxies=settings.PROXY_URL,
+              proxy=settings.PROXY_URL,
               headers={"User-Agent": akismet.USER_AGENT}
           )
       )
@@ -244,7 +244,7 @@ use, it's available as :data:`akismet.USER_AGENT`.
 
       akismet_client = await akismet.AsyncClient.validated_client(
           http_client=httpx.AsyncClient(
-              proxies=settings.PROXY_URL,
+              proxy=settings.PROXY_URL,
               headers={"User-Agent": akismet.USER_AGENT}
           )
       )
@@ -262,8 +262,8 @@ If you don't want to configure your Akismet client via the standard environment
 variables, or aren't able to set the environment variables, you can avoid the
 ``validated_client()`` method and instantiate your Akismet client
 directly. This is done via the :class:`akismet.Config` utility tuple. You
-should also the make sure to validate the configuration before trying to use
-the client.
+should also make sure to validate the configuration before trying to use the
+client.
 
 .. tab:: Sync
 

diff --git a/src/akismet/__init__.py b/src/akismet/__init__.py
@@ -22,37 +22,35 @@
 You can then construct a client instance and call its methods. For example, to check a
 submitted forum post for spam:
 
-.. tab:: Sync
+.. code-block:: python
 
-   .. code-block:: python
+   import akismet
 
-      import akismet
+   akismet_client = akismet.SyncClient.validated_client()
 
-      akismet_client = akismet.SyncClient.validated_client()
+   if akismet_client.comment_check(
+       user_ip=submitter_ip,
+       comment_content=submitted_content,
+       comment_type="forum-post",
+       comment_author=submitter_name
+   ):
+       # This piece of content was classified as spam; handle it appropriately.
 
-      if akismet_client.comment_check(
-          user_ip=submitter_ip,
-          comment_content=submitted_content,
-          comment_type="forum-post",
-          comment_author=submitter_name
-      ):
-          # This piece of content was classified as spam; handle it appropriately.
+Or using the asynchronous client:
 
-.. tab:: Async
+.. code-block:: python
 
-   .. code-block:: python
+   import akismet
 
-      import akismet
+   akismet_client = await akismet.AsyncClient.validated_client()
 
-      akismet_client = await akismet.AsyncClient.validated_client()
-
-      if await akismet_client.comment_check(
-          user_ip=submitter_ip,
-          comment_content=submitted_content,
-          comment_type="forum-post",
-          comment_author=submitter_name
-      ):
-          # This piece of content was classified as spam; handle it appropriately.
+   if await akismet_client.comment_check(
+       user_ip=submitter_ip,
+       comment_content=submitted_content,
+       comment_type="forum-post",
+       comment_author=submitter_name
+   ):
+       # This piece of content was classified as spam; handle it appropriately.
 
 Note that in both cases the client instance is created via the alternate constructor
 ``validated_client()``. This is recommended instead of using the default constructor

diff --git a/src/akismet/_async_client.py b/src/akismet/_async_client.py
@@ -6,13 +6,13 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 import textwrap
-import typing
+from typing import TYPE_CHECKING, Optional, Union
 
 import httpx
 
 from . import _common, _exceptions
 
-if typing.TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover
     import akismet
 
 
@@ -75,6 +75,20 @@ class AsyncClient:
     string used by the Akismet API clients, and <https://www.python-httpx.org> for the
     full documentation of the HTTPX module.
 
+    .. code-block:: python
+
+       import akismet
+       import httpx
+
+       from your_app.config import settings
+
+       akismet_client = await akismet.AsyncClient.validated_client(
+           http_client=httpx.AsyncClient(
+               proxy=settings.PROXY_URL,
+               headers={"User-Agent": akismet.USER_AGENT}
+           )
+       )
+
     Note that if you only want to set a custom request timeout threshold (the default is
     1 second), you can specify it by setting the environment variable
     ``PYTHON_AKISMET_TIMEOUT`` to a value that can be parsed into a :class:`float` or
@@ -102,7 +116,7 @@ class AsyncClient:
     def __init__(
         self,
         config: _common.Config,
-        http_client: typing.Optional[httpx.AsyncClient] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
     ) -> None:
         """
         Default constructor.
@@ -115,7 +129,7 @@ def __init__(
 
     @classmethod
     async def validated_client(
-        cls, http_client: typing.Optional[httpx.AsyncClient] = None
+        cls, http_client: Optional[httpx.AsyncClient] = None
     ) -> "AsyncClient":
         """
         Constructor of :class:`AsyncClient`.
@@ -309,8 +323,7 @@ async def comment_check(
 
         The IP address of the user posting the content is required. All `other
         comment-check arguments documented by Akismet
-        <https://akismet.com/developers/comment-check/>`_ are also optionally accepted,
-        except for the PHP server information array.
+        <https://akismet.com/developers/comment-check/>`_ are also optionally accepted.
 
         It is recommended that you supply at least the following optional arguments:
         ``comment_content``; ``comment_type``; and ``comment_author`` and/or
@@ -364,8 +377,7 @@ async def submit_ham(self, user_ip: str, **kwargs: str) -> bool:
 
         The IP address of the user posting the content is required. All `other
         submit-ham arguments documented by Akismet
-        <https://akismet.com/developers/submit-ham/>`_ are also optionally accepted,
-        except for the PHP server information array.
+        <https://akismet.com/developers/submit-ham/>`_ are also optionally accepted.
 
         It is recommended that you supply at least the following optional arguments:
         ``comment_content``; ``comment_type``; and ``comment_author`` and/or
@@ -405,8 +417,7 @@ async def submit_spam(self, user_ip: str, **kwargs: str) -> bool:
 
         The IP address of the user posting the content is required. All `other
         submit-spam arguments documented by Akismet
-        <https://akismet.com/developers/submit-spam/>`_ are also optionally accepted,
-        except for the PHP server information array.
+        <https://akismet.com/developers/submit-spam/>`_ are also optionally accepted.
 
         It is recommended that you supply at least the following optional arguments:
         ``comment_content``; ``comment_type``; and ``comment_author`` and/or
@@ -442,13 +453,13 @@ async def submit_spam(self, user_ip: str, **kwargs: str) -> bool:
 
     async def key_sites(  # pylint: disable=too-many-arguments
         self,
-        month: typing.Optional[str] = None,
-        url_filter: typing.Optional[str] = None,
-        result_format: typing.Optional[str] = None,
-        order: typing.Optional[str] = None,
-        limit: typing.Optional[int] = None,
-        offset: typing.Optional[int] = None,
-    ) -> typing.Union[dict, str]:
+        month: Optional[str] = None,
+        url_filter: Optional[str] = None,
+        result_format: Optional[str] = None,
+        order: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> Union[dict, str]:
         """
         Return Akismet API usage statistics keyed by site.
 

diff --git a/src/akismet/_legacy_client.py b/src/akismet/_legacy_client.py
@@ -80,9 +80,9 @@ def __init__(
         warnings.warn(
             textwrap.dedent(
                 """
-            The akismet.Akismet API client is deprecated and will be removed in version
-            2.0. Please migrate to either akismet.SyncClient or akismet.AsyncClient.
-                """,
+                The akismet.Akismet API client is deprecated and will be removed in
+            version 2.0. Please migrate to either akismet.SyncClient or
+            akismet.AsyncClient.  """,
             ),
             DeprecationWarning,
             stacklevel=2,
@@ -116,10 +116,9 @@ def _api_request(
         """
         Make a request to the Akismet API.
 
-        This method is used for all API calls except key verification,
-        since all endpoints other than key verification must
-        interpolate the API key into the URL and supply certain basic
-        data.
+        This method is used for all API calls except key verification, since all
+        endpoints other than key verification must interpolate the API key into the URL
+        and supply certain basic data.
 
         """
         unknown_args = [k for k in kwargs if k not in self.OPTIONAL_KEYS]
@@ -210,15 +209,14 @@ def comment_check(  # pylint: disable=inconsistent-return-statements
         """
         Check a comment to determine whether it is spam.
 
-        The IP address and user-agent string of the remote user are
-        required. All other arguments documented by Akismet (other
-        than the PHP server information) are also optionally accepted.
-        See the Akismet API documentation for a full list:
+        The IP address and user-agent string of the remote user are required. All other
+        arguments documented by Akismet (other than the PHP server information) are also
+        optionally accepted.  See the Akismet API documentation for a full list:
 
         https://akismet.com/developers/comment-check/
 
-        Like the Akismet web API, returns True for a comment that is
-        spam, and False for a comment that is not spam.
+        Like the Akismet web API, returns True for a comment that is spam, and False for
+        a comment that is not spam.
 
         """
         response = self._api_request(
@@ -234,10 +232,9 @@ def submit_spam(self, user_ip: str, user_agent: str, **kwargs: str) -> bool:
         """
         Inform Akismet that a comment is spam.
 
-        The IP address and user-agent string of the remote user are
-        required. All other arguments documented by Akismet (other
-        than the PHP server information) are also optionally accepted.
-        See the Akismet API documentation for a full list:
+        The IP address and user-agent string of the remote user are required. All other
+        arguments documented by Akismet (other than the PHP server information) are also
+        optionally accepted.  See the Akismet API documentation for a full list:
 
         https://akismet.com/developers/submit-spam-missed-spam/
 
@@ -250,10 +247,9 @@ def submit_ham(self, user_ip: str, user_agent: str, **kwargs: str) -> bool:
         """
         Inform Akismet that a comment is not spam.
 
-        The IP address and user-agent string of the remote user are
-        required. All other arguments documented by Akismet (other
-        than the PHP server information) are also optionally accepted.
-        See the Akismet API documentation for a full list:
+        The IP address and user-agent string of the remote user are required. All other
+        arguments documented by Akismet (other than the PHP server information) are also
+        optionally accepted.  See the Akismet API documentation for a full list:
 
         https://akismet.com/developers/submit-ham-false-positives/