1# Copyright 2020 Patrick Ulbrich <zulu99@gmx.net>
2# Copyright 2016 Timo Kankare <timo.kankare@iki.fi>
3#
4# This program is free software; you can redistribute it and/or modify
5# it under the terms of the GNU General Public License as published by
6# the Free Software Foundation; either version 2 of the License, or
7# (at your option) any later version.
8#
9# This program is distributed in the hope that it will be useful,
10# but WITHOUT ANY WARRANTY; without even the implied warranty of
11# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12# GNU General Public License for more details.
13#
14# You should have received a copy of the GNU General Public License
15# along with this program; if not, write to the Free Software
16# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
17# MA 02110-1301, USA.
18#
19
20"""Interface and base implementation for mailbox backends."""
21
22from abc import ABCMeta, abstractmethod
23
24
25class MailboxBackend(object, metaclass=ABCMeta):
26	"""Interface for mailbox backends.
27
28	Mailbox backend implements access to the specific type of mailbox.
29	"""
30
31	def __init__(self, **kw):
32		"""Constructor should accept any kind of backend specific
33		parameters.
34		"""
35
36	@abstractmethod
37	def open(self):
38		"""Opens the mailbox."""
39		raise NotImplementedError
40
41	@abstractmethod
42	def close(self):
43		"""Closes the mailbox."""
44		raise NotImplementedError
45
46	@abstractmethod
47	def is_open(self):
48		"""Returns true if mailbox is open."""
49		raise NotImplementedError
50
51	@abstractmethod
52	def list_messages(self):
53		"""Lists unseen messages from the mailbox for this account.
54		Yields tuples (folder, message, flags) for every message.
55		"""
56		raise NotImplementedError
57
58	@abstractmethod
59	def request_folders(self):
60		"""Returns list of folder names available in the mailbox.
61		Raises an exceptions if mailbox does not support folders.
62		"""
63		raise NotImplementedError
64
65	def supports_mark_as_seen(self):
66		"""Returns True if mailbox supports flagging mails as seen."""
67		# Default implementation
68		return False
69
70	@abstractmethod
71	def mark_as_seen(self, mails):
72		"""Asks mailbox to flag mails in the list as seen.
73		This may raise an exception if mailbox does not support this action.
74		"""
75		raise NotImplementedError
76
77	def supports_notifications(self):
78		"""Returns True if mailbox supports notifications."""
79		# Default implementation
80		return False
81
82	@abstractmethod
83	def notify_next_change(self, callback=None, timeout=None):
84		"""Asks mailbox to notify next change.
85		Callback is called when new mail arrives or a mail is removed.
86		This may raise an exception if mailbox does not support
87		notifications.
88		"""
89		raise NotImplementedError
90
91	@abstractmethod
92	def cancel_notifications(self):
93		"""Cancels notifications.
94		This may raise an exception if mailbox does not support
95		notifications.
96		"""
97		raise NotImplementedError
98
99