| Name | mstarpy JSON |
| Version |
2.0.2
JSON |
| download |
| home_page | None |
| Summary | Mutual funds and stocks data extraction from MorningStar with Python |
| upload_time | 2024-10-22 22:41:05 |
| maintainer | None |
| docs_url | None |
| author | Maël Jourdain |
| requires_python | >=3.10 |
| license | MIT License |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Introduction
MStarpy is a Python Package to extract data from
[morningstar.com](https://www.morningstar.com/).
MStarpy provides stock and fund public data to retail and professional
investors for **free**. The main goal is to give investors access to the
same information and help them in their investment process.
The project is **open-source** and anyone can contribute on
[GitHub](https://github.com/Mael-J/mstarpy).
[](https://github.com/Mael-J/mstarpy./releases)
# Getting Started
## Installation
You can install it **via pip** on the terminal by typing:
``` bash
pip install mstarpy
```
You can also install it **via git** on the terminal bu using :
``` bash
pip install git+https://github.com/Mael-J/mstarpy.git@master
```
## First commands
### Look for funds with [search_funds]{.title-ref}
You can look for funds by using the method [search_funds]{.title-ref}.
In the following example, we will look for 40 funds in the US market
with the term \"technology\" in their name. We want to get the name, the
ID and the 12 months return. We transform the result in a pandas
DataFrame to make it more clear.
``` python
import mstarpy
import pandas as pd
response = mstarpy.search_funds(term="technology", field=["Name", "fundShareClassId", "GBRReturnM12"], country="us", pageSize=40, currency ="USD")
df = pd.DataFrame(response)
print(df.head())
```
``` python
Name fundShareClassId GBRReturnM12
0 Baron Technology Instituitional F00001CUJ3 -21.64
1 Baron Technology R6 F00001CUJ1 -21.88
2 Baron Technology Retail F00001CUJ2 -21.91
3 Black Oak Emerging Technology FOUSA00LIX -8.33
4 BlackRock Technology Opportunities K F000014AX6 -21.09
```
### Look for fields with [search_field]{.title-ref}
You can find the field you need for the [search_funds]{.title-ref} and
[search_stock]{.title-ref} methods using [search_field]{.title-ref}. In
the following example, we get all fields.
``` python
from mstarpy import search_field
response = search_field(pattern='')
print(response)
```
``` python
['AdministratorCompanyId', 'AlphaM36', 'AnalystRatingScale', 'AverageCreditQualityCode', 'AverageMarketCapital', 'BetaM36', 'BondStyleBox', 'brandingCompanyId', 'categoryId', 'CategoryName', 'ClosePrice', 'currency', 'DebtEquityRatio', 'distribution', 'DividendYield', 'EBTMarginYear1', 'EffectiveDuration', 'EPSGrowth3YYear1', 'equityStyle', 'EquityStyleBox', 'exchangeCode', 'ExchangeId', 'ExpertiseAdvanced', 'ExpertiseBasic', 'ExpertiseInformed', 'FeeLevel', 'fundShareClassId', 'fundSize', 'fundStyle', 'FundTNAV', 'GBRReturnD1', 'GBRReturnM0', 'GBRReturnM1', 'GBRReturnM12', 'GBRReturnM120', 'GBRReturnM3', 'GBRReturnM36', 'GBRReturnM6', 'GBRReturnM60', 'GBRReturnW1', 'geoRegion', 'globalAssetClassId', 'globalCategoryId', 'iMASectorId', 'IndustryName', 'InitialPurchase', 'instrumentName', 'investment', 'investmentExpertise', 'investmentObjective', 'investmentType', 'investorType', 'InvestorTypeEligibleCounterparty', 'InvestorTypeProfessional', 'InvestorTypeRetail', 'LargestSector', 'LegalName', 'managementStyle', 'ManagerTenure', 'MarketCap', 'MarketCountryName', 'MaxDeferredLoad', 'MaxFrontEndLoad', 'MaximumExitCostAcquired', 'MorningstarRiskM255', 'Name', 'NetMargin', 'ongoingCharge', 'OngoingCostActual', 'PEGRatio', 'PERatio', 'PerformanceFeeActual', 'PriceCurrency', 'QuantitativeRating', 'R2M36', 'ReturnD1', 'ReturnM0', 'ReturnM1', 'ReturnM12', 'ReturnM120', 'ReturnM3', 'ReturnM36', 'ReturnM6', 'ReturnM60', 'ReturnProfileGrowth', 'ReturnProfileHedging', 'ReturnProfileIncome', 'ReturnProfileOther', 'ReturnProfilePreservation', 'ReturnW1', 'RevenueGrowth3Y', 'riskSrri', 'ROATTM', 'ROETTM', 'ROEYear1', 'ROICYear1', 'SecId', 'SectorName', 'shareClassType', 'SharpeM36', 'StandardDeviationM36', 'starRating', 'StarRatingM255', 'SustainabilityRank', 'sustainabilityRating', 'TenforeId', 'Ticker', 'totalReturn', 'totalReturnTimeFrame', 'TrackRecordExtension', 'TransactionFeeActual', 'umbrellaCompanyId', 'Universe', 'Yield_M12', 'yieldPercent']
```
### Analysis of funds
Once, you know what fund you want to analyse, you can load it with the
class [Funds]{.title-ref} and then access all the methods to get data.
``` python
import mstarpy
fund = mstarpy.Funds(term="FOUSA00LIX", country="us")
```
You can access to his property name.
``` python
print(fund.name)
```
``` python
'Black Oak Emerging Technology Fund'
```
You can show the equity holdings of the fund.
``` python
df_equity_holdings = fund.holdings(holdingType="equity")
print(df_equity_holdings[["securityName", "weighting", "susEsgRiskScore"]].head())
```
``` python
securityName weighting susEsgRiskScore
0 Apple Inc 5.03336 16.6849
1 KLA Corp 4.90005 16.6870
2 Kulicke & Soffa Industries Inc 4.23065 17.2155
3 SolarEdge Technologies Inc 4.13637 24.6126
4 Ambarella Inc 4.10950 33.1408
```
You can find the historical Nav and total return of the fund.
``` python
import datetime
import pandas as pd
start_date = datetime.datetime(2023,1,1)
end_date = datetime.datetime(2023,3,2)
#get historical data
history = fund.nav(start_date=start_date,end_date=end_date, frequency="daily")
#convert it in pandas DataFrame
df_history = pd.DataFrame(history)
print(df_history.head())
```
``` python
nav totalReturn date
0 6.28 10.21504 2022-12-30
1 6.23 10.13371 2023-01-03
2 6.31 10.26383 2023-01-04
3 6.18 10.05238 2023-01-05
4 6.37 10.36143 2023-01-06
```
### Look for stock with [search_stock]{.title-ref}
You can look for stocks by using the method [search_stock]{.title-ref}.
In the following example, we will look for 20 stocks on the Paris Stock
Exchange with the term \"AB\" in their name. We want to get the name,
the ID and the Sector. We transform the result in a pandas DataFrame to
make it more clear.
``` python
import mstarpy
import pandas as pd
response = mstarpy.search_stock(term="AB",field=["Name", "fundShareClassId", "SectorName"], exchange='XPAR',pageSize=20)
df = pd.DataFrame(response)
print(df.head())
```
``` python
Name fundShareClassId SectorName
0 AB Science 0P0000NQNE Healthcare
1 ABC arbitrage SA 0P00009W9I Financial Services
2 Abeo SA 0P00018PIU Consumer Cyclical
3 Abionyx Pharma Ordinary Shares 0P00015JGM Healthcare
4 Abivax SA 0P00016673 Healthcare
```
Tips : You can get different exchange by looking at the variable
EXCHANGE in mstarpy.utils
``` python
from mstarpy.utils import EXCHANGE
print(list(EXCHANGE))
```
``` python
['ARCX', 'BATS', 'CHIA', 'E0WWE$$ALL', 'FINR', 'IPSX', 'IXUS', 'MABX', 'MSCO', 'MSTARFund', 'OTCM', 'USCO', 'XAMS', 'XASE', 'XASX', 'XATH', 'XBER', 'XBKK', 'XBOM', 'XBRU', 'XCNQ', 'XCSE', 'XDUB', 'XDUS', 'XETR', 'XEUR', 'XFRA', 'XHAM', 'XHAN', 'XHEL', 'XHKF', 'XHKG', 'XICE', 'XIST', 'XKOS', 'XLIS', 'XLIT', 'XLON', 'XLUX', 'XMEX', 'XMIL', 'XMUN', 'XNAS', 'XNSE', 'XNYS', 'XNZE', 'XOSE', 'XOSL', 'XOTC', 'XPAR', 'XRIS', 'XSES', 'XSHE', 'XSHG', 'XSTO', 'XSTU', 'XSWX', 'XTAI', 'XTAL', 'XTKS', 'XTSE', 'XWAR', 'XWBO']
```
### Analysis of stocks
Once, you know what stock you want to analyse, you can load it with the
class [Stock]{.title-ref} and then access all the methods to get data.
``` python
import mstarpy
stock = stock = mstarpy.Stock(term="0P00018PIU", exchange="PARIS")
```
You can access to his property name.
``` python
print(stock.name)
```
``` python
'Abeo SA'
```
You can find the historical price and volume of the stock.
``` python
import datetime
import pandas as pd
start_date = datetime.datetime(2023,1,1)
end_date = datetime.datetime(2023,3,2)
#get historical data
history = stock.historical(start_date=start_date,end_date=end_date, frequency="daily")
#convert it in pandas DataFrame
df_history = pd.DataFrame(history)
print(df_history.head())
```
``` python
open high low close volume previousClose date
0 18.60 18.60 18.55 18.55 194 18.55 2022-12-30
1 18.70 18.70 18.70 18.70 9 18.55 2023-01-02
2 18.65 18.70 18.55 18.60 275 18.70 2023-01-03
3 18.65 18.65 18.50 18.60 994 18.60 2023-01-04
4 18.65 18.95 18.50 18.60 999 18.60 2023-01-05
```
You can show the financial statements such as the balance sheet.
``` python
bs = stock.balanceSheet(period='annual', reportType='original')
```
## More commands
You can find all the methods of the classes [Funds]{.title-ref} and
[Stocks]{.title-ref} in the part Indices and tables of this
documentation.
# Search with filters
You can use filters to search funds and stocks more precisely with
methods [search_funds]{.title-ref} and [search_stock]{.title-ref}.
## Choose filters
You can find the possible filters with the methods
[search_filter]{.title-ref}
for funds:
``` python
from mstarpy import search_filter
filter_fund = search_filter(pattern = '', asset_type ='fund')
print(filter_fund)
```
``` python
['AdministratorCompanyId', 'AnalystRatingScale', 'BondStyleBox', 'BrandingCompanyId', 'CategoryId', 'CollectedSRRI', 'distribution', 'EquityStyleBox', 'ExpertiseInformed', 'FeeLevel', 'FundTNAV', 'GBRReturnM0', 'GBRReturnM12', 'GBRReturnM120', 'GBRReturnM36', 'GBRReturnM60', 'GlobalAssetClassId', 'GlobalCategoryId', 'IMASectorID', 'IndexFund', 'InvestorTypeProfessional', 'LargestRegion', 'LargestSector', 'OngoingCharge', 'QuantitativeRating', 'ReturnProfilePreservation', 'ShareClassTypeId', 'SustainabilityRank', 'UmbrellaCompanyId', 'Yield_M12']
```
for stocks:
``` python
from mstarpy import search_filter
filter_stock = search_filter(pattern = '', asset_type ='stock')
print(filter_stock)
```
``` python
['debtEquityRatio', 'DividendYield', 'epsGrowth3YYear1', 'EquityStyleBox', 'GBRReturnM0', 'GBRReturnM12', 'GBRReturnM36', 'GBRReturnM60', 'GBRReturnM120', 'IndustryId', 'MarketCap', 'netMargin', 'PBRatio', 'PEGRatio', 'PERatio', 'PSRatio', 'revenueGrowth3Y', 'roattm', 'roettm', 'SectorId']
```
## Find filters values
Once, you know what filters you want you use the method
[filter_universe]{.title-ref} to show the possible values of each
filter.
``` python
from mstarpy import filter_universe
filter_value = filter_universe(["GBRReturnM12", "PERatio", "LargestSector"])
print(filter_value)
```
You have two types of filters values, either qualitative or
quantitative. By example, the filter LargestSector has qualitative
values such as SB_Healthcare or SB_Utilities. The filter PERatio works
with quantitative values between 0 and 100000.
## Filter funds
Let say we want to find funds that invest mainly in the consumer
defensive sector. We can use filters like in this example:
``` python
from mstarpy import search_funds
response = search_funds(term='',field=["Name", "fundShareClassId", "GBRReturnM12"], country='fr', filters = {"LargestSector" : "SB_ConsumerDefensive"})
df = pd.DataFrame(response)
print(df.head())
```
``` python
Name fundShareClassId GBRReturnM12
0 AB US High Yield A2 EUR H F00000O4X9 -9.71
1 AB US High Yield A2 USD F00000O4XA -6.88
2 AB US High Yield I2 EUR H F00000O4X6 -9.18
3 AB US High Yield I2 USD F00000O4XB -6.36
4 abrdn China A Share Sus Eq A Acc EUR F000015MAW -8.41
```
If we want to search for funds which invest mainly in consumer defensive
or healthcare sectors, we can add filters values to a list.
``` python
from mstarpy import search_funds
response = search_funds(term='',field=["Name", "fundShareClassId", "GBRReturnM12"], country='fr', filters = {"LargestSector" : ["SB_ConsumerDefensive", "SB_Healthcare"]})
df = pd.DataFrame(response)
print(df.head())
```
``` python
Name fundShareClassId GBRReturnM12
0 AB Concentrated Global Eq A EUR H F00000SJ2P -10.46
1 AB Concentrated Global Eq I EUR H F00000SJ2J -9.77
2 AB Concentrated Global Eq I USD F00000SE91 -5.77
3 AB Concentrated Global Eq S USD F00000SE93 1.16
4 AB Concentrated Global Eq S1 EUR F00001CYZS -1.89
```
In the previous examples, we saw how to search for securities with a
qualitative filter, now let see how to use quantitativer filters.
## Filter stocks
We want to find stocks with a 12 months return superior to 20%. The
value of filter is a 2 length tuple. the first element is the sign
superior \"\>\", the second element the 12 months return of 20.
``` python
from mstarpy import search_stock
response = search_stock(term='',field=["Name", "fundShareClassId", "GBRReturnM12", "PERatio"], exchange='XPAR', filters={"GBRReturnM12" : (">", 20)})
df = pd.DataFrame(response)
print(df.head())
```
``` python
0 1000Mercis SA 0P0000DKX2 24.89 95.24
1 Abeo SA 0P00018PIU 21.73 14.84
2 ABL Diagnostics 0P00009WGF 279.01 NaN
3 Acteos 0P00009W9O 27.01 NaN
4 Actia group 0P00009W9P 44.36 NaN
```
It will work similar if we are looking for stocks with a PERatio
inferior to 10. The value of filter is a 2 length tuple. the first
element is the sign inferior \"\<\", the second element is the PERatio
10.
``` python
from mstarpy import search_stock
response = search_stock(term='',field=["Name", "fundShareClassId", "GBRReturnM12", "PERatio"], exchange='XPAR', filters={"PERatio" : ("<", 10)})
df = pd.DataFrame(response)
print(df.head())
```
``` python
Name fundShareClassId GBRReturnM12 PERatio
0 Acanthe Developpement SA 0P00009W9K -23.27 5.78
1 ALD SA 0P0001AM22 31.89 5.07
2 Altarea SCA 0P00009WAG -2.20 8.18
3 Altur Investissement SCA 0P0000DKYA 33.38 1.98
4 Archos 0P00009WAT -97.02 0.00
```
We can also look like stocks with a PERatio between 10 and 20. The value
of filter is a 2 length tuple. the first element is the lower bound
PERatio of 10, the second element is the upper bound PERatio of 20.
``` python
from mstarpy import search_stock
response = search_stock(term='',field=["Name", "fundShareClassId", "GBRReturnM12", "PERatio"], exchange='XPAR', filters={"PERatio" : (10, 20)})
df = pd.DataFrame(response)
print(df.head())
```
``` python
Name fundShareClassId GBRReturnM12 PERatio
0 ABC arbitrage SA 0P00009W9I -5.73 14.10
1 Abeo SA 0P00018PIU 21.73 14.84
2 AdUX SA 0P00009WIO -32.05 11.49
3 Altareit SA 0P00009WHA -11.03 12.69
4 Alten 0P00009WAH 14.25 19.96
```
Now we know how to use filters, we can combine them to find a precise
securities universe. The world is your oyster.
``` python
from mstarpy import search_stock
response = search_stock(term='',field=["Name", "fundShareClassId", "GBRReturnM12", "PERatio"],
exchange='XPAR', filters={"PERatio" : ("<", '10'), "GBRReturnM12" : (">", 20),
"debtEquityRatio" : (0, 5), "SectorId" : ["IG000BA008", "IG000BA006"] })
df = pd.DataFrame(response)
print(df.head())
```
``` python
Name fundShareClassId GBRReturnM12 PERatio
0 ALD SA 0P0001AM22 31.89 5.07
1 Coheris 0P00009WDN 72.68 5.27
2 Ediliziacrobatica SpA 0P0001GZM9 24.07 6.85
3 Rexel SA 0P00009WO9 32.27 7.96
4 Soditech SA 0P00009WQ2 97.45 4.49
```
# MStarpy in the world
## Albertine.io
The site [albertine.io](https://albertine.io/#/funds) uses MStarpy to
compare funds. You can create PDF reports and extract data in Excel
format.
## Contribution
The project is **open-source** and you can contribute on
[github](https://github.com/Mael-J/mstarpy).
# Disclaimer
MStarpy is not affiliated to
[morningstar.com](https://www.morningstar.com/) or any other companies.
The package aims to share public information about funds and stocks to
automatize analysis. It is the result of a free, free and independent
work.
MStarpy does not give any investment recommendations.
Raw data
{
"_id": null,
"home_page": null,
"name": "mstarpy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Ma\u00ebl Jourdain",
"author_email": "mael.jourdain@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fc/16/91b93075cf643e910c02296b869e04837e522fed87660e22b2259d3424a8/mstarpy-2.0.2.tar.gz",
"platform": null,
"description": "# Introduction\n\nMStarpy is a Python Package to extract data from\n[morningstar.com](https://www.morningstar.com/).\n\nMStarpy provides stock and fund public data to retail and professional\ninvestors for **free**. The main goal is to give investors access to the\nsame information and help them in their investment process.\n\nThe project is **open-source** and anyone can contribute on\n[GitHub](https://github.com/Mael-J/mstarpy).\n\n[](https://github.com/Mael-J/mstarpy./releases)\n\n# Getting Started\n\n## Installation\n\nYou can install it **via pip** on the terminal by typing:\n\n``` bash\npip install mstarpy\n```\n\nYou can also install it **via git** on the terminal bu using :\n\n``` bash\npip install git+https://github.com/Mael-J/mstarpy.git@master\n```\n\n## First commands\n\n### Look for funds with [search_funds]{.title-ref}\n\nYou can look for funds by using the method [search_funds]{.title-ref}.\nIn the following example, we will look for 40 funds in the US market\nwith the term \\\"technology\\\" in their name. We want to get the name, the\nID and the 12 months return. We transform the result in a pandas\nDataFrame to make it more clear.\n\n``` python\nimport mstarpy\nimport pandas as pd\n\nresponse = mstarpy.search_funds(term=\"technology\", field=[\"Name\", \"fundShareClassId\", \"GBRReturnM12\"], country=\"us\", pageSize=40, currency =\"USD\")\n\ndf = pd.DataFrame(response)\nprint(df.head())\n```\n\n``` python\nName fundShareClassId GBRReturnM12\n0 Baron Technology Instituitional F00001CUJ3 -21.64\n1 Baron Technology R6 F00001CUJ1 -21.88\n2 Baron Technology Retail F00001CUJ2 -21.91\n3 Black Oak Emerging Technology FOUSA00LIX -8.33\n4 BlackRock Technology Opportunities K F000014AX6 -21.09\n```\n\n### Look for fields with [search_field]{.title-ref}\n\nYou can find the field you need for the [search_funds]{.title-ref} and\n[search_stock]{.title-ref} methods using [search_field]{.title-ref}. In\nthe following example, we get all fields.\n\n``` python\nfrom mstarpy import search_field\n\nresponse = search_field(pattern='')\n\nprint(response)\n```\n\n``` python\n['AdministratorCompanyId', 'AlphaM36', 'AnalystRatingScale', 'AverageCreditQualityCode', 'AverageMarketCapital', 'BetaM36', 'BondStyleBox', 'brandingCompanyId', 'categoryId', 'CategoryName', 'ClosePrice', 'currency', 'DebtEquityRatio', 'distribution', 'DividendYield', 'EBTMarginYear1', 'EffectiveDuration', 'EPSGrowth3YYear1', 'equityStyle', 'EquityStyleBox', 'exchangeCode', 'ExchangeId', 'ExpertiseAdvanced', 'ExpertiseBasic', 'ExpertiseInformed', 'FeeLevel', 'fundShareClassId', 'fundSize', 'fundStyle', 'FundTNAV', 'GBRReturnD1', 'GBRReturnM0', 'GBRReturnM1', 'GBRReturnM12', 'GBRReturnM120', 'GBRReturnM3', 'GBRReturnM36', 'GBRReturnM6', 'GBRReturnM60', 'GBRReturnW1', 'geoRegion', 'globalAssetClassId', 'globalCategoryId', 'iMASectorId', 'IndustryName', 'InitialPurchase', 'instrumentName', 'investment', 'investmentExpertise', 'investmentObjective', 'investmentType', 'investorType', 'InvestorTypeEligibleCounterparty', 'InvestorTypeProfessional', 'InvestorTypeRetail', 'LargestSector', 'LegalName', 'managementStyle', 'ManagerTenure', 'MarketCap', 'MarketCountryName', 'MaxDeferredLoad', 'MaxFrontEndLoad', 'MaximumExitCostAcquired', 'MorningstarRiskM255', 'Name', 'NetMargin', 'ongoingCharge', 'OngoingCostActual', 'PEGRatio', 'PERatio', 'PerformanceFeeActual', 'PriceCurrency', 'QuantitativeRating', 'R2M36', 'ReturnD1', 'ReturnM0', 'ReturnM1', 'ReturnM12', 'ReturnM120', 'ReturnM3', 'ReturnM36', 'ReturnM6', 'ReturnM60', 'ReturnProfileGrowth', 'ReturnProfileHedging', 'ReturnProfileIncome', 'ReturnProfileOther', 'ReturnProfilePreservation', 'ReturnW1', 'RevenueGrowth3Y', 'riskSrri', 'ROATTM', 'ROETTM', 'ROEYear1', 'ROICYear1', 'SecId', 'SectorName', 'shareClassType', 'SharpeM36', 'StandardDeviationM36', 'starRating', 'StarRatingM255', 'SustainabilityRank', 'sustainabilityRating', 'TenforeId', 'Ticker', 'totalReturn', 'totalReturnTimeFrame', 'TrackRecordExtension', 'TransactionFeeActual', 'umbrellaCompanyId', 'Universe', 'Yield_M12', 'yieldPercent']\n```\n\n### Analysis of funds\n\nOnce, you know what fund you want to analyse, you can load it with the\nclass [Funds]{.title-ref} and then access all the methods to get data.\n\n``` python\nimport mstarpy\n\nfund = mstarpy.Funds(term=\"FOUSA00LIX\", country=\"us\")\n```\n\nYou can access to his property name.\n\n``` python\nprint(fund.name)\n```\n\n``` python\n'Black Oak Emerging Technology Fund'\n```\n\nYou can show the equity holdings of the fund.\n\n``` python\ndf_equity_holdings = fund.holdings(holdingType=\"equity\")\nprint(df_equity_holdings[[\"securityName\", \"weighting\", \"susEsgRiskScore\"]].head())\n```\n\n``` python\nsecurityName weighting susEsgRiskScore\n0 Apple Inc 5.03336 16.6849\n1 KLA Corp 4.90005 16.6870\n2 Kulicke & Soffa Industries Inc 4.23065 17.2155\n3 SolarEdge Technologies Inc 4.13637 24.6126\n4 Ambarella Inc 4.10950 33.1408\n```\n\nYou can find the historical Nav and total return of the fund.\n\n``` python\nimport datetime\nimport pandas as pd\nstart_date = datetime.datetime(2023,1,1)\nend_date = datetime.datetime(2023,3,2)\n#get historical data\nhistory = fund.nav(start_date=start_date,end_date=end_date, frequency=\"daily\")\n#convert it in pandas DataFrame\ndf_history = pd.DataFrame(history)\n\nprint(df_history.head())\n```\n\n``` python\nnav totalReturn date\n0 6.28 10.21504 2022-12-30\n1 6.23 10.13371 2023-01-03\n2 6.31 10.26383 2023-01-04\n3 6.18 10.05238 2023-01-05\n4 6.37 10.36143 2023-01-06\n```\n\n### Look for stock with [search_stock]{.title-ref}\n\nYou can look for stocks by using the method [search_stock]{.title-ref}.\nIn the following example, we will look for 20 stocks on the Paris Stock\nExchange with the term \\\"AB\\\" in their name. We want to get the name,\nthe ID and the Sector. We transform the result in a pandas DataFrame to\nmake it more clear.\n\n``` python\nimport mstarpy\nimport pandas as pd\n\nresponse = mstarpy.search_stock(term=\"AB\",field=[\"Name\", \"fundShareClassId\", \"SectorName\"], exchange='XPAR',pageSize=20)\n\ndf = pd.DataFrame(response)\nprint(df.head())\n```\n\n``` python\nName fundShareClassId SectorName\n0 AB Science 0P0000NQNE Healthcare\n1 ABC arbitrage SA 0P00009W9I Financial Services\n2 Abeo SA 0P00018PIU Consumer Cyclical\n3 Abionyx Pharma Ordinary Shares 0P00015JGM Healthcare\n4 Abivax SA 0P00016673 Healthcare\n```\n\nTips : You can get different exchange by looking at the variable\nEXCHANGE in mstarpy.utils\n\n``` python\nfrom mstarpy.utils import EXCHANGE\n\nprint(list(EXCHANGE))\n```\n\n``` python\n['ARCX', 'BATS', 'CHIA', 'E0WWE$$ALL', 'FINR', 'IPSX', 'IXUS', 'MABX', 'MSCO', 'MSTARFund', 'OTCM', 'USCO', 'XAMS', 'XASE', 'XASX', 'XATH', 'XBER', 'XBKK', 'XBOM', 'XBRU', 'XCNQ', 'XCSE', 'XDUB', 'XDUS', 'XETR', 'XEUR', 'XFRA', 'XHAM', 'XHAN', 'XHEL', 'XHKF', 'XHKG', 'XICE', 'XIST', 'XKOS', 'XLIS', 'XLIT', 'XLON', 'XLUX', 'XMEX', 'XMIL', 'XMUN', 'XNAS', 'XNSE', 'XNYS', 'XNZE', 'XOSE', 'XOSL', 'XOTC', 'XPAR', 'XRIS', 'XSES', 'XSHE', 'XSHG', 'XSTO', 'XSTU', 'XSWX', 'XTAI', 'XTAL', 'XTKS', 'XTSE', 'XWAR', 'XWBO']\n```\n\n### Analysis of stocks\n\nOnce, you know what stock you want to analyse, you can load it with the\nclass [Stock]{.title-ref} and then access all the methods to get data.\n\n``` python\nimport mstarpy\n\nstock = stock = mstarpy.Stock(term=\"0P00018PIU\", exchange=\"PARIS\")\n```\n\nYou can access to his property name.\n\n``` python\nprint(stock.name)\n```\n\n``` python\n'Abeo SA'\n```\n\nYou can find the historical price and volume of the stock.\n\n``` python\nimport datetime\nimport pandas as pd\nstart_date = datetime.datetime(2023,1,1)\nend_date = datetime.datetime(2023,3,2)\n#get historical data\nhistory = stock.historical(start_date=start_date,end_date=end_date, frequency=\"daily\")\n#convert it in pandas DataFrame\ndf_history = pd.DataFrame(history)\n\nprint(df_history.head())\n```\n\n``` python\nopen high low close volume previousClose date\n0 18.60 18.60 18.55 18.55 194 18.55 2022-12-30\n1 18.70 18.70 18.70 18.70 9 18.55 2023-01-02\n2 18.65 18.70 18.55 18.60 275 18.70 2023-01-03\n3 18.65 18.65 18.50 18.60 994 18.60 2023-01-04\n4 18.65 18.95 18.50 18.60 999 18.60 2023-01-05\n```\n\nYou can show the financial statements such as the balance sheet.\n\n``` python\nbs = stock.balanceSheet(period='annual', reportType='original')\n```\n\n## More commands\n\nYou can find all the methods of the classes [Funds]{.title-ref} and\n[Stocks]{.title-ref} in the part Indices and tables of this\ndocumentation.\n\n# Search with filters\n\nYou can use filters to search funds and stocks more precisely with\nmethods [search_funds]{.title-ref} and [search_stock]{.title-ref}.\n\n## Choose filters\n\nYou can find the possible filters with the methods\n[search_filter]{.title-ref}\n\nfor funds:\n\n``` python\nfrom mstarpy import search_filter\n\nfilter_fund = search_filter(pattern = '', asset_type ='fund')\n\nprint(filter_fund)\n```\n\n``` python\n['AdministratorCompanyId', 'AnalystRatingScale', 'BondStyleBox', 'BrandingCompanyId', 'CategoryId', 'CollectedSRRI', 'distribution', 'EquityStyleBox', 'ExpertiseInformed', 'FeeLevel', 'FundTNAV', 'GBRReturnM0', 'GBRReturnM12', 'GBRReturnM120', 'GBRReturnM36', 'GBRReturnM60', 'GlobalAssetClassId', 'GlobalCategoryId', 'IMASectorID', 'IndexFund', 'InvestorTypeProfessional', 'LargestRegion', 'LargestSector', 'OngoingCharge', 'QuantitativeRating', 'ReturnProfilePreservation', 'ShareClassTypeId', 'SustainabilityRank', 'UmbrellaCompanyId', 'Yield_M12']\n```\n\nfor stocks:\n\n``` python\nfrom mstarpy import search_filter\n\nfilter_stock = search_filter(pattern = '', asset_type ='stock')\n\nprint(filter_stock)\n```\n\n``` python\n['debtEquityRatio', 'DividendYield', 'epsGrowth3YYear1', 'EquityStyleBox', 'GBRReturnM0', 'GBRReturnM12', 'GBRReturnM36', 'GBRReturnM60', 'GBRReturnM120', 'IndustryId', 'MarketCap', 'netMargin', 'PBRatio', 'PEGRatio', 'PERatio', 'PSRatio', 'revenueGrowth3Y', 'roattm', 'roettm', 'SectorId']\n```\n\n## Find filters values\n\nOnce, you know what filters you want you use the method\n[filter_universe]{.title-ref} to show the possible values of each\nfilter.\n\n``` python\nfrom mstarpy import filter_universe\n\nfilter_value = filter_universe([\"GBRReturnM12\", \"PERatio\", \"LargestSector\"])\n\nprint(filter_value)\n```\n\nYou have two types of filters values, either qualitative or\nquantitative. By example, the filter LargestSector has qualitative\nvalues such as SB_Healthcare or SB_Utilities. The filter PERatio works\nwith quantitative values between 0 and 100000.\n\n## Filter funds\n\nLet say we want to find funds that invest mainly in the consumer\ndefensive sector. We can use filters like in this example:\n\n``` python\nfrom mstarpy import search_funds\n\nresponse = search_funds(term='',field=[\"Name\", \"fundShareClassId\", \"GBRReturnM12\"], country='fr', filters = {\"LargestSector\" : \"SB_ConsumerDefensive\"})\n\ndf = pd.DataFrame(response)\n\nprint(df.head())\n```\n\n``` python\nName fundShareClassId GBRReturnM12\n0 AB US High Yield A2 EUR H F00000O4X9 -9.71\n1 AB US High Yield A2 USD F00000O4XA -6.88\n2 AB US High Yield I2 EUR H F00000O4X6 -9.18\n3 AB US High Yield I2 USD F00000O4XB -6.36\n4 abrdn China A Share Sus Eq A Acc EUR F000015MAW -8.41\n```\n\nIf we want to search for funds which invest mainly in consumer defensive\nor healthcare sectors, we can add filters values to a list.\n\n``` python\nfrom mstarpy import search_funds\n\nresponse = search_funds(term='',field=[\"Name\", \"fundShareClassId\", \"GBRReturnM12\"], country='fr', filters = {\"LargestSector\" : [\"SB_ConsumerDefensive\", \"SB_Healthcare\"]})\n\ndf = pd.DataFrame(response)\n\nprint(df.head())\n```\n\n``` python\nName fundShareClassId GBRReturnM12\n0 AB Concentrated Global Eq A EUR H F00000SJ2P -10.46\n1 AB Concentrated Global Eq I EUR H F00000SJ2J -9.77\n2 AB Concentrated Global Eq I USD F00000SE91 -5.77\n3 AB Concentrated Global Eq S USD F00000SE93 1.16\n4 AB Concentrated Global Eq S1 EUR F00001CYZS -1.89\n```\n\nIn the previous examples, we saw how to search for securities with a\nqualitative filter, now let see how to use quantitativer filters.\n\n## Filter stocks\n\nWe want to find stocks with a 12 months return superior to 20%. The\nvalue of filter is a 2 length tuple. the first element is the sign\nsuperior \\\"\\>\\\", the second element the 12 months return of 20.\n\n``` python\nfrom mstarpy import search_stock\n\nresponse = search_stock(term='',field=[\"Name\", \"fundShareClassId\", \"GBRReturnM12\", \"PERatio\"], exchange='XPAR', filters={\"GBRReturnM12\" : (\">\", 20)})\n\ndf = pd.DataFrame(response)\n\nprint(df.head())\n```\n\n``` python\n0 1000Mercis SA 0P0000DKX2 24.89 95.24\n1 Abeo SA 0P00018PIU 21.73 14.84\n2 ABL Diagnostics 0P00009WGF 279.01 NaN\n3 Acteos 0P00009W9O 27.01 NaN\n4 Actia group 0P00009W9P 44.36 NaN\n```\n\nIt will work similar if we are looking for stocks with a PERatio\ninferior to 10. The value of filter is a 2 length tuple. the first\nelement is the sign inferior \\\"\\<\\\", the second element is the PERatio\n10.\n\n``` python\nfrom mstarpy import search_stock\n\nresponse = search_stock(term='',field=[\"Name\", \"fundShareClassId\", \"GBRReturnM12\", \"PERatio\"], exchange='XPAR', filters={\"PERatio\" : (\"<\", 10)})\n\ndf = pd.DataFrame(response)\n\nprint(df.head())\n```\n\n``` python\nName fundShareClassId GBRReturnM12 PERatio\n0 Acanthe Developpement SA 0P00009W9K -23.27 5.78\n1 ALD SA 0P0001AM22 31.89 5.07\n2 Altarea SCA 0P00009WAG -2.20 8.18\n3 Altur Investissement SCA 0P0000DKYA 33.38 1.98\n4 Archos 0P00009WAT -97.02 0.00\n```\n\nWe can also look like stocks with a PERatio between 10 and 20. The value\nof filter is a 2 length tuple. the first element is the lower bound\nPERatio of 10, the second element is the upper bound PERatio of 20.\n\n``` python\nfrom mstarpy import search_stock\n\nresponse = search_stock(term='',field=[\"Name\", \"fundShareClassId\", \"GBRReturnM12\", \"PERatio\"], exchange='XPAR', filters={\"PERatio\" : (10, 20)})\n\ndf = pd.DataFrame(response)\n\nprint(df.head())\n```\n\n``` python\nName fundShareClassId GBRReturnM12 PERatio\n0 ABC arbitrage SA 0P00009W9I -5.73 14.10\n1 Abeo SA 0P00018PIU 21.73 14.84\n2 AdUX SA 0P00009WIO -32.05 11.49\n3 Altareit SA 0P00009WHA -11.03 12.69\n4 Alten 0P00009WAH 14.25 19.96\n```\n\nNow we know how to use filters, we can combine them to find a precise\nsecurities universe. The world is your oyster.\n\n``` python\nfrom mstarpy import search_stock\n\nresponse = search_stock(term='',field=[\"Name\", \"fundShareClassId\", \"GBRReturnM12\", \"PERatio\"], \n exchange='XPAR', filters={\"PERatio\" : (\"<\", '10'), \"GBRReturnM12\" : (\">\", 20), \n \"debtEquityRatio\" : (0, 5), \"SectorId\" : [\"IG000BA008\", \"IG000BA006\"] })\n\ndf = pd.DataFrame(response)\n\nprint(df.head())\n```\n\n``` python\nName fundShareClassId GBRReturnM12 PERatio\n0 ALD SA 0P0001AM22 31.89 5.07\n1 Coheris 0P00009WDN 72.68 5.27\n2 Ediliziacrobatica SpA 0P0001GZM9 24.07 6.85\n3 Rexel SA 0P00009WO9 32.27 7.96\n4 Soditech SA 0P00009WQ2 97.45 4.49\n```\n\n# MStarpy in the world\n\n## Albertine.io\n\nThe site [albertine.io](https://albertine.io/#/funds) uses MStarpy to\ncompare funds. You can create PDF reports and extract data in Excel\nformat.\n\n## Contribution\n\nThe project is **open-source** and you can contribute on\n[github](https://github.com/Mael-J/mstarpy).\n\n# Disclaimer\n\nMStarpy is not affiliated to\n[morningstar.com](https://www.morningstar.com/) or any other companies.\n\nThe package aims to share public information about funds and stocks to\nautomatize analysis. It is the result of a free, free and independent\nwork.\n\nMStarpy does not give any investment recommendations.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Mutual funds and stocks data extraction from MorningStar with Python",
"version": "2.0.2",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1bfb27b76a64bfed26d3559d26b96d4197fca675d379d7c4f0ad67c6ef2a7820",
"md5": "32fcd616a95a982fe88fc7060fde048b",
"sha256": "dd82cbdfe760d3248143773ba889dc2575e07c9d7a0f756945beb9ff864588a1"
},
"downloads": -1,
"filename": "mstarpy-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "32fcd616a95a982fe88fc7060fde048b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 29257,
"upload_time": "2024-10-22T22:41:03",
"upload_time_iso_8601": "2024-10-22T22:41:03.916675Z",
"url": "https://files.pythonhosted.org/packages/1b/fb/27b76a64bfed26d3559d26b96d4197fca675d379d7c4f0ad67c6ef2a7820/mstarpy-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fc1691b93075cf643e910c02296b869e04837e522fed87660e22b2259d3424a8",
"md5": "0e1c5cc95f39c7c6185f13dfbaccf23b",
"sha256": "a0365fe94d75e862409e54f8a19341e926be5b13b03186a08fda35109832f68a"
},
"downloads": -1,
"filename": "mstarpy-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "0e1c5cc95f39c7c6185f13dfbaccf23b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 32038,
"upload_time": "2024-10-22T22:41:05",
"upload_time_iso_8601": "2024-10-22T22:41:05.574919Z",
"url": "https://files.pythonhosted.org/packages/fc/16/91b93075cf643e910c02296b869e04837e522fed87660e22b2259d3424a8/mstarpy-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 22:41:05",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mstarpy"
}
