0
# The Passive Investor
1
2
A comprehensive Python library for ETF (Exchange-Traded Fund) analysis and reporting. Enables passive investors to collect, analyze, and compare ETF data to make informed investment decisions with automated Excel report generation.
3
4
## Package Information
5
6
- **Package Name**: thepassiveinvestor
7
- **Version**: 1.2.2
8
- **Language**: Python
9
- **Installation**: `pip install thepassiveinvestor`
10
- **Requirements**: Python >=3.10, <3.13
11
12
## Core Imports
13
14
```python
15
import thepassiveinvestor as pi
16
```
17
18
Individual imports:
19
20
```python
21
from thepassiveinvestor import collect_data, create_ETF_report
22
```
23
24
## Basic Usage
25
26
```python
27
import thepassiveinvestor as pi
28
29
# Collect data from a single ETF
30
vanguard_sp500 = pi.collect_data('VOO')
31
print(vanguard_sp500['long_name']) # "Vanguard 500 Index Fund"
32
33
# Create an Excel report for multiple ETFs
34
pi.create_ETF_report(['VOO', 'QQQ', 'ARKG'], 'my_etf_analysis.xlsx')
35
36
# Compare multiple ETFs in a DataFrame
37
comparison_df = pi.collect_data(['VOO', 'QQQ', 'VTI'], comparison=True)
38
print(comparison_df.head())
39
```
40
41
## Capabilities
42
43
### ETF Data Collection
44
45
Collects comprehensive ETF data from Yahoo Finance including sector holdings, company holdings, annual returns, risk statistics, and key characteristics.
46
47
```python { .api }
48
def collect_data(tickers, comparison=False, surpress_print=False):
49
"""
50
Collect comprehensive ETF data from Yahoo Finance.
51
52
Parameters:
53
- tickers (str or list): Single ticker string or list of ETF ticker symbols (e.g., 'VOO' or ['VOO', 'QQQ'])
54
- comparison (bool, default False): If True, returns a comparison DataFrame instead of dictionary
55
- surpress_print (bool, default False): If True, suppresses error messages for failed tickers
56
57
Returns:
58
- dict: Single ETF data dictionary (when single ticker and comparison=False)
59
- dict: Dictionary of ticker->data mappings (when multiple tickers and comparison=False)
60
- pandas.DataFrame: Multi-index comparison DataFrame (when comparison=True)
61
62
Collected Data Fields:
63
- long_name: ETF full name
64
- summary: Fund description and strategy
65
- image_URL: Style box image URL
66
- sector_holdings: Sector allocation percentages
67
- company_holdings: Top company holdings with percentages
68
- annual_returns: Historical annual returns (last 6 years)
69
- risk_data: Risk metrics by time period (3y, 5y, 10y)
70
- key_characteristics: Fund inception date, category, total assets, NAV, currency, previous close
71
"""
72
```
73
74
### Excel Report Generation
75
76
Creates comprehensive Excel reports with multiple sheets containing ETF data, formatted tables, charts, and images.
77
78
```python { .api }
79
def create_ETF_report(tickers, filename, folder=None):
80
"""
81
Generate comprehensive Excel report with ETF analysis data.
82
83
Parameters:
84
- tickers (str or list): Single ticker string or list of ETF ticker symbols
85
- filename (str): Output filename (automatically appends .xlsx if missing)
86
- folder (str, optional): Directory path for output file
87
88
Returns:
89
- None: Creates Excel file at specified location
90
91
Report Features:
92
- Individual sheet per ETF with formatted data tables
93
- Stock price history chart for each ETF
94
- Sector holdings with percentage formatting
95
- Top company holdings tables
96
- Risk statistics comparison (3y, 5y, 10y)
97
- Annual returns history
98
- ETF style box images
99
- Hidden stock data sheet for chart generation
100
"""
101
```
102
103
### Configuration Constants
104
105
Predefined configuration constants for customizing data collection and display formatting.
106
107
```python { .api }
108
DEFAULT_KEY_STATISTICS_CHOICES: dict
109
# Maps Yahoo Finance key statistics field names to display names
110
# Fields: fundInceptionDate -> "Fund Inception Date", category -> "Category", totalAssets -> "Total Assets"
111
112
DEFAULT_SUMMARY_DETAIL_CHOICES: dict
113
# Maps Yahoo Finance summary detail field names to display names
114
# Fields: currency -> "Currency", navPrice -> "Net Asset Value", previousClose -> "Previous Close"
115
116
EMPTY_RISK_STATISTICS: dict
117
# Default risk statistics template used when historical data unavailable
118
# Fields: Years, Alpha, Beta, Mean Annual Return, R-squared, Standard Deviation, Sharpe Ratio, Treynor Ratio
119
```
120
121
### Utility Functions
122
123
Internal utility functions for Excel manipulation and formatting (exported but primarily for internal use).
124
125
```python { .api }
126
def data_placer(data, sheet, starting_row, column, column_key, column_value,
127
horizontal_alignment_key=False, horizontal_alignment_value=False,
128
change_key_dimensions=True, change_value_dimensions=True,
129
key_number=None, value_percentage=None):
130
"""
131
Place dictionary data in Excel sheet with formatting options.
132
133
Parameters:
134
- data (dict): Data to place in sheet
135
- sheet (openpyxl.Worksheet): Target Excel worksheet
136
- starting_row (int): First row for data placement
137
- column (int): Column number for key placement
138
- column_key (str): Column letter for keys (e.g., 'B')
139
- column_value (str): Column letter for values (e.g., 'C')
140
- horizontal_alignment_key (str or False): Horizontal alignment for keys
141
- horizontal_alignment_value (str or False): Horizontal alignment for values
142
- change_key_dimensions (bool): Auto-adjust key column width
143
- change_value_dimensions (bool): Auto-adjust value column width
144
- key_number (bool or None): Convert keys to numbers if possible
145
- value_percentage (bool or None): Format values as percentages
146
"""
147
148
def image_placer(image_url, sheet, location):
149
"""
150
Download and place image in Excel sheet.
151
152
Parameters:
153
- image_url (str): URL of image to download
154
- sheet (openpyxl.Worksheet): Target Excel worksheet
155
- location (str): Cell location for image (e.g., 'L12')
156
"""
157
158
def graph_placer(stock_sheet, stock_data, sheet, min_col, min_row, max_col, location):
159
"""
160
Create and place stock price line chart in Excel sheet.
161
162
Parameters:
163
- stock_sheet (openpyxl.Worksheet): Sheet containing stock data
164
- stock_data (pandas.DataFrame): Stock price data
165
- sheet (openpyxl.Worksheet): Target sheet for chart
166
- min_col (int): Minimum column for data range
167
- min_row (int): Minimum row for data range
168
- max_col (int): Maximum column for data range
169
- location (str): Cell location for chart placement
170
"""
171
```
172
173
## Data Structures
174
175
### ETF Data Dictionary
176
177
The `collect_data()` function returns a dictionary with the following structure:
178
179
```python { .api }
180
# ETF Data Dictionary Structure
181
{
182
'long_name': str, # ETF full name (e.g., "Vanguard 500 Index Fund")
183
'summary': str, # Fund description and investment strategy
184
'image_URL': str, # URL to ETF style box image
185
'sector_holdings': { # Sector allocation percentages
186
'technology': '23.65%',
187
'healthcare': '15.27%',
188
'financial_services': '13.7%',
189
# ... other sectors
190
},
191
'company_holdings': { # Top company holdings with percentages
192
'Apple Inc': '5.92%',
193
'Microsoft Corp': '5.62%',
194
# ... other holdings
195
},
196
'annual_returns': { # Historical annual returns (last 6 years)
197
'2022': '-18.15%',
198
'2021': '28.66%',
199
# ... other years
200
},
201
'risk_data': { # Risk metrics by time period
202
'3y': {
203
'year': '3y',
204
'alpha': -0.04,
205
'beta': 1.0,
206
'meanAnnualReturn': 0.8,
207
'rSquared': 100,
208
'stdDev': 21.17,
209
'sharpeRatio': -0.55,
210
'treynorRatio': 6.76
211
},
212
'5y': { /* similar structure */ },
213
'10y': { /* similar structure */ }
214
},
215
'key_characteristics': { # Fund characteristics and current data
216
'fundInceptionDate': datetime.date(2010, 9, 7),
217
'category': 'Large Blend',
218
'totalAssets': 744769716224,
219
'currency': 'USD',
220
'navPrice': 366.24,
221
'previousClose': 365.67
222
}
223
}
224
```
225
226
### Comparison DataFrame Structure
227
228
When `comparison=True`, returns a pandas DataFrame with:
229
230
```python { .api }
231
# MultiIndex DataFrame structure
232
# Index: (category, field) tuples like ('sector_holdings', 'technology')
233
# Columns: ETF ticker symbols
234
# Values: Corresponding data values (percentages, numbers, dates)
235
236
# Example rows:
237
# ('sector_holdings', 'technology') | VOO: '23.65%' | QQQ: '47.62%'
238
# ('annual_returns', '2022') | VOO: '-18.15%'| QQQ: '-32.49%'
239
# ('key_characteristics', 'category') | VOO: 'Large Blend' | QQQ: 'Large Growth'
240
```
241
242
## Error Handling
243
244
The library implements graceful error handling for common issues:
245
246
- **Invalid tickers**: Failed tickers are skipped with optional warning messages
247
- **Missing data**: Uses default values and empty structures when specific data unavailable
248
- **Network issues**: Handles Yahoo Finance API failures gracefully
249
- **Image download failures**: Falls back to text placeholder when style box images unavailable
250
- **Excel generation errors**: Continues processing other ETFs when individual ticker fails
251
252
Use `surpress_print=True` in `collect_data()` to disable error messages for production use.
253
254
## Dependencies
255
256
Core dependencies automatically installed:
257
258
- **pandas** (with excel, computation, performance extras): Data manipulation and analysis
259
- **yahooquery**: Yahoo Finance data access
260
- **urllib3**: HTTP client for image downloads
261
- **openpyxl** (via pandas): Excel file generation and manipulation