Add method to get Message object by its ID

Made changes requested by bboe for pull request

CHANGES.rst

@@ -30,6 +30,8 @@ Unreleased
    site, not the casing used to construct the Subreddit instance. To quickly
    fetch the name of an unloaded Subreddit, use ``str(sub_instance)``, or
    ``unicode(sub_instance)``.
+ * **[FEATURE]** Added :meth:`get_message` to fetch a single Message object
+   by its ID.
 
 PRAW 2.1.21
 -----------

praw/__init__.py

@@ -122,6 +122,7 @@ class Config(object):  # pylint: disable=R0903
                  'login':               'api/login/',
                  'me':                  'api/v1/me',
                  'mentions':            'message/mentions',
+                 'message':             'message/messages/%s/',
                  'messages':            'message/messages/',
                  'moderators':          'r/%s/about/moderators/',
                  'modlog':              'r/%s/about/log/',
@@ -2048,6 +2049,19 @@ def get_inbox(self, *args, **kwargs):
         """
         return self.get_content(self.config['inbox'], *args, **kwargs)
 
+    @decorators.restrict_access(scope='privatemessages')
+    def get_message(self, message_id, *args, **kwargs):
+        """Return a Message object corresponding to the given ID.
+
+        :param message_id: The ID or Fullname for a Message
+
+        The additional parameters are passed into
+        :meth:`.from_id` of Message, and subsequently into
+        :meth:`.request_json`.
+
+        """
+        return objects.Message.from_id(self, message_id, *args, **kwargs)
+
     @decorators.restrict_access(scope='privatemessages')
     def get_messages(self, *args, **kwargs):
         """Return a get_content generator for inbox (messages only).

praw/objects.py

@@ -636,6 +636,33 @@ class Message(Inboxable):
 
     """A class for private messages."""
 
+    @staticmethod
+    @restrict_access(scope='privatemessages')
+    def from_id(reddit_session, message_id, *args, **kwargs):
+        """Request the url for a Message and return a Message object.
+
+        :param reddit_session: The session to make the request with.
+        :param message_id: The ID of the message to request.
+
+        The additional parameters are passed directly into
+        :meth:`.request_json`.
+
+        """
+        # Reduce fullname to ID if necessary
+        message_id = message_id.split('_', 1)[-1]
+        url = reddit_session.config['message'] % message_id
+        message_info = reddit_session.request_json(url, *args, **kwargs)
+        message = message_info['data']['children'][0]
+
+        # Messages are received as a listing such that
+        # the first item is always the thread's root.
+        # The ID requested by the user may be a child.
+        if message.id == message_id:
+            return message
+        for child in message.replies:
+            if child.id == message_id:
+                return child
+
     def __init__(self, reddit_session, json_dict):
         """Construct an instnace of the Message object."""
         super(Message, self).__init__(reddit_session, json_dict)

tests/old.py

@@ -820,6 +820,13 @@ def test_get_unread_update_has_mail(self):
         self.r.get_unread(limit=1, unset_has_mail=True, update_user=True)
         self.assertFalse(self.r.user.has_mail)
 
+    def test_get_message(self):
+        message1 = next(self.r.get_inbox(limit=1))
+        message2 = self.r.get_message(message1.id)
+        self.assertEqual(message1, message2)
+        self.assertEqual(self.r.user.name.lower(), message2.dest.lower())
+        self.assertTrue(isinstance(message2.replies, list))
+
     def test_mark_as_read(self):
         self.r.login(self.other_user_name, self.other_user_pswd)
         # pylint: disable-msg=E1101