Frequently asked questions#
The following notes answer common questions, and may be useful to you when
using akismet
.
What versions of Python are supported?#
The 1.3 release of akismet
supports the following versions of Python:
Python 3.8
Python 3.9
Python 3.10
Python 3.11
Python 3.12
Older versions of Python are not supported and will cause errors.
Do I have to send all the optional arguments?#
The Akismet web service supports a large number of optional arguments to
provide additional information for classification and training. You can submit
as many of them as you wish with the comment_check
, submit_ham
, and
submit_spam
operations. The Akismet documentation recommends sending as
much information as possible, though only the user_ip
argument to those
methods is actually required.
Is this only for blog comments?#
The Akismet web service can handle many types of user-submitted content, including comments, contact-form submissions, user signups and more. See Akismet’s documentation of the comment check operation for details.
Why shouldn’t I create the client directly?#
Both of the API clients provide a classmethod
which serves as an alternate
constructor: akismet.SyncClient.validated_client()
and
akismet.AsyncClient.validated_client()
, and you’re encouraged to use
these alternate constructors when you need an instance of one of the clients.
The short explanation for this is that the validated_client()
constructor
will automatically read your Akismet API key and site URL from environment
variables (PYTHON_AKISMET_API_KEY
and PYTHON_AKISMET_BLOG_URL
) and
validate them via the verify_key
operation before returning the API client
instance to you, and this is highly useful behavior.
If you don’t use the validated_client()
constructor, you’ll need to
construct your own Config
to pass in to the default
constructor, and you’ll want to ensure you call the verify-key operation to
validate that configuration.
The longer explanation is that the validated_client()
constructor allows
both the sync and async clients to provide the same
interface. SyncClient
could easily just read the
configuration and do the validation in its own __init__()
method. But
AsyncClient
cannot do this, because its
verify_key()
method is asynchronous; calling it in
__init__()
would require making the __init__()
method asynchronous too,
and an async __init__()
is not currently supported by Python.
This limitation does not apply to classmethods used as alternate constructors,
so to provide a useful constructor that does automatic discovery and validation
of your Akismet configuration, AsyncClient
defines the
alternate constructor validated_client()
. And to
ensure both client classes have the same interface,
SyncClient
also provides a
validated_client()
constructor.
How do I check my key?#
The simplest way is to set your key and site URL in the standard environment
variables (PYTHON_AKISMET_API_KEY
/ PYTHON_AKISMET_BLOG_URL
), and then
call either akismet.SyncClient.validated_client()
or
akismet.AsyncClient.validated_client()
; the validated_client()
constructor automatically verifies the key and URL for you, and will raise
APIKeyError
if the key is invalid.
If you’re not able to do this, you can also manually instantiate a client and
then call its verify_key()
method, passing the key and URL you want to
check as the arguments. For example:
import akismet
config = akismet.Config(key=key_to_test, url=url_to_test)
client = akismet.SyncClient(config=config)
if not client.verify_key(key_to_test, url_to_test):
# The key/URL were invalid.
import akismet
config = akismet.Config(key=key_to_test, url=url_to_test)
client = akismet.AyncClient(config=config)
if not await client.verify_key(key_to_test, url_to_test):
# The key/URL were invalid.
How can I test that it’s working?#
The documentation includes a section on how to run
akismet
’s unit test suite.
If you want to manually perform your own tests, you can also instantiate an
Akismet client class and call its methods. When doing so, it is recommended
that you pass the optional keyword argument is_test=1
to the comment-check,
submit-ham, and submit-spam operations; this tells the Akismet web service that
you are only issuing requests for testing purposes, and will not result in any
submissions being incorporated into Akismet’s training corpus.
How am I allowed to use this module?#
akismet
is distributed under a three-clause BSD license. This is an open-source license
which grants you broad freedom to use, redistribute, modify and distribute
modified versions of akismet
. For details, see the file LICENSE
in the
source distribution of akismet
.
I found a bug or want to make an improvement!#
The canonical development repository for akismet
is online at
<https://github.com/ubernostrum/akismet>. Issues and pull requests can both be
filed there.