Add docstrings to undocumented functions and updated existing docstri…

…ngs.

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

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,

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"]
 

sec_cik_mapper/BaseMapper.py

@@ -14,13 +14,16 @@
 
 
 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",
         "Host": "www.sec.gov",
     }
 
     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,42 +106,75 @@ 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"]
         return self._form_kv_mapping(ticker_col, cik_col)
 
     @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)