aiospamc package

Submodules

aiospamc.client module

Contains the Client class that is used to interact with SPAMD.

class aiospamc.client.Client(socket_path: str = '/var/run/spamassassin/spamd.sock', host: str = None, port: int = 783, user: str = None, compress: bool = False, ssl: bool = False, loop: asyncio.events.AbstractEventLoop = None)[source]

Bases: object

Client object for interacting with SPAMD.

async check(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

Raises
async headers(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain the modified headers of the message.

Raises
async ping() → aiospamc.responses.Response[source]

Sends a ping request to the SPAMD service and will receive a response if the service is alive.

Returns

Response message will contain ‘PONG’ if successful.

Raises
async process(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain a modified version of the message.

Raises
async report(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain a report composed by the SPAMD service.

Raises
async report_if_spam(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain a report composed by the SPAMD service only if the message is marked as being spam.

Raises
async send(request: aiospamc.requests.Request) → aiospamc.responses.Response[source]

Sends a request to the SPAMD service.

If the SPAMD service gives a temporary failure response, then its retried.

Parameters

request – Request object to send.

Raises
async symbols(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain a comma separated list of all the rule names.

Raises
async tell(message_class: aiospamc.options.MessageClassOption, message: Union[bytes, SupportsBytes], remove_action: aiospamc.options.ActionOption = None, set_action: aiospamc.options.ActionOption = None)[source]

Instruct the SPAMD service to to mark the message

Parameters

  • message_class – An enumeration to classify the message as ‘spam’ or ‘ham.’

  • message –

    A byte string containing the contents of the message to be scanned.

    SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

  • remove_action – Remove message class for message in database.

  • set_action – Set message class for message in database.

Returns

Will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain a report composed by the SPAMD service only if message is marked as being spam.

Raises

aiospamc.common module

Common classes for the project.

class aiospamc.common.SpamcBody[source]

Bases: object

Provides a descriptor for a bytes-like object.

class aiospamc.common.SpamcHeaders(*, headers: Iterator[aiospamc.headers.Header] = None, **_)[source]

Bases: collections.abc.Mapping

Provides a dictionary-like interface for headers.

items() → a set-like object providing a view on D's items[source]
keys() → a set-like object providing a view on D's keys[source]
values() → an object providing a view on D's values[source]

aiospamc.exceptions module

Collection of exceptions.

exception aiospamc.exceptions.AIOSpamcConnectionException[source]

Bases: Exception

Base class for exceptions from the connection.

exception aiospamc.exceptions.AIOSpamcConnectionFailed[source]

Bases: aiospamc.exceptions.AIOSpamcConnectionException

Connection failed.

exception aiospamc.exceptions.BadRequest[source]

Bases: aiospamc.exceptions.ClientException

Request is not in the expected format.

exception aiospamc.exceptions.BadResponse[source]

Bases: aiospamc.exceptions.ClientException

Response is not in the expected format.

exception aiospamc.exceptions.CantCreateException[source]

Bases: aiospamc.exceptions.ResponseException

Can’t create (user) output file.

code = 73
exception aiospamc.exceptions.ClientException[source]

Bases: Exception

Base class for exceptions raised from the client.

exception aiospamc.exceptions.ConfigException[source]

Bases: aiospamc.exceptions.ResponseException

Configuration error.

code = 78
exception aiospamc.exceptions.DataErrorException[source]

Bases: aiospamc.exceptions.ResponseException

Data format error.

code = 65
exception aiospamc.exceptions.IOErrorException[source]

Bases: aiospamc.exceptions.ResponseException

Input/output error.

code = 74
exception aiospamc.exceptions.InternalSoftwareException[source]

Bases: aiospamc.exceptions.ResponseException

Internal software error.

code = 70
exception aiospamc.exceptions.NoHostException[source]

Bases: aiospamc.exceptions.ResponseException

Hostname unknown.

code = 68
exception aiospamc.exceptions.NoInputException[source]

Bases: aiospamc.exceptions.ResponseException

Cannot open input.

code = 66
exception aiospamc.exceptions.NoPermissionException[source]

Bases: aiospamc.exceptions.ResponseException

Permission denied.

code = 77
exception aiospamc.exceptions.NoUserException[source]

Bases: aiospamc.exceptions.ResponseException

Addressee unknown.

code = 67
exception aiospamc.exceptions.OSErrorException[source]

Bases: aiospamc.exceptions.ResponseException

System error (e.g. can’t fork the process).

code = 71
exception aiospamc.exceptions.OSFileException[source]

Bases: aiospamc.exceptions.ResponseException

Critical operating system file missing.

code = 72
exception aiospamc.exceptions.ProtocolException[source]

Bases: aiospamc.exceptions.ResponseException

Remote error in protocol.

code = 76
exception aiospamc.exceptions.ResponseException[source]

Bases: Exception

Base class for exceptions raised from a response.

exception aiospamc.exceptions.TemporaryFailureException[source]

Bases: aiospamc.exceptions.ResponseException

Temporary failure, user is invited to try again.

code = 75
exception aiospamc.exceptions.TimeoutException[source]

Bases: aiospamc.exceptions.ResponseException

Read timeout.

code = 79
exception aiospamc.exceptions.UnavailableException[source]

Bases: aiospamc.exceptions.ResponseException

Service unavailable.

code = 69
exception aiospamc.exceptions.UsageException[source]

Bases: aiospamc.exceptions.ResponseException

Command line usage error.

code = 64

aiospamc.headers module

Collection of request and response headers.

class aiospamc.headers.Compress[source]

Bases: aiospamc.headers.Header

Compress header. Specifies what encryption scheme to use. So far only ‘zlib’ is supported.

field_name() → str[source]

Returns the the field name for the header.

class aiospamc.headers.ContentLength(length: int = 0)[source]

Bases: aiospamc.headers.Header

ContentLength header. Indicates the length of the body in bytes.

field_name() → str[source]

Returns the the field name for the header.

class aiospamc.headers.DidRemove(action: aiospamc.options.ActionOption = None)[source]

Bases: aiospamc.headers._SetRemoveBase

DidRemove header. Used by SPAMD to indicate if a message was removed from either a local or remote database in response to a TELL request.

field_name() → str[source]

Returns the the field name for the header.

class aiospamc.headers.DidSet(action: aiospamc.options.ActionOption = None)[source]

Bases: aiospamc.headers._SetRemoveBase

DidRemove header. Used by SPAMD to indicate if a message was added to either a local or remote database in response to a TELL request.

field_name() → str[source]

Returns the the field name for the header.

class aiospamc.headers.Header[source]

Bases: object

Header base class.

field_name() → str[source]

Returns the the field name for the header.

class aiospamc.headers.MessageClass(value: aiospamc.options.MessageClassOption = None)[source]

Bases: aiospamc.headers.Header

MessageClass header. Used to specify whether a message is ‘spam’ or ‘ham.’

field_name() → str[source]

Returns the the field name for the header.

class aiospamc.headers.Remove(action: aiospamc.options.ActionOption = None)[source]

Bases: aiospamc.headers._SetRemoveBase

Remove header. Used in a TELL request to ask the SPAMD service remove a message from a local or remote database. The SPAMD service must have the –allow-tells switch in order for this to do anything.

field_name()[source]

Returns the the field name for the header.

class aiospamc.headers.Set(action: aiospamc.options.ActionOption = None)[source]

Bases: aiospamc.headers._SetRemoveBase

Set header. Used in a TELL request to ask the SPAMD service add a message from a local or remote database. The SPAMD service must have the –allow-tells switch in order for this to do anything.

field_name() → str[source]

Returns the the field name for the header.

class aiospamc.headers.Spam(value: bool = False, score: float = 0.0, threshold: float = 0.0)[source]

Bases: aiospamc.headers.Header

Spam header. Used by the SPAMD service to report on if the submitted message was spam and the score/threshold that it used.

field_name() → str[source]

Returns the the field name for the header.

class aiospamc.headers.User(name: str = None)[source]

Bases: aiospamc.headers.Header

User header. Used to specify which user the SPAMD service should use when loading configuration files.

field_name() → str[source]

Returns the the field name for the header.

class aiospamc.headers.XHeader(name: str, value: str)[source]

Bases: aiospamc.headers.Header

Extension header. Used to specify a header that’s not supported natively by the SPAMD service.

field_name() → str[source]

Returns the the field name for the header.

aiospamc.options module

Data structures used for function parameters.

class aiospamc.options.ActionOption(local, remote)

Bases: tuple

Option to be used in the DidRemove, DidSet, Set, and Remove headers.

localbool

An action will be performed on the SPAMD service’s local database.

remotebool

An action will be performed on the SPAMD service’s remote database.

property local

Alias for field number 0

property remote

Alias for field number 1

class aiospamc.options.MessageClassOption[source]

Bases: enum.IntEnum

Option to be used for the MessageClass header.

ham = 2
spam = 1

aiospamc.parser module

Parser object for SPAMC/SPAMD requests and responses.

exception aiospamc.parser.ParseError(index: int, message: str)[source]

Bases: Exception

An exception occurring when parsing.

class aiospamc.parser.Parser(string: bytes = None)[source]

Bases: object

Parser object for requests and responses.

advance(by: int) → None[source]

Advance the current index by number of bytes.

Parameters

by – Number of bytes in the stream to advance.

body() → bytes[source]

Consumes the rest of the message and returns the contents.

compress_value() → str[source]

Consumes the Compression header value.

consume(pattern: bytes) → Match[bytes][source]

If the pattern matches, advances the index the length of the match. Returns the regular expression match.

Parameters

pattern – Regular expression pattern.

Raises

ParseError –

content_length_value() → int[source]

Consumes the Content-length header value.

current() → bytes[source]

The remainder of the string that hasn’t been parsed.

end() → bool[source]

Whether the parser has parsed the entire string.

header() → aiospamc.headers.Header[source]

Consumes the string and returns an instance of aiospamc.headers.Header.

headers() → List[aiospamc.headers.Header][source]

Consumes all headers.

match(pattern: bytes) → Optional[Match[bytes]][source]

Returns the regular expression matches string at the current index.

Parameters

pattern – Regular expression pattern.

message() → str[source]

Consumes a string until it matches a newline.

message_class_value() → aiospamc.options.MessageClassOption[source]

Consumes the Message-class header value.

method() → str[source]

Consumes the method name in a request.

newline() → None[source]

Consumes a newline sequence (carriage return and line feed).

request() → aiospamc.requests.Request[source]

Consumes a SPAMC request.

response() → aiospamc.responses.Response[source]

Consumes a SPAMD response.

set_remove_value() → aiospamc.options.ActionOption[source]

Consumes the value for the DidRemove, DidSet, Remove and Set headers.

static skip(func: Callable) → None[source]

Makes the parser function optional by ignore whether it raises a aiospamc.parser.ParseError exception or not.

Parameters

func – Function to execute.

spam_value() → Mapping[str, Union[bool, float]][source]

Consumes the Spam header value.

spamc_protocol() → str[source]

Consumes the string “SPAMC”.

spamd_protocol() → str[source]

Consumes the string “SPAMD”.

status_code() → int[source]

Consumes the status code.

user_value() → str[source]

Consumes the User header value.

version() → str[source]

Consumes a version pattern. For example, “1.5”.

whitespace() → None[source]

Consumes spaces or tabs.

aiospamc.parser.checkpoint(func) → Callable[source]

A decorator to restore the index if an exception occurred.

aiospamc.parser.parse(string) → Union[aiospamc.requests.Request, aiospamc.responses.Response][source]

Parses a request or response.

aiospamc.requests module

Contains all requests that can be made to the SPAMD service.

class aiospamc.requests.Request(verb: str, version: str = '1.5', headers: Iterator[aiospamc.headers.Header] = None, body: Union[bytes, SupportsBytes] = None)[source]

Bases: object

SPAMC request object.

body

Provides a descriptor for a bytes-like object.

aiospamc.responses module

Contains classes used for responses.

class aiospamc.responses.Response(version: str, status_code: aiospamc.responses.Status, message: str, headers: Iterator[aiospamc.headers.Header] = None, body=None)[source]

Bases: object

Class to encapsulate response.

body

Provides a descriptor for a bytes-like object.

raise_for_status() → None[source]
class aiospamc.responses.Status[source]

Bases: enum.IntEnum

Enumeration of status codes that the SPAMD will accompany with a response.

Reference: https://svn.apache.org/repos/asf/spamassassin/trunk/spamd/spamd.raw Look for the %resphash variable.

EX_CANTCREAT = 73
EX_CONFIG = 78
EX_DATAERR = 65
EX_IOERR = 74
EX_NOHOST = 68
EX_NOINPUT = 66
EX_NOPERM = 77
EX_NOUSER = 67
EX_OK = 0
EX_OSERR = 71
EX_OSFILE = 72
EX_PROTOCOL = 76
EX_SOFTWARE = 70
EX_TEMPFAIL = 75
EX_TIMEOUT = 79
EX_UNAVAILABLE = 69
EX_USAGE = 64

Module contents

aiospamc package.

An asyncio-based library to communicate with SpamAssassin’s SPAMD service.

class aiospamc.Client(socket_path: str = '/var/run/spamassassin/spamd.sock', host: str = None, port: int = 783, user: str = None, compress: bool = False, ssl: bool = False, loop: asyncio.events.AbstractEventLoop = None)[source]

Bases: object

Client object for interacting with SPAMD.

async check(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

Raises
async headers(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain the modified headers of the message.

Raises
async ping() → aiospamc.responses.Response[source]

Sends a ping request to the SPAMD service and will receive a response if the service is alive.

Returns

Response message will contain ‘PONG’ if successful.

Raises
async process(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain a modified version of the message.

Raises
async report(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain a report composed by the SPAMD service.

Raises
async report_if_spam(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain a report composed by the SPAMD service only if the message is marked as being spam.

Raises
async send(request: aiospamc.requests.Request) → aiospamc.responses.Response[source]

Sends a request to the SPAMD service.

If the SPAMD service gives a temporary failure response, then its retried.

Parameters

request – Request object to send.

Raises
async symbols(message: Union[bytes, SupportsBytes]) → aiospamc.responses.Response[source]

Request the SPAMD service to check a message with a HEADERS request.

Parameters

message –

A byte string containing the contents of the message to be scanned.

SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

Returns

The response will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain a comma separated list of all the rule names.

Raises
async tell(message_class: aiospamc.options.MessageClassOption, message: Union[bytes, SupportsBytes], remove_action: aiospamc.options.ActionOption = None, set_action: aiospamc.options.ActionOption = None)[source]

Instruct the SPAMD service to to mark the message

Parameters

  • message_class – An enumeration to classify the message as ‘spam’ or ‘ham.’

  • message –

    A byte string containing the contents of the message to be scanned.

    SPAMD will perform a scan on the included message. SPAMD expects an RFC 822 or RFC 2822 formatted email.

  • remove_action – Remove message class for message in database.

  • set_action – Set message class for message in database.

Returns

Will contain a ‘Spam’ header if the message is marked as spam as well as the score and threshold.

The body will contain a report composed by the SPAMD service only if message is marked as being spam.

Raises
class aiospamc.MessageClassOption[source]

Bases: enum.IntEnum

Option to be used for the MessageClass header.

ham = 2
spam = 1
class aiospamc.ActionOption(local, remote)

Bases: tuple

Option to be used in the DidRemove, DidSet, Set, and Remove headers.

localbool

An action will be performed on the SPAMD service’s local database.

remotebool

An action will be performed on the SPAMD service’s remote database.

property local

Alias for field number 0

property remote

Alias for field number 1