From 21160e0ee0b348efe7bc303d512b92005d0cd297 Mon Sep 17 00:00:00 2001 From: Jad Chaar Date: Sat, 25 Dec 2021 18:57:01 -0500 Subject: [PATCH] Add docstrings to undocumented functions and updated existing docstrings. --- README.rst | 44 ++++++------ docs/conf.py | 2 +- pyproject.toml | 2 +- sec_cik_mapper/BaseMapper.py | 103 ++++++++++++++++++++--------- sec_cik_mapper/MutualFundMapper.py | 86 +++++++++++++++++++++++- sec_cik_mapper/StockMapper.py | 59 ++++++++++++----- sec_cik_mapper/retrievers.py | 2 + 7 files changed, 221 insertions(+), 77 deletions(-) diff --git a/README.rst b/README.rst index 7309283..bf14fbe 100644 --- a/README.rst +++ b/README.rst @@ -29,12 +29,12 @@ sec-cik-mapper :alt: Code Style: Black :target: https://github.com/python/black -**sec-cik-mapper** is a Python package for obtaining mappings between stock and mutual fund identifier data provided by the SEC. +**sec-cik-mapper** is a Python package for generating mappings between stock and mutual fund identifier data provided by the SEC. Features -------- -- Up-to-date mappings from the SEC provided as native Python dictionaries +- Generate up-to-date mappings from the SEC as native Python dictionaries - Mappings for both stocks and mutual funds - Mapping data exposed as a raw pandas dataframe for custom data processing and usage - Support for Python 3.6+ @@ -86,35 +86,35 @@ Basic Usage >>> mapper = StockMapper() # Get mapping from CIK to tickers - >>> cik_to_tickers = mapper.cik_to_tickers + >>> mapper.cik_to_tickers {'0000320193': {'AAPL'}, '0000789019': {'MSFT'}, '0001652044': {'GOOG', 'GOOGL'}, ...} # Get mapping from ticker to CIK - >>> ticker_to_cik = mapper.ticker_to_cik + >>> mapper.ticker_to_cik {'AAPL': '0000320193', 'MSFT': '0000789019', 'GOOG': '0001652044', ...} # Get mapping from CIK to company name - >>> cik_to_company_name = mapper.cik_to_company_name + >>> mapper.cik_to_company_name {'0000320193': 'Apple Inc.', '0000789019': 'Microsoft Corp', '0001652044': 'Alphabet Inc.', ...} # Get mapping from ticker to company name - >>> ticker_to_company_name = mapper.ticker_to_company_name + >>> mapper.ticker_to_company_name {'AAPL': 'Apple Inc.', 'MSFT': 'Microsoft Corp', 'GOOG': 'Alphabet Inc.', ...} # Get mapping from ticker to exchange - >>> ticker_to_exchange = mapper.ticker_to_exchange + >>> mapper.ticker_to_exchange {'AAPL': 'Nasdaq', 'MSFT': 'Nasdaq', 'GOOG': 'Nasdaq', ...} # Get mapping from exchange to tickers - >>> exchange_to_tickers = mapper.exchange_to_tickers + >>> mapper.exchange_to_tickers {'Nasdaq': {'CYRN', 'OHPAW', 'SANW', ...}, 'NYSE': {'PLAG', 'TDW-WTB', 'RS', ...}, 'OTC': {'ZICX', 'LTGJ', 'AVNI', ...}, ...} # Get mapping from CIK to exchange - >>> cik_to_exchange = mapper.cik_to_exchange + >>> mapper.cik_to_exchange {'0000320193': 'Nasdaq', '0000789019': 'Nasdaq', '0001652044': 'Nasdaq', ...} # Get mapping from exchange to CIKs - >>> exchange_to_ciks = mapper.exchange_to_ciks + >>> mapper.exchange_to_ciks {'Nasdaq': {'0000779544', '0001508171', '0001060955', ...}, 'NYSE': {'0000764478', '0000008818', '0001725057', ...}, 'OTC': {'0001044676', '0001592411', '0001284452', ...}, ...} # Save CIK, ticker, exchange, and company name mappings to a CSV file @@ -149,47 +149,47 @@ Basic Usage >>> mapper = MutualFundMapper() # Get mapping from CIK to tickers - >>> cik_to_tickers = mapper.cik_to_tickers - {'0000002110': {'CRBYX', 'CEFZX', 'CSSRX', ...}, '0000002646': {'IIBPX', 'IPISX', 'IIBTX', ...}, '0000002663': {'IMSXX', 'VMTXX', 'IVMXX', ...}} + >>> mapper.cik_to_tickers + {'0000002110': {'CRBYX', 'CEFZX', 'CSSRX', ...}, '0000002646': {'IIBPX', 'IPISX', 'IIBTX', ...}, '0000002663': {'IMSXX', 'VMTXX', 'IVMXX', ...}, ...} # Get mapping from ticker to CIK - >>> ticker_to_cik = mapper.ticker_to_cik + >>> mapper.ticker_to_cik {'LACAX': '0000002110', 'LIACX': '0000002110', 'ACRNX': '0000002110', ...} # Get mapping from CIK to series ID - >>> cik_to_series_ids = mapper.cik_to_series_ids + >>> mapper.cik_to_series_ids {'0000002110': {'S000009184', 'S000033622', 'S000009185', ...}, '0000002646': {'S000008760'}, '0000002663': {'S000008702'}, ...} # Get mapping from ticker to series ID - >>> ticker_to_series_id = mapper.ticker_to_series_id + >>> mapper.ticker_to_series_id {'LACAX': 'S000009184', 'LIACX': 'S000009184', 'ACRNX': 'S000009184', ...} # Get mapping from series ID to CIK - >>> series_id_to_cik = mapper.series_id_to_cik + >>> mapper.series_id_to_cik {'S000009184': '0000002110', 'S000009185': '0000002110', 'S000009186': '0000002110', ...} # Get mapping from series ID to tickers - >>> series_id_to_tickers = mapper.series_id_to_tickers + >>> mapper.series_id_to_tickers {'S000009184': {'CEARX', 'CRBYX', 'ACRNX', ...}, 'S000009185': {'ACINX', 'CACRX', 'CAIRX', ...}, 'S000009186': {'LAUCX', 'LAUAX', 'CUSAX', ...}, ...} # Get mapping from series ID to class IDs - >>> series_id_to_class_ids = mapper.series_id_to_class_ids + >>> mapper.series_id_to_class_ids {'S000009184': {'C000024956', 'C000122737', 'C000024957', ...}, 'S000009185': {'C000024958', 'C000122739', 'C000097733', ...}, 'S000009186': {'C000024962', 'C000024964', 'C000122740', ...}, ...} # Get mapping from ticker to class ID - >>> ticker_to_class_id = mapper.ticker_to_class_id + >>> mapper.ticker_to_class_id {'LACAX': 'C000024954', 'LIACX': 'C000024956', 'ACRNX': 'C000024957', ...} # Get mapping from CIK to class IDs - >>> cik_to_class_ids = mapper.cik_to_class_ids + >>> mapper.cik_to_class_ids {'0000002110': {'C000024958', 'C000024969', 'C000024957', ...}, '0000002646': {'C000023849', 'C000074893', 'C000028785', ...}, '0000002663': {'C000023718', 'C000028786', 'C000076529', ...}, ...} # Get mapping from class ID to CIK - >>> class_id_to_cik = mapper.class_id_to_cik + >>> mapper.class_id_to_cik {'C000024954': '0000002110', 'C000024956': '0000002110', 'C000024957': '0000002110', ...} # Get mapping from class ID to ticker - >>> class_id_to_ticker = mapper.class_id_to_ticker + >>> mapper.class_id_to_ticker {'C000024954': 'LACAX', 'C000024956': 'LIACX', 'C000024957': 'ACRNX', ...} # Save CIK, ticker, series ID, and class ID mappings to a CSV file diff --git a/docs/conf.py b/docs/conf.py index f8fafcc..ccf3882 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,7 +47,7 @@ html_theme = "alabaster" html_theme_options = { - "description": "Generate mappings between CIKs, tickers, and company names using Python", + "description": "Generate mappings between SEC identifiers using Python", "github_user": "jadchaar", "github_repo": "sec-cik-mapper", "github_banner": True, diff --git a/pyproject.toml b/pyproject.toml index 5705e10..21ee9d3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -32,7 +32,7 @@ dependencies = [ "typing_extensions", ] requires-python = ">=3.6" -description = "Generate mappings between CIKs, tickers, exchanges, and company names using Python" +description = "Generate mappings between CIKs, tickers, exchanges, company names, class IDs, and series IDs using Python" keywords = ["sec", "edgar", "filing", "financial", "finance", "sec.gov", "stocks", "mutual funds", "cik", "ticker"] dynamic = ["version"] diff --git a/sec_cik_mapper/BaseMapper.py b/sec_cik_mapper/BaseMapper.py index 1a3f904..909dc29 100644 --- a/sec_cik_mapper/BaseMapper.py +++ b/sec_cik_mapper/BaseMapper.py @@ -14,6 +14,8 @@ class BaseMapper: + """A :class:`BaseMapper` object.""" + headers: ClassVar[Dict[str, str]] = { "User-Agent": f"{int(time.time())} {int(time.time())}@gmail.com", "Accept-Encoding": "gzip, deflate", @@ -21,6 +23,7 @@ class BaseMapper: } def __init__(self, retriever: Union[StockRetriever, MutualFundRetriever]) -> None: + """Constructor for the :class:`BaseMapper` class.""" self.retriever = retriever self.mapping_metadata = self._get_mapping_metadata_from_sec() @@ -40,10 +43,11 @@ def __new__(cls, *args, **kwargs): def _get_indices_from_fields(self, fields: Fields) -> FieldIndices: """Get list indices from field names.""" - return cast(FieldIndices, {field: fields.index(field) for field in fields}) + field_indices = {field: fields.index(field) for field in fields} + return cast(FieldIndices, field_indices) def _get_mapping_metadata_from_sec(self) -> pd.DataFrame: - """Get company metadata from SEC.""" + """Get company mapping metadata from SEC.""" resp = requests.get(self.retriever.source_url, headers=BaseMapper.headers) resp.raise_for_status() data = resp.json() @@ -62,9 +66,11 @@ def _get_mapping_metadata_from_sec(self) -> pd.DataFrame: return pd.DataFrame(transformed_data) def _form_kv_set_mapping(self, keys: pd.Series, values: pd.Series) -> KeyToValueSet: - """Form mapping from key to list of values, ignoring blank keys and values""" - # Example: numerous CIKs map to multiple tickers (e.g. Banco Santander), - # so we must keep a list of tickers for each unique CIK. + """Form mapping from key to list of values, ignoring blank keys and values. + + Example: numerous CIKs map to multiple tickers (e.g. Banco Santander), + so we must keep a list of tickers for each unique CIK. + """ mapping = defaultdict(set) for key, value in zip(keys, values): # Ignore blank keys and values @@ -78,19 +84,17 @@ def _form_kv_mapping(self, keys: pd.Series, values: pd.Series) -> Dict[str, str] @property def cik_to_tickers(self) -> KeyToValueSet: - """Get CIK to ticker mapping. + """Get CIK to tickers mapping. Usage:: - >>> from sec_cik_mapper import CIKMapper - >>> from pathlib import Path - - # Initialize a CIK mapper instance - >>> cikMapper = CIKMapper() - - # Get a dictionary mapping CIK to a list of tickers - >>> cikMapper.get_cik_to_ticker_mapping() - {'0000320193': ['AAPL'], '0001652044': ['GOOG', 'GOOGL'], ...} + >>> from sec_cik_mapper import MutualFundMapper, StockMapper + >>> stock_mapper = StockMapper() + >>> mutual_fund_mapper = MutualFundMapper() + >>> stock_mapper.cik_to_tickers + {'0000320193': {'AAPL'}, '0001652044': {'GOOG', 'GOOGL'}, ...} + >>> mutual_fund_mapper.cik_to_tickers + {'0000002110': {'CRBYX', 'CEFZX', ...}, '0000002646': {'IIBPX', 'IPISX', ...}, ...} """ cik_col = self.mapping_metadata["CIK"] ticker_col = self.mapping_metadata["Ticker"] @@ -102,15 +106,13 @@ def ticker_to_cik(self) -> Dict[str, str]: Usage:: - >>> from sec_cik_mapper import CIKMapper - >>> from pathlib import Path - - # Initialize a CIK mapper instance - >>> cikMapper = CIKMapper() - - # Get a dictionary mapping ticker to CIK - >>> cikMapper.get_ticker_to_cik_mapping() + >>> from sec_cik_mapper import MutualFundMapper, StockMapper + >>> stock_mapper = StockMapper() + >>> mutual_fund_mapper = MutualFundMapper() + >>> stock_mapper.ticker_to_cik {'AAPL': '0000320193', 'MSFT': '0000789019', 'GOOG': '0001652044', ...} + >>> mutual_fund_mapper.ticker_to_cik + {'LACAX': '0000002110', 'LIACX': '0000002110', 'ACRNX': '0000002110', ...} """ cik_col = self.mapping_metadata["CIK"] ticker_col = self.mapping_metadata["Ticker"] @@ -118,26 +120,61 @@ def ticker_to_cik(self) -> Dict[str, str]: @property def raw_dataframe(self) -> pd.DataFrame: + """Get raw pandas dataframe. + + Usage:: + + >>> from sec_cik_mapper import MutualFundMapper, StockMapper + >>> stock_mapper = StockMapper() + >>> mutual_fund_mapper = MutualFundMapper() + >>> stock_mapper.raw_dataframe + CIK Ticker Name Exchange + 0 0000320193 AAPL Apple Inc. Nasdaq + 1 0000789019 MSFT Microsoft Corp Nasdaq + 2 0001652044 GOOG Alphabet Inc. Nasdaq + 3 0001018724 AMZN Amazon Com Inc Nasdaq + 4 0001318605 TSLA Tesla, Inc. Nasdaq + ... ... ... ... ... + 13184 0001866816 OLITU Omnilit Acquisition Corp. Nasdaq + 13185 0001870778 OHAAU Opy Acquisition Corp. I Nasdaq + 13186 0001873324 PEPLW Pepperlime Health Acquisition Corp Nasdaq + 13187 0001877557 WEL-UN Integrated Wellness Acquisition Corp NYSE + 13188 0001877787 ZGN-WT Ermenegildo Zegna Holditalia S.P.A. NYSE + + [13189 rows x 4 columns] + >>> mutual_fund_mapper.raw_dataframe + CIK Ticker Series ID Class ID + 0 0000002110 LACAX S000009184 C000024954 + 1 0000002110 LIACX S000009184 C000024956 + 2 0000002110 ACRNX S000009184 C000024957 + 3 0000002110 CEARX S000009184 C000122735 + 4 0000002110 CRBRX S000009184 C000122736 + ... ... ... ... ... + 29237 0001860434 SIHY S000072555 C000228888 + 29238 0001860434 SIFI S000072556 C000228889 + 29239 0001860434 INNO S000073580 C000230585 + 29240 0001877493 BTF S000074058 C000231452 + 29241 0001877493 VBB S000075054 C000233857 + + [29242 rows x 4 columns] + """ return self.mapping_metadata def save_metadata_to_csv(self, path: Union[str, Path]) -> None: - """Save company stock metadata (CIK, ticker, exchange, and - company name) or mutual fund metadata (CIK, ticker, series ID, - class ID) from SEC to CSV. + """Save stock mapping metadata (CIK, ticker, exchange, and company name) + or mutual fund mapping metadata (CIK, ticker, series ID, class ID) from + SEC to CSV. Usage:: >>> from sec_cik_mapper import StockMapper, MutualFundMapper >>> from pathlib import Path - - >>> stockMapper = StockMapper() - >>> mutualFundMapper = MutualFundMapper() + >>> stock_mapper = StockMapper() + >>> mutual_fund_mapper = MutualFundMapper() >>> csv_path = Path("cik_mapping.csv") - # Save full CIK, ticker, exchange, and company name mapping to a CSV file - >>> stockMapper.save_metadata_to_csv(csv_path) - + >>> stock_mapper.save_metadata_to_csv(csv_path) # Save full CIK, ticker, series ID, and class ID mapping to a CSV file - >>> mutualFundMapper.save_metadata_to_csv(csv_path) + >>> mutual_fund_mapper.save_metadata_to_csv(csv_path) """ self.mapping_metadata.to_csv(path, index=False) diff --git a/sec_cik_mapper/MutualFundMapper.py b/sec_cik_mapper/MutualFundMapper.py index 7d5aac7..ad5633f 100644 --- a/sec_cik_mapper/MutualFundMapper.py +++ b/sec_cik_mapper/MutualFundMapper.py @@ -14,66 +14,146 @@ class MutualFundMapper(BaseMapper): Usage:: >>> from sec_cik_mapper import MutualFundMapper - - # Create a MutualFundMapper instance - >>> mutualFundMapper = MutualFundMapper() + >>> mutual_fund_mapper = MutualFundMapper() """ _retriever: ClassVar[MutualFundRetriever] = MutualFundRetriever() def __init__(self) -> None: + """Constructor for the :class:`MutualFundMapper` class.""" super().__init__(MutualFundMapper._retriever) @property def cik_to_series_ids(self) -> KeyToValueSet: + """Get CIK to series ID mapping. + + Usage:: + + >>> from sec_cik_mapper import MutualFundMapper + >>> mutual_fund_mapper = MutualFundMapper() + >>> mutual_fund_mapper.cik_to_series_ids + {'0000002110': {'S000009184', 'S000033622', ...}, '0000002646': {'S000008760'}, ...} + """ cik_col = self.mapping_metadata["CIK"] series_id_col = self.mapping_metadata["Series ID"] return self._form_kv_set_mapping(cik_col, series_id_col) @property def ticker_to_series_id(self) -> Dict[str, str]: + """Get ticker to series ID mapping. + + Usage:: + + >>> from sec_cik_mapper import MutualFundMapper + >>> mutual_fund_mapper = MutualFundMapper() + >>> mutual_fund_mapper.ticker_to_series_id + {'LACAX': 'S000009184', 'LIACX': 'S000009184', 'ACRNX': 'S000009184', ...} + """ ticker_col = self.mapping_metadata["Ticker"] series_id_col = self.mapping_metadata["Series ID"] return self._form_kv_mapping(ticker_col, series_id_col) @property def series_id_to_cik(self) -> Dict[str, str]: + """Get series ID to CIK mapping. + + Usage:: + + >>> from sec_cik_mapper import MutualFundMapper + >>> mutual_fund_mapper = MutualFundMapper() + >>> mutual_fund_mapper.series_id_to_cik + {'S000009184': '0000002110', 'S000009185': '0000002110', ...} + """ cik_col = self.mapping_metadata["CIK"] series_id_col = self.mapping_metadata["Series ID"] return self._form_kv_mapping(series_id_col, cik_col) @property def series_id_to_tickers(self) -> KeyToValueSet: + """Get series ID to tickers mapping. + + Usage:: + + >>> from sec_cik_mapper import MutualFundMapper + >>> mutual_fund_mapper = MutualFundMapper() + >>> mutual_fund_mapper.series_id_to_tickers + {'S000009184': {'CEARX', 'CRBYX', ...}, 'S000009185': {'ACINX', 'CACRX', ...}, ...} + """ ticker_col = self.mapping_metadata["Ticker"] series_id_col = self.mapping_metadata["Series ID"] return self._form_kv_set_mapping(series_id_col, ticker_col) @property def series_id_to_class_ids(self) -> KeyToValueSet: + """Get series ID to class IDs mapping. + + Usage:: + + >>> from sec_cik_mapper import MutualFundMapper + >>> mutual_fund_mapper = MutualFundMapper() + >>> mutual_fund_mapper.series_id_to_class_ids + {'S000009184': {'C000024956', ...}, 'S000009185': {'C000024958', ...}, ...} + """ class_id_col = self.mapping_metadata["Class ID"] series_id_col = self.mapping_metadata["Series ID"] return self._form_kv_set_mapping(series_id_col, class_id_col) @property def ticker_to_class_id(self) -> Dict[str, str]: + """Get ticker to class ID mapping. + + Usage:: + + >>> from sec_cik_mapper import MutualFundMapper + >>> mutual_fund_mapper = MutualFundMapper() + >>> mutual_fund_mapper.ticker_to_class_id + {'LACAX': 'C000024954', 'LIACX': 'C000024956', 'ACRNX': 'C000024957', ...} + """ ticker_col = self.mapping_metadata["Ticker"] class_id_col = self.mapping_metadata["Class ID"] return self._form_kv_mapping(ticker_col, class_id_col) @property def cik_to_class_ids(self) -> KeyToValueSet: + """Get CIK to class IDs mapping. + + Usage:: + + >>> from sec_cik_mapper import MutualFundMapper + >>> mutual_fund_mapper = MutualFundMapper() + >>> mutual_fund_mapper.cik_to_class_ids + {'0000002110': {'C000024958', ...}, '0000002646': {'C000023849', ...}, ...} + """ cik_col = self.mapping_metadata["CIK"] class_id_col = self.mapping_metadata["Class ID"] return self._form_kv_set_mapping(cik_col, class_id_col) @property def class_id_to_cik(self) -> Dict[str, str]: + """Get class ID to CIK mapping. + + Usage:: + + >>> from sec_cik_mapper import MutualFundMapper + >>> mutual_fund_mapper = MutualFundMapper() + >>> mutual_fund_mapper.class_id_to_cik + {'C000024954': '0000002110', 'C000024956': '0000002110', ...} + """ cik_col = self.mapping_metadata["CIK"] class_id_col = self.mapping_metadata["Class ID"] return self._form_kv_mapping(class_id_col, cik_col) @property def class_id_to_ticker(self) -> Dict[str, str]: + """Get class ID to ticker mapping. + + Usage:: + + >>> from sec_cik_mapper import MutualFundMapper + >>> mutual_fund_mapper = MutualFundMapper() + >>> mutual_fund_mapper.class_id_to_ticker + {'C000024954': 'LACAX', 'C000024956': 'LIACX', 'C000024957': 'ACRNX', ...} + """ ticker_col = self.mapping_metadata["Ticker"] class_id_col = self.mapping_metadata["Class ID"] return self._form_kv_mapping(class_id_col, ticker_col) diff --git a/sec_cik_mapper/StockMapper.py b/sec_cik_mapper/StockMapper.py index eb2fb35..06a71ce 100644 --- a/sec_cik_mapper/StockMapper.py +++ b/sec_cik_mapper/StockMapper.py @@ -14,14 +14,13 @@ class StockMapper(BaseMapper): Usage:: >>> from sec_cik_mapper import StockMapper - - # Create a StockMapper instance - >>> stockMapper = StockMapper() + >>> stock_mapper = StockMapper() """ _retriever: ClassVar[StockRetriever] = StockRetriever() def __init__(self) -> None: + """Constructor for the :class:`StockMapper` class.""" super().__init__(StockMapper._retriever) @property @@ -31,13 +30,8 @@ def cik_to_company_name(self) -> Dict[str, str]: Usage:: >>> from sec_cik_mapper import StockMapper - >>> from pathlib import Path - - # Initialize a CIK mapper instance - >>> stockMapper = StockMapper() - - # Get a dictionary mapping CIK to company name - >>> stockMapper.get_cik_to_company_name_mapping() + >>> stock_mapper = StockMapper() + >>> stock_mapper.cik_to_company_name {'0000320193': 'Apple Inc.', '0000789019': 'Microsoft Corp', ...} """ cik_col = self.mapping_metadata["CIK"] @@ -51,13 +45,8 @@ def ticker_to_company_name(self) -> Dict[str, str]: Usage:: >>> from sec_cik_mapper import StockMapper - >>> from pathlib import Path - - # Initialize a CIK mapper instance - >>> stockMapper = StockMapper() - - # Get a dictionary mapping ticker to company name - >>> stockMapper.get_ticker_to_company_name_mapping() + >>> stock_mapper = StockMapper() + >>> stock_mapper.ticker_to_company_name {'AAPL': 'Apple Inc.', 'MSFT': 'Microsoft Corp', 'GOOG': 'Alphabet Inc.', ...} """ ticker_col = self.mapping_metadata["Ticker"] @@ -66,24 +55,60 @@ def ticker_to_company_name(self) -> Dict[str, str]: @property def ticker_to_exchange(self) -> Dict[str, str]: + """Get ticker to exchange mapping. + + Usage:: + + >>> from sec_cik_mapper import StockMapper + >>> stock_mapper = StockMapper() + >>> stock_mapper.ticker_to_exchange + {'AAPL': 'Nasdaq', 'MSFT': 'Nasdaq', 'GOOG': 'Nasdaq', ...} + """ ticker_col = self.mapping_metadata["Ticker"] exchange_col = self.mapping_metadata["Exchange"] return self._form_kv_mapping(ticker_col, exchange_col) @property def exchange_to_tickers(self) -> KeyToValueSet: + """Get exchange to tickers mapping. + + Usage:: + + >>> from sec_cik_mapper import StockMapper + >>> stock_mapper = StockMapper() + >>> stock_mapper.exchange_to_tickers + {'Nasdaq': {'CYRN', 'OHPAW', ...}, 'NYSE': {'PLAG', 'TDW-WTB', ...}, ...} + """ ticker_col = self.mapping_metadata["Ticker"] exchange_col = self.mapping_metadata["Exchange"] return self._form_kv_set_mapping(exchange_col, ticker_col) @property def cik_to_exchange(self) -> Dict[str, str]: + """Get CIK to exchange mapping. + + Usage:: + + >>> from sec_cik_mapper import StockMapper + >>> stock_mapper = StockMapper() + >>> stock_mapper.cik_to_exchange + {'0000320193': 'Nasdaq', '0000789019': 'Nasdaq', '0001652044': 'Nasdaq', ...} + """ cik_col = self.mapping_metadata["CIK"] exchange_col = self.mapping_metadata["Exchange"] return self._form_kv_mapping(cik_col, exchange_col) @property def exchange_to_ciks(self) -> KeyToValueSet: + """Get exchange to CIKs mapping. + + Usage:: + + >>> from sec_cik_mapper import StockMapper + >>> stock_mapper = StockMapper() + >>> stock_mapper.exchange_to_ciks + {'Nasdaq': {'0000779544', ...}, 'NYSE': {'0000764478', ...}, ...} + """ cik_col = self.mapping_metadata["CIK"] exchange_col = self.mapping_metadata["Exchange"] return self._form_kv_set_mapping(exchange_col, cik_col) diff --git a/sec_cik_mapper/retrievers.py b/sec_cik_mapper/retrievers.py index cf2c830..173d761 100644 --- a/sec_cik_mapper/retrievers.py +++ b/sec_cik_mapper/retrievers.py @@ -1,3 +1,5 @@ +"""Retrieval abstractions for SEC source URLs and data transformers.""" + import re from abc import ABCMeta, abstractmethod from typing import ClassVar, Dict, List, Pattern, Union, cast