1"""Provide the MessageableMixin class."""
2from ....const import API_PATH
3
4
5class MessageableMixin(object):
6    """Interface for classes that can be messaged."""
7
8    def message(self, subject, message, from_subreddit=None):
9        """
10        Send a message to a redditor or a subreddit's moderators (mod mail).
11
12        :param subject: The subject of the message.
13        :param message: The message content.
14        :param from_subreddit: A Subreddit instance or string to send the
15            message from. When provided, messages are sent from the subreddit
16            rather than from the authenticated user. Note that the
17            authenticated user must be a moderator of the subreddit and have
18            mail permissions.
19
20        For example, to send a private message to ``/u/spez``, try:
21
22        .. code:: python
23
24           reddit.redditor('spez').message('TEST', 'test message from PRAW')
25
26        To send a message to ``u/spez`` from the moderators of ``r/test`` try:
27
28        .. code:: python
29
30           reddit.redditor('spez').message('TEST', 'test message from r/test',
31                                           from_subreddit='test')
32
33        To send a message to the moderators of ``/r/test``, try:
34
35        .. code:: python
36
37           reddit.subreddit('test').message('TEST', 'test PM from PRAW')
38
39        """
40        data = {
41            "subject": subject,
42            "text": message,
43            "to": "{}{}".format(
44                getattr(self.__class__, "MESSAGE_PREFIX", ""), self
45            ),
46        }
47        if from_subreddit:
48            data["from_sr"] = str(from_subreddit)
49        self._reddit.post(API_PATH["compose"], data=data)
50