From 3ef0ddf0c6aa972e01d2e1b4f80e0e90b50b3bc5 Mon Sep 17 00:00:00 2001
From: Stewart Douglas <sdouglas@quantopian.com>
Date: Thu, 1 Oct 2015 16:13:02 -0400
Subject: [PATCH] ENH: Add future_symbol API method

---
 tests/test_algorithm.py | 25 +++++++++++++++++++++++++
 zipline/algorithm.py    | 22 ++++++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/tests/test_algorithm.py b/tests/test_algorithm.py
index f9f4b4ba..53a20df9 100644
--- a/tests/test_algorithm.py
+++ b/tests/test_algorithm.py
@@ -425,6 +425,31 @@ class TestMiscellaneousAPI(TestCase):
         self.assertIsInstance(algo.sid(3), Equity)
         self.assertIsInstance(algo.sid(4), Equity)
 
+    def test_future_symbol(self):
+        """ Tests the future_symbol API function.
+        """
+        algo = TradingAlgorithm(env=self.env)
+        algo.datetime = pd.Timestamp('2006-12-01', tz='UTC')
+
+        # Check that we get the correct fields for the CLG06 symbol
+        cl = algo.future_symbol('CLG06')
+        self.assertEqual(cl.sid, 5)
+        self.assertEqual(cl.symbol, 'CLG06')
+        self.assertEqual(cl.root_symbol, 'CL')
+        self.assertEqual(cl.start_date, pd.Timestamp('2005-12-01', tz='UTC'))
+        self.assertEqual(cl.notice_date, pd.Timestamp('2005-12-20', tz='UTC'))
+        self.assertEqual(cl.expiration_date,
+                         pd.Timestamp('2006-01-20', tz='UTC'))
+
+        with self.assertRaises(SymbolNotFound):
+            algo.future_symbol('')
+
+        with self.assertRaises(SymbolNotFound):
+            algo.future_symbol('PLAY')
+
+        with self.assertRaises(SymbolNotFound):
+            algo.future_symbol('FOOBAR')
+
     def test_future_chain(self):
         """ Tests the future_chain API function.
         """
diff --git a/zipline/algorithm.py b/zipline/algorithm.py
index 05fda7ab..5fd87da7 100644
--- a/zipline/algorithm.py
+++ b/zipline/algorithm.py
@@ -769,6 +769,28 @@ class TradingAlgorithm(object):
         """
         return self.asset_finder.retrieve_asset(a_sid)
 
+    @api_method
+    def future_symbol(self, symbol):
+        """ Lookup a futures contract with a given symbol.
+
+        Parameters
+        ----------
+        symbol : str
+            The symbol of the desired contract.
+
+        Returns
+        -------
+        Future
+            A Future object.
+
+        Raises
+        ------
+        SymbolNotFound
+            Raised when no contract named 'symbol' is found.
+
+        """
+        return self.asset_finder.lookup_future_symbol(symbol)
+
     @api_method
     def future_chain(self, root_symbol, as_of_date=None):
         """ Look up a future chain with the specified parameters.