ENH: Add future_symbol API method

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.
         """

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.