towards testing README.md

Author: tschm

README.md

@@ -94,25 +94,31 @@ demonstrating how easy it is to find the long-only portfolio
 that maximises the Sharpe ratio (a measure of risk-adjusted returns).
 
 ```python
-import pandas as pd
-from pypfopt import EfficientFrontier
-from pypfopt import risk_models
-from pypfopt import expected_returns
+>>> import pandas as pd
+>>> from pypfopt import EfficientFrontier
+>>> from pypfopt import risk_models
+>>> from pypfopt import expected_returns
 
 # Read in price data
-df = pd.read_csv("tests/resources/stock_prices.csv", parse_dates=True, index_col="date")
+>>> df = pd.read_csv("tests/resources/stock_prices.csv", parse_dates=True, index_col="date")
 
 # Calculate expected returns and sample covariance
-mu = expected_returns.mean_historical_return(df)
-S = risk_models.sample_cov(df)
+>>> mu = expected_returns.mean_historical_return(df)
+>>> S = risk_models.sample_cov(df)
 
 # Optimize for maximal Sharpe ratio
-ef = EfficientFrontier(mu, S)
-raw_weights = ef.max_sharpe()
-cleaned_weights = ef.clean_weights()
-ef.save_weights_to_file("weights.csv")  # saves to file
-print(cleaned_weights)
-ef.portfolio_performance(verbose=True)
+>>> ef = EfficientFrontier(mu, S)
+>>> raw_weights = ef.max_sharpe()
+>>> cleaned_weights = ef.clean_weights()
+>>> ef.save_weights_to_file("weights.csv")  # saves to file
+>>> cleaned_weights
+OrderedDict({'GOOG': 0.0458, 'AAPL': 0.06743, 'FB': 0.2008, 'BABA': 0.08494, 'AMZN': 0.03525, 'GE': 0.0, 'AMD': 0.0, 'WMT': 0.0, 'BAC': 0.0, 'GM': 0.0, 'T': 0.0, 'UAA': 0.0, 'SHLD': 0.0, 'XOM': 0.0, 'RRC': 0.0, 'BBY': 0.01587, 'MA': 0.3287, 'PFE': 0.20394, 'JPM': 0.0, 'SBUX': 0.01726})
+>>> ef.portfolio_performance(verbose=True)
+Expected annual return: 29.9%
+Annual volatility: 21.8%
+Sharpe Ratio: 1.38
+(0.29944709161230304, 0.21764331681393406, 1.375861643701672)
+
 ```
 
 This outputs the following weights:
@@ -150,22 +156,17 @@ convert the above continuous weights to an actual allocation
 that you could buy. Just enter the most recent prices, and the desired portfolio size ($10,000 in this example):
 
 ```python
-from pypfopt.discrete_allocation import DiscreteAllocation, get_latest_prices
+>>> from pypfopt.discrete_allocation import DiscreteAllocation, get_latest_prices
 
+>>> latest_prices = get_latest_prices(df)
 
-latest_prices = get_latest_prices(df)
+>>> da = DiscreteAllocation(cleaned_weights, latest_prices, total_portfolio_value=10000)
+>>> allocation, leftover = da.greedy_portfolio()
+>>> print("Discrete allocation:", allocation)
+Discrete allocation: {'MA': 19, 'PFE': 57, 'FB': 12, 'BABA': 4, 'AAPL': 4, 'GOOG': 1, 'SBUX': 2, 'BBY': 2}
+>>> print("Funds remaining: ${:.2f}".format(leftover))
+Funds remaining: $17.46
 
-da = DiscreteAllocation(weights, latest_prices, total_portfolio_value=10000)
-allocation, leftover = da.greedy_portfolio()
-print("Discrete allocation:", allocation)
-print("Funds remaining: ${:.2f}".format(leftover))
-```
-
-```txt
-12 out of 20 tickers were removed
-Discrete allocation: {'GOOG': 1, 'AAPL': 4, 'FB': 12, 'BABA': 4, 'BBY': 2,
-                      'MA': 20, 'PFE': 54, 'SBUX': 1}
-Funds remaining: $11.89
 ```
 
 _Disclaimer: nothing about this project constitues investment advice, 

pypfopt/base_optimizer.py

@@ -571,11 +571,11 @@ def portfolio_performance(
             print("Expected annual return: {:.1f}%".format(100 * mu))
             print("Annual volatility: {:.1f}%".format(100 * sigma))
             print("Sharpe Ratio: {:.2f}".format(sharpe))
-        return mu, sigma, sharpe
+        return float(mu), float(sigma), float(sharpe)
     else:
         if verbose:
             print("Annual volatility: {:.1f}%".format(100 * sigma))
-        return None, sigma, None
+        return None, float(sigma), None
 
 
 def _get_all_args(expression: cp.Expression) -> List[cp.Expression]:

tests/test_doctest.py tests/test_docs.pytests/test_doctest.py renamed to tests/test_docs.py

@@ -1,15 +1,23 @@
-"""Tests for doctest examples in the project documentation.
+"""Tests that README.md Python code blocks execute without errors.
 
-This module contains tests that verify that the code examples in the project's
-documentation (specifically in the README file) can be executed successfully
-using Python's doctest module.
+This test extracts all fenced code blocks labeled as Python from README.md and
+executes them sequentially in a shared namespace. This ensures the examples in
+our documentation stay correct as the code evolves.
 """
 
-import doctest
+import os
+import re
+import textwrap
+import warnings
 from pathlib import Path
 
+import numpy as np
 import pytest
 
+
+import doctest
+
+
 @pytest.fixture()
 def readme_path() -> Path:
     """Provide the path to the project's README.md file.
@@ -38,15 +46,6 @@ def readme_path() -> Path:
 
 
 def test_doc(readme_path):
-    """Test that the README file's code examples work correctly.
-
-    This test runs doctest on the project's README file to verify that all
-    code examples in the file execute correctly and produce the expected output.
-
-    Parameters
-    ----------
-    readme_path : Path
-        Path to the README file to test
-
-    """
-    doctest.testfile(str(readme_path), module_relative=False, verbose=True, optionflags=doctest.ELLIPSIS)
+    """Test the README file with doctest."""
+    result = doctest.testfile(str(readme_path), module_relative=False, verbose=True, optionflags=doctest.ELLIPSIS)
+    assert result.failed == 0