aiospamc package
Submodules
aiospamc.cli module
CLI commands.
- class aiospamc.cli.Output(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
-
Output formats.
- Json = 'json'
- Text = 'text'
- class aiospamc.cli.CliClientBuilder[source]
Bases:
object
Client builder for CLI arguments.
- build() Client [source]
Builds the
aiospamc.client.Client
.- Returns:
An instance of
aiospamc.client.Client
.
- with_connection(host: str = 'localhost', port: int = 783, socket_path: Path | None = None) CliClientBuilder [source]
Sets the type of connection manager to use.
Defaults to TCP, but if a Unix socket is provided it will be used.
- Parameters:
host – TCP hostname to use.
port – TCP port to use.
socket_path – Path to the Unix socket.
- Returns:
This builder instance.
- set_timeout(timeout: Timeout) CliClientBuilder [source]
Sets the timeout for the connection.
- Parameters:
timeout – Timeout object.
- Returns:
This builder instance.
- add_verify(verify: bool) CliClientBuilder [source]
Adds an SSL context to the connection manager.
- Parameters:
verify – How to configure the SSL context. If True, add the default certificate authorities. If False, accept any certificate.
- Returns:
This builder instance.
- add_ca_cert(ca_cert: Path | None) CliClientBuilder [source]
Adds trusted certificate authorities.
- Parameters:
ca_cert – Path to the cerficiate file or directory.
- Returns:
This builder instance.
- add_client_cert(cert: Path | None, key: Path | None = None, password: str | None = None) CliClientBuilder [source]
Add a client certificate to authenticate to the server.
- Parameters:
cert – Path to the client certificate and optionally the key.
key – Path to the client key.
password – Password of the client key.
- Returns:
This builder instance.
- class aiospamc.cli.CommandRunner(client: Client, request: Request, output: Output = Output.Text)[source]
Bases:
object
Object to execute requests and handle exceptions.
- __init__(client: Client, request: Request, output: Output = Output.Text)[source]
CommandRunner constructor.
- Parameters:
request – Request to send.
response – Response if returned from server.
output – Output format when printing to console.
- aiospamc.cli.ping(host: str = 'localhost', port: int = 783, socket_path: Path | None = None, ssl: bool = False, timeout: float = 10, out: Output = Output.Text, ca_cert: Path | None = None, client_cert: Path | None = None, client_key: Path | None = None, key_password: str | None = None)[source]
Pings the SpamAssassin daemon.
A successful pong exits with code 0.
- aiospamc.cli.read_message(file: BufferedReader | None) bytes [source]
Utility function to read data from stdin.
- Parameters:
file – File-like object.
- aiospamc.cli.check(message: FileBinaryRead | None = None, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, ssl: bool = False, user: str = 'docs', timeout: float = 10, out: Output = Output.Text, ca_cert: Path | None = None, client_cert: Path | None = None, client_key: Path | None = None, key_password: str | None = None)[source]
Submits a message to SpamAssassin and returns the processed message.
- aiospamc.cli.learn(message: FileBinaryRead | None = None, message_class: MessageClassOption = MessageClassOption.spam, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, ssl: bool = False, user: str = 'docs', timeout: float = 10, out: Output = Output.Text, ca_cert: Path | None = None, client_cert: Path | None = None, client_key: Path | None = None, key_password: str | None = None)[source]
Ask server to learn the message as spam or ham.
- aiospamc.cli.forget(message: FileBinaryRead | None = None, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, ssl: bool = False, user: str = 'docs', timeout: float = 10, out: Output = Output.Text, ca_cert: Path | None = None, client_cert: Path | None = None, client_key: Path | None = None, key_password: str | None = None)[source]
Forgets the classification of a message.
- aiospamc.cli.report(message: FileBinaryRead | None = None, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, ssl: bool = False, user: str = 'docs', timeout: float = 10, out: Output = Output.Text, ca_cert: Path | None = None, client_cert: Path | None = None, client_key: Path | None = None, key_password: str | None = None)[source]
Report a message to collaborative filtering databases as spam.
- aiospamc.cli.revoke(message: FileBinaryRead | None = None, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, ssl: bool = False, user: str = 'docs', timeout: float = 10, out: Output = Output.Text, ca_cert: Path | None = None, client_cert: Path | None = None, client_key: Path | None = None, key_password: str | None = None)[source]
Revoke a message to collaborative filtering databases.
- aiospamc.cli.version_callback(version: bool)[source]
Callback to print the version.
- Parameters:
version – Switch on whether to print and exit.
aiospamc.client module
Module implementing client objects that all requests go through.
- class aiospamc.client.Client(connection_manager: ConnectionManager)[source]
Bases:
object
Client object to submit requests.
- __init__(connection_manager: ConnectionManager)[source]
Client constructor.
- Parameters:
connection_manager – Instance of a connection manager.
- async request(req: Request)[source]
Sends a request and returns the parsed response.
- Parameters:
req – The request to send.
- Returns:
The parsed response.
- Raises:
BadResponse – If the response from SPAMD is ill-formed this exception will be raised.
AIOSpamcConnectionFailed – Raised if an error occurred when trying to connect.
UsageException – Error in command line usage.
DataErrorException – Error with data format.
NoInputException – Cannot open input.
NoUserException – Addressee unknown.
NoHostException – Hostname unknown.
UnavailableException – Service unavailable.
InternalSoftwareException – Internal software error.
OSErrorException – System error.
OSFileException – Operating system file missing.
CantCreateException – Cannot create output file.
IOErrorException – Input/output error.
TemporaryFailureException – Temporary failure, may reattempt.
ProtocolException – Error in the protocol.
NoPermissionException – Permission denied.
ConfigException – Error in configuration.
ServerTimeoutException – Server returned a response that it timed out.
ClientTimeoutException – Client timed out during connection.
aiospamc.connections module
ConnectionManager classes for TCP and Unix sockets.
- class aiospamc.connections.Timeout(total: float = 600, connection: float | None = None, response: float | None = None)[source]
Bases:
object
Container object for defining timeouts.
- __init__(total: float = 600, connection: float | None = None, response: float | None = None) None [source]
Timeout constructor.
- Parameters:
total – The total length of time in seconds to set the timeout.
connection – The length of time in seconds to allow for a connection to live before timing out.
response – The length of time in seconds to allow for a response from the server before timing out.
- class aiospamc.connections.ConnectionManagerBuilder[source]
Bases:
object
Builder for connection managers.
- class ManagerType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Bases:
Enum
Define connection manager type during build.
- Undefined = 1
- Tcp = 2
- Unix = 3
- build() UnixConnectionManager | TcpConnectionManager [source]
Builds the
aiospamc.connections.ConnectionManager
.- Returns:
An instance of
aiospamc.connections.TcpConnectionManager
oraiospamc.connections.UnixConnectionManager
- with_unix_socket(path: Path) ConnectionManagerBuilder [source]
Configures the builder to use a Unix socket connection.
- Parameters:
path – Path to the Unix socket.
- Returns:
This builder instance.
- with_tcp(host: str, port: int = 783) ConnectionManagerBuilder [source]
Configures the builder to use a TCP connection.
- Parameters:
host – Hostname to use.
port – Port to use.
- Returns:
This builder instance.
- add_ssl_context(context: SSLContext) ConnectionManagerBuilder [source]
Adds an SSL context when a TCP connection is being used.
- Parameters:
context –
ssl.SSLContext
instance.- Returns:
This builder instance.
- set_timeout(timeout: Timeout) ConnectionManagerBuilder [source]
Sets the timeout for the connection.
- Parameters:
timeout – Timeout object.
- Returns:
This builder instance.
- class aiospamc.connections.ConnectionManager(connection_string: str, timeout: Timeout | None = None)[source]
Bases:
object
Stores connection parameters and creates connections.
- __init__(connection_string: str, timeout: Timeout | None = None) None [source]
ConnectionManager constructor.
- Parameters:
timeout – Timeout configuration
- property logger: loguru.Logger
Return the logger object.
- async request(data: bytes) bytes [source]
Send bytes data and receive a response.
- Raises:
AIOSpamcConnectionFailed
- Raises:
ClientTimeoutException
- Parameters:
data – Data to send.
- class aiospamc.connections.TcpConnectionManagerBuilder[source]
Bases:
object
Builder for
aiospamc.connections.TcpConnectionManager
- build() TcpConnectionManager [source]
Builds the
aiospamc.connections.TcpConnectionManager
.- Returns:
An instance of
aiospamc.connections.TcpConnectionManager
.
- set_host(host: str) TcpConnectionManagerBuilder [source]
Sets the host to use.
- Parameters:
host – Hostname to use.
- Returns:
This builder instance.
- set_port(port: int) TcpConnectionManagerBuilder [source]
Sets the port to use.
- Parameters:
port – Port to use.
- Returns:
This builder instance.
- set_ssl_context(context: SSLContext) TcpConnectionManagerBuilder [source]
Set an SSL context.
- Parameters:
context – An instance of
ssl.SSLContext
.- Returns:
This builder instance.
- set_timeout(timeout: Timeout) TcpConnectionManagerBuilder [source]
Sets the timeout for the connection.
- Parameters:
timeout – Timeout object.
- Returns:
This builder instance.
- class aiospamc.connections.TcpConnectionManager(host: str, port: int, ssl_context: SSLContext | None = None, timeout: Timeout | None = None)[source]
Bases:
ConnectionManager
Connection manager for TCP connections.
- class aiospamc.connections.UnixConnectionManagerBuilder[source]
Bases:
object
Builder for
aiospamc.connections.UnixConnectionManager
.- build() UnixConnectionManager [source]
Builds a
aiospamc.connections.UnixConnectionManager
.- Returns:
An instance of
aiospamc.connections.UnixConnectionManager
.
- set_path(path: Path) UnixConnectionManagerBuilder [source]
Sets the unix socket path.
- Parameters:
path – Path to the Unix socket.
- Returns:
This builder instance.
- set_timeout(timeout: Timeout) UnixConnectionManagerBuilder [source]
Sets the timeout for the connection.
- Parameters:
timeout – Timeout object.
- Returns:
This builder instance.
- class aiospamc.connections.UnixConnectionManager(path: Path, timeout: Timeout | None = None)[source]
Bases:
ConnectionManager
Connection manager for Unix pipes.
- class aiospamc.connections.SSLContextBuilder[source]
Bases:
object
SSL context builder.
- build() SSLContext [source]
Builds the SSL context.
- Returns:
An instance of
ssl.SSLContext
.
- with_context(context: SSLContext) SSLContextBuilder [source]
Use the SSL context.
- Parameters:
context – Provided SSL context.
- Returns:
The builder instance.
- add_ca_file(file: Path) SSLContextBuilder [source]
Add certificate authority from a file.
- Parameters:
file – File of concatenated certificates.
- Returns:
The builder instance.
- add_ca_dir(dir: Path) SSLContextBuilder [source]
Add certificate authority from a directory.
- Parameters:
dir – Directory of certificates.
- Returns:
The builder instance.
- add_ca(path: Path) SSLContextBuilder [source]
Add a certificate authority.
- Parameters:
path – Directory or file of certificates.
- Returns:
The builder instance.
- add_default_ca() SSLContextBuilder [source]
Add default certificate authorities.
- Returns:
The builder instance.
- add_client(file: Path, key: Path | None = None, password: Callable[[], str | bytes | bytearray] | None = None) SSLContextBuilder [source]
Add client certificate.
- Parameters:
file – Path to the client certificate.
key – Path to the key.
password – Callable that returns the password, if any.
- dont_verify() SSLContextBuilder [source]
Set the context to not verify certificates.
aiospamc.exceptions module
Collection of exceptions.
- exception aiospamc.exceptions.ClientException[source]
Bases:
Exception
Base class for exceptions raised from the client.
- exception aiospamc.exceptions.BadRequest[source]
Bases:
ClientException
Request is not in the expected format.
- exception aiospamc.exceptions.BadResponse[source]
Bases:
ClientException
Response is not in the expected format.
- exception aiospamc.exceptions.AIOSpamcConnectionFailed[source]
Bases:
ClientException
Connection failed.
- exception aiospamc.exceptions.ClientTimeoutException[source]
Bases:
ClientException
,TimeoutException
Timeout exception from the client.
- exception aiospamc.exceptions.ParseError(message=None)[source]
Bases:
Exception
Error occurred while parsing.
- exception aiospamc.exceptions.NotEnoughDataError(message=None)[source]
Bases:
ParseError
Expected more data than what the protocol content specified.
- exception aiospamc.exceptions.TooMuchDataError(message=None)[source]
Bases:
ParseError
Too much data was received than what the protocol content specified.
aiospamc.frontend module
Frontend functions for the package.
- class aiospamc.frontend.FrontendClientBuilder[source]
Bases:
object
Builds the
aiospamc.client.Client
based off of frontend arguments.- build() Client [source]
Builds the
aiospamc.client.Client
.- Returns:
An instance of
aiospamc.client.Client
.
- with_connection(host: str = 'localhost', port: int = 783, socket_path: Path | None = None) FrontendClientBuilder [source]
Sets the type of connection manager to use.
Defaults to TCP, but if a Unix socket is provided it will be used.
- Parameters:
host – TCP hostname to use.
port – TCP port to use.
socket_path – Path to the Unix socket.
- Returns:
This builder instance.
- add_verify(verify: bool | Path | SSLContext | None = None) FrontendClientBuilder [source]
Adds an SSL context to the connection manager.
- Parameters:
verify – How to configure the SSL context. If True, add the default certificate authorities. If False, accept any certificate. If a
pathlib.Path
, add the certificates from it. If anssl.SSLContext
, then use it.- Returns:
This builder instance.
- add_client_cert(cert: Path | Tuple[Path, Path | None] | Tuple[Path, Path | None, str | None] | None) FrontendClientBuilder [source]
Add a client certificate to authenticate to the server.
- Parameters:
cert – Client certificate. Takes up to three a three tuple value. 1. Path to the certificate and key. 2. Path to the certificate and path to the key. 3. Path to the certificate, path to the key, and password of the key.
- Returns:
This builder instance.
- set_timeout(timeout: Timeout | None = None) FrontendClientBuilder [source]
Sets the timeout for the connection.
- Parameters:
timeout – Timeout object.
- Returns:
This builder instance.
- async aiospamc.frontend.check(message: bytes | SupportsBytes, *, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, timeout: Timeout | None = None, verify: bool | Path | SSLContext | None = None, cert: Path | Tuple[Path, Path | None] | Tuple[Path, Path | None, str | None] | None = None, user: str | None = None, compress: bool = False) Response [source]
Checks a message if it’s spam and return a response with a score header.
- Parameters:
message – Copy of the message.
host – Hostname or IP address of the SPAMD service, defaults to localhost.
port – Port number for the SPAMD service, defaults to 783.
socket_path – Path to Unix socket.
timeout – Timeout settings.
verify – Enable SSL. True will use the root certificates from the
certifi
package. False will use SSL, but not verify the root certificates. Passing a string to a filename will use the path to verify the root certificates.cert – Use client certificate. Can either by a
pathlib.Path
to a file that includes both the certificate and key. Can be a tuple containing apathlib.Path
to the certificate and apathlib.Path
to the key. Can be a tuple containing apathlib.Path
to the certificate,pathlib.Path
to the key, and a password.user – Username to pass to the SPAMD service.
compress – Enable compress of the request body.
- Returns:
A successful response with a “Spam” header showing if the message is considered spam as well as the score.
- Raises:
BadResponse – If the response from SPAMD is ill-formed this exception will be raised.
AIOSpamcConnectionFailed – Raised if an error occurred when trying to connect.
UsageException – Error in command line usage.
DataErrorException – Error with data format.
NoInputException – Cannot open input.
NoUserException – Addressee unknown.
NoHostException – Hostname unknown.
UnavailableException – Service unavailable.
InternalSoftwareException – Internal software error.
OSErrorException – System error.
OSFileException – Operating system file missing.
CantCreateException – Cannot create output file.
IOErrorException – Input/output error.
TemporaryFailureException – Temporary failure, may reattempt.
ProtocolException – Error in the protocol.
NoPermissionException – Permission denied.
ConfigException – Error in configuration.
ServerTimeoutException – Server returned a response that it timed out.
ClientTimeoutException – Client timed out during connection.
- async aiospamc.frontend.headers(message: bytes | SupportsBytes, *, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, timeout: Timeout | None = None, verify: bool | Path | SSLContext | None = None, cert: Path | Tuple[Path, Path | None] | Tuple[Path, Path | None, str | None] | None = None, user: str | None = None, compress: bool = False) Response [source]
Checks a message if it’s spam and return the modified message headers.
- Parameters:
message – Copy of the message.
host – Hostname or IP address of the SPAMD service, defaults to localhost.
port – Port number for the SPAMD service, defaults to 783.
socket_path – Path to Unix socket.
timeout – Timeout settings.
verify – Enable SSL. True will use the root certificates from the
certifi
package. False will use SSL, but not verify the root certificates. Passing a string to a filename will use the path to verify the root certificates.cert – Use client certificate. Can either by a
pathlib.Path
to a file that includes both the certificate and key. Can be a tuple containing apathlib.Path
to the certificate and apathlib.Path
to the key. Can be a tuple containing apathlib.Path
to the certificate,pathlib.Path
to the key, and a password.user – Username to pass to the SPAMD service.
compress – Enable compress of the request body.
- Returns:
A successful response with a “Spam” header showing if the message is considered spam as well as the score. The body contains the modified message headers, but not the content of the message.
- Raises:
BadResponse – If the response from SPAMD is ill-formed this exception will be raised.
AIOSpamcConnectionFailed – Raised if an error occurred when trying to connect.
UsageException – Error in command line usage.
DataErrorException – Error with data format.
NoInputException – Cannot open input.
NoUserException – Addressee unknown.
NoHostException – Hostname unknown.
UnavailableException – Service unavailable.
InternalSoftwareException – Internal software error.
OSErrorException – System error.
OSFileException – Operating system file missing.
CantCreateException – Cannot create output file.
IOErrorException – Input/output error.
TemporaryFailureException – Temporary failure, may reattempt.
ProtocolException – Error in the protocol.
NoPermissionException – Permission denied.
ConfigException – Error in configuration.
ServerTimeoutException – Server returned a response that it timed out.
ClientTimeoutException – Client timed out during connection.
- async aiospamc.frontend.ping(*, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, timeout: Timeout | None = None, verify: bool | Path | SSLContext | None = None, cert: Path | Tuple[Path, Path | None] | Tuple[Path, Path | None, str | None] | None = None) Response [source]
Sends a ping to the SPAMD service.
- Parameters:
host – Hostname or IP address of the SPAMD service, defaults to localhost.
port – Port number for the SPAMD service, defaults to 783.
socket_path – Path to Unix socket.
timeout – Timeout settings.
verify – Enable SSL. True will use the root certificates from the
certifi
package. False will use SSL, but not verify the root certificates. Passing a string to a filename will use the path to verify the root certificates.cert – Use client certificate. Can either by a
pathlib.Path
to a file that includes both the certificate and key. Can be a tuple containing apathlib.Path
to the certificate and apathlib.Path
to the key. Can be a tuple containing apathlib.Path
to the certificate,pathlib.Path
to the key, and a password.
- Returns:
A response with “PONG”.
- Raises:
BadResponse – If the response from SPAMD is ill-formed this exception will be raised.
AIOSpamcConnectionFailed – Raised if an error occurred when trying to connect.
UsageException – Error in command line usage.
DataErrorException – Error with data format.
NoInputException – Cannot open input.
NoUserException – Addressee unknown.
NoHostException – Hostname unknown.
UnavailableException – Service unavailable.
InternalSoftwareException – Internal software error.
OSErrorException – System error.
OSFileException – Operating system file missing.
CantCreateException – Cannot create output file.
IOErrorException – Input/output error.
TemporaryFailureException – Temporary failure, may reattempt.
ProtocolException – Error in the protocol.
NoPermissionException – Permission denied.
ConfigException – Error in configuration.
ServerTimeoutException – Server returned a response that it timed out.
ClientTimeoutException – Client timed out during connection.
- async aiospamc.frontend.process(message: bytes | SupportsBytes, *, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, timeout: Timeout | None = None, verify: bool | Path | SSLContext | None = None, cert: Path | Tuple[Path, Path | None] | Tuple[Path, Path | None, str | None] | None = None, user: str | None = None, compress: bool = False) Response [source]
Checks a message if it’s spam and return a response with a score header.
- Parameters:
message – Copy of the message.
host – Hostname or IP address of the SPAMD service, defaults to localhost.
port – Port number for the SPAMD service, defaults to 783.
socket_path – Path to Unix socket.
timeout – Timeout settings.
verify – Enable SSL. True will use the root certificates from the
certifi
package. False will use SSL, but not verify the root certificates. Passing a string to a filename will use the path to verify the root certificates.cert – Use client certificate. Can either by a
pathlib.Path
to a file that includes both the certificate and key. Can be a tuple containing apathlib.Path
to the certificate and apathlib.Path
to the key. Can be a tuple containing apathlib.Path
to the certificate,pathlib.Path
to the key, and a password.user – Username to pass to the SPAMD service.
compress – Enable compress of the request body.
- Returns:
A successful response with a “Spam” header showing if the message is considered spam as well as the score. The body contains a modified copy of the message.
- Raises:
BadResponse – If the response from SPAMD is ill-formed this exception will be raised.
AIOSpamcConnectionFailed – Raised if an error occurred when trying to connect.
UsageException – Error in command line usage.
DataErrorException – Error with data format.
NoInputException – Cannot open input.
NoUserException – Addressee unknown.
NoHostException – Hostname unknown.
UnavailableException – Service unavailable.
InternalSoftwareException – Internal software error.
OSErrorException – System error.
OSFileException – Operating system file missing.
CantCreateException – Cannot create output file.
IOErrorException – Input/output error.
TemporaryFailureException – Temporary failure, may reattempt.
ProtocolException – Error in the protocol.
NoPermissionException – Permission denied.
ConfigException – Error in configuration.
ServerTimeoutException – Server returned a response that it timed out.
ClientTimeoutException – Client timed out during connection.
- async aiospamc.frontend.report(message: bytes | SupportsBytes, *, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, timeout: Timeout | None = None, verify: bool | Path | SSLContext | None = None, cert: Path | Tuple[Path, Path | None] | Tuple[Path, Path | None, str | None] | None = None, user: str | None = None, compress: bool = False) Response [source]
Checks a message if it’s spam and return a response with a score header.
- Parameters:
message – Copy of the message.
host – Hostname or IP address of the SPAMD service, defaults to localhost.
port – Port number for the SPAMD service, defaults to 783.
socket_path – Path to Unix socket.
timeout – Timeout settings.
verify – Enable SSL. True will use the root certificates from the
certifi
package. False will use SSL, but not verify the root certificates. Passing a string to a filename will use the path to verify the root certificates.cert – Use client certificate. Can either by a
pathlib.Path
to a file that includes both the certificate and key. Can be a tuple containing apathlib.Path
to the certificate and apathlib.Path
to the key. Can be a tuple containing apathlib.Path
to the certificate,pathlib.Path
to the key, and a password.user – Username to pass to the SPAMD service.
compress – Enable compress of the request body.
- Returns:
A successful response with a “Spam” header showing if the message is considered spam as well as the score. The body contains a report.
- Raises:
BadResponse – If the response from SPAMD is ill-formed this exception will be raised.
AIOSpamcConnectionFailed – Raised if an error occurred when trying to connect.
UsageException – Error in command line usage.
DataErrorException – Error with data format.
NoInputException – Cannot open input.
NoUserException – Addressee unknown.
NoHostException – Hostname unknown.
UnavailableException – Service unavailable.
InternalSoftwareException – Internal software error.
OSErrorException – System error.
OSFileException – Operating system file missing.
CantCreateException – Cannot create output file.
IOErrorException – Input/output error.
TemporaryFailureException – Temporary failure, may reattempt.
ProtocolException – Error in the protocol.
NoPermissionException – Permission denied.
ConfigException – Error in configuration.
ServerTimeoutException – Server returned a response that it timed out.
ClientTimeoutException – Client timed out during connection.
- async aiospamc.frontend.report_if_spam(message: bytes | SupportsBytes, *, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, timeout: Timeout | None = None, verify: bool | Path | SSLContext | None = None, cert: Path | Tuple[Path, Path | None] | Tuple[Path, Path | None, str | None] | None = None, user: str | None = None, compress: bool = False) Response [source]
Checks a message if it’s spam and return a response with a score header.
- Parameters:
message – Copy of the message.
host – Hostname or IP address of the SPAMD service, defaults to localhost.
port – Port number for the SPAMD service, defaults to 783.
socket_path – Path to Unix socket.
timeout – Timeout settings.
verify – Enable SSL. True will use the root certificates from the
certifi
package. False will use SSL, but not verify the root certificates. Passing a string to a filename will use the path to verify the root certificates.cert – Use client certificate. Can either by a
pathlib.Path
to a file that includes both the certificate and key. Can be a tuple containing apathlib.Path
to the certificate and apathlib.Path
to the key. Can be a tuple containing apathlib.Path
to the certificate,pathlib.Path
to the key, and a password.user – Username to pass to the SPAMD service.
compress – Enable compress of the request body.
- Returns:
A successful response with a “Spam” header showing if the message is considered spam as well as the score. The body contains a report if the message is considered spam.
- Raises:
BadResponse – If the response from SPAMD is ill-formed this exception will be raised.
AIOSpamcConnectionFailed – Raised if an error occurred when trying to connect.
UsageException – Error in command line usage.
DataErrorException – Error with data format.
NoInputException – Cannot open input.
NoUserException – Addressee unknown.
NoHostException – Hostname unknown.
UnavailableException – Service unavailable.
InternalSoftwareException – Internal software error.
OSErrorException – System error.
OSFileException – Operating system file missing.
CantCreateException – Cannot create output file.
IOErrorException – Input/output error.
TemporaryFailureException – Temporary failure, may reattempt.
ProtocolException – Error in the protocol.
NoPermissionException – Permission denied.
ConfigException – Error in configuration.
ServerTimeoutException – Server returned a response that it timed out.
ClientTimeoutException – Client timed out during connection.
- async aiospamc.frontend.symbols(message: bytes | SupportsBytes, *, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, timeout: Timeout | None = None, verify: bool | Path | SSLContext | None = None, cert: Path | Tuple[Path, Path | None] | Tuple[Path, Path | None, str | None] | None = None, user: str | None = None, compress: bool = False) Response [source]
Checks a message if it’s spam and return a response with rules that matched.
- Parameters:
message – Copy of the message.
host – Hostname or IP address of the SPAMD service, defaults to localhost.
port – Port number for the SPAMD service, defaults to 783.
socket_path – Path to Unix socket.
timeout – Timeout settings.
verify – Enable SSL. True will use the root certificates from the
certifi
package. False will use SSL, but not verify the root certificates. Passing a string to a filename will use the path to verify the root certificates.cert – Use client certificate. Can either by a
pathlib.Path
to a file that includes both the certificate and key. Can be a tuple containing apathlib.Path
to the certificate and apathlib.Path
to the key. Can be a tuple containing apathlib.Path
to the certificate,pathlib.Path
to the key, and a password.user – Username to pass to the SPAMD service.
compress – Enable compress of the request body.
- Returns:
A successful response with a “Spam” header showing if the message is considered spam as well as the score. The body contains a comma-separated list of the symbols that were hit.
- Raises:
BadResponse – If the response from SPAMD is ill-formed this exception will be raised.
AIOSpamcConnectionFailed – Raised if an error occurred when trying to connect.
UsageException – Error in command line usage.
DataErrorException – Error with data format.
NoInputException – Cannot open input.
NoUserException – Addressee unknown.
NoHostException – Hostname unknown.
UnavailableException – Service unavailable.
InternalSoftwareException – Internal software error.
OSErrorException – System error.
OSFileException – Operating system file missing.
CantCreateException – Cannot create output file.
IOErrorException – Input/output error.
TemporaryFailureException – Temporary failure, may reattempt.
ProtocolException – Error in the protocol.
NoPermissionException – Permission denied.
ConfigException – Error in configuration.
ServerTimeoutException – Server returned a response that it timed out.
ClientTimeoutException – Client timed out during connection.
- async aiospamc.frontend.tell(message: bytes | SupportsBytes, message_class: str | MessageClassOption, remove_action: str | ActionOption | None = None, set_action: str | ActionOption | None = None, *, host: str = 'localhost', port: int = 783, socket_path: Path | None = None, timeout: Timeout | None = None, verify: bool | Path | SSLContext | None = None, cert: Path | Tuple[Path, Path | None] | Tuple[Path, Path | None, str | None] | None = None, user: str | None = None, compress: bool = False) Response [source]
Checks a message if it’s spam and return a response with a score header.
- Parameters:
message – Copy of the message.
message_class – Classify the message as ‘spam’ or ‘ham’.
remove_action – Remove message class for message in database.
set_action – Set message class for message in database.
host – Hostname or IP address of the SPAMD service, defaults to localhost.
port – Port number for the SPAMD service, defaults to 783.
socket_path – Path to Unix socket.
timeout – Timeout settings.
verify – Enable SSL. True will use the root certificates from the
certifi
package. False will use SSL, but not verify the root certificates. Passing a string to a filename will use the path to verify the root certificates.cert – Use client certificate. Can either by a
pathlib.Path
to a file that includes both the certificate and key. Can be a tuple containing apathlib.Path
to the certificate and apathlib.Path
to the key. Can be a tuple containing apathlib.Path
to the certificate,pathlib.Path
to the key, and a password.user – Username to pass to the SPAMD service.
compress – Enable compress of the request body.
- Returns:
A successful response with “DidSet” and/or “DidRemove” headers along with the actions that were taken.
- Raises:
BadResponse – If the response from SPAMD is ill-formed this exception will be raised.
AIOSpamcConnectionFailed – Raised if an error occurred when trying to connect.
UsageException – Error in command line usage.
DataErrorException – Error with data format.
NoInputException – Cannot open input.
NoUserException – Addressee unknown.
NoHostException – Hostname unknown.
UnavailableException – Service unavailable.
InternalSoftwareException – Internal software error.
OSErrorException – System error.
OSFileException – Operating system file missing.
CantCreateException – Cannot create output file.
IOErrorException – Input/output error.
TemporaryFailureException – Temporary failure, may reattempt.
ProtocolException – Error in the protocol.
NoPermissionException – Permission denied.
ConfigException – Error in configuration.
ServerTimeoutException – Server returned a response that it timed out.
ClientTimeoutException – Client timed out during connection.
aiospamc.header_values module
Collection of request and response header value objects.
- protocol aiospamc.header_values.HeaderValue[source]
Bases:
Protocol
Protocol for headers.
Classes that implement this protocol must have the following methods / attributes:
- class aiospamc.header_values.BytesHeaderValue(value: bytes)[source]
Bases:
object
Header with bytes value.
- Parameters:
value – Value of the header.
- class aiospamc.header_values.GenericHeaderValue(value: str, encoding: str = 'utf8')[source]
Bases:
object
Generic header value.
- class aiospamc.header_values.CompressValue(algorithm: str = 'zlib')[source]
Bases:
object
Compress header. Specifies what encryption scheme to use. So far only ‘zlib’ is supported.
- class aiospamc.header_values.ContentLengthValue(length: int = 0)[source]
Bases:
object
ContentLength header. Indicates the length of the body in bytes.
- class aiospamc.header_values.MessageClassOption(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
-
Option to be used for the MessageClass header.
- spam = 'spam'
- ham = 'ham'
- class aiospamc.header_values.MessageClassValue(value: MessageClassOption = MessageClassOption.ham)[source]
Bases:
object
MessageClass header. Used to specify whether a message is ‘spam’ or ‘ham.’
- value: MessageClassOption = 'ham'
- __init__(value: MessageClassOption = MessageClassOption.ham) None
- class aiospamc.header_values.ActionOption(local: bool = False, remote: bool = False)[source]
Bases:
object
Option to be used in the DidRemove, DidSet, Set, and Remove headers.
- Parameters:
local – An action will be performed on the SPAMD service’s local database.
remote – An action will be performed on the SPAMD service’s remote database.
- class aiospamc.header_values.SetOrRemoveValue(action: ActionOption)[source]
Bases:
object
Base class for headers that implement “local” and “remote” rules.
- action: ActionOption
- __init__(action: ActionOption) None
- class aiospamc.header_values.SpamValue(value: bool = False, score: float = 0.0, threshold: float = 0.0)[source]
Bases:
object
Spam header. Used by the SPAMD service to report on if the submitted message was spam and the score/threshold that it used.
- class aiospamc.header_values.UserValue(name: str = 'docs')[source]
Bases:
object
User header. Used to specify which user the SPAMD service should use when loading configuration files.
- class aiospamc.header_values.Headers(dict=None, /, **kwargs)[source]
Bases:
UserDict
Class to store headers with shortcut properties.
- get_header(name: str) str | None [source]
Get a string header if it exists.
- Parameters:
name – Name of the header.
- Returns:
The header value.
- set_header(name: str, value: str)[source]
Sets a string header.
- Parameters:
name – Name of the header.
value – Value of the header.
- get_bytes_header(name: str) bytes | None [source]
Get a bytes header if it exists.
- Parameters:
name – Name of the header.
- Returns:
The header value.
- set_bytes_header(name: str, value: bytes)[source]
Sets a string header.
- Parameters:
name – Name of the header.
value – Value of the header.
- property compress: str | None
Gets the Compress header if it exists.
- Returns:
Compress header value.
- property content_length: int | None
Gets the Content-length header if it exists.
- Returns:
Content-length header value.
- property message_class: MessageClassOption | None
Gets the Message-class header if it exists.
- Returns:
Message-class header value.
- property set_: ActionOption | None
Gets the Set header if it exists.
- Returns:
Set header value.
- property remove: ActionOption | None
Gets the Remove header if it exists.
- Returns:
Remove header value.
- property did_set: ActionOption | None
Gets the DidSet header if it exists.
- Returns:
DidSet header value.
- property did_remove: ActionOption | None
Gets the DidRemove header if it exists.
- Returns:
DidRemove header value.
aiospamc.incremental_parser module
Module for the parsing functions and objects.
- class aiospamc.incremental_parser.States(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Bases:
Enum
States for the parser state machine.
- Status = 1
- Header = 2
- Body = 3
- Done = 4
- class aiospamc.incremental_parser.Parser(delimiter: bytes, status_parser: Callable[[bytes], Mapping[str, str]], header_parser: Callable[[bytes], Tuple[str, Any]], body_parser: Callable[[bytes, int], bytes], start: States = States.Status)[source]
Bases:
object
The parser state machine.
- Variables:
result – Storage location for parsing results.
- __init__(delimiter: bytes, status_parser: Callable[[bytes], Mapping[str, str]], header_parser: Callable[[bytes], Tuple[str, Any]], body_parser: Callable[[bytes, int], bytes], start: States = States.Status) None [source]
Parser constructor.
- Parameters:
delimiter – Byte string to split the different sections of the message.
status_parser – Callable to parse the status line of the message.
header_parser – Callable to parse each header line of the message.
body_parser – Callable to parse the body of the message.
start – The state to start the parser on. Allowed for easier testing.
- parse(stream: bytes) Mapping[str, Any] [source]
Entry method to parse a message.
- Parameters:
stream – Byte string to parse.
- Returns:
Returns the parser results dictionary stored in the class attribute
result
.- Raises:
NotEnoughDataError – Raised when not enough data is sent to be parsed.
TooMuchDataError – Raised when too much data is sent to be parsed.
ParseError – Raised when a general parse error is found.
- status() None [source]
Splits the message at the delimiter and sends the first part of the message to the
status_parser
callable to be parsed. If successful then the results are stored in theresult
class attribute and the state transitions toStates.Header
.- Raises:
NotEnoughDataError – When there is no delimiter the message is incomplete.
ParseError – When the
status_parser
callable experiences an error.
- header() None [source]
Splits the message at the delimiter and sends the line to the
header_parser
.When splitting the action will be determined depending what is matched:
Header line
Delimiter
Leftover
Action
No
Yes
Delimiter
Headers done, empty body. Clear buffer and transition to
States.Body
.No
Yes
N/A
Headers done. Transition to
States.Body
.Yes
Yes
N/A
Parse header. Record in
result
class attribute.No
No
No
Message was a status line only. Transition to
States.Body
.- Raises:
ParseError – None of the previous conditions are matched.
- body() None [source]
Uses the length defined in the Content-length header (defaulted to 0) to determine how many bytes the body contains.
- Raises:
TooMuchDataError – When there are too many bytes in the buffer compared to the Content-length header value. Transitions the state to
States.Done
.
- aiospamc.incremental_parser.parse_request_status(stream: bytes) Dict[str, str] [source]
Parses the status line from a request.
- Parameters:
stream – The byte stream to parse.
- Returns:
A dictionary with the keys verb, protocol and version.
- Raises:
ParseError – When the status line is in an invalid format, not a valid verb, or doesn’t have the correct protocol.
- aiospamc.incremental_parser.parse_response_status(stream: bytes) Dict[str, str | int] [source]
Parse the status line for a response.
- Parameters:
stream – The byte stream to parse.
- Returns:
A dictionary with the keys protocol, version, status_code, and message.
- Raises:
ParseError – When the status line is in an invalid format, status code is not an integer, or doesn’t have the correct protocol.
- aiospamc.incremental_parser.parse_message_class_value(stream: str | MessageClassOption) MessageClassValue [source]
Parses the Message-class header value.
- Parameters:
stream – String or
aiospamc.header_values.MessageClassOption
instance.- Returns:
A
aiospamc.header_values.MessageClassValue
instance representing the value.- Raises:
ParseError – When the value doesn’t match either ham or spam.
- aiospamc.incremental_parser.parse_content_length_value(stream: str | int) ContentLengthValue [source]
Parses the Content-length header value.
- Parameters:
stream – String or integer value of the header.
- Returns:
A
aiospamc.header_values.ContentLengthValue
instance.- Raises:
ParseError – When the value cannot be cast to an integer.
- aiospamc.incremental_parser.parse_compress_value(stream: str) CompressValue [source]
Parses a value for the Compress header.
- Parameters:
stream – String to parse.
- Returns:
A
aiospamc.header_values.CompressValue
instance.
- aiospamc.incremental_parser.parse_set_remove_value(stream: ActionOption | str) SetOrRemoveValue [source]
Parse a value for the
aiospamc.header_values.DidRemove
,aiospamc.header_values.DidSet
,aiospamc.header_values.Remove
, andaiospamc.header_values.Set
headers.- Parameters:
stream – String to parse or an instance of
aiospamc.header_values.ActionOption
.- Returns:
A
aiospamc.header_values.SetOrRemoveValue
instance.
- aiospamc.incremental_parser.parse_spam_value(stream: str) SpamValue [source]
Parses the values for the Spam header.
- Parameters:
stream – String to parse.
- Returns:
A
aiospamc.header_values.SpamValue
instance.- Raises:
ParseError – Raised if there is no true/false value, or valid numbers for the score or threshold.
- aiospamc.incremental_parser.parse_user_value(stream: str) UserValue [source]
Parse the username.
- Parameters:
stream – String of username to parse. Whitespace is trimmed.
- Returns:
The
aiospamc.header_values.UserValue
instance.
- aiospamc.incremental_parser.parse_header_value(header: str, value: str | bytes) Any [source]
Sends the header value stream to the header value parsing function.
- Parameters:
header – Name of the header.
value – String or byte stream of the header value.
- Returns:
The
aiospamc.header_values.HeaderValue
instance from the parsing function.
- aiospamc.incremental_parser.parse_header(stream: bytes) Tuple[str, Any] [source]
Splits the header line and sends to the header parsing function.
- Parameters:
stream – Byte stream of the header line.
- Returns:
A tuple of the header name and value.
- aiospamc.incremental_parser.parse_body(stream: bytes, content_length: int) bytes [source]
Parses the body of a message.
- Parameters:
stream – Byte stream for the body.
content_length – Expected length of the body in bytes.
- Returns:
Byte stream of the body.
- Raises:
NotEnoughDataError – If the length is less than the stream.
TooMuchDataError – If the length is more than the stream.
- aiospamc.incremental_parser.header_value_parsers = {'Compress': <function parse_compress_value>, 'Content-length': <function parse_content_length_value>, 'DidRemove': <function parse_set_remove_value>, 'DidSet': <function parse_set_remove_value>, 'Message-class': <function parse_message_class_value>, 'Remove': <function parse_set_remove_value>, 'Set': <function parse_set_remove_value>, 'Spam': <function parse_spam_value>, 'User': <function parse_user_value>}
Mapping for header names to their parsing functions.
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: Dict[str, Any] | Headers | None = None, body: bytes | SupportsBytes = b'', **_)[source]
Bases:
object
SPAMC request object.
- __init__(verb: str, version: str = '1.5', headers: Dict[str, Any] | Headers | None = None, body: bytes | SupportsBytes = b'', **_) None [source]
Request constructor.
- Parameters:
verb – Method name of the request.
version – Version of the protocol.
headers – Collection of headers to be added.
body – Byte string representation of the body.
aiospamc.responses module
Contains classes used for responses.
- class aiospamc.responses.Status(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Bases:
IntEnum
Enumeration for the status values defined by SPAMD.
- EX_OK = 0
- EX_USAGE = 64
- EX_DATAERR = 65
- EX_NOINPUT = 66
- EX_NOUSER = 67
- EX_NOHOST = 68
- EX_UNAVAILABLE = 69
- EX_SOFTWARE = 70
- EX_OSERR = 71
- EX_OSFILE = 72
- EX_CANTCREAT = 73
- EX_IOERR = 74
- EX_TEMPFAIL = 75
- EX_PROTOCOL = 76
- EX_NOPERM = 77
- EX_CONFIG = 78
- EX_TIMEOUT = 79
- class aiospamc.responses.Response(version: str = '1.5', status_code: Status | int = 0, message: str = '', headers: Dict[str, Any] | Headers | None = None, body: bytes = b'', **_)[source]
Bases:
object
Class to encapsulate response.
- __init__(version: str = '1.5', status_code: Status | int = 0, message: str = '', headers: Dict[str, Any] | Headers | None = None, body: bytes = b'', **_)[source]
Response constructor.
- Parameters:
version – Version reported by the SPAMD service response.
status_code – Success or error code.
message – Message associated with status code.
body – Byte string representation of the body.
headers – Collection of headers to be added.
- exception aiospamc.responses.ResponseException(code: int, message: str, response: Response)[source]
Bases:
Exception
Base class for exceptions raised from a response.
- exception aiospamc.responses.UsageException(message: str, response: Response)[source]
Bases:
ResponseException
Command line usage error.
- exception aiospamc.responses.DataErrorException(message: str, response: Response)[source]
Bases:
ResponseException
Data format error.
- exception aiospamc.responses.NoInputException(message: str, response: Response)[source]
Bases:
ResponseException
Cannot open input.
- exception aiospamc.responses.NoUserException(message: str, response: Response)[source]
Bases:
ResponseException
Addressee unknown.
- exception aiospamc.responses.NoHostException(message: str, response: Response)[source]
Bases:
ResponseException
Hostname unknown.
Bases:
ResponseException
Service unavailable.
UnavailableException constructor.
- Parameters:
message – Message response.
- exception aiospamc.responses.InternalSoftwareException(message: str, response: Response)[source]
Bases:
ResponseException
Internal software error.
- exception aiospamc.responses.OSErrorException(message: str, response: Response)[source]
Bases:
ResponseException
System error (e.g. can’t fork the process).
- exception aiospamc.responses.OSFileException(message: str, response: Response)[source]
Bases:
ResponseException
Critical operating system file missing.
- exception aiospamc.responses.CantCreateException(message: str, response: Response)[source]
Bases:
ResponseException
Can’t create (user) output file.
- exception aiospamc.responses.IOErrorException(message: str, response: Response)[source]
Bases:
ResponseException
Input/output error.
- exception aiospamc.responses.TemporaryFailureException(message: str, response: Response)[source]
Bases:
ResponseException
Temporary failure, user is invited to try again.
- exception aiospamc.responses.ProtocolException(message: str, response: Response)[source]
Bases:
ResponseException
Remote error in protocol.
- exception aiospamc.responses.NoPermissionException(message: str, response: Response)[source]
Bases:
ResponseException
Permission denied.
- exception aiospamc.responses.ConfigException(message: str, response: Response)[source]
Bases:
ResponseException
Configuration error.
- exception aiospamc.responses.ServerTimeoutException(message: str, response: Response)[source]
Bases:
ResponseException
,TimeoutException
Timeout exception from the server.
aiospamc.user_warnings module
Functions to raise warnings based on user inputs.
- aiospamc.user_warnings.raise_warnings(request: Request, connection: ConnectionManager)[source]
Calls all warning functions.
- Parameters:
request – Instance of a request.
connection – Connection manager instance.
- aiospamc.user_warnings.warn_spamd_bug_7183(request: Request, connection: ConnectionManager)[source]
Warn on spamd bug if using compression with an SSL connection.
- Parameters:
request – Instance of a request.
connection – Connection manager instance.
Bug: https://bz.apache.org/SpamAssassin/show_bug.cgi?id=7183
Module contents
aiospamc package.
An asyncio-based library to communicate with SpamAssassin’s SPAMD service.