mailadmin_core module

Core classes for administering the mail server database.

Classes and functions for inspecting and manipulating the database associated with a Postfix- and Dovecot-based mail server configured according to the instructions from Linode (https://www.linode.com/docs/guides/email-with-postfix-dovecot-and-mysql/).

class mailadmin_core.Alias(alias_id: int, domain_id: int, source: str, destination: str, table_names)

Bases: object

A representation of an email alias database entry.

id

The ID of the user.

Type

int

domain_id

The ID of the user’s email domain.

Type

int

source

The full email address whose mail should be forwarded.

Type

str

destination

The full email address which should receive forwarded mail.

Type

str

create(db)

Insert a new alias into the database.

Parameters

db (pymysql.connections.Connection) – A connection to the database.

Returns

The ID of the newly-inserted item if successful. False otherwise.

Return type

int or bool

delete(db)

Delete an existing alias from the database.

Parameters

db (pymysql.connections.Connection) – A connection to the database.

Returns

Whether the delete was successful.

Return type

bool

update(db)

Update an existing alias in the database.

Parameters

db (pymysql.connections.Connection) – A connection to the database.

Returns

Whether the update was successful.

Return type

bool

exception mailadmin_core.DatabaseException

Bases: Exception

Custom exception to raise when user makes invalid database requests.

class mailadmin_core.Domain(domain_id, name, table_names)

Bases: object

A representation of an email domain database entry.

id

The ID of the domain.

Type

int

name

The name of the domain.

Type

str

create(db)

Insert a new domain into the database.

Parameters

db (pymysql.connections.Connection) – A connection to the database.

Returns

The ID of the newly-inserted item if successful. False otherwise.

Return type

int or bool

delete(db)

Delete a domain from the database.

Parameters

db (pymysql.connections.Connection) – A connection to the database.

Returns

Whether the delete was successful.

Return type

bool

update(db)

Update an existing domain in the database.

Parameters

db (pymysql.connections.Connection) – A connection to the database.

Returns

Whether the update was successful.

Return type

bool

class mailadmin_core.MailAdminDatabase

Bases: object

A representation of the mailserver database.

commit_alias(alias: mailadmin_core.Alias) → mailadmin_core.Alias

Update the database with a given alias.

Parameters

alias (Alias) – The alias to insert into or update in the database.

Returns

The alias after the insertion/update has completed.

Return type

Alias

Raises

DatabaseException – If the user makes an invalid request.

commit_domain(domain: mailadmin_core.Domain) → mailadmin_core.Domain

Insert or update a domain into or in the database.

Parameters

domain (Domain) – The domain to be added or updated.

Returns

The domain after being added or updated.

Return type

Domain

Raises

DatabaseException – If the the invoker makes an invalid request.

commit_user(user: mailadmin_core.User) → mailadmin_core.User

Update the database with a given user.

Parameters

user (User) – The user to insert into or update in the database.

Returns

The user after the insertion/update has completed.

Return type

User

Raises

DatabaseException – If the user makes an invalid request.

delete_alias(alias_id: int) → bool

Delete an alias from the database.

Parameters

alias_id (int) – The ID of the alias to delete.

Returns

Whether the deletion was successful.

Return type

bool

Raises

DatabaseException – If the alias already did not exist.

delete_domain(domain_id: int) → bool

Delete the specified domain.

Parameters

domain_id (int) – The ID of the domain to delete

Returns

Whether the deletion was successful.

Return type

bool

Raises

DatabaseException – If the user attempts to delete a domain which does not exist.

delete_user(user_id: int) → bool

Delete a user from the database.

Parameters

user_id (int) – The ID of the user to delete.

Returns

Whether the deletion was successful.

Return type

bool

Raises

DatabaseException – If the user does not exist.

delete_user_by_email(email: str) → bool

Delete a user, specified by an email address, from the database.

Parameters

email (str) – The user’s email address.

Returns

Whether the deletion was successful.

Return type

bool

Raises

DatabaseException – If the requested user does not exist.

get_alias(alias_id: Optional[int] = None) → mailadmin_core.Alias

Return an alias specified by ID.

Parameters

alias_id (int or None) – The ID of the alias to return, or None or 0 to create a new alias.

Returns

The requested alias.

Return type

Alias

Raises

DatabaseException – If the alias is not found, or if no valid combinations of domains and users are found to create an alias destination.

get_aliases()

Return lists of IDs, domain IDs, and source and destination addresses of the aliases.

Returns

  • ids (list of int) – The IDs of the users.

  • domain_ids (list of int) – The IDs of the users’ domains.

  • sources (list of str) – The source email addresses of the users.

  • destinations (list of str) – The destination email addresses of the users.

get_domain(domain_id: Optional[int] = None)

Return a domain specified by an ID, or a new domain if no ID is given.

Parameters

domain_id (int or None) – The ID of the domain to return, or None if a new domain is desired.

Returns

The requested domain.

Return type

Domain

Raises

DatabaseException – If an ID is given but the requested domain is not found.

get_domain_by_name(name: str) → mailadmin_core.Domain

Return a domain specified by a name.

Parameters

name (str) – The name of the domain to return.

Returns

The requested domain.

Return type

Domain

Raises

DatabaseException – If the requested domain is not found.

get_domains()

Return lists of IDs and names of the domains.

Returns

  • ids (list of int) – The IDs of the domains.

  • names (list of str) – The domain names.

get_user(user_id: Optional[int] = None) → mailadmin_core.User

Return a user specified by an ID, or a new user if no ID is given.

Parameters

user_id (int or None) – The ID of the user to return, or None if a new user is desired.

Returns

The requested user.

Return type

User

Raises

DatabaseException – If an ID is given but the requested user is not found, or if there are no domains.

get_user_by_email(email: str) → mailadmin_core.User

Return a user specified by an email address.

Parameters

email (str) – The email address of the user to return.

Returns

The requested user.

Return type

User

Raises

DatabaseException – If no user is found with the given email address

get_users()

Return lists of IDs, domain IDs, and email addresses of the users.

Returns

  • ids (list of int) – The IDs of the users.

  • domain_ids (list of int) – The IDs of the users’ domains.

  • emails (list of str) – The email addresses of the users.

print_aliases()

Print a list of the aliases.

print_domains()

Print a list of the known domains.

print_users()

Print a list of the known users.

class mailadmin_core.Table(headings, alignments)

Bases: object

An object for printing nicely formatted tables

add_row(new_row)

Add a new row to the table.

Parameters

new_row (list of str) – A list of new values to add to the table

print(sep=' ')

Print the contents of the table to the console.

Parameters

sep (str) – The string to separate the columns of the table (Default: ‘ ‘).

class mailadmin_core.User(user_id: int, domain_id: int, email: str, table_names)

Bases: object

A representation of an email user database entry.

id

The ID of the user.

Type

int

domain_id

The ID of the user’s email domain.

Type

int

email

The full email address of the user.

Type

str

password

The user’s password (only ever populated with user input for changing/creating).

Type

str

create(db)

Insert a new user into the database.

Parameters

db (pymysql.connections.Connection) – A connection to the database.

Returns

The ID of the newly-inserted item if successful. False otherwise.

Return type

int or bool

delete(db)

Delete an existing user from the database.

Parameters

db (pymysql.connections.Connection) – A connection to the database.

Returns

Whether the delete was successful.

Return type

bool

update(db)

Update an existing user in the database.

Parameters

db (pymysql.connections.Connection) – A connection to the database.

Returns

Whether the update was successful.

Return type

bool

mailadmin_core.first_or_default(sequence: Iterable, condition: Callable[], bool], default=None)

Return the first item in the sequence matching the condition.

Parameters

  • sequence (Iterable) – The sequence to search for an item to match the condition.

  • condition (callable) – The condition to be met in the form of a callback function which accepts objects in the sequence and returns a boolean.

  • default (Object) – What to return if no item in the sequence matches the condition.

Returns

The first object in the sequence to satisfy the condition.

Return type

Object

mailadmin_core.first_or_default_index(sequence: Iterable, condition: Callable[], bool], default=- 1)

Return the index of the first item in the sequence matching the condition.

Parameters

  • sequence (Iterable) – The sequence to search for an item to match the condition.

  • condition (callable) – The condition to be met in the form of a callback function which accepts objects in the sequence and returns a boolean.

  • default (int) – What to return if no item in the sequence matches the condition (default -1)

Returns

The index of the first item matching the condition.

Return type

int