7.1.1. isbg package

7.1.1.2. Module contents

isbg scans an IMAP Inbox and runs every entry against SpamAssassin.

For any entries that match, the message is copied to another folder, and the original marked or deleted.

isbg.learn_mail(mail, learn_type)

Process a email and try to learn or unlearn it.

Parameters:
  • mail (email.message.Message) – email to learn.
  • learn_type (str) – `spam` to learn spam, `ham` to learn nonspam or `forget`.
Returns:

It returns a pair of int

The first integer:

A return code of 6 means it was already learned or forgotten, a return code of 5 means it has been learned or forgotten, a -9999 means an error communicating with spamc. If spamc returns an exit code, it returns it.

The second integer:

It’s the original exit code from spamc

Return type:

int, int

Notes

See Exit Codes section of the man page of spamc for more information about other exit codes.

isbg.test_mail(mail, spamc=False, cmd=False)

Test a email with spamassassin.

isbg.unwrap(mail)

Unwrap a email from the spamassasin email.

the mail could be a email.message.Email, a file or a string or buffer. It ruturns a list with all the email.message.Email founds.

Parameters:mail (email.message.Message, FILE_TYPES, str) – the mail to unwrap.
Returns:A list with the unwraped mails.
Return type:[email.message.Message]
class isbg.ISBG

Bases: object

Main ISBG class.

See also

isbg.__main__ for command line usage.

Examples

>>> import isbg
>>> sbg = isbg.ISBG()
>>> sbg.imapsets.host = "imap.example.org"
>>> sbg.imapsets.port = 993
>>> sbg.imapsets.user = "example@example.org"
>>> sbg.imapsets.passwd = "xxxxxxxx"
>>> sbg.imapsets.inbox = "INBOX"
>>> sbg.imapsets.spaminbox = "INBOX.Spam"
>>> sbg.imapsets.learnspambox = "INBOX.Spam"
>>> sbg.imapsets.learnhambox = "NOSPAM"
>>> # Set the number of mails to chech
>>> sbg.partialrun = 4        # Only check 4 mails for every proc.
>>> sbg.verbose = True        # Show more info
>>> sbg.ignorelockfile = True # Ignore lock file
>>> sbg.removelock()          # if there is a lock file
>>> sbg.do_isbg()      # Connects to the imap and checks for spam
imap

class that take care of connection and communication with the IMAP server. It’s initialized calling do_imap_login() and every time that calling do_isbg().

Type:isbg.imaputils.IsbgImap4
imapsets

Object to store the IMAP settings. It’s initialized when ISBG is initialized and also stores the IMAP folders used by ISBG.

It also stores the command line args for:
user (imapuser), passwd (imappasswd), host (imaphost), port (imapport), nossl (nossl), inbox (imapinbox), spaminbox (spaminbox), learnspambox (learnspambox) and learnhambox (learnhambox).
Type:isbg.imaputils.ImapSettings
logger

Object used to output info. It’s initialized when ISBG is initialized.

Type:logging.Logger

These are attributes derived from the command line and needed for normal operations:

exitcodes

If True returns more exit codes. Defaults to True.

Type:bool
imaplist

If True shows the folder list. Default to False.

Type:bool
noreport

If True not adds SpamAssassin report to mails. Default to False.

Type:bool
nostats

If True no shows stats. Default to False.

Type:bool
verbose_mails

If True shows the email content. Default to False.

Type:bool
verbose

a property that if it’s set to True show more information. Default to False.

These are attributes derived for the command line, and needed for SpamAssassin operations:

dryrun

If True don’t do changes in the IMAP account. Default to False.

Type:bool
maxsize

Max file size to process. Default to 120,000.

Type:int
teachonly

If True don’t search spam, only learn. Default to False.

Type:bool
spamc

If True use spamc instead of standalone SpamAssassin. Default to False.

Type:bool
gmail

If True Delete by copying to [Gmail]/Trash folder. Default to False.

Type:bool
deletehigherthan

If it’s not None, the minimum score from a mail to be deleted. Default to None.

Type:float
delete

If True the spam mails will be marked for deletion. Default to False.

Type:bool
expunge

If True causes marked for deletion messages to also be deleted (only useful if deleted is True. Default to None.

Type:bool
flag

If True the spams will be flagged in your INBOX. Default to False.

Type:bool
learnflagged

If True only learn flagged messages. Default to False.

Type:bool
learnunflagged

If True only learn unflagged messages. Default to False.

Type:bool
learnthendestroy

If True mark learned messages for deletion. Default to False.

Type:bool
learnthenflag

If True flag learned messages. Default to False.

Type:bool
movehamto

If it’s not None, IMAP folder where the ham mail will be moved. Default to None.

Type:str

These are attributes derived from the command line and related to the lock file:

ignorelockfile

If True and there is the lock file a error is raised.

Type:bool
lockfile

Full path and name of the lock file.

The path it’s initialized with the xdg cache home specification plus /isbg/ and with the name lock.

Type:str
lockfilegrace

Lifetime of the lock file in seconds. Default to 240.0

Type:float

These are attributes derived for the command line, related to the IMAP password and files:

passwdfilename

The fill name where the password will be stored. Defaults to None. It only have use if savepw is True.

Type:str
savepw

If True a obfuscated password will be stored into a file.

Type:bool
trackfile

Base name where the processed uids will be stored to not reprocess them. Default to None when initialized and initialized the first time that is needed.

Type:str
__init__()

Initialize a ISBG object.

logger = None

a logger

static set_filename(imapsets, filetype)

Set the filename of cached created files.

If filetype is password, the file name start with .isbg-, else it starts with the filetype. A hash from the imapsets it’s appended to it. The path of the file will be xdg_cache_home/isbg/

Parameters:
Returns:

The full file path.

Return type:

str

verbose

Get the verbose property.

Getter:Gets the verbose property.
Setter:Sets verbose property.
Type:bool
removelock()

Remove the lockfile.

assertok(res, *args)

Check that the return code is OK.

It also prints out what happened (which would end up /dev/null’ed in non-verbose mode)

pastuid_read(uidvalidity, folder='inbox')

Read the uids stored in a file for a folder.

pastuids_read keeps track of which uids we have already seen, so that we don’t analyze them multiple times. We store its contents between sessions by saving into a file as Python code (makes loading it here real easy since we just source the file)

pastuid_write(uidvalidity, origpastuids, newpastuids, folder='inbox')

Write the uids in a file for the folder.

do_list_imap()

List the imap boxes.

do_spamassassin()

Do the spamassassin procesing.

It creates a instance of SpamAssassin every time that this method is called. The SpamAssasssin object would contact to the IMAP server to get the emails and to SpamAssassin command line to process them.

do_imap_login()

Login to the imap.

do_imap_logout()

Sign off from the imap connection.

do_isbg()

Execute the main isbg process.

It should be called to process the IMAP account. It returns a exitcode if its called from the command line and have the –exitcodes param.

exception isbg.ISBGError(exitcode=0, message='')

Bases: Exception

Class for the ISBG exceptions.

exitcode

The exit code for the error.

Type:int
message

The human readable error message.

Type:str
__init__(exitcode=0, message='')

Initialize a ISBGError object.

Parameters:
  • exitcode (int) – Exit code. It must be a __exitcodes__ valid value.
  • message (str) – Human readable error message.
Raises:

ValueError – If the exitcode is not in __exitcodes__.