Ticket #6334: sage-6334.patch

File sage-6334.patch, 15.4 KB (added by cswiercz, 12 years ago)
  • sage/finance/stock.py

    # HG changeset patch
    # User Chris Swierczewski <cswiercz@gmail.com>
    # Date 1245190561 25200
    # Node ID 076428507bd6a10fa87abb6da2496e1426a7eecd
    # Parent  bca08329c6af361c9a9585ba97b8946339492377
    Fixes bug in Stock.google(). Also updates documentation for Sphinx formatting.
    
    diff -r bca08329c6af -r 076428507bd6 sage/finance/stock.py
    a b  
    44AUTHORS:
    55    -- William Stein, 2008
    66    -- Brett Nakayama, 2008
    7     -- Chris Swierczewski, 2008
     7    -- Chris Swierczewski, 2008, 2009
    88
    99TESTS:
    1010    sage: ohlc = sage.finance.stock.OHLC('18-Aug-04', 100.01, 104.06, 95.96, 100.34, 22353092)
     
    2323        a timestamp for that data along with the volume.
    2424
    2525        INPUT:
    26             timestamp -- string
    27             open, high, low, close -- float
    28             volume -- int
    2926
    30         EXAMPLES:
     27
     28        - ``timestamp`` - string
     29
     30        - ``open, high, low, close`` - float
     31
     32        - ``volume`` - int
     33
     34
     35        EXAMPLES::
     36
    3137            sage: sage.finance.stock.OHLC('18-Aug-04', 100.01, 104.06, 95.96, 100.34, 22353092)
    3238             18-Aug-04 100.01 104.06 95.96 100.34   22353092
    3339        """
     
    3945        """
    4046        Return string representation of stock OHLC data.
    4147
    42         EXAMPLES:
     48        EXAMPLES::
     49
    4350            sage: sage.finance.stock.OHLC('18-Aug-04', 100.01, 104.06, 95.96, 100.34, 22353092).__repr__()
    4451            ' 18-Aug-04 100.01 104.06 95.96 100.34   22353092'
    4552        """
     
    5057        """
    5158        Compare self and other.
    5259
    53         EXAMPLES:
     60        EXAMPLES::
     61
    5462            sage: ohlc = sage.finance.stock.OHLC('18-Aug-04', 100.01, 104.06, 95.96, 100.34, 22353092)
    5563            sage: ohlc2 = sage.finance.stock.OHLC('18-Aug-04', 101.01, 104.06, 95.96, 100.34, 22353092)
    5664            sage: cmp(ohlc, ohlc2)
     
    7179        for each equity used by Google Finance.
    7280
    7381        INPUT:
    74             symbol -- string, a ticker symbol (with or without market)
    75                       format: "MARKET:SYMBOL" or "SYMBOL", if you don't
    76                               supply the market, it is assumed to be
    77                               NYSE or NASDAQ.
    78                       eg. "goog" or "OTC:NTDOY"
    79             cid    -- Integer, a Google contract ID (optional)
     82
     83        - ``symbol`` - string, a ticker symbol (with or without market)
     84                       format: "MARKET:SYMBOL" or "SYMBOL", if you don't
     85                               supply the market, it is assumed to be
     86                               NYSE or NASDAQ.
     87                       eg. "goog" or "OTC:NTDOY"
     88
     89        - ``cid`` - Integer, a Google contract ID (optional)
     90
    8091
    8192        LIMITATIONS:
    82             Currently, the symbol and cid do not have to match.  When using
    83             google(), the cid will take precedence.
    8493
    85         EXAMPLES:
     94        Currently, the symbol and cid do not have to match.  When using
     95        google(), the cid will take precedence.
     96
     97        EXAMPLES::
     98
    8699            sage: S = finance.Stock('ibm')
    87100            sage: S        # random; optional -- internet
    88101            IBM (127.48)           
     
    94107        """
    95108        Return string representation of this stock.
    96109
    97         EXAMPLES:
     110        EXAMPLES::
     111
    98112            sage: finance.Stock('ibm').__repr__()     # random; optional -- internet
    99113            'IBM (127.47)'
    100114        """
     
    105119        Return the current market value of this stock.
    106120
    107121        OUTPUT:
    108             Python float
    109122
    110         EXAMPLES:
     123
     124        - market value - float
     125
     126
     127        EXAMPLES::
     128
    111129            sage: finance.Stock('goog').market_value()   # random; optional - internet
    112130            575.83000000000004
    113131        """
     
    118136        Get Yahoo current price data for this stock.
    119137
    120138        OUTPUT:
    121             dict
    122139
    123         EXAMPLES:
     140
     141        - current price data, dict
     142
     143
     144        EXAMPLES::
     145
    124146            sage: finance.Stock('GOOG').yahoo()          # random; optional -- internet
    125147            {'stock_exchange': '"NasdaqNM"', 'market_cap': '181.1B', '200day_moving_avg': '564.569', '52_week_high': '747.24', 'price_earnings_growth_ratio': '1.04', 'price_sales_ratio': '10.16', 'price': '576.48', 'earnings_per_share': '14.463', '50day_moving_avg': '549.293', 'avg_daily_volume': '6292480', 'volume': '1613507', '52_week_low': '412.11', 'short_ratio': '1.00', 'price_earnings_ratio': '40.50', 'dividend_yield': 'N/A', 'dividend_per_share': '0.00', 'price_book_ratio': '7.55', 'ebitda': '6.513B', 'change': '-9.32', 'book_value': '77.576'}
    126148        """
     
    160182        'Mon' is a three character abbreviation of the month's name.
    161183
    162184        NOTE:
    163             Google Finance returns the past year's financial data by default
    164             when startdate is set too low from the equity's date of going
    165             public.  By default, this function only looks at the NASDAQ and
    166             NYSE markets.  However, if you sepcified the market during
    167             initialization of the stock (i.e. "finance.Stock("OTC:NTDOY")"),
    168             Stock.google() will give correct results.
     185
     186        Google Finance returns the past year's financial data by default
     187        when startdate is set too low from the equity's date of going
     188        public.  By default, this function only looks at the NASDAQ and
     189        NYSE markets.  However, if you sepcified the market during
     190        initialization of the stock (i.e. "finance.Stock("OTC:NTDOY")"),
     191        Stock.google() will give correct results.
    169192
    170193        INPUT:
    171             startdate -- string, (default: 'Jan+1,+1900')
    172             enddate   -- string, (default: current date )
    173             histperiod -- string, ('daily' or 'weekly')
     194
     195           
     196        - ``startdate`` - string, (default: 'Jan+1,+1900')
     197
     198        - ``enddate`` - string, (default: current date )
     199
     200        - ``histperiod`` - string, ('daily' or 'weekly')
     201
    174202
    175203        OUTPUT:
    176             Sequence
     204
     205
     206        - financial data - sequence.Sequence
     207
    177208
    178209        EXAMPLES:
    179         We get the first five days of VMware's stock history:
    180             sage: finance.Stock('vmw').google()[:5]   # optional -- internet
     210
     211        By default, ``Stock.google()`` will retrieve the past year's financial
     212        data. This example was done on 16 June, 2009. You can see that it
     213        matches with an explicit query::
     214
     215            sage: finance.Stock('vmw').google()[:5]   # random
    181216            [
    182              28-Nov-07 80.57 88.49 80.57 87.69    7496000,
    183              29-Nov-07 90.91 93.20 89.50 90.85    5497600,
    184              30-Nov-07 95.39 95.60 89.85 91.37    4750200,
    185               3-Dec-07 89.87 96.00 88.70 94.97    4401100,
    186               4-Dec-07 92.26 97.10 92.05 95.08    2896600
     217             16-Jun-08 66.00 67.50 65.60 67.47    1742000,
     218             17-Jun-08 67.84 67.84 66.03 67.00    1196900,
     219             18-Jun-08 66.50 66.56 64.76 66.19    1186400,
     220             19-Jun-08 65.92 66.50 64.69 65.72     549200,
     221             20-Jun-08 65.72 65.72 63.12 63.86    1242300
    187222            ]
     223
     224            sage: finance.Stock('vmw').google(startdate='Jun+16,+2008')[:5]  # optional - internet
     225            [
     226             16-Jun-08 66.00 67.50 65.60 67.47    1742000,
     227             17-Jun-08 67.84 67.84 66.03 67.00    1196900,
     228             18-Jun-08 66.50 66.56 64.76 66.19    1186400,
     229             19-Jun-08 65.92 66.50 64.69 65.72     549200,
     230             20-Jun-08 65.72 65.72 63.12 63.86    1242300
     231            ]
     232
     233        Here is another example with explicit start and end dates::
    188234           
    189235            sage: finance.Stock('F').google('Jan+3,+1978', 'Jul+7,+2008')[:5] # optional -- internet
    190236            [
     
    198244        Note that when startdate is too far prior to a stock's actual start
    199245        date, Google Finance defaults to a year's worth of stock history
    200246        leading up to the specified enddate.  For example, Apple's (AAPL) stock
    201         history only dates back to September 7, 1984
     247        history only dates back to September 7, 1984::
    202248           
    203249            sage: finance.Stock('AAPL').google('Sep+1,+1900', 'Jan+1,+2000')[0:5] # optional -- internet
    204250            [
     
    210256            ]
    211257           
    212258        Here is an example where we create and get the history of a stock
    213         that is not in NASDAQ or NYSE
     259        that is not in NASDAQ or NYSE::
    214260               
    215261            sage: finance.Stock("OTC:NTDOY").google(startdate="Jan+1,+2007", enddate="Jan+1,+2008")[:5]  # optional -- internet
    216262            [
     
    220266              8-Jan-07 30.10 30.50 30.00 30.10     130765,
    221267              9-Jan-07 29.90 30.05 29.60 29.90     103338
    222268            ]
    223 
    224269       
    225270        Here, we create a stock by cid, and get historical data.
    226271        Note that when using historical, if a cid is specified,
    227272        it will take precedence over the stock's symbol.  So, if
    228273        the symbol and cid do not match, the history based on the
    229         contract id will be returned.
     274        contract id will be returned.::
    230275       
    231             sage: sage.finance.stock.Stock("AAPL", 22144).google(startdate='Jan+1,+1990')[:5] #optional -- internet
     276            sage: sage.finance.stock.Stock("AAPL", 22144).google(startdate='Jan+1,+1990')[:5] # optional -- internet
    232277            [
    233278              2-Jan-90 0.00 9.38 8.75 9.31    6542800,
    234279              3-Jan-90 0.00 9.50 9.38 9.38    7428400,
     
    262307        data. Otherwise, data will be gotten from Google Finance.
    263308
    264309        INPUT:
    265             startdate  -- string, (default: 'Jan+1,+1900')
    266             enddate    -- string, (default: current date)
    267             histperiod -- string, ('daily' or 'weekly')
     310
     311
     312        - ``startdate`` - string, (default: 'Jan+1,+1900')
     313
     314        - ``enddate`` - string, (default: current date)
     315
     316        - ``histperiod`` - string, ('daily' or 'weekly')
     317
    268318
    269319        OUTPUT:
    270             TimeSeries -- Close price data
     320
     321
     322        - TimeSeries - Close price data
     323
    271324
    272325        EXAMPLES:
    273         You can directly obtain Open data as so:
     326        You can directly obtain Open data as so::
     327
    274328            sage: finance.Stock('vmw').open(startdate='Jan+1,+2008', enddate='Feb+1,+2008')                 # optional -- internet
    275329            [83.0500, 85.4900, 84.9000, 82.0000, 81.2500 ... 82.0000, 58.2700, 54.4900, 55.6000, 56.9800]
    276330
    277331        Or, you can initialize stock data first and then extract the Open
    278         data:
     332        data::
     333
    279334            sage: c = finance.Stock('vmw')
    280335            sage: c.google(startdate='Feb+1,+2008', enddate='Mar+1,+2008')[:5]    # optional -- internet
    281336            [
     
    288343            sage: c.open()    # optional -- internet
    289344            [55.6000, 56.9800, 58.0000, 57.6000, 60.3200 ... 56.5500, 59.3000, 60.0000, 59.7900, 59.2600]
    290345
    291         Otherwise, \code{self.google()} will be called with the default
    292         arguements returning a year's worth of data:
     346        Otherwise, ``self.google()`` will be called with the default
     347        arguements returning a year's worth of data::
     348
    293349            sage: finance.Stock('vmw').open()   # random; optional -- internet
    294350            [52.1100, 60.9900, 59.0000, 56.0500, 57.2500 ... 83.0500, 85.4900, 84.9000, 82.0000, 81.2500]
    295351
     
    314370        Otherwise, data will be gotten from Google Finance.
    315371
    316372        INPUT:
    317             startdate  -- string, (default: 'Jan+1,+1900')
    318             enddate    -- string, (default: current date)
    319             histperiod -- string, ('daily' or 'weekly')
     373
     374
     375        - ``startdate`` - string, (default: 'Jan+1,+1900')
     376
     377        - ``enddate`` - string, (default: current date)
     378
     379        - ``histperiod`` - string, ('daily' or 'weekly')
     380
    320381
    321382        OUTPUT:
    322             TimeSeries -- Close price data
     383
     384
     385        - TimeSeries - Close price data
    323386
    324387        EXAMPLES:
    325         You can directly obtain close data as so:
     388        You can directly obtain close data as so::
     389
    326390            sage: finance.Stock('vmw').close(startdate='Jan+1,+2008', enddate='Feb+1,+2008')                 # optional -- internet
    327391            [84.9900, 84.6000, 83.9500, 80.4900, 72.9900 ... 83.0000, 54.8700, 56.4200, 56.6700, 57.8500]
    328392
    329393        Or, you can initialize stock data first and then extract the Close
    330         data:
     394        data::
     395
    331396            sage: c = finance.Stock('vmw')
    332397            sage: c.google(startdate='Feb+1,+2008', enddate='Mar+1,+2008')[:5]    # optional -- internet
    333398            [
     
    340405            sage: c.close()    # optional -- internet
    341406            [56.6700, 57.8500, 58.0500, 59.3000, 61.5200 ... 58.2900, 60.1800, 59.8600, 59.9500, 58.6700]
    342407
     408        Otherwise, ``self.google()`` will be called with the default
     409        arguements returning a year's worh of data::
    343410
    344 
    345         Otherwise, \code{self.google()} will be called with the default
    346         arguements returning a year's worh of data:
    347411            sage: finance.Stock('vmw').close()   # random; optional -- internet
    348412            [57.7100, 56.9900, 55.5500, 57.3300, 65.9900 ... 84.9900, 84.6000, 83.9500, 80.4900, 72.9900]
    349413        """
     
    370434        Timestamp,Open,High,Low,Close,Volume
    371435
    372436        INPUT:
    373             file -- local file with Google Finance formatted OHLC data
     437
     438
     439        - ``file`` - local file with Google Finance formatted OHLC data
     440
    374441
    375442        OUTPUTS:
    376             Sequence -- OHLC data
     443
     444
     445        - Sequence -- OHLC data
     446n
    377447
    378448        EXAMPLES:
    379449        Suppose you have a file in your home directoy containing Apple stock
    380450        OHLC data, such as that from Google Finance, called AAPL-minutely.csv.
    381451        One can load this information into a Stock object like so. Note that
    382         the path must be explicit:
     452        the path must be explicit::
     453
    383454            sage: finance.Stock('aapl').load_from_file(SAGE_ROOT + '/examples/finance/AAPL-minutely.csv')[:5]
    384455            [
    385456            1212408060 188.00 188.00 188.00 188.00        687,
     
    394465        equity the information comes from, the symbol designated at
    395466        initialization of Stock need not match the source of the data. For
    396467        example, we can initialize a Stock object with the symbol 'goog',
    397         but load data from 'aapl' stock prices:
     468        but load data from 'aapl' stock prices::
     469
    398470            sage: finance.Stock('goog').load_from_file(SAGE_ROOT + '/examples/finance/AAPL-minutely.csv')[:5]
    399471            [
    400472            1212408060 188.00 188.00 188.00 188.00        687,
     
    404476            1212405780 187.80 187.80 187.80 187.80        100
    405477            ]
    406478
    407         This tests a file that doesn't exist:
     479        This tests a file that doesn't exist::
     480
    408481            sage: finance.Stock("AAPL").load_from_file("I am not a file")
    409482            Bad path or file name
    410483
     
    420493       
    421494    def _load_from_csv(self, R):
    422495        """
     496        Helper method that loads financial data from a CSV file.
     497
    423498        EXAMPLES:
    424         This indirectly tests _load_from_csv():
     499        This indirectly tests _load_from_csv()::
     500
    425501            sage: finance.Stock('aapl').load_from_file(SAGE_ROOT + "/examples/finance/AAPL-minutely.csv")
    426502            [
    427503            1212408060 188.00 188.00 188.00 188.00        687,
     
    451527        This function is used internally.
    452528
    453529        EXAMPLES:
    454         This indirectly tests the use of get_data.
     530        This indirectly tests the use of get_data::
     531
    455532            sage: finance.Stock('aapl').google(startdate='Jan+1,+1990')[:2]    # optional -- internet
    456533            [
    457534              2-Jan-90 0.00 9.38 8.75 9.31    6542800,