Repository: TheFriendlyCoder/friendlypins

Issue:
add helper method to retrieve a specific pin based on its ID
In order to use the Pinterest REST API more efficiently I want to add support for loading data for a specific pin directly with just its unique identifier, lazy loading REST API data when needed.

Discussion:

Patch:
diff --git a/src/friendlypins/api.py b/src/friendlypins/api.py
index 120116c..92b4475 100644
--- a/src/friendlypins/api.py
+++ b/src/friendlypins/api.py
@@ -2,10 +2,11 @@
 import logging
 from friendlypins.user import User
 from friendlypins.board import Board
+from friendlypins.pin import Pin
 from friendlypins.utils.rest_io import RestIO
 
 
-class API(object):  # pylint: disable=too-few-public-methods
+class API(object):
     """High level abstraction for the core Pinterest API"""
 
     def __init__(self, personal_access_token):
@@ -35,6 +36,23 @@ class API(object):  # pylint: disable=too-few-public-methods
         board_url = "boards/{0}".format(board_id)
         return Board(board_url, self._io)
 
+    def get_pin_by_id(self, pin_id):
+        """Locates a specific Pinterest pin given it's internal identifier
+
+        NOTE: this API assumes that the ID provided references a valid pin.
+        If it does not, the object returned will be invalid and any attempts
+        to access data from the pin will result in an error.
+
+        Args:
+            pin_id (int):
+                the unique identifier for the board
+
+        Returns:
+            Pin: reference to the Pinterest pin
+        """
+        pin_url = "pins/{0}".format(pin_id)
+        return Pin(pin_url, self._io)
+
     @property
     def user(self):
         """User: Gets all primitives associated with the authenticated user"""


Test patch:
diff --git a/tests/test_api.py b/tests/test_api.py
index 026b261..5c2e0b0 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -1,5 +1,7 @@
 import mock
 from friendlypins.api import API
+from friendlypins.board import Board
+from friendlypins.pin import Pin
 from dateutil import tz
 
 
@@ -30,6 +32,30 @@ def test_get_user():
         assert expected_id == result.unique_id
 
 
+@mock.patch("friendlypins.utils.rest_io.requests")
+def test_get_board_by_id(mock_requests):
+    mock_response = mock.MagicMock()
+    mock_requests.get.return_value = mock_response
+
+    obj = API("abcd1234")
+    result = obj.get_board_by_id("1234")
+    assert result is not None
+    assert isinstance(result, Board)
+    assert mock_requests.get.call_count == 0
+
+
+@mock.patch("friendlypins.utils.rest_io.requests")
+def test_get_pin_by_id(mock_requests):
+    mock_response = mock.MagicMock()
+    mock_requests.get.return_value = mock_response
+
+    obj = API("abcd1234")
+    result = obj.get_pin_by_id("1234")
+    assert result is not None
+    assert isinstance(result, Pin)
+    assert mock_requests.get.call_count == 0
+
+
 @mock.patch("friendlypins.utils.rest_io.requests")
 def test_transaction_limit(mock_requests):
     mock_response = mock.MagicMock()