Usage overview¶
Once you have akismet installed, you can begin using it as soon as you register an API key and a site to use it on.
Obtaining an API key¶
Use of akismet requires an Akismet API key, and requires associating that API key with the site you’ll use akismet on. Visit akismet.com to purchase an API key and associate it with a site.
Optional arguments to API methods¶
For API methods other than verify_key()
, only the end
user’s IP address and user-agent string are required to be passed as
arguments (a third argument, blog, will be automatically inserted
for you). However, these methods all accept a large set of optional
keyword arguments, corresponding to additional data accepted by the
Akismet web service. This set of arguments is identical across all the
API methods.
Akismet recommends sending as many of these arguments as possible, as additional data helps with identification of spam and training the service.
For a full list of the supported arguments, see the Akismet web service documentation.
The most commonly useful arguments are:
- comment_author – a
str
containing the name or username of the person posting the comment. - comment_content – a
str
containing the contents of the comment. - comment_type – a
str
indicating the type of comment. For typical site comments, set this to “comment”. For a contact form, use “contact-form”. For a user-account signup, use “signup”.
If you call a method of Akismet
and pass one or more
arguments not recognized by the Akismet web service, an
UnknownArgumentError
will be raised.
Exceptions¶
To represent different possible error conditions, akismet provides several exception classes:
Base class for all exceptions directly raised by akismet. Other exceptions may still occur (for example, due to network unavailability or timeout), and will not be caught by akismet or replaced with this exception.
Subclass of
AkismetError
indicating an unexpected argument was provided as part of a request. The message raised with this exception will include the names of all the unknown arguments.
Subclass of
AkismetError
indicating an unexpected or non-standard response was received from the Akismet web service. The message raised with this exception will include the API method invoked, and the contents of the unexpected response.
Subclass of
AkismetError
indicating that the supplied configuration is missing or invalid. The message raised with this exception will provide details of the problem.
Subclass of
ConfigurationError
to indicate the specific case of an invalid API key.