The asynchronous Akismet client#

class akismet.AsyncClient(config: Config, http_client: AsyncClient | None = None)[source]#

Asynchronous Akismet API client.

All methods of the Akismet 1.1 and 1.2 web APIs are implemented here:

Use of this client requires an Akismet API key; see <https://akismet.com> for instructions on how to obtain one. Once you have an Akismet API key and corresponding registered site URL to use with it, you can create an API client in either of two ways.

Recommended for most uses: Place your Akismet API key and site URL in the environment variables PYTHON_AKISMET_API_KEY and PYTHON_AKISMET_BLOG_URL, and then use the validated_client() constructor:

import akismet
akismet_client = await akismet.AsyncClient.validated_client()

This will automatically read the API key and site URL from the environment variables, instantiate a client, and use its verify_key() method to ensure the key and URL are valid before returning the client instance to you. See the FAQ for the technical reasons why the default constructor does not have this behavior.

Advanced/unusual use cases: Instantiate the client directly. You must construct a Config instance with your API key and site URL, and they will not be automatically validated for you.

import akismet
config = akismet.Config(key=your_api_key, url=your_site_url)
akismet_client = akismet.AsyncClient(config=config)

Warning

Consequences of invalid configurationn

If you construct an Akismet API client manually and provide an invalid key or URL, all operations of the Akismet web service, other than key verification, will reply with an invalid-key message. This will cause all client methods other than verify_key() to raise akismet.APIKeyError. To avoid this situation, it is strongly recommended that you call verify_key() to validate your configuration prior to calling any other methods.

If you want to modify the HTTP request behavior – for example, to support a required HTTP proxy – you can construct a custom httpx.AsyncClient and pass it as the keyword argument http_client to either validated_client() or the default constructor. See akismet.USER_AGENT for the default user-agent string used by the Akismet API clients, and <https://www.python-httpx.org> for the full documentation of the HTTPX module.

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 float or int.

Parameters:

  • config – An Akismet Config, consisting of an API key and site URL.

  • http_client – An optional httpx async HTTP client instance to use. Generally you should only pass this in if you need significantly customized HTTP-client behavior, and if you do pass this argument you are responsible for setting an appropriate User-Agent (see USER_AGENT), timeout, and other configuration values. If all you want is to change the default timeout (1 second), store the desired timeout as a floating-point or integer value in the environment variable PYTHON_AKISMET_TIMEOUT.

async classmethod validated_client(http_client: AsyncClient | None = None) → AsyncClient[source]#

Constructor of AsyncClient.

This is usually preferred over the default AsyncClient() constructor, because this constructor will discover and validate the Akismet configuration (API key and URL) prior to returning the client instance. The Akismet API key will be read from the environment variable PYTHON_AKISMET_API_KEY, and the registered site URL from the environment variable PYTHON_AKISMET_BLOG_URL.

Parameters:

http_client – An optional httpx async HTTP client instance to use. Generally you should only pass this in if you need significantly customized HTTP-client behavior, and if you do pass this argument you are responsible for setting an appropriate User-Agent (see USER_AGENT), timeout, and other configuration values. If all you want is to change the default timeout (1 second), store the desired timeout as a floating-point or integer value in the environment variable PYTHON_AKISMET_TIMEOUT.

Raises:

  • akismet.APIKeyError – When the discovered Akismet configuration is invalid according to verify_key().

  • akismet.ConfigurationError – When the Akismet configuration is partially or completely missing, or when the supplied site URL is in the wrong format (does not begin with http:// or https://).

async comment_check(user_ip: str, **kwargs: str) → akismet.CheckResponse[source]#

Check a piece of user-submitted content to determine whether it is spam.

The IP address of the user posting the content is required. All other comment-check arguments documented by Akismet 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 comment_author_email.

The return value is an int from the CheckResponse enum, which can be used as a truthy value (0/False if the content is not classified as spam, 1/True if it is classified as spam). But making use of the full set of enum values allows detecting the presence of the “discard” value in the X-akismet-pro-tip header to indicate “blatant” spam.

Parameters:

  • user_ip – The IP address of the user who submitted the content.

  • comment_content (str) – (optional, recommended) The content the user submitted.

  • comment_type (str) – (optional, recommended) The type of content, with common values being "comment", "forum-post", "contact-form", and "signup". See the Akismet service documentation for a full list of common/recommended types.

  • comment_author (str) – (optional, recommended) The name (such as username) of the content’s submitter.

  • comment_author_email (str) – (optional, recommended) The email address of the content’s submitter.

  • is_test (int) – (optional) Set to 1 if you are making requests for testing purposes; this tells Akismet not to incorporate the request into its training corpus or allow it to affect future responses.

Raises:

akismet.ProtocolError – When an unexpected/invalid response type is received from the Akismet API.

async key_sites(month: str | None = None, url_filter: str | None = None, result_format: str | None = None, order: str | None = None, limit: int | None = None, offset: int | None = None) → dict | str[source]#

Return Akismet API usage statistics keyed by site.

All arguments are optional, and the Akismet API will set them to default values if not supplied.

See the Akismet key-sites documentation for examples of the response data from this method.

Parameters:

  • month – The month, in "YYYY-MM" format, to retrieve statistics for. If not supplied, defaults to the current month.

  • url_filter – A full or partial site URL to filter results by. If not supplied, results for all sites under the current API key will be returned.

  • result_format – The format in which to return results. Supported options are "json" and "csv". Defaults to "json" if not supplied.

  • order – For CSV-formatted results, the column by which the results should be sorted.

  • limit – The maximum number of results to return. If not supplied, defaults to 500.

  • offset – The offset from which to begin result reporting. If not supplied, defaults to 0.

async submit_ham(user_ip: str, **kwargs: str) → bool[source]#

Inform Akismet that a piece of user-submitted comment is not spam.

The IP address of the user posting the content is required. All other submit-ham arguments documented by Akismet 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 comment_author_email.

Will return True on success (the only expected response).

Parameters:

  • user_ip – The IP address of the user who submitted the content.

  • comment_content (str) – (optional, recommended) The content the user submitted.

  • comment_type (str) – (optional, recommended) The type of content, with common values being "comment", "forum-post", "contact-form", and "signup". See the Akismet service documentation for a full list of common/recommended types.

  • comment_author (str) – (optional, recommended) The name (such as username) of the content’s submitter.

  • comment_author_email (str) – (optional, recommended) The email address of the content’s submitter.

  • is_test (int) – (optional) Set to 1 if you are making requests for testing purposes; this tells Akismet not to incorporate the request into its training corpus or allow it to affect future responses.

Raises:

akismet.ProtocolError – When an unexpected/invalid response type is received from the Akismet API.

async submit_spam(user_ip: str, **kwargs: str) → bool[source]#

Inform Akismet that a piece of user-submitted comment is spam.

The IP address of the user posting the content is required. All other submit-spam arguments documented by Akismet 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 comment_author_email.

Will return True on success (the only expected response).

Parameters:

  • user_ip – The IP address of the user who submitted the content.

  • comment_content (str) – (optional, recommended) The content the user submitted.

  • comment_type (str) – (optional, recommended) The type of content, with common values being "comment", "forum-post", "contact-form", and "signup". See the Akismet service documentation for a full list of common/recommended types.

  • comment_author (str) – (optional, recommended) The name (such as username) of the content’s submitter.

  • comment_author_email (str) – (optional, recommended) The email address of the content’s submitter.

  • is_test (int) – (optional) Set to 1 if you are making requests for testing purposes; this tells Akismet not to incorporate the request into its training corpus or allow it to affect future responses.

Raises:

akismet.ProtocolError – When an unexpected/invalid response type is received from the Akismet API.

async usage_limit() → dict[source]#

Return Akismet API usage statistics for the current month.

See the Akismet usage-limit documentation for examples of the response data from this method.

async verify_key(key: str, url: str) → bool[source]#

Verify an Akismet API key and URL.

Return True if the key and URL are valid, False otherwise.

In general, you should not need to explicitly call this method. The validated_client() constructor will ensure this method is called during client construction, after which the now-verified key/URL can be trusted.

Parameters:

  • key – The API key to check.

  • url – The URL to check.

Raises:

akismet.ProtocolError – When an unexpected/invalid response type is received from the Akismet API.